Nakama Surface Contract

This contract defines the server-side surface for Multiplayer integration and automated agent/Genie interactions. Game mechanics must be fully verified by the server.

1. Genie Orchestration RPCs

The server MUST implement standard RPCs to permit orchestration by Genie agents, AI trainers, and headless tests.

`genie_ingest_state`

Fetches the authoritative match state for external agents.

// Request: { "match_id": "string" }
// Response:
{
  "match_id": "...",
  "tick": 1423,
  "phase": "playing",
  "state": {
    "players": [{ "id": "uuid", "score": 10 }],
    "entities": []
  }
}

`genie_inject_event`

Injects an event directly into the match loop, skipping standard client authentication if the caller is an authenticated server/agent profile.

// Request:
{
  "match_id": "...",
  "op_code": 14,
  "payload": { "x": 10, "y": 20 }
}
// Response: { "success": true, "tick_applied": 1424 }

`genie_set_bot_profile`

Configures a fallback bot’s behavior parameters dynamically.

// Request:
{
  "match_id": "...",
  "bot_id": "uuid",
  "difficulty": 0.8,
  "persona": "aggressive"
}

2. Match Handler Allowlist

The client may only send specific, deterministic op_codes. These usually map to:

1 (Input/Move)
2 (Select/Interact)
3 (Emote/Ping)
9 (Leave Match)

3. The Deny List (Anti-Patterns)

To maintain match integrity, the following operations are strictly prohibited:

Direct State Mutation: The client CANNOT send { "score": 100 } or { "hp": 50 }. State changes must result from action logic processed within match_loop.go.
Hidden Information Exposure: The server MUST scrub hidden information (e.g., opponent’s drawn cards, hidden fog-of-war entities) before broadcasting the state to clients.
Unauthenticated RPCs: Any RPC modifying state must verify the session ID or require an S2S key.

4. Acceptance & Verification

Criteria: Match state must be fully authoritative and un-exploitable.
- Verify: Run genie_ingest_state manually via cURL; ensure hidden data is stripped. Attempt to send an unauthorized op_code to mutate state, and assert the server rejects it.