プロトコル v1 — ゲームイベント SDK

目的：ゲームや MOD から Hovermate へイベントを送り、内蔵カードと同じようにタイムラインマーカーとハイライトを自動作成します。ネットワーク、ファイルのみ、ログのみの環境を 3 種類の送信方法でカバーします。

1. 接続情報の検出

SDK が有効な間、Engine は %LOCALAPPDATA%\Hovermate\Sdk\connection.json を書き込みます（設定 › クリップ › ゲームイベント SDK。初期状態で有効）。

{
  "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 はイベントの送信先です。このファイルから読み取り、書かれているとおりに使ってください。ホスト、ポート、パスをコードに埋め込んだり変更したりしないでください。現在 Hovermate は http://local.hovermate.gg/hovermate/v1/events を書き込みます。SDK のテストサーバーは独自のテスト用アドレスを書き込みます。
クライアントは起動時と 401 応答の後にファイルを読みます。トークンは変更される場合があります。
HOVERMATE_SDK_CONNECTION=<path> はテスト、ツール、分離したデータ環境用にファイルの場所を上書きします。受信フォルダーは必ずファイル内の inbox から取得し、独自に組み立てないでください。
ファイルがない場合、Hovermate が未インストールか SDK が無効です。クライアントは何もせず、ゲームへ例外を送出しません。

2. 送信方法

2.1 HTTP（ネットワーク対応 MOD：C#、C++、Java、Python、JS）

POST {url}。ヘッダー：Authorization: Bearer <token>、Content-Type: application/json。
Origin ヘッダーを含むリクエストは 403 で拒否され、ブラウザーからの投稿を防ぎます。
本文はイベントオブジェクト 1 件、または最大 100 件の { "events": [ ... ] } です。本文の上限は 64 KB です。
バッチは全件受理または全件拒否です。Hovermate は先にすべてを検証し、1 件でも不正なら何も受理せず、400 本文に位置を返します：{ "error": "<code>", "detail": "...", "index": 3 }。そのセッションで初めてのゲームは、最初にそのゲームを参照するバッチ内のイベントで game.name を指定する必要があります。
応答：
- 202 受理。
- 400 不正。本文は { "error": "<code>", "detail": "...", "index": <n, batches only> }。
- 401 トークンが不正または欠落。
- 403 リクエストに Origin ヘッダーがある。
- 413 本文が大きすぎる。クライアントがステータスを受け取れるよう、最大 1 MB は先に読み取って破棄します。それより大きい本文は読む前に拒否し、接続を閉じる場合があります。
- 429 1 ゲームで毎秒 20 件を超えるイベント。
- 405、411、415 はメソッド不正、長さの欠落、コンテンツタイプ不正。
クライアントはバックグラウンドで送信し、ゲームスレッドを待たせません。タイムアウトは最大 250 ms、キューは上限付きで最古を破棄し、再試行は最大 1 回です。

2.2 JSONL 受信フォルダー（ファイルを書けるがネットワークのない MOD）

{inbox}\<game.id>.jsonl に UTF-8 で追記します。1 行にイベントオブジェクト 1 件、BOM は付けません。
フォルダーはユーザー所有のため、トークンは不要です。
Engine は起動時、受信フォルダー内の各 *.jsonl ファイルの末尾から追記を監視します。MOD はセッション開始時に自分のファイルを空にできます。

2.3 ログ行の規約（ゲームログにしか書けないスクリプト MOD）

マーカー [HOVERMATE] と、その直後の JSON イベントオブジェクト 1 件を含む行を使用します。時刻やチャンネル名など、マーカーより前は無視されます。
SDK カードの「ファイルからイベントを読む」一覧で、ユーザーがログのパスを追加します。他の方法で届いた hello イベント（§4）でも提案できます。Engine は既存のログ追跡アダプターで読み込みます。
ログの場所が既知のゲームでは、実行中に Hovermate が自動監視します。リストはゲームカタログ（sdkLogs）にあり、例は Documents\The Witcher 3\scriptslog.txt と Skyrim/Fallout の Papyrus ログです。ゲームのスクリプトログを有効にする以外の設定は不要です。

2.4 MOD フォルダーのイベントファイル（自分のフォルダーにしか書けない環境）

Cyber Engine Tweaks の Lua MOD など、MOD フォルダーにしか書けない環境では、その中の hovermate-events.jsonl に JSONL（§2.2）を追記します。
ユーザーが SDK カードの「ファイルからイベントを読む」に追加します。MOD の README にファイルの場所を記載してください。Hovermate は受信フォルダーと同じように追記を読みます。
別の送信方法が使える場合、MOD のパスを [HOVERMATE] ログ行で 1 回表示するか、パスの配列 hello.files で送れます。Hovermate が追加を提案します。

3. イベントオブジェクト

{
  "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：必須。値は 1。
game.id：必須。[a-z0-9._-]{3,64} に一致する逆 DNS 名または短い識別子で、MOD のバージョン間で固定します。
game.name：セッション最初のイベントまたは hello で必須。最大 64 文字。
game.exe：任意。ファイル名のみ。検出したゲームフォルダーにイベントを関連付け、その実行ファイルでリプレイバッファを開始できるようにします。
type：必須。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、または "custom"。Docs/CLIPS.md のリストが正式な定義で、追加のみ行われます。未知の標準タイプは 400 で拒否します。
customType / customLabel：type が "custom" の場合に必須。customType は [a-z0-9_.-]{1,32} に一致し、customLabel はカードの切り替え名として最大 40 文字です。
label：任意。マーカーのツールチップやクリップ名に使う表示文で、最大 80 文字。
tags：任意。最大 8 タグで、それぞれ [a-z0-9_-]{1,24} に一致させます。
context：任意。ハイライト名に使うマップ、レベル、エリア。最大 64 文字。
time：任意。ISO-8601 UTC。Engine が受信時刻を記録し、前後 ±5 秒以内の time で補正します。それ以外は無視します。
未知のフィールドは無視します。将来のバージョンではフィールドを追加します。
文字数は JavaScript の length や .NET の string.Length と同じ UTF-16 コード単位です。パターンは値全体に一致する必要があり、末尾の改行は不正です。空文字列や空白のみの文字列は未指定とみなします。
個人情報を送らないでください。ラベルやコンテキストがクリップ名やファイル名に使われる場合があります。

4. `hello`（任意、推奨）

{ "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" }

最初の実イベントより前に、ゲームカードとハイライト切り替えを作成できます。
offers は標準タイプや独自タイプのオブジェクトを列挙します。
任意の log はログ行方式のファイル、files は MOD フォルダーのイベントファイル（§2.4）を提案します。Hovermate は提案されたパスを読む前にユーザーへ確認します。
hello はすべての送信方法で受理され、[HOVERMATE] ログ行にも対応します。

5. Hovermate の動作

新しい game.id の最初の正常なイベントまたは hello で「SDK」ゲームカードを作ります。ゲーム名、exe、一致するインストール済みゲームのフォルダーとカバー、通知・受信した各タイプの切り替え、前後の時間設定を使用します。プレイヤーがタイプを有効にするまでハイライトはオフですが、マーカーは常に記録します。
イベントは内蔵カードと同じ処理経路を通ります。履歴、クリップとセッションのマーカー、ハイライトウィンドウ、通知が含まれます。
game.exe が検出した前面のゲームに一致すると、そのゲームに関連付けます。それ以外は録画またはバッファ動作中のみ受理し、SDK ゲームとして記録します。
制限：
- 1 ゲームあたり毎秒 20 イベント。
- 1 ゲームあたり独自タイプは 200 個。
- 受信フォルダーの 4 KB を超える行は破棄します。
- 不正な行を数え、カードに「N 件の不正イベント」と表示します。内容をそのままログには記録しません。