Envía eventos de juego a Hovermate

Cómo funciona

1. Tu mod notifica un momento. Basta una llamada, como event("bossKill"). El cliente lo envía en segundo plano sin bloquear el juego.
2. Hovermate lo marca. Cada evento se convierte en un marcador de la grabación y la sesión con tu etiqueta.
3. El jugador elige los momentos destacados. Tu juego obtiene su propia ficha en Clips. Para cada tipo activado por el jugador también se guarda un clip.

Mientras el SDK está activo, Hovermate publica su dirección, un token y su carpeta de entrada en connection.json:

{
  "version": 1,
  "url": "http://local.hovermate.gg/hovermate/v1/events",
  "token": "<random, base64url, 32 bytes>",
  "inbox": "C:\\Users\\<user>\\AppData\\Local\\Hovermate\\Sdk\\Inbox"
}

Lee url de este archivo y úsalo exactamente como está escrito; nunca fijes en el código ni cambies su host, puerto o ruta.

Los clientes leen %LOCALAPPDATA%\Hovermate\Sdk\connection.json, o la ruta de HOVERMATE_SDK_CONNECTION para pruebas y configuraciones aisladas. Vuelven a leerlo tras una respuesta 401, porque el token cambia al desactivar y activar el SDK. Si el archivo no existe, Hovermate no está instalado o el SDK está desactivado; los clientes permanecen en silencio.

Tres formas de enviar eventos

Usa la primera que permita el entorno de tu mod.

POST /hovermate/v1/events HTTP/1.1
Host: local.hovermate.gg
Authorization: Bearer <token from connection.json>
Content-Type: application/json
Content-Length: 95

{"v":1,"game":{"id":"com.example.mygame","name":"My Game"},"type":"kill","label":"Double kill"}

[12:00:01] [Script] [HOVERMATE] {"v":1,"game":{"id":"com.example.mygame","name":"My Game"},"type":"bossKill","context":"Act 2"}

Inicio rápido

Cada ejemplo envía hello, kill, bossKill y un evento personalizado parry. Son los archivos ejecutables de la carpeta examples del SDK.

// Sends hello, kill, bossKill and a custom "parry" event to Hovermate (or to tools/mock-server.py).
// Run: dotnet run
using System;
using Hovermate.Sdk;

HovermateEvents.Log = Console.WriteLine;
HovermateEvents.Init("com.example.sdkdemo", "SDK Demo", "SdkDemo.exe");
HovermateEvents.Hello(new HovermateOffer[] { "kill", "bossKill", HovermateOffer.Custom("parry", "Parry") });
HovermateEvents.Event("kill", label: "Double kill", tags: new[] { "headshot" }, context: "Act 2");
HovermateEvents.Event("bossKill", label: "The Warden", context: "Act 2");
HovermateEvents.Custom("parry", "Parry", label: "Perfect parry");
Console.WriteLine(HovermateEvents.Flush(2000) ? "sent" : "timed out");
HovermateEvents.Shutdown();

dotnet run

// Sends hello, kill, bossKill and a custom "parry" event to Hovermate (or to tools/mock-server.py).
// Build (Developer Command Prompt): cl /std:c++17 /EHsc /utf-8 /I..\..\cpp example.cpp
#include <cstdio>
#include "hovermate_events.h"

int main() {
    hovermate::set_log([](const std::string& message) { std::printf("%s\n", message.c_str()); });
    hovermate::init("com.example.sdkdemo", "SDK Demo", "SdkDemo.exe");
    hovermate::hello({ "kill", "bossKill", hovermate::Offer::custom("parry", "Parry") });
    hovermate::event("kill", { "Double kill", { "headshot" }, "Act 2" });
    hovermate::event("bossKill", { "The Warden", {}, "Act 2" });
    hovermate::custom("parry", "Parry", { "Perfect parry", {}, {} });
    std::printf("%s\n", hovermate::flush(2000) ? "sent" : "timed out");
    hovermate::shutdown();
    return 0;
}

cl /std:c++17 /EHsc /utf-8 /I..\..\cpp example.cpp

// Sends hello, kill, bossKill and a custom "parry" event to Hovermate (or to tools/mock-server.py).
// Run (Java 8+): javac -d out ../../java/HovermateEvents.java Example.java && java -cp out Example
import gg.hovermate.sdk.HovermateEvents;
import gg.hovermate.sdk.HovermateEvents.Offer;
import java.util.Arrays;

public class Example {
    public static void main(String[] args) {
        HovermateEvents.log = System.out::println;
        HovermateEvents.init("com.example.sdkdemo", "SDK Demo", "SdkDemo.exe");
        HovermateEvents.hello(Offer.of("kill"), Offer.of("bossKill"), Offer.custom("parry", "Parry"));
        HovermateEvents.event("kill", "Double kill", Arrays.asList("headshot"), "Act 2");
        HovermateEvents.event("bossKill", "The Warden", null, "Act 2");
        HovermateEvents.custom("parry", "Parry", "Perfect parry", null, null);
        System.out.println(HovermateEvents.flush(2000) ? "sent" : "timed out");
        HovermateEvents.shutdown(1000);
    }
}

