HovermateHovermateDocumentation
Français

SDK d’événements de jeu · Référence

Protocole v1

Le contrat entre les jeux et Hovermate. Cette page est générée depuis PROTOCOL.md, fourni dans le SDK.

Objectif : permettre à tout jeu ou mod d’envoyer des événements à Hovermate, qui les transforme en marqueurs et moments forts automatiques comme les fiches intégrées. Trois transports couvrent les environnements réseau, fichiers seuls et journal seul.

1. Découverte de la connexion

Quand le SDK est activé, Engine écrit %LOCALAPPDATA%\Hovermate\Sdk\connection.json (Paramètres › Clips › SDK d’événements de jeu, activé par défaut) :

{
  "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 est l’adresse où les événements sont envoyés. Lisez-la dans ce fichier et utilisez-la exactement telle qu’elle est écrite ; ne codez jamais en dur et ne modifiez jamais l’hôte, le port ou le chemin. Hovermate écrit actuellement http://local.hovermate.gg/hovermate/v1/events ; le serveur de test du SDK écrit sa propre adresse de test.
  • Les clients lisent ce fichier au démarrage puis après chaque réponse 401. Le jeton peut changer.
  • HOVERMATE_SDK_CONNECTION=<path> remplace l’emplacement du fichier pour les tests, outils et dossiers isolés. Les clients prennent toujours le dossier d’entrée dans le champ inbox, sans le déduire eux-mêmes.
  • Si le fichier manque, Hovermate n’est pas installé ou le SDK est désactivé. Les clients restent silencieux et ne transmettent jamais d’exception au jeu.

2. Transports

2.1 HTTP (mods avec réseau : C#, C++, Java, Python, JS)

  • POST {url} ; en-têtes Authorization: Bearer <token>, Content-Type: application/json.
  • Les requêtes contenant un en-tête Origin sont refusées avec 403, empêchant l’envoi par les navigateurs.
  • Corps : un objet événement ou { "events": [ ... ] } contenant au plus 100 événements. Taille maximale : 64 Ko.
  • Un lot est accepté ou refusé en entier. Hovermate valide d’abord tous les événements. Si l’un est invalide, aucun n’est accepté et le corps 400 donne sa position : { "error": "<code>", "detail": "...", "index": 3 }. Pour un nouveau jeu de la session, game.name doit figurer dans le premier événement du lot qui le mentionne.
  • Réponses :
    • 202 accepté ;
    • 400 invalide, avec le corps { "error": "<code>", "detail": "...", "index": <n, batches only> } ;
    • 401 jeton incorrect ou manquant ;
    • 403 la requête contient un en-tête Origin ;
    • 413 corps trop grand. Jusqu’à 1 Mo est d’abord lu et ignoré pour que le client reçoive le statut ; un corps plus grand peut être refusé avant lecture, avec fermeture de la connexion ;
    • 429 plus de 20 événements/s par jeu ;
    • 405, 411, 415 méthode incorrecte, longueur absente ou type de contenu incorrect.
  • Les clients envoient sans attendre depuis un traitement en arrière-plan. Ils ne bloquent jamais le fil du jeu, utilisent un délai maximal de 250 ms, une file bornée supprimant le plus ancien et au plus une nouvelle tentative.

2.2 Réception JSONL (mods pouvant écrire des fichiers, sans réseau)

  • Ajoutez des lignes UTF-8 à {inbox}\<game.id>.jsonl : un objet événement par ligne, sans BOM.
  • Aucun jeton nécessaire : le dossier appartient à l’utilisateur.
  • Au démarrage, Engine suit chaque fichier *.jsonl du dossier d’entrée à partir de sa fin. Le mod peut tronquer son fichier au début d’une session.

2.3 Convention de journal (scripts limités au journal du jeu)

  • Toute ligne contenant le marqueur [HOVERMATE] , puis un objet événement JSON. Tout ce qui précède le marqueur, horodatages et noms de canaux compris, est ignoré.
  • La fiche SDK contient la liste « Lire les événements depuis un fichier », où l’utilisateur ajoute le chemin du journal. Un événement hello (§4) reçu par un autre transport peut aussi le proposer. Engine utilise l’adaptateur de suivi des journaux existant.
  • Hovermate suit automatiquement les journaux de scripts connus pendant le jeu. La liste est dans le catalogue des jeux (sdkLogs), par exemple Documents\The Witcher 3\scriptslog.txt et les journaux Papyrus de Skyrim/Fallout. Ces mods demandent seulement d’activer les journaux de scripts du jeu.

2.4 Fichier d’événements du mod (sandboxes limitées au dossier du mod)

  • Certains environnements, dont les mods Lua Cyber Engine Tweaks, n’autorisent l’écriture que dans le dossier du mod. Le mod y ajoute des lignes JSONL (§2.2) dans hovermate-events.jsonl.
  • L’utilisateur ajoute ce fichier à « Lire les événements depuis un fichier » dans la fiche SDK. Le README du mod doit indiquer son emplacement. Hovermate le suit comme un fichier de réception.
  • Le mod peut aussi afficher une fois son chemin dans une ligne de journal [HOVERMATE], ou l’envoyer dans hello.files, un tableau de chemins, via un autre transport. Hovermate propose alors de l’ajouter.

3. Objet événement

{
  "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 — obligatoire, 1.
  • game.id — obligatoire, [a-z0-9._-]{3,64}. Nom DNS inversé ou identifiant court, stable entre les versions du mod.
  • game.name — obligatoire dans le premier événement ou hello de la session ; 64 caractères maximum.
  • game.exe — facultatif, nom de fichier uniquement. Lie les événements au dossier du jeu détecté et permet à cet exécutable de démarrer le tampon de replay.
  • type — obligatoire. Un type standard du vocabulaire partagé dans 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 ; ou "custom". La liste de Docs/CLIPS.md fait autorité et s’allonge seulement. Un type standard inconnu est refusé avec 400.
  • customType / customLabel — obligatoires quand type vaut "custom". customType correspond à [a-z0-9_.-]{1,32} ; customLabel, limité à 40 caractères, est le nom de l’option dans la fiche.
  • label — texte facultatif de cet événement, pour l’infobulle du marqueur et le titre du clip ; 80 caractères maximum.
  • tags — facultatif, jusqu’à 8 tags correspondant chacun à [a-z0-9_-]{1,24}.
  • context — carte, niveau ou zone facultatifs pour les titres des moments forts ; 64 caractères maximum.
  • time — facultatif, ISO-8601 UTC. Engine date la réception ; time à ±5 s l’affine, toute autre valeur est ignorée.
  • Les champs inconnus sont ignorés : les versions suivantes ajoutent seulement des champs.
  • Les limites comptent les unités UTF-16, comme length en JavaScript et string.Length en .NET. Les motifs doivent couvrir toute la valeur : un saut de ligne final est invalide. Une chaîne vide ou composée d’espaces est considérée absente.
  • N’envoyez pas de données personnelles : libellés et contextes peuvent apparaître dans les titres des clips et noms de fichiers.
{ "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" }
  • Permet à Hovermate de créer la fiche du jeu et ses options avant le premier événement réel.
  • offers énumère les types standard et/ou les objets de types personnalisés.
  • log, facultatif, propose un journal ; files, facultatif, propose des fichiers d’événements du mod (§2.4). Hovermate demande l’accord de l’utilisateur avant de lire tout chemin proposé.
  • hello est accepté par tous les transports, y compris une ligne de journal [HOVERMATE].

5. Comportement de Hovermate

  • Le premier événement valide ou hello d’un nouveau game.id crée une fiche de jeu « SDK ». Elle utilise le nom, l’exécutable, le dossier et la jaquette s’il correspond à un jeu installé, une option par type annoncé ou reçu et les durées avant/après. Les moments forts restent désactivés jusqu’au choix des types par le joueur ; les marqueurs sont toujours écrits.
  • Les événements suivent le même circuit que les fiches intégrées : journal, marqueurs des clips et sessions, fenêtre de moments forts, notifications.
  • Les événements sont attribués au jeu au premier plan quand game.exe correspond. Sinon, ils sont acceptés uniquement pendant un enregistrement ou l’exécution du tampon et associés au jeu SDK.
  • Limites :
    • 20 événements/s par jeu ;
    • 200 types personnalisés par jeu ;
    • les lignes de réception dépassant 4 Ko sont ignorées ;
    • les lignes mal formées sont comptées dans l’état de la fiche (« N événements invalides »), sans jamais être journalisées brutes.