HovermateHovermateДокументация
Русский

SDK игровых событий · Справочник

Протокол v1

Контракт между играми и Hovermate. Страница создана из PROTOCOL.md, входящего в SDK.

Цель: любая игра или мод могут передавать события в Hovermate. Они превращаются в маркеры и автоматически сохранённые яркие моменты, как во встроенных карточках. Три канала передачи охватывают среды с сетью, только с файлами и только с журналом.

1. Поиск подключения

Пока SDK включён, Engine записывает %LOCALAPPDATA%\Hovermate\Sdk\connection.json (Настройки › Клипы › SDK игровых событий; по умолчанию включён):

{
  "version": 1,
  "url": "http://local.hovermate.gg/hovermate/v1/events",
  "token": "<random, base64url, 32 bytes>",
  "inbox": "C:\\Users\\<user>\\AppData\\Local\\Hovermate\\Sdk\\Inbox"
}
  • url — адрес, на который отправляются события. Читайте его из этого файла и используйте точно в том виде, в каком он записан; никогда не прописывайте в коде и не меняйте хост, порт или путь. Сейчас Hovermate записывает http://local.hovermate.gg/hovermate/v1/events; тестовый сервер SDK записывает свой тестовый адрес.
  • Клиенты читают файл при запуске и после каждого ответа 401: токен может меняться.
  • HOVERMATE_SDK_CONNECTION=<path> переопределяет путь для тестов, инструментов и изолированных папок данных. Клиенты всегда берут входящую папку из поля inbox, а не вычисляют её сами.
  • Если файла нет, Hovermate не установлен или SDK выключен. Клиенты молчат и не передают исключения в игру.

2. Способы передачи