javac -d out ../../java/HovermateEvents.java Example.java && java -cp out Example

"""Sends hello, kill, bossKill and a custom "parry" event to Hovermate (or to tools/mock-server.py).

Run from any folder: python example.py
"""
import os
import sys

sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', '..', 'python'))
import hovermate_events as hovermate  # noqa: E402

hovermate.set_log(print)
hovermate.init('com.example.sdkdemo', 'SDK Demo', 'SdkDemo.exe')
hovermate.hello(['kill', 'bossKill', hovermate.custom_offer('parry', 'Parry')])
hovermate.event('kill', label='Double kill', tags=['headshot'], context='Act 2')
hovermate.event('bossKill', label='The Warden', context='Act 2')
hovermate.custom('parry', 'Parry', label='Perfect parry')
print('sent' if hovermate.flush(2.0) else 'timed out')
hovermate.shutdown()

python example.py

// Sends hello, kill, bossKill and a custom "parry" event to Hovermate (or to tools/mock-server.py).
// Run with Node.js 18+: node example.mjs
import * as hovermate from '../../js/hovermate-events.mjs';

hovermate.setLog(console.log);
hovermate.init('com.example.sdkdemo', 'SDK Demo', 'SdkDemo.exe');
hovermate.hello(['kill', 'bossKill', hovermate.customOffer('parry', 'Parry')]);
hovermate.event('kill', { label: 'Double kill', tags: ['headshot'], context: 'Act 2' });
hovermate.event('bossKill', { label: 'The Warden', context: 'Act 2' });
hovermate.custom('parry', 'Parry', { label: 'Perfect parry' });
console.log((await hovermate.flush(2000)) ? 'sent' : 'timed out');
await hovermate.shutdown();

node example.mjs

-- Sends hello, kill, bossKill and a custom "parry" event to Hovermate (or to tools/mock-server.py --watch).
-- Run from the folder that stands in for your mod folder: lua path/to/example.lua
-- It writes hovermate-events.jsonl into the current folder.
--
-- In a Cyber Engine Tweaks mod, copy hovermate_events.lua next to init.lua and call it from your events:
--   local hovermate = require("hovermate_events")
--   registerForEvent("onInit", function()
--     hovermate.init("com.example.mymod", "My Mod", "Cyberpunk2077.exe", { log = print })
--     hovermate.hello({ "kill", "bossKill", hovermate.customOffer("parry", "Parry") })
--   end)
-- Then tell your users to add <game>\bin\x64\plugins\cyber_engine_tweaks\mods\<your mod>\hovermate-events.jsonl
-- in Hovermate: Clips > the game's card > Read events from a file.

local here = (arg and arg[0] or ''):match('^(.*[\\/])') or './'
package.path = here .. '../../lua/?.lua;' .. package.path
local hovermate = require('hovermate_events')

hovermate.init('com.example.sdkdemo', 'SDK Demo', 'SdkDemo.exe', { log = print, writer = print })
print('transport', hovermate.transport())
hovermate.hello({ 'kill', 'bossKill', hovermate.customOffer('parry', 'Parry') })
hovermate.event('kill', { label = 'Double kill', tags = { 'headshot' }, context = 'Act 2' })
hovermate.event('bossKill', { label = 'The Warden', context = 'Act 2' })
hovermate.custom('parry', 'Parry', { label = 'Perfect parry' })
print('log line for script-only mods:', hovermate.logLine('kill', { label = 'Double kill' }))
hovermate.shutdown()

lua example.lua

Comportamiento de los clientes

• Las llamadas regresan al instante y nunca propagan excepciones al juego.
• Un proceso en segundo plano envía eventos con un tiempo de espera de 250 ms y reintenta una vez las solicitudes fallidas.
• La cola admite 256 eventos y descarta el más antiguo.
• Si HTTP no está disponible, los eventos se envían a la carpeta de entrada durante unos segundos.
• Sin connection.json, el cliente permanece en silencio y comprueba de nuevo cada 5 segundos.
• Cada evento incluye game.name. El texto se recorta a los límites indicados abajo y las etiquetas no válidas se descartan sin provocar un fallo.

El cliente Lua (hovermate_events.lua) escribe cada evento al instante. Prefiere hovermate-events.jsonl en la carpeta del mod, después la carpeta de entrada si se permiten rutas absolutas y, por último, líneas [HOVERMATE] mediante una función writer que proporcionas, como print. logLine(type, options) devuelve una de esas líneas para que la imprimas.

El 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" }

Las longitudes cuentan unidades UTF-16: un emoji ocupa 2. Los campos de texto rechazan caracteres de control. Los campos desconocidos se ignoran y las nuevas versiones solo añaden campos. No envíes datos personales: las etiquetas y el contexto pueden aparecer en títulos de clips y nombres de archivos.

Tipos estándar

29 tipos compartidos con las fichas integradas de Hovermate. La lista solo crece; los tipos estándar desconocidos se rechazan.

• kill
• death
• assist
• multikill
• roundWon
• roundLost
• matchWon
• matchLost
• mvp
• goal
• save
• objective
• mission
• lap
• bestLap
• position
• crash
• incident
• penalty
• pit
• finish
• raceWon
• landing
• takeoff
• fightWon
• levelUp
• bossKill
• zone
• achievement

Tipos personalizados

Para momentos fuera de la lista estándar. Cada tipo tiene su propio interruptor, cuyo nombre indica customLabel; hasta 200 por juego.

{ "v": 1, "game": { "id": "com.example.mygame" },
  "type": "custom", "customType": "parry", "customLabel": "Parry", "label": "Perfect parry" }

hello

Opcional y recomendado. Crea la ficha del juego y sus interruptores antes del primer evento real para que el jugador pueda configurarla de antemano.

{ "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",
  "files": ["C:\\Games\\MyGame\\mods\\my_mod\\hovermate-events.jsonl"] }

• offers enumera tipos estándar y objetos { "customType", "customLabel" }.
• log propone un registro con líneas [HOVERMATE]; files propone archivos de eventos del mod. Hovermate pide permiso al jugador antes de leer cualquier ruta propuesta.
• hello funciona con cualquier transporte, incluida una línea de registro [HOVERMATE].

Límites y respuestas

Códigos de error: invalid_json, version, game, type, custom, label, tags, context, offers, log, files, batch. Las líneas incorrectas de los archivos se cuentan y aparecen como eventos no válidos en la ficha del juego; Hovermate nunca registra su contenido original.

Prueba sin Hovermate

El receptor de prueba mock-server.py (Python 3.8+, biblioteca estándar) responde exactamente como Hovermate. Crea su propio connection.json en una carpeta temporal, aplica las mismas reglas y códigos de error, sigue la carpeta de entrada y los archivos de --watch, e imprime cada evento y error.

A diferencia de Hovermate, el receptor de prueba escucha en un puerto numérico de loopback y escribe esa dirección en su connection.json. Es solo una herramienta de prueba: los clientes usan la url que contenga el archivo.

python tools/mock-server.py
# In another terminal, with the path it printed:
$env:HOVERMATE_SDK_CONNECTION = "C:\Users\you\AppData\Local\Temp\hovermate-sdk-mock-…\connection.json"
python examples/python/example.py

Hovermate SDK mock listening on http://127.0.0.1:52777/hovermate/v1/events
[21:15:03.120] http  com.example.sdkdemo hello offers=kill,bossKill,custom:parry
[21:15:03.131] http  com.example.sdkdemo kill "Double kill" tags=headshot context="Act 2"
[21:15:03.140] http  com.example.sdkdemo bossKill "The Warden" context="Act 2"
[21:15:03.148] http  com.example.sdkdemo custom:parry "Parry" "Perfect parry"

• --watch FILE sigue un archivo del mod hovermate-events.jsonl o un registro del juego con líneas [HOVERMATE].
• --follow-proposals lee las rutas propuestas por hello, como si el jugador las hubiera autorizado.
• --record FILE añade cada evento aceptado o rechazado como línea JSON para comprobaciones automáticas.

HOVERMATE_SDK_CONNECTION funciona igual con Hovermate, por lo que las pruebas nunca tocan el archivo de conexión real.

Casos de conformidad

El SDK incluye conformance/cases.json: solicitudes con las respuestas esperadas de Hovermate, desde eventos válidos hasta cada código de error. conformance/run.py las envía al receptor de prueba o a cualquier otro. Hovermate usa ese mismo archivo en sus propias pruebas.

python conformance/run.py
# or against a running receiver:
python conformance/run.py --connection path\to\connection.json

Qué ve el jugador

• El primer evento válido o hello de un nuevo game.id crea una ficha SDK en Clips con el nombre, la carpeta y la portada si exe coincide con un juego instalado, y un interruptor por cada tipo anunciado o recibido.
• Los interruptores de momentos destacados empiezan desactivados: el jugador elige qué tipos guardan clips. Los marcadores siempre se escriben.
• Los eventos siguen el mismo recorrido que las fichas integradas: diario, marcadores de clips y sesiones, ventana de momentos destacados y notificaciones.
• Si game.exe coincide con el juego en primer plano, los eventos se atribuyen a ese juego. Si no, solo se aceptan durante una grabación o con el búfer de repetición activo.
• Los eventos no válidos se cuentan en el estado de la ficha para que los jugadores puedan informar de problemas.

Protocolo y archivos

El protocolo v1 es el contrato completo: detección de conexión, cuatro formas de entrega, objeto de evento, hello y comportamiento de Hovermate.

El SDK —clientes, ejemplos, herramientas, casos de conformidad y protocolo— tiene licencia MIT, así que puedes incluir un cliente en tu mod. Hovermate en sí no está cubierto por esa licencia.