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 помилкових подій»), їхній початковий текст не журналюється.