Введение

Это руководство проведёт вас от пустого проекта до собственного индикатора, который появляется на канвасе Velitask. Оно намеренно практическое: что взять, что поставить, что подключить, что собрать и куда нажать. Точный контракт классов SDK здесь не разбирается — для этого есть JavaDoc и документация эталонных плагинов (см. Что дальше).

Velitask намеренно сделан открытым — чтобы дать разработчикам максимальную свободу. Все данные проекта хранятся в локальной базе SQLite, и плагин работает с ней напрямую: читает данные источников и сенсоров, а также может заводить собственные таблицы и хранить в них свою аналитику.

🔓 Исходный код всех официальных плагинов открыт

Код plugin-official — всех плагинов, поставляемых с Velitask, — полностью открыт. Вы можете:

• изучать его и брать за основу своих индикаторов;
• копировать и править как угодно, под свои задачи;
• дополнять и развивать существующие индикаторы;
• присылать улучшения через pull request — они приветствуются.

Не начинайте с нуля: форкните рабочий плагин и переделайте его под себя.

Ваш форк заменяет официальный плагин. Плагин опознаётся по идентификатору (UID). Если ваша сборка сохраняет тот же UID, что и встроенный плагин, Velitask загрузит только одну из них — собранную позже. Поднимать версию не нужно: достаточно пересобрать форк, и система подхватит ваш свежий JAR по дате файла вместо встроенного.

Плагин и индикатор

Плагин — это JAR-файл, который добавляет в Velitask Desktop один или несколько индикаторов. Velitask находит плагины в заданных папках, загружает их при запуске и может перезагружать на лету при разработке.

Индикатор — визуальный компонент, который рисуется поверх кадра в проекте (в композиции, которая в Velitask называется Миксель). Индикатор читает данные источника — скорость, дистанцию, высоту, координаты, время — и отрисовывает их так, как вы запрограммировали: спидометр, текст, график, карта. Пользователь добавляет индикатор на канвас, настраивает его свойства и видит результат прямо в превью.

Один плагин может содержать несколько индикаторов. Минимальный рабочий плагин — это один класс плагина (точка входа) плюс один класс индикатора.

Где что лежит

Что мы соберём

В этом курсе вы:

1. поставите инструменты и возьмёте эталонный проект — Что понадобится;
2. подключите SDK и соберёте JAR — Сборка и подключение SDK;
3. установите плагин в Velitask и выведете индикатор на канвас — Установка и запуск;
4. настроите горячую перезагрузку, чтобы правки подхватывались без перезапуска — Цикл разработки;
5. узнаете, где брать детали API, когда захотите большего — Что дальше.

К концу вы получите собственный индикатор на канвасе и рабочий цикл, в котором изменение кода почти сразу видно в приложении.

Дальше: Что понадобится.

Что понадобится

Перед сборкой плагина подготовьте окружение и возьмите эталонный проект.

Инструменты

Проверьте, что Java видна в консоли:

java -version

Версия должна быть 21 или выше.

Установка Gradle

Подробная официальная инструкция — на gradle.org/install. Кратко по платформам:

• Windows — проще всего через менеджер пакетов:
  • Chocolatey: choco install gradle
  • Scoop: scoop install gradle
  • либо вручную: скачать ZIP с gradle.org/releases, распаковать и добавить папку bin в переменную PATH (см. шаги в официальной инструкции).
• macOS / Linux — через SDKMAN: sdk install gradle, либо brew install gradle (macOS, Homebrew).

Проверьте установку:

gradle -v

Версия Gradle должна быть 8 или выше, а в строке JVM — Java 21+.

Эталонный проект также содержит Gradle Wrapper (gradlew / gradlew.bat) — он скачивает нужную версию Gradle сам. Если предпочитаете wrapper, во всех командах ниже заменяйте gradle на ./gradlew (или gradlew.bat на Windows).

Эталонный проект

Не начинайте с пустого проекта — возьмите plugin-example. Это минимальный рабочий плагин с одним индикатором, правильно настроенной сборкой, манифестом и локализацией. Дальше вы переделаете его под себя.

Форкните репозиторий на GitHub и склонируйте свой форк, либо склонируйте напрямую:

git clone https://github.com/velitask/plugin-example.git
cd plugin-example

Проверка окружения

Соберите эталонный проект как есть — это убедит, что JDK и Gradle настроены правильно, ещё до того как вы что-то меняете:

gradle jar

Сборка должна завершиться успешно, а в папке build/libs/ появится JAR-файл. Если здесь что-то падает — проблема в окружении (чаще всего не та версия Java), и её надо устранить до следующего шага.

