Game Watcher einrichten

Es gibt zwei Wege: Chatlix Connect (empfohlen, wenn du es sowieso schon für OBS nutzt) oder den Standalone Game-Watcher (Node-Binary, läuft auch ohne Connect). Beide schreiben am Ende in dieselbe Events-Tabelle.

Schritt 1 — Personal Access Token erzeugen (nur für Standalone)

Im Dashboard Profil → API-Tokens öffnen.
Token erstellen mit Scope game_watcher. Ohne diesen Scope antwortet die API mit 403 scope_required.
Token kopieren — er wird nur ein einziges Mal angezeigt.

Token wie ein Passwort behandeln. Bei Verdacht auf Leak: im Dashboard löschen, neuen erstellen, in der Config eintragen. (Chatlix Connect braucht keinen PAT — der nutzt einen eigenen Bridge-Token, der schon beim Connect-Login mitkommt.)

Schritt 2 — Watcher holen

Chatlix Connect: Game-Watcher-Modul in den Connect-Settings aktivieren. Erkennt laufende Spiele automatisch (Connect-Prozessliste, ~240 bekannte Titel) und sendet mindestens session_started/session_ended. Korrektur: Nicht nur Connect schickt einen Heartbeat — der Standalone-Watcher tut das ebenfalls (alle 30s, PAT-Auth), siehe Abschnitt "Heartbeat" unten.
Standalone: chatlix-game-watcher-win.exe bzw. -linux aus dem Downloads-Bereich. Node.js wird für die gepackte Binary nicht gebraucht, für den Source-Checkout schon (Node ≥ 18).

Windows-Hinweis (Beta): Beim ersten Start der Standalone-.exe zeigt SmartScreen eine Warnung — es gibt bewusst noch kein Code-Signing-Zertifikat in der Beta-Phase. Vor dem Ausführen den SHA-256 gegen SHA256SUMS.txt aus demselben Downloads-Ordner prüfen (PowerShell: Get-FileHash datei.exe -Algorithm SHA256).

Schritt 3 — Watcher konfigurieren (Standalone)

Config liegt als config.json neben der Binary (Vorlage: config.example.json):

Feld	Wert
`chatlix.apiBase`	`https://api.chatlix.app` (Default). Bei `http://` schaltet der Watcher automatisch in den Dry-Run.
`chatlix.token`	dein PAT aus Schritt 1. Solange hier `PASTE_LOCAL_TOKEN_HERE` oder leer steht, läuft alles im Dry-Run (nur Konsolen-Ausgabe, kein HTTP-Call).
`chatlix.channelId`	optional — bindet alle Events an einen Channel (nötig für Overlay-Bridge/Cinematics).
`chatlix.dryRun`	`true`/`false` — Testmodus erzwingen.
`watchers[].type`	`minecraft` (einziger "live"-Typ), `generic-log`, `generic-json` (beide live), oder ein Stub: `factorio`, `project-zomboid`, `rust`, `valheim`, `seven-days-to-die`.
`watchers[].id`	frei wählbarer Name, erlaubt mehrere Watcher gleichzeitig (z.B. "Survival-Server" + "Solo-Welt").

Beispiel Minecraft-Watcher (der einzige aktuell durchgetestete Typ):

{
  "id": "minecraft-main",
  "type": "minecraft",
  "enabled": true,
  "playerName": "DeinName",
  "paths": {
    "latestLog": "C:/Users/DU/AppData/Roaming/.minecraft/logs/latest.log"
  }
}

playerName filtert auf einen Spieler — wichtig bei Server-Logs mit mehreren Leuten, bei Singleplayer auf den eigenen Namen setzen.

Beispiel generic-log (für alles ohne fertigen Watcher-Typ):

{
  "id": "my-game",
  "type": "generic-log",
  "enabled": true,
  "path": "./game.log",
  "patterns": [
    { "event": "player_death", "severity": "normal",
      "regex": "^(?<player>\S+) died to (?<cause>.+)$" }
  ]
}

Erstes matchendes Pattern pro Zeile gewinnt — verhindert doppelte Events aus derselben Log-Zeile.

Schritt 4 — Doctor + Test

