프로토콜 v1 — 게임 이벤트 SDK

목적: 게임이나 모드의 이벤트를 Hovermate로 보내 내장 게임 카드처럼 타임라인 마커와 하이라이트를 자동 생성합니다. 네트워크, 파일 전용, 로그 전용 환경을 세 가지 전송 방식으로 지원합니다.

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(네트워크 사용 모드: C#, C++, Java, Python, JS)

POST {url}, 헤더는 Authorization: Bearer <token>, Content-Type: application/json입니다.
Origin 헤더가 있는 요청은 403로 거부하여 브라우저의 전송을 막습니다.
본문은 이벤트 객체 하나 또는 최대 100개 이벤트를 담은 { "events": [ ... ] }입니다. 최대 본문 크기는 64 KB입니다.
일괄 요청은 전부 수락하거나 거부합니다. Hovermate가 모든 이벤트를 먼저 검증하며 하나라도 잘못되면 아무것도 수락하지 않고 400 본문에 위치를 반환합니다: { "error": "<code>", "detail": "...", "index": 3 }. 세션의 새 게임은 일괄 요청에서 처음 언급하는 이벤트에 game.name가 있어야 합니다.
응답:
- 202 수락됨;
- 400 잘못됨, 본문은 { "error": "<code>", "detail": "...", "index": <n, batches only> };
- 401 토큰이 없거나 잘못됨;
- 403 요청에 Origin 헤더가 있음;
- 413 본문이 너무 큼. 클라이언트가 상태를 받도록 최대 1 MB를 먼저 읽고 버립니다. 더 큰 본문은 읽기 전에 거부하고 연결을 닫을 수 있습니다;
- 429 게임당 초당 20개 이벤트 초과;
- 405, 411, 415는 잘못된 메서드, 길이 누락 또는 잘못된 콘텐츠 유형입니다.
클라이언트는 백그라운드에서 보내며 게임 스레드를 막지 않습니다. 제한 시간은 최대 250 ms이고, 크기가 제한된 큐에서 가장 오래된 항목을 버리며 한 번만 재시도합니다.

2.2 JSONL 수신 폴더(파일은 쓸 수 있지만 네트워크는 못 쓰는 모드)

{inbox}\<game.id>.jsonl에 UTF-8 줄을 추가합니다. 한 줄에 이벤트 객체 하나이며 BOM은 넣지 않습니다.
폴더가 사용자 소유이므로 토큰이 필요 없습니다.
Engine은 시작 시 수신 폴더의 각 *.jsonl 파일 끝부터 추가된 내용을 추적합니다. 모드는 세션 시작 시 자신의 파일을 비울 수 있습니다.

2.3 로그 줄 규칙(게임 로그에만 쓰는 스크립트 모드)

마커 [HOVERMATE] 뒤에 JSON 이벤트 객체 하나가 있는 줄을 사용합니다. 시간과 채널 이름 등 마커 이전 내용은 무시됩니다.
SDK 카드의 ‘파일에서 이벤트 읽기’ 목록에 사용자가 로그 경로를 추가합니다. 다른 방식으로 받은 hello 이벤트(§4)도 경로를 제안할 수 있습니다. Engine은 기존 로그 추적 어댑터로 파일을 읽습니다.
스크립트 로그 위치를 아는 게임은 실행 중에 Hovermate가 자동 추적합니다. 목록은 게임 카탈로그(sdkLogs)에 있으며 예로 Documents\The Witcher 3\scriptslog.txt와 Skyrim/Fallout Papyrus 로그가 있습니다. 이런 모드는 게임의 스크립트 로깅만 켜면 됩니다.

2.4 모드 폴더 이벤트 파일(자기 폴더에만 쓰는 샌드박스)

Cyber Engine Tweaks Lua 모드 같은 환경은 모드 폴더에만 쓸 수 있습니다. 그 안의 hovermate-events.jsonl에 JSONL 줄(§2.2)을 추가합니다.
사용자는 SDK 카드의 ‘파일에서 이벤트 읽기’에 파일을 추가합니다. 모드 README에 파일 위치를 안내해야 합니다. Hovermate는 수신 파일처럼 추가된 내용을 읽습니다.
모드는 경로를 [HOVERMATE] 로그 줄로 한 번 출력하거나 다른 전송 수단이 있을 때 경로 배열인 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 또는 짧은 식별자로 모드 버전 간에 유지합니다.
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는 모드 폴더의 이벤트 파일(§2.4)을 제안합니다. Hovermate는 어떤 경로든 읽기 전에 사용자에게 묻습니다.
hello는 [HOVERMATE] 로그 줄을 포함한 모든 전송 방식으로 수락됩니다.

5. Hovermate 동작

새 game.id의 첫 정상 이벤트 또는 hello는 ‘SDK’ 게임 카드를 만듭니다. 이름과 exe, 설치된 게임과 exe가 일치할 때 폴더와 표지, 선언되거나 받은 유형별 스위치와 이벤트 전후 시간 설정을 사용합니다. 사용자가 유형을 켤 때까지 하이라이트는 꺼져 있지만 마커는 항상 기록됩니다.
이벤트는 내장 카드와 같은 처리 경로를 따릅니다. 기록, 클립 및 세션 마커, 하이라이트 창, 알림을 사용합니다.
game.exe가 감지된 전면 게임과 일치하면 이벤트를 그 게임에 연결합니다. 그렇지 않으면 녹화나 버퍼가 실행 중일 때만 수락하고 SDK 게임으로 표시합니다.
제한:
- 게임당 초당 이벤트 20개;
- 게임당 사용자 지정 유형 200개;
- 4 KB를 넘는 수신 줄은 버립니다;
- 잘못된 줄 수를 세어 카드 상태에 ‘잘못된 이벤트 N개’로 표시하며 원문을 기록하지 않습니다.