Дальше: Сборка и подключение SDK.

Сборка и подключение SDK

Здесь разберём, что в проекте плагина отвечает за подключение SDK и за то, чтобы Velitask распознал собранный JAR. В plugin-example всё это уже настроено — ниже объясняется, что именно делает каждый кусок, чтобы вы могли повторить это в своём проекте.

Подключение SDK

SDK публикуется через JitPack. В build.gradle нужны репозиторий JitPack и зависимость на SDK:

plugins {
    id 'java'
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.velitask:velitask-sdk:1.0.+'
}

Ключевой момент — compileOnly. SDK нужен только для компиляции: в момент работы плагина его предоставляет само приложение Velitask. Если упаковать SDK внутрь JAR-плагина (implementation вместо compileOnly), классы задвоятся и плагин не загрузится. Поэтому SDK — всегда compileOnly.

1.0.+ берёт последнюю версию ветки 1.0. Для воспроизводимой сборки замените на конкретную версию из Releases.

Манифест JAR

Velitask находит плагин по атрибуту в манифесте JAR. Без него приложение не поймёт, что это плагин. Настраивается в задаче jar:

jar {
    archiveBaseName = 'my-indicator'

    manifest {
        attributes(
            'Velitask-Plugin-Class': 'com.example.myplugin.MyPlagin',
            'Velitask-Plugin-Localization': 'strings/strings'
        )
    }
}

Точка входа и сам индикатор — это код вашего плагина; в plugin-example они уже написаны, а их устройство разбирается в документации этого проекта (см. Что дальше). На текущем шаге достаточно знать: класс из Velitask-Plugin-Class реализует IPlagin и возвращает список индикаторов.

Сборка JAR

gradle jar

Результат — build/libs/<archiveBaseName>-<версия>.jar. Это и есть готовый плагин: один файл, который вы отдадите Velitask на следующем шаге.

Дальше: Установка и запуск.

Установка и запуск

JAR собран — осталось отдать его Velitask и вывести индикатор на канвас.

1. Куда положить плагин

Velitask загружает плагины из заданных папок. Есть два пути.

Вариант A — стандартная папка плагинов

Скопируйте JAR в пользовательскую папку плагинов:

Вариант B — указать папку сборки (удобно при разработке)

Чтобы не копировать JAR после каждой сборки, укажите Velitask саму папку build/libs:

1. Откройте Инструменты → Настройки….
2. Выберите категорию Папки с плагинами.
3. Нажмите Добавить… и выберите папку build/libs вашего проекта.

Изменения применяются сразу — Velitask пересканирует папки в фоне, перезапуск не нужен. В этой же категории список папок можно переупорядочивать (Вверх / Вниз) и удалять (Удалить).

2. Открыть канвас

Индикатор рисуется поверх кадра в Микселе — композиции источника. Чтобы получить канвас:

1. Создайте или откройте проект: Файл → Создать проект… или Файл → Открыть проект….
2. Добавьте в проект источник (видео, GPX и т.п.), если его ещё нет.
3. Двойным кликом по источнику в панели Проект откройте его редактор — в центре появится канвас Микселя.

3. Вывести индикатор на канвас

1. Откройте панель Индикаторы (Вид → Индикаторы; по умолчанию слева).
2. Найдите свой индикатор по названию в строке поиска.
3. Перетащите его из списка на канвас — либо вызовите контекстное меню индикатора и выберите Добавить на миксель.

Индикатор появляется на канвасе как новый слой. Выделите его в панели Слои — справа, в панели Свойства, доступны его настройки (те самые, что объявлены в коде индикатора).

Не видите свой индикатор в списке? Индикатор показывается и добавляется только если он совместим с типом данных текущего источника. Проверьте также, что JAR лежит в подключённой папке и собрался без ошибок. Частые причины и их разбор — в Что дальше и документации plugin-example.

После того как индикатор появился на канвасе — настройте удобный цикл разработки, чтобы правки подхватывались без ручного копирования и перезапуска.

Дальше: Цикл разработки.

Цикл разработки

Когда индикатор уже на канвасе, главная боль — цикл «пересобрал → перезапустил Velitask». Его убирает Dev API: локальный HTTP-эндпоинт, через который Gradle подкидывает свежий JAR в работающее приложение и перезагружает плагин на месте, без перезапуска и без потери открытого проекта.

1. Включить Dev API (один раз)

1. Откройте Инструменты → Настройки… → Папки с плагинами.
2. В секции Dev API (HTTP) включите Включить локальный API для перезагрузки плагинов.
3. Порт по умолчанию — 19809 (можно изменить).

Эндпоинт перезагрузки (его подсказывает само окно настроек):