2.1 HTTP (моды с сетью: C#, C++, Java, Python, JS)

  • POST {url}; заголовки Authorization: Bearer <token>, Content-Type: application/json.
  • Запросы с заголовком Origin отклоняются ответом 403, поэтому браузеры не могут отправлять события.
  • Тело: один объект события либо { "events": [ ... ] } с максимум 100 событиями. Размер тела — до 64 КБ.
  • Пакет принимается целиком либо отклоняется. Hovermate сначала проверяет все события. При ошибке ни одно не принимается, а тело 400 указывает позицию: { "error": "<code>", "detail": "...", "index": 3 }. Для новой в этой сессии игры поле game.name обязательно в первом упоминающем её событии пакета.
  • Ответы:
    • 202 принято;
    • 400 ошибка данных, тело { "error": "<code>", "detail": "...", "index": <n, batches only> };
    • 401 токен неверен или отсутствует;
    • 403 запрос содержит заголовок Origin;
    • 413 тело слишком велико. До 1 МБ сначала считывается и отбрасывается, чтобы клиент получил статус; более крупное тело может быть отклонено до чтения с закрытием соединения;
    • 429 более 20 событий/с для игры;
    • 405, 411, 415 неверный метод, нет длины либо неверный тип содержимого.
  • Клиенты отправляют события в фоне без ожидания ответа в игровом потоке. Используют тайм-аут до 250 мс, ограниченную очередь с удалением старого и не более одного повтора.

2.2 Входящая папка JSONL (моды с записью файлов без сети)

  • Добавляйте строки UTF-8 в {inbox}\<game.id>.jsonl: по одному объекту события, без BOM.
  • Токен не нужен: папка принадлежит пользователю.
  • При запуске Engine начинает следить за каждым файлом *.jsonl во входящей папке с его конца. Мод может очистить свой файл в начале сессии.

2.3 Строки журнала (скрипты с записью только в журнал игры)

  • Строка должна содержать маркер [HOVERMATE] и один JSON-объект события. Всё до маркера, включая время и имя канала, игнорируется.
  • В карточке SDK есть список «Читать события из файла», куда игрок добавляет путь к журналу. Его также может предложить событие hello (§4), пришедшее другим способом. Engine читает файл существующим адаптером слежения за журналом.
  • Hovermate автоматически следит за известными журналами скриптов, пока игра работает. Пути находятся в каталоге игр (sdkLogs), например Documents\The Witcher 3\scriptslog.txt и журналы Papyrus Skyrim/Fallout. Достаточно включить журналирование скриптов в игре.

2.4 Файл событий в папке мода (среды с записью только в свою папку)

  • Некоторые среды, например Lua-моды Cyber Engine Tweaks, разрешают запись только в папку мода. Такой мод добавляет строки JSONL (§2.2) в свой файл hovermate-events.jsonl.
  • Игрок добавляет файл в список «Читать события из файла» карточки SDK. README мода должен указывать его путь. Hovermate читает добавленные строки как во входящем файле.
  • Мод также может один раз вывести свой путь строкой журнала [HOVERMATE] либо передать его в hello.files — массиве путей — через другой доступный канал. Hovermate предложит добавить файл.

3. Объект события

{
  "v": 1,
  "game": { "id": "com.example.mygame", "name": "My Game", "exe": "MyGame.exe" },
  "type": "kill",
  "label": "Double kill",
  "tags": ["headshot"],
  "context": "Act 2 · The City",
  "time": "2026-11-09T21:15:03.120Z"
}
  • v — обязательно, 1.
  • game.id — обязательно, [a-z0-9._-]{3,64}. Обратное DNS-имя или короткий идентификатор, неизменный между версиями мода.
  • game.name — обязательно в первом событии или hello сессии; до 64 символов.
  • game.exe — необязательно, только имя файла. Связывает события с найденной папкой игры и разрешает этой программе запускать буфер повтора.
  • type — обязательно. Стандартный тип из общего списка в Docs/CLIPS.md: kill, death, assist, multikill, roundWon, roundLost, matchWon, matchLost, mvp, objective, lap, bestLap, position, crash, incident, levelUp, bossKill, zone, achievement, goal, save, mission, fightWon, penalty, pit, finish, raceWon, landing, takeoff — либо "custom". Список в Docs/CLIPS.md является основным и только расширяется. Неизвестный тип отклоняется с 400.
  • customType / customLabel — обязательны, если type равен "custom". customType соответствует [a-z0-9_.-]{1,32}; customLabel — подпись переключателя в карточке длиной до 40 символов.
  • label — необязательная подпись события для подсказки маркера и названия клипа; до 80 символов.
  • tags — необязательно, до 8 тегов, каждый соответствует [a-z0-9_-]{1,24}.
  • context — необязательная карта, уровень или область для названий ярких моментов; до 64 символов.
  • time — необязательное время ISO-8601 UTC. Engine ставит время получения; time в пределах ±5 с уточняет отметку, другие значения игнорируются.
  • Неизвестные поля игнорируются; новые версии только добавляют поля.
  • Ограничения длины считаются в кодовых единицах UTF-16, как length в JavaScript и string.Length в .NET. Шаблон должен совпадать со всем значением: перевод строки в конце недопустим. Пустые строки и строки из пробелов считаются отсутствующими.
  • Не передавайте персональные данные: подписи и контекст могут появиться в названиях клипов и файлов.
{ "v": 1, "game": { "id": "com.example.mygame", "name": "My Game", "exe": "MyGame.exe" },
  "type": "hello",
  "offers": ["kill", "death", "bossKill", { "customType": "parry", "customLabel": "Parry" }],
  "log": "%LOCALAPPDATA%\\MyGame\\Saved\\Logs\\MyGame.log" }
  • Позволяет Hovermate создать карточку игры с переключателями до получения первого события.
  • offers перечисляет стандартные типы и/или объекты пользовательских типов.
  • log необязательно предлагает журнал для построчной передачи; files — файлы событий в папке мода (§2.4). Hovermate спрашивает пользователя перед чтением любого предложенного пути.
  • hello принимается любым способом, включая строку журнала [HOVERMATE].

5. Поведение Hovermate

  • Первое корректное событие или hello для нового game.id создаёт карточку игры «SDK». В ней используются название, exe, папка и обложка при совпадении с установленной игрой, переключатели объявленных или полученных типов и настройки времени до и после события. Яркие моменты выключены до выбора типов игроком; маркеры записываются всегда.
  • События проходят тот же конвейер, что и встроенные карточки: журнал, маркеры в клипах и сессиях, окно ярких моментов, уведомления.
  • При совпадении game.exe с обнаруженной активной игрой события относятся к ней. Иначе они принимаются только во время записи или работы буфера и помечаются SDK-игрой.
  • Ограничения:
    • 20 событий/с на игру;
    • 200 пользовательских типов на игру;
    • строки входящих файлов длиннее 4 КБ отбрасываются;
    • некорректные строки учитываются в статусе карточки («N ошибочных событий»), их исходный текст не журналируется.