chatlix-game-watcher-win.exe doctor --config config.json — prüft OS/Node-Version, API-Erreichbarkeit, pro Watcher ob Pfad lesbar und Token/enabled gesetzt ist. Immer zuerst laufen lassen, spart Rätselraten.
chatlix-game-watcher-win.exe test-event --config config.json — schickt ein synthetisches Event durch die echte Pipeline.
Alternativ im Dashboard: Game Watcher → Test-Event senden (API: POST /v1/integrations/game-watcher/test-event, Session-Auth). Erzeugt keinen DB-Eintrag — reiner Pipeline-Pulse, nicht in der Events-History sichtbar.

Heartbeat — beide Wege

Korrektur: Es gibt keinen fehlenden Heartbeat beim Standalone-Watcher. Chatlix Connect schickt seinen Heartbeat per Bridge-Token an POST /v1/connect/game-watcher-heartbeat. Der Standalone-Watcher schickt unabhängig davon alle 30 Sekunden per PAT einen eigenen Heartbeat an POST /v1/integrations/game-watcher/heartbeat (inkl. instance_id, Agent-Version, Hostname, OS-Plattform, Watcher-Liste — Quelle: dem Game-Watcher). Damit zeigt das Dashboard "Watcher online/offline" für beide Wege verlässlich an.

Dual-PC / LAN-Token

Wenn Spiel und Streaming-PC getrennt laufen, gibt es einen LAN-Token-Abruf (GET /v1/connect/game-watcher-lan-token), damit der Watcher auf dem Gaming-PC sich automatisch mit der Connect-Instanz auf dem Streaming-PC koppeln kann, ohne den Token manuell zu übertragen. Aktuell als V1.2-Feature markiert — bei Problemen lieber den PAT-Weg (Schritt 1–3) nutzen.

Mehrere Watcher

Du kannst beliebig viele Watcher gleichzeitig laufen lassen, jeder mit eigener id, alle auf demselben Token/config.json.

Generic HTTP-Endpoint (eigener Client)

Wenn du selbst postest statt den Watcher zu nutzen (eigener Server-Mod, Custom-Script):

POST https://api.chatlix.app/v1/integrations/game-watcher/events
Authorization: Bearer <dein-PAT>
Content-Type: application/json

{
  "source": "generic-log",
  "watcher_id": "my-watcher",
  "event_type": "player_death",
  "severity": "normal",
  "occurred_at": "2026-07-08T12:34:56Z",
  "actor": "Steve",
  "message": "Steve fiel von einer Klippe",
  "metadata": { "cause": "fall" }
}

Wichtig, nochmal korrigiert: source ist keine Freitext-Angabe, aber auch keine feste 8-Werte-Liste — die Allowlist ist deutlich größer und teils dynamisch (Code: EventNormalizer::ALLOWED_SOURCES + TelemetryProfileCatalog::WATCHER_REGISTRY, zusammen über 120 Werte, u.a. minecraft, minecraft-server, factorio, project-zomboid, rust, valheim, seven-days-to-die, isaac, hades-2, sekiro, souls-save, mod-bridge, crimson-desert, subnautica, subnautica-below-zero, generic-log, generic-json, dashboard, hotkey, test, api, process_scanner plus rund 100 weitere Watcher-Registry-Einträge wie palworld-server oder ets2-telemetry). Ein selbst erfundener Wert wie custom_game wird trotzdem mit {"ok":false,"code":"source_not_allowed"} abgelehnt (HTTP 200 — kein Retry nötig, es liegt am Payload). Für eigene Integrationen ohne passenden Watcher-Typ bleiben generic-log/generic-json die einfachste, sichere Wahl.

Weitere Regeln für den generic-HTTP-Weg:

event_type muss dem Muster ^[a-z][a-z0-9_]{0,63}$ entsprechen.
severity: low / normal / high / critical (Aliase: info→low, warn/warning→high, error→critical).
occurred_at: ISO-8601, max. 10 Minuten in der Zukunft, max. 24 Stunden Backdate — sonst occurred_at_in_future / occurred_at_too_old.
Body-Limit 64 KB (413 payload_too_large).
Rate-Limit pro Token: 200 Events Burst, danach 10/s nachhaltig (siehe Stats-Seite für die Retention-Limits).

Alle Fehlercodes im Detail: siehe Troubleshooting.