GET http://127.0.0.1:19809/api/plugins/v1/plugin/reload/{uid}

{uid} — идентификатор вашего плагина (тот, что возвращает getUID()). Доступ только с localhost.

2. Задача Gradle для пересборки и перезагрузки

Добавьте в build.gradle задачу, которая собирает JAR, кладёт его в папку плагинов и дёргает reload:

tasks.register('installAndReload') {
    group = 'velitask'
    description = 'Build jar, install it, and reload the plugin in a running Velitask'
    dependsOn 'jar'

    doLast {
        def home = System.getProperty('user.home')
        def pluginsDir = file("${home}/.velitask/plugins")
        pluginsDir.mkdirs()

        def srcJar = jar.archiveFile.get().asFile
        def dstJar = new File(pluginsDir, srcJar.name)
        dstJar.bytes = srcJar.bytes
        logger.lifecycle("[installAndReload] installed: ${dstJar}")

        def port = (project.findProperty('devApiPort') ?: '19809') as int
        def uid  = 'com.example.myplugin'   // ← uid вашего плагина (совпадает с getUID())
        def url  = new URL("http://127.0.0.1:${port}/api/plugins/v1/plugin/reload/${uid}")

        try {
            def conn = (HttpURLConnection) url.openConnection()
            conn.requestMethod = 'GET'
            conn.connectTimeout = 3000
            conn.readTimeout = 65000
            logger.lifecycle("[installAndReload] ${url} → ${conn.responseCode}")
        } catch (Throwable ex) {
            logger.warn("[installAndReload] reload skipped: ${ex.message} (Velitask не запущен или Dev API выключен?)")
        }
    }
}

tasks.named('build').configure { finalizedBy 'installAndReload' }

Последняя строка вешает перезагрузку на каждую сборку: IDE по кнопке Build вызывает gradle build, а значит и installAndReload.

3. Ежедневный цикл

1. Velitask запущен, ваш индикатор стоит на канвасе.
2. Правите код в IDE.
3. Жмёте Build (или gradle build в консоли).
4. Velitask перезагружает плагин и перерисовывает канвас новой версией.

Если Velitask не запущен или Dev API выключен — задача просто положит JAR на место, а шаг reload пропустится; сборка не упадёт.

При перезагрузке Velitask создаёт новый экземпляр плагина в свежем classloader-е, а старый — выгружает. Поэтому плагин обязан корректно освобождать ресурсы при выгрузке; что именно за это отвечает — в документации plugin-example (см. Что дальше).

Дальше: Что дальше.

Что дальше

Свой индикатор на канвасе, рабочий цикл с горячей перезагрузкой — основа готова. Дальше начинается собственно содержательная часть: что индикатор показывает и как выглядит. Эта документация — общая инструкция по обвязке; детали API и приёмы живут в трёх местах.

Эталонные плагины

• plugin-example — минимальный плагин, который вы форкнули. Его код и wiki разбирают «скелет»: класс плагина, индикатор, объявление свойств, локализация, схема БД. Лучшая отправная точка, когда нужно понять «как это устроено в малом».
• plugin-official — production-плагин, поставляемый с Velitask (спидометр, дистанция, график уклона, карта и т.д.). Канонический референс для нетривиальных индикаторов: чтение сенсоров, рисование графиков и карт, скины, фигуры. Смотрите его, когда ваш индикатор перерастает «hello world».

JavaDoc

Точный контракт каждого класса и метода SDK — в JavaDoc:

• в IDE — наведение или Ctrl+Q на любом классе SDK;
• онлайн, после публикации релиза на JitPack: https://javadoc.jitpack.io/com/github/velitask/velitask-sdk/<версия>/javadoc/.

JavaDoc — первоисточник по сигнатурам и поведению. Концептуальные обзоры (этот курс, wiki плагинов) его дополняют, а не заменяют.

Что искать под конкретную задачу

Если что-то не работает

• Плагин не появился в списке индикаторов — проверьте, что JAR лежит в подключённой папке, манифест содержит Velitask-Plugin-Class, а указанный класс реализует IPlagin. Индикатор виден только при совместимости с типом текущего источника.
• Плагин не загрузился / ошибка при загрузке — Velitask проверяет байткод плагина по белому списку допустимых API. Если плагин обращается к запрещённым классам (сеть, файловая система, запуск процессов), загрузка отклоняется. Допустимые API и ограничения разобраны в документации plugin-example.
• Свежие правки не применяются — убедитесь, что включён Dev API и задача installAndReload действительно дёргает reload (см. Цикл разработки).

Назад к началу: Введение · Оглавление.