HovermateHovermateDocumentación
Español

SDK de eventos de juego · Referencia

Protocolo v1

El contrato entre los juegos y Hovermate. La página se genera a partir de PROTOCOL.md, incluido en la descarga del SDK.

Objetivo: cualquier juego o mod puede enviar eventos a Hovermate, que los convierte en marcadores y momentos destacados automáticos como las fichas integradas. Tres transportes cubren entornos con red, solo archivos o solo registro.

1. Detección de conexión

Engine escribe %LOCALAPPDATA%\Hovermate\Sdk\connection.json cuando el SDK está activo (Ajustes › Clips › SDK de eventos de juego, activo por defecto):

{
  "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 es adonde se envían los eventos. Léelo de este archivo y úsalo exactamente como está escrito; nunca fijes en el código ni cambies el host, el puerto o la ruta. Hovermate escribe actualmente http://local.hovermate.gg/hovermate/v1/events; el servidor de prueba del SDK escribe su propia dirección de prueba.
  • Los clientes leen el archivo al iniciar y después de cada respuesta 401. El token puede cambiar.
  • HOVERMATE_SDK_CONNECTION=<path> sustituye la ubicación para pruebas, herramientas y carpetas aisladas. Los clientes toman siempre la carpeta de entrada del campo inbox, sin deducirla por su cuenta.
  • Si el archivo no existe, Hovermate no está instalado o el SDK está desactivado. Los clientes permanecen en silencio y no propagan excepciones al juego.

2. Transportes

2.1 HTTP (mods con red: C#, C++, Java, Python, JS)

  • POST {url}; cabeceras Authorization: Bearer <token>, Content-Type: application/json.
  • Las solicitudes con cabecera Origin se rechazan con 403, impidiendo el envío desde navegadores.
  • Cuerpo: un objeto de evento o { "events": [ ... ] } con hasta 100 eventos. Tamaño máximo: 64 KB.
  • Un lote se acepta o rechaza entero. Hovermate valida todos los eventos primero. Si uno falla, no se acepta ninguno y el cuerpo 400 indica su posición: { "error": "<code>", "detail": "...", "index": 3 }. Para un juego nuevo en la sesión, game.name debe aparecer en el primer evento del lote que lo mencione.
  • Respuestas:
    • 202 aceptado;
    • 400 no válido, con cuerpo { "error": "<code>", "detail": "...", "index": <n, batches only> };
    • 401 token incorrecto o ausente;
    • 403 la solicitud contiene una cabecera Origin;
    • 413 cuerpo demasiado grande. Primero se lee y descarta hasta 1 MB para que el cliente vea el estado; los cuerpos mayores pueden rechazarse antes de leerlos y se cierra la conexión;
    • 429 más de 20 eventos/s por juego;
    • 405, 411, 415 método incorrecto, longitud ausente o tipo de contenido incorrecto.
  • Los clientes envían en segundo plano sin esperar en el hilo del juego. Usan un tiempo máximo de 250 ms, una cola limitada que descarta el más antiguo y como máximo un reintento.

2.2 Entrada JSONL (mods con escritura de archivos pero sin red)

  • Añade líneas UTF-8 a {inbox}\<game.id>.jsonl, un objeto de evento por línea, sin BOM.
  • No hace falta token: la carpeta pertenece al usuario.
  • Al iniciar, Engine sigue cada archivo *.jsonl de la carpeta de entrada desde su final. El mod puede truncar su archivo al empezar una sesión.

2.3 Convención de líneas de registro (scripts limitados al registro del juego)

  • Una línea con el marcador [HOVERMATE] seguido de un objeto de evento JSON. Se ignora todo lo anterior, incluidas marcas de tiempo y nombres de canales.
  • La ficha SDK tiene la lista «Leer eventos de un archivo», donde el usuario añade la ruta del registro. Un evento hello (§4) recibido por otro transporte también puede proponerla. Engine lee el archivo con el adaptador de seguimiento de registros existente.
  • Hovermate sigue automáticamente los registros de scripts conocidos mientras el juego está abierto. La lista está en el catálogo de juegos (sdkLogs), como Documents\The Witcher 3\scriptslog.txt y los registros Papyrus de Skyrim/Fallout. En esos mods solo hay que activar el registro de scripts del juego.

2.4 Archivo de eventos en la carpeta del mod (sandboxes limitadas a su propia carpeta)

  • Algunos entornos, como los mods Lua de Cyber Engine Tweaks, solo permiten escribir en la carpeta del mod. La mod añade allí líneas JSONL (§2.2) a hovermate-events.jsonl.
  • El usuario añade el archivo a «Leer eventos de un archivo» en la ficha SDK. El README del mod debe indicar su ruta. Hovermate lo sigue como un archivo de entrada.
  • El mod también puede imprimir una vez su ruta como línea de registro [HOVERMATE], o enviarla en hello.files, un array de rutas, mediante otro transporte. Hovermate propone entonces añadirla.

3. Objeto de evento

{
  "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 — obligatorio, 1.
  • game.id — obligatorio, [a-z0-9._-]{3,64}. DNS inverso o identificador corto, estable entre versiones del mod.
  • game.name — obligatorio en el primer evento o hello de la sesión; máximo 64 caracteres.
  • game.exe — opcional, solo un nombre de archivo. Vincula los eventos a la carpeta detectada y permite al ejecutable iniciar el búfer de repetición.
  • type — obligatorio. Un tipo estándar del vocabulario compartido en 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; o "custom". La lista de Docs/CLIPS.md es la referencia y solo crece. Un tipo desconocido se rechaza con 400.
  • customType / customLabel — obligatorios cuando type es "custom". customType coincide con [a-z0-9_.-]{1,32}; customLabel es el nombre del interruptor de la ficha, de hasta 40 caracteres.
  • label — texto opcional de este evento para la ayuda del marcador y el título del clip; máximo 80 caracteres.
  • tags — opcional, hasta 8 etiquetas, cada una conforme a [a-z0-9_-]{1,24}.
  • context — mapa, nivel o zona opcional para los títulos de momentos destacados; máximo 64 caracteres.
  • time — opcional, ISO-8601 UTC. Engine registra la llegada; time dentro de ±5 s la precisa; el resto se ignora.
  • Los campos desconocidos se ignoran; las versiones futuras solo añaden campos.
  • Los límites cuentan unidades UTF-16, como length de JavaScript y string.Length de .NET. Los patrones deben coincidir con todo el valor: un salto de línea final no es válido. Las cadenas vacías o solo con espacios se consideran ausentes.
  • No envíes datos personales. Las etiquetas y el contexto pueden aparecer en títulos de clips y nombres de archivos.
{ "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" }
  • Permite a Hovermate crear la ficha del juego y sus interruptores antes del primer evento real.
  • offers enumera tipos estándar y/u objetos de tipos personalizados.
  • log propone opcionalmente un registro; files propone archivos del mod (§2.4). Hovermate pide permiso al usuario antes de leer cualquier ruta propuesta.
  • hello se acepta por cualquier transporte, incluida una línea de registro [HOVERMATE].

5. Comportamiento de Hovermate

  • El primer evento válido o hello de un nuevo game.id crea una ficha «SDK». Usa nombre, exe, carpeta y portada si coincide con un juego instalado, un interruptor por tipo anunciado o visto y ajustes antes/después. Los momentos destacados quedan desactivados hasta que el usuario activa tipos; los marcadores siempre se escriben.
  • Los eventos siguen el mismo flujo que las fichas integradas: diario, marcadores de clips y sesiones, ventana de momentos destacados y notificaciones.
  • Los eventos se atribuyen al juego detectado en primer plano cuando game.exe coincide. En caso contrario solo se aceptan mientras una grabación o el búfer están activos y se etiquetan con el juego SDK.
  • Límites:
    • 20 eventos/s por juego;
    • 200 tipos personalizados por juego;
    • las líneas de entrada de más de 4 KB se descartan;
    • las líneas incorrectas se cuentan en el estado de la ficha («N eventos no válidos»), sin registrar nunca su contenido original.