HovermateHovermateDocumentazione
Italiano

SDK degli eventi di gioco · Riferimento

Protocollo v1

Il contratto tra i giochi e Hovermate. La pagina è generata da PROTOCOL.md contenuto nell’SDK.

Obiettivo: consentire a qualsiasi gioco o mod di inviare eventi a Hovermate, che crea marcatori e momenti salienti automatici come per le schede integrate. Tre trasporti coprono ambienti con rete, solo file o solo log.

1. Rilevamento della connessione

Engine scrive %LOCALAPPDATA%\Hovermate\Sdk\connection.json quando l’SDK è attivo (Impostazioni › Clip › SDK degli eventi di gioco, attivo per impostazione predefinita):

{
  "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 è l’indirizzo a cui vengono inviati gli eventi. Leggilo da questo file e usalo esattamente come è scritto; non scrivere mai nel codice né modificare host, porta o percorso. Al momento Hovermate scrive http://local.hovermate.gg/hovermate/v1/events; il server di prova dell’SDK scrive un proprio indirizzo di prova.
  • I client leggono il file all’avvio e dopo ogni risposta 401. Il token può cambiare.
  • HOVERMATE_SDK_CONNECTION=<path> sostituisce il percorso per test, strumenti e cartelle isolate. I client prendono sempre il percorso d’ingresso dal campo inbox, senza ricavarlo autonomamente.
  • Se il file manca, Hovermate non è installato o l’SDK è disattivato. I client restano silenziosi e non propagano eccezioni al gioco.

2. Trasporti

2.1 HTTP (mod con rete: C#, C++, Java, Python, JS)

  • POST {url}; intestazioni Authorization: Bearer <token>, Content-Type: application/json.
  • Le richieste con intestazione Origin vengono rifiutate con 403, impedendo l’invio dai browser.
  • Corpo: un oggetto evento o { "events": [ ... ] } con massimo 100 eventi. Dimensione massima: 64 KB.
  • Un lotto viene accettato o rifiutato interamente. Hovermate verifica prima ogni evento. Se uno è errato, non ne accetta nessuno e il corpo 400 indica la posizione: { "error": "<code>", "detail": "...", "index": 3 }. Per un gioco nuovo nella sessione, game.name deve apparire nel primo evento del lotto che lo cita.
  • Risposte:
    • 202 accettato;
    • 400 non valido, con corpo { "error": "<code>", "detail": "...", "index": <n, batches only> };
    • 401 token errato o mancante;
    • 403 la richiesta contiene un’intestazione Origin;
    • 413 corpo troppo grande. Fino a 1 MB viene prima letto e scartato perché il client riceva lo stato; corpi maggiori possono essere rifiutati prima della lettura, chiudendo la connessione;
    • 429 più di 20 eventi/s per gioco;
    • 405, 411, 415 metodo errato, lunghezza assente o tipo di contenuto errato.
  • I client inviano in background senza attendere nel thread del gioco. Usano timeout di massimo 250 ms, una coda limitata che scarta il più vecchio e al massimo un nuovo tentativo.

2.2 Cartella JSONL (mod che scrivono file ma non usano la rete)

  • Aggiungi righe UTF-8 a {inbox}\<game.id>.jsonl, un oggetto evento per riga, senza BOM.
  • Nessun token richiesto: la cartella appartiene all’utente.
  • All’avvio Engine segue ogni file *.jsonl nella cartella d’ingresso partendo dalla fine. La mod può troncare il proprio file all’inizio di una sessione.

2.3 Convenzione delle righe di log (script limitati al log del gioco)

  • Una riga contenente il marcatore [HOVERMATE] seguito da un oggetto evento JSON. Tutto ciò che precede il marcatore, inclusi orari e nomi dei canali, viene ignorato.
  • La scheda SDK ha l’elenco «Leggi eventi da un file», dove l’utente aggiunge il percorso del log. Un evento hello (§4) arrivato da un altro trasporto può proporlo. Engine usa l’adattatore esistente per seguire il log.
  • Hovermate segue automaticamente i log degli script noti mentre il gioco è in esecuzione. L’elenco è nel catalogo giochi (sdkLogs), ad esempio Documents\The Witcher 3\scriptslog.txt e i log Papyrus di Skyrim/Fallout. Per queste mod basta attivare il logging degli script del gioco.

2.4 File eventi nella cartella della mod (sandbox limitate alla propria cartella)

  • Alcuni ambienti, ad esempio le mod Lua di Cyber Engine Tweaks, permettono di scrivere soltanto nella cartella della mod. La mod aggiunge lì righe JSONL (§2.2) a hovermate-events.jsonl.
  • L’utente aggiunge il file a «Leggi eventi da un file» nella scheda SDK. Il README della mod dovrebbe indicarne il percorso. Hovermate lo segue come un file di ingresso.
  • La mod può anche stampare una volta il proprio percorso come riga di log [HOVERMATE], oppure inviarlo in hello.files, un array di percorsi, se è disponibile un altro trasporto. Hovermate propone quindi di aggiungerlo.

3. Oggetto 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 — obbligatorio, 1.
  • game.id — obbligatorio, [a-z0-9._-]{3,64}. Nome DNS inverso o identificatore breve, stabile tra le versioni della mod.
  • game.name — obbligatorio nel primo evento o hello della sessione; massimo 64 caratteri.
  • game.exe — facoltativo, solo nome di file. Collega gli eventi alla cartella del gioco rilevato e consente all’eseguibile di avviare il buffer di replay.
  • type — obbligatorio. Un tipo standard del vocabolario condiviso in 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; oppure "custom". L’elenco in Docs/CLIPS.md è autorevole e può solo crescere. Un tipo sconosciuto viene rifiutato con 400.
  • customType / customLabel — obbligatori quando type è "custom". customType corrisponde a [a-z0-9_.-]{1,32}; customLabel, massimo 40 caratteri, è il nome dell’interruttore nella scheda.
  • label — testo facoltativo per il singolo evento, suggerimento del marcatore e titolo della clip; massimo 80 caratteri.
  • tags — facoltativo, massimo 8 tag, ciascuno conforme a [a-z0-9_-]{1,24}.
  • context — mappa, livello o area facoltativi per i titoli dei momenti salienti; massimo 64 caratteri.
  • time — facoltativo, ISO-8601 UTC. Engine registra l’ora di arrivo; time entro ±5 s la precisa, altrimenti viene ignorato.
  • I campi sconosciuti vengono ignorati; le versioni future aggiungono solo campi.
  • I limiti contano unità UTF-16 come length di JavaScript e string.Length di .NET. I pattern devono coprire l’intero valore: un ritorno a capo finale non è valido. Stringhe vuote o con soli spazi sono considerate assenti.
  • Non inviare dati personali. Etichette e contesti possono apparire nei titoli delle clip e nei nomi dei file.
{ "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" }
  • Consente a Hovermate di creare la scheda del gioco e gli interruttori prima del primo evento reale.
  • offers elenca tipi standard e/o oggetti di tipi personalizzati.
  • log propone facoltativamente un log; files propone file di eventi del mod (§2.4). Hovermate chiede all’utente prima di leggere qualsiasi percorso proposto.
  • hello è accettato da tutti i trasporti, comprese le righe di log [HOVERMATE].

5. Comportamento di Hovermate

  • Il primo evento valido o hello di un nuovo game.id crea una scheda di gioco «SDK». Usa nome, exe, cartella e copertina se corrisponde a un gioco installato, interruttori per i tipi annunciati o ricevuti e impostazioni prima/dopo. I momenti salienti restano spenti finché l’utente non attiva i tipi; i marcatori vengono sempre scritti.
  • Gli eventi attraversano lo stesso flusso delle schede integrate: registro, marcatori nelle clip e sessioni, finestra dei momenti salienti, notifiche.
  • Gli eventi sono attribuiti al gioco rilevato in primo piano quando game.exe corrisponde. Altrimenti sono accettati soltanto con registrazione o buffer attivi e associati al gioco SDK.
  • Limiti:
    • 20 eventi/s per gioco;
    • 200 tipi personalizzati per gioco;
    • le righe d’ingresso oltre 4 KB vengono scartate;
    • le righe errate sono contate nello stato della scheda («N eventi non validi»), mai registrate come testo grezzo.