HovermateHovermateDokumentation
Deutsch

Spielereignis-SDK · Referenz

Protokoll v1

Der Vertrag zwischen Spielen und Hovermate. Diese Seite wird aus PROTOCOL.md im SDK-Download erzeugt.

Ziel: Jedes Spiel oder Mod kann Spielereignisse an Hovermate senden. Wie bei integrierten Spielkarten werden daraus Zeitleistenmarkierungen und automatische Highlights. Drei Transportarten decken Netzwerk-, reine Datei- und reine Protokollumgebungen ab.

1. Verbindungserkennung

Engine schreibt %LOCALAPPDATA%\Hovermate\Sdk\connection.json, solange das SDK aktiviert ist (Einstellungen › Clips › Spielereignis-SDK, standardmäßig an):

{
  "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 ist das Ziel der Ereignisse. Lesen Sie es aus dieser Datei und verwenden Sie es genau so, wie es dort steht; Host, Port oder Pfad nie fest einprogrammieren oder ändern. Hovermate schreibt derzeit http://local.hovermate.gg/hovermate/v1/events; der Testserver des SDK schreibt seine eigene Testadresse.
  • Clients lesen die Datei beim Start und nach jeder 401-Antwort erneut. Das Token kann wechseln.
  • HOVERMATE_SDK_CONNECTION=<path> überschreibt den Speicherort für Tests, Werkzeuge und isolierte Datenordner. Clients nehmen den Eingangsordner immer aus dem Feld inbox und leiten ihn niemals selbst ab.
  • Fehlt die Datei, ist Hovermate nicht installiert oder das SDK aus. Clients bleiben still und geben niemals Ausnahmen an das Spiel weiter.

2. Übertragungswege

2.1 HTTP (Mods mit Netzwerk: C#, C++, Java, Python, JS)

  • POST {url}; Header Authorization: Bearer <token>, Content-Type: application/json.
  • Anfragen mit einem Origin-Header werden mit 403 abgewiesen, damit Browser keine Ereignisse senden können.
  • Inhalt: ein Ereignisobjekt oder { "events": [ ... ] } mit höchstens 100 Ereignissen. Maximale Größe: 64 KB.
  • Ein Stapel gilt ganz oder gar nicht. Hovermate prüft alle Ereignisse zuerst. Ist eines ungültig, wird keines angenommen, und die 400-Antwort nennt die Position: { "error": "<code>", "detail": "...", "index": 3 }. Für ein neues Spiel dieser Sitzung muss game.name im ersten Ereignis stehen, das es im Stapel erwähnt.
  • Antworten:
    • 202 akzeptiert;
    • 400 ungültig, mit Antwortinhalt { "error": "<code>", "detail": "...", "index": <n, batches only> };
    • 401 Token falsch oder fehlend;
    • 403 Anfrage enthält einen Origin-Header;
    • 413 Inhalt zu groß. Bis zu 1 MB wird zunächst gelesen und verworfen, damit der Client den Status erhält; größere Inhalte können vor dem Lesen mit Schließen der Verbindung abgewiesen werden;
    • 429 mehr als 20 Ereignisse/s pro Spiel;
    • 405, 411, 415 falsche Methode, fehlende Länge oder falscher Inhaltstyp.
  • Clients senden ohne Warten aus einem Hintergrundprozess. Sie blockieren nie den Spielthread, nutzen höchstens 250 ms Zeitlimit, eine begrenzte Warteschlange mit Entfernen des ältesten Eintrags und maximal eine Wiederholung.

2.2 JSONL-Eingang (Mods mit Dateizugriff ohne Netzwerk)

  • Hänge UTF-8-Zeilen an {inbox}\<game.id>.jsonl an, ein Ereignisobjekt pro Zeile, ohne BOM.
  • Kein Token nötig: Der Ordner gehört dem Benutzer.
  • Engine verfolgt beim Start jede *.jsonl-Datei im Eingangsordner ab deren Ende. Ein Mod darf seine Datei am Sitzungsbeginn leeren.

2.3 Protokollzeilen-Konvention (Skriptmods mit ausschließlich Spielprotokollzugriff)

  • Eine Zeile mit der Markierung [HOVERMATE] , gefolgt von genau einem JSON-Ereignisobjekt. Alles davor, etwa Zeitstempel und Kanalnamen, wird ignoriert.
  • In der SDK-Karte fügt der Benutzer im Bereich „Ereignisse aus Datei lesen“ einen Protokollpfad hinzu. Ein über einen anderen Transport empfangenes hello (§4) kann ebenfalls einen vorschlagen. Engine liest mit dem vorhandenen Protokolladapter.
  • Hovermate verfolgt bekannte Skriptprotokolle automatisch während des Spiels. Die Liste steht im Spielkatalog (sdkLogs), etwa Documents\The Witcher 3\scriptslog.txt und die Papyrus-Protokolle von Skyrim/Fallout. Bei diesen Mods muss der Benutzer nur die Skriptprotokollierung des Spiels aktivieren.

2.4 Ereignisdatei im Mod-Ordner (Sandboxes mit Zugriff nur auf den eigenen Ordner)

  • Manche Mod-Umgebungen wie Cyber Engine Tweaks Lua erlauben Schreiben nur im Mod-Ordner. Der Mod hängt dort JSONL-Zeilen (§2.2) an hovermate-events.jsonl an.
  • Der Benutzer fügt diese Datei unter „Ereignisse aus Datei lesen“ in der SDK-Karte hinzu. Die Mod-README sollte den Pfad nennen. Hovermate verfolgt sie wie eine Eingangsdatei.
  • Ein Mod kann seinen Pfad auch einmal als [HOVERMATE]-Protokollzeile ausgeben oder über einen anderen verfügbaren Transport in hello.files, einer Pfadliste, senden. Hovermate bietet dann das Hinzufügen an.

3. Ereignisobjekt

{
  "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 — erforderlich, 1.
  • game.id — erforderlich, [a-z0-9._-]{3,64}. Umgekehrter DNS-Name oder Kurzkennung, zwischen Mod-Versionen stabil.
  • game.name — im ersten Ereignis oder hello pro Sitzung erforderlich; höchstens 64 Zeichen.
  • game.exe — optional, nur ein Dateiname. Verknüpft Ereignisse mit dem erkannten Spielordner und lässt diese Anwendung den Replay-Puffer starten.
  • type — erforderlich. Ein Standardtyp aus dem gemeinsamen Vokabular 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; oder "custom". Die Liste in Docs/CLIPS.md ist maßgeblich und wächst nur. Unbekannte Standardtypen werden mit 400 abgewiesen.
  • customType / customLabel — erforderlich, wenn type gleich "custom" ist. customType entspricht [a-z0-9_.-]{1,32}; customLabel ist der in der Karte angezeigte Schaltername mit höchstens 40 Zeichen.
  • label — optionaler Text dieses Ereignisses für Markierungsinfo und Clip-Titel; höchstens 80 Zeichen.
  • tags — optional, bis zu 8 Tags, jeweils passend zu [a-z0-9_-]{1,24}.
  • context — optionale Karte, Level oder Bereich für Highlight-Titel; höchstens 64 Zeichen.
  • time — optional, ISO-8601 UTC. Engine erfasst die Ankunftszeit. time innerhalb von ±5 s präzisiert sie; andere Werte werden ignoriert.
  • Unbekannte Felder werden ignoriert; zukünftige Versionen ergänzen nur Felder.
  • Zeichengrenzen zählen UTF-16-Codeeinheiten wie JavaScript-length und .NET-string.Length. Muster müssen den ganzen Wert abdecken; ein abschließender Zeilenumbruch ist ungültig. Leere oder nur aus Leerraum bestehende Zeichenfolgen gelten als fehlend.
  • Sende keine personenbezogenen Daten. Beschriftungen und Kontexte können in Clip-Titeln und Dateinamen erscheinen.
{ "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" }
  • Ermöglicht Hovermate, die Spielkarte samt Highlight-Schaltern vor dem ersten echten Ereignis zu erstellen.
  • offers enthält Standardtypen und/oder Objekte eigener Typen.
  • log schlägt optional ein Protokoll vor; files optional Ereignisdateien im Mod-Ordner (§2.4). Hovermate fragt den Benutzer vor dem Lesen jedes vorgeschlagenen Pfads.
  • hello wird über jeden Transport akzeptiert, auch als [HOVERMATE]-Protokollzeile.

5. Hovermate-Verhalten

  • Das erste gültige Ereignis oder hello einer neuen game.id erstellt eine SDK-Spielkarte. Sie nutzt Name, exe, Spielordner und Cover bei passendem installierten Spiel, Schalter pro angekündigtem oder gesehenem Typ und Vorher/Nachher-Einstellungen. Highlights bleiben aus, bis der Benutzer Typen aktiviert; Markierungen werden immer geschrieben.
  • Ereignisse durchlaufen dieselbe Pipeline wie integrierte Karten: Journal, Markierungen in Clips und Sitzungen, Highlight-Fenster, Benachrichtigungen.
  • Ereignisse werden dem erkannten Vordergrundspiel zugeordnet, wenn game.exe dazu passt. Andernfalls werden sie nur während Aufnahme oder Pufferbetrieb angenommen und mit dem SDK-Spiel versehen.
  • Grenzen:
    • 20 Ereignisse/s pro Spiel;
    • 200 eigene Typen pro Spiel;
    • Eingangszeilen über 4 KB werden verworfen;
    • fehlerhafte Zeilen werden im Kartenstatus als „N ungültige Ereignisse“ gezählt, niemals im Rohformat protokolliert.