Envoyez des événements de jeu à Hovermate

Fonctionnement

1. Votre mod signale un moment. Un seul appel suffit, par exemple event("bossKill"). Le client l’envoie en arrière-plan sans bloquer le jeu.
2. Hovermate le marque. Chaque événement devient un marqueur de l’enregistrement et de la session, avec votre libellé.
3. Le joueur choisit les moments forts. Votre jeu reçoit sa propre fiche dans Clips. Chaque type activé par le joueur enregistre aussi un clip.

Quand son SDK est activé, Hovermate publie son adresse, un jeton et son dossier de réception dans 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"
}

Lisez url dans ce fichier et utilisez-le exactement tel qu’il est écrit ; ne codez jamais en dur et ne modifiez jamais son hôte, son port ou son chemin.

Les clients lisent %LOCALAPPDATA%\Hovermate\Sdk\connection.json, ou le chemin de HOVERMATE_SDK_CONNECTION pour les tests et configurations isolées. Ils le relisent après une réponse 401, car le jeton change à chaque désactivation puis réactivation du SDK. L’absence du fichier signifie que Hovermate n’est pas installé ou que le SDK est désactivé ; les clients restent silencieux.

Trois façons d’envoyer des événements

Utilisez la première autorisée par l’environnement de votre 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"}

Démarrage rapide

Chaque exemple envoie hello, kill, bossKill et un événement personnalisé parry. Ce sont les fichiers exécutables du dossier examples du 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

Comportement des clients

• Les appels reviennent immédiatement et ne transmettent jamais d’exception au jeu.
• Un traitement en arrière-plan envoie les événements avec un délai maximal de 250 ms et réessaie une fois les requêtes en échec.
• La file contient 256 événements et supprime le plus ancien en cas de dépassement.
• Si HTTP est inaccessible, les événements sont envoyés au dossier de réception pendant quelques secondes.
• Sans connection.json, le client reste silencieux et vérifie à nouveau toutes les 5 secondes.
• Chaque événement contient game.name. Le texte est tronqué aux limites ci-dessous et les tags invalides sont ignorés au lieu de provoquer un échec.

Le client Lua (hovermate_events.lua) écrit immédiatement chaque événement. Il privilégie hovermate-events.jsonl dans le dossier du mod, puis le dossier de réception si les chemins absolus sont autorisés, puis des lignes [HOVERMATE] via la fonction writer fournie, par exemple print. logLine(type, options) renvoie une telle ligne pour que vous l’affichiez.

L’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" }

Les longueurs comptent les unités UTF-16 : un emoji compte pour 2. Les champs texte refusent les caractères de contrôle. Les champs inconnus sont ignorés ; les versions suivantes ajoutent seulement des champs. N’envoyez pas de données personnelles : libellés et contextes peuvent apparaître dans les titres de clips et noms de fichiers.

Types standard

29 types partagés avec les fiches de jeux intégrées de Hovermate. La liste s’allonge seulement ; un type standard inconnu est refusé.

• 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

Types personnalisés

Pour les moments absents de la liste standard. Chaque type a sa propre option de moments forts, nommée par customLabel ; un jeu peut en avoir jusqu’à 200.

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

hello

Facultatif et recommandé. Crée la fiche de votre jeu et ses options avant le premier événement réel, afin que le joueur puisse la configurer à l’avance.

{ "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 énumère les types standard et les objets { "customType", "customLabel" }.
• log propose un journal avec des lignes [HOVERMATE] ; files propose des fichiers d’événements du mod. Hovermate demande l’accord du joueur avant de lire un chemin proposé.
• hello fonctionne avec tous les transports, y compris une ligne de journal [HOVERMATE].

Limites et réponses

Codes d’erreur : invalid_json, version, game, type, custom, label, tags, context, offers, log, files, batch. Les lignes invalides des fichiers sont comptées et signalées dans la fiche du jeu ; Hovermate ne journalise jamais leur contenu brut.

Tester sans Hovermate

Le récepteur de test mock-server.py (Python 3.8+, bibliothèque standard) répond exactement comme Hovermate. Il crée son propre connection.json dans un dossier temporaire, applique les mêmes règles et codes d’erreur, suit le dossier d’entrée et les fichiers de --watch, puis affiche chaque événement et chaque erreur.

Contrairement à Hovermate, le récepteur de test écoute sur un port numérique de loopback et écrit cette adresse dans son connection.json. Ce n’est qu’un outil de test : les clients utilisent l’url que contient le fichier.

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 suit un fichier de mod hovermate-events.jsonl ou un journal contenant des lignes [HOVERMATE].
• --follow-proposals lit les chemins proposés par hello, comme si le joueur les avait autorisés.
• --record FILE ajoute chaque événement accepté ou refusé sous forme de ligne JSON pour les vérifications automatiques.

HOVERMATE_SDK_CONNECTION fonctionne aussi avec Hovermate lui-même : les tests ne touchent jamais le vrai fichier de connexion.

Cas de conformité

Le SDK inclut conformance/cases.json : des requêtes et les réponses attendues de Hovermate, des événements valides à chaque code d’erreur. conformance/run.py les envoie au récepteur de test ou à tout autre récepteur. Hovermate utilise le même fichier dans ses propres tests.

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

Ce que voit le joueur

• Le premier événement valide ou hello d’un nouveau game.id crée une fiche SDK dans Clips : nom du jeu, dossier et jaquette si exe correspond à un jeu installé, et une option pour chaque type annoncé ou reçu.
• Les options de moments forts sont initialement désactivées : le joueur choisit les types qui enregistrent des clips. 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 et notifications.
• Quand game.exe correspond au jeu au premier plan, les événements lui sont attribués. Sinon, ils sont acceptés uniquement pendant un enregistrement ou l’exécution du tampon de replay.
• Les événements invalides sont comptés dans l’état de la fiche pour que les joueurs puissent vous signaler un problème.

Protocole et fichiers

Le protocole v1 est le contrat complet : découverte de la connexion, quatre moyens de livraison, objet événement, hello et comportement de Hovermate.

Le SDK — clients, exemples, outils, cas de conformité et protocole — est sous licence MIT : vous pouvez intégrer un client à votre mod. Cette licence ne couvre pas Hovermate lui-même.