devstack 0.1.0

package/vendor/skills/skills/rivetkit/reference/cookbook/multiplayer-game.md

@@ -0,0 +1,714 @@
+# Multiplayer Game
+
+> Source: `src/content/cookbook/multiplayer-game.mdx`
+> Canonical URL: https://rivet.dev/cookbook/multiplayer-game
+> Description: Pragmatic patterns for building multiplayer games: matchmaking, tick loops, realtime state, interest management, and validation.
+
+---
+
+Patterns for building multiplayer games with RivetKit, intended as a practical checklist you can adapt per genre.
+
+## Starter Code
+
+Start with one of the working examples on [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/) and adapt it to your game. Do not start from scratch for matchmaking and lifecycle flows.
+
+| Game Classification | Starter Code                                                                                                        | Common Examples                                                                                                 |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Battle Royale       | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/battle-royale/) | Fortnite, Apex Legends, PUBG, Warzone                                                                           |
+| Arena               | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/arena/)         | Call of Duty TDM/FFA, Halo Slayer, Counter-Strike casual, VALORANT unrated, Overwatch Quick Play, Rocket League |
+| IO Style            | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/io-style/)      | Agar.io, Slither.io, surviv.io                                                                                  |
+| Open World          | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/open-world/)    | Minecraft survival servers, Rust-like worlds, MMO zone/chunk worlds                                             |
+| Party               | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/party/)         | Fall Guys private lobbies, custom game rooms, social party sessions                                             |
+| Physics 2D          | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/physics-2d/)    | Top-down physics brawlers, 2D arena games, platform fighters                                                    |
+| Physics 3D          | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/physics-3d/)    | Physics sandbox sessions, 3D arena games, movement playgrounds                                                  |
+| Ranked              | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/ranked/)        | Chess ladders, competitive card games, duel arena ranked queues                                                 |
+| Turn-Based          | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/turn-based/)    | Chess correspondence, Words With Friends, async board games                                                     |
+| Idle                | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/idle/)          | Cookie Clicker, Idle Miner Tycoon, Adventure Capitalist                                                         |
+
+## Server Simulation
+
+### Game Loop And Tick Rates
+
+| Pattern                    | Use When                                           | Implementation Guidance                                                                                                        |
+| -------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Fixed realtime loop        | Battle Royale, Arena, IO Style, Open World, Ranked | Run in `run` with `sleep(tickMs)` and exit on `c.aborted`.                                                                     |
+| Action-driven updates      | Party, Turn-Based                                  | Mutate and broadcast only on actions/events rather than scheduled ticks.                                                       |
+| Coarse offline progression | Any mode with idle progression                     | Use `c.schedule.after(...)` with coarse windows (for example 5 to 15 minutes) and apply catch-up from elapsed wall clock time. |
+
+### Physics
+
+Start with custom kinematic logic for simple games. Switch to a full physics engine when you need joints, stacked bodies, high collision density, or complex shapes (rotated polygons, capsules, convex hulls, triangle meshes).
+
+Pick one engine per simulation. Keep frontend-only libs out of backend simulation paths and treat server state as authoritative.
+
+| Dimension | Primary Engine       | Fallback Engines         | Example Code                                                                                                     |
+| --------- | -------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| 2D        | `@dimforge/rapier2d` | `planck-js`, `matter-js` | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/physics-2d/) |
+| 3D        | `@dimforge/rapier3d` | `cannon-es`, `ammo.js`   | [GitHub](https://github.com/rivet-dev/rivet/tree/main/examples/multiplayer-game-patterns/src/actors/physics-3d/) |
+
+### Spatial Indexing
+
+For non-physics spatial queries, use a dedicated index instead of naive `O(n^2)` checks:
+
+| Index Type  | Recommendation                                                                                                  |
+| ----------- | --------------------------------------------------------------------------------------------------------------- |
+| AABB index  | For AOI, visibility, and non-collider entities, use `rbush` for dynamic sets or `flatbush` for static-ish sets. |
+| Point index | For nearest-neighbor or within-radius queries, use `d3-quadtree`.                                               |
+
+## Networking & State Sync
+
+### Netcode
+
+| Model                                   | When To Use                           | Implementation                                                                                                                                                  |
+| --------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Hybrid (client movement, server combat) | Shooters, action sports, ranked duels | Client owns movement and sends capped-rate position updates. Server validates for anti-cheat. Combat (projectiles, hits, damage) is fully server-authoritative. |
+| Server-authoritative with interpolation | IO Style, persistent worlds           | Client sends input commands. Server simulates on fixed ticks and publishes authoritative snapshots. Client interpolates between snapshots.                      |
+| Server-authoritative (basic logic)      | Turn-based, event-driven              | Server validates and applies discrete actions (turns, phase transitions, votes). Client displays confirmed state.                                               |
+
+### Realtime Data Model
+
+- **Snapshots and diffs**: Publish state as events. Send a full snapshot on join/resync, then per-tick diffs for regular updates.
+- **Batch per tick**: Keep events small and typed. Batch high-frequency updates per tick.
+- **Avoid UI framework state for game updates**: Use `requestAnimationFrame` or a Canvas/Three.js loop for simulation, not React state. Reserve UI framework state for menus, HUD, and forms.
+- **Broadcast vs per-connection**: Use `c.broadcast(...)` for shared updates and `conn.send(...)` for private/per-player data.
+
+### Shared Simulation Logic
+
+Shared simulation logic runs on both the client and the server. For example, an `applyInput(state, input, dt)` function that integrates velocity and clamps to world bounds can run on the client for prediction and on the server for validation.
+
+- **Hybrid modes**: Client runs shared movement as primary authority, server runs it for anti-cheat validation.
+- **Server-authoritative modes**: Client uses shared logic for interpolation and prediction only.
+- **Keep it pure**: Movement integration, input transforms, collision helpers, and constants only.
+- **Put shared code in `src/shared/`**: Keep deterministic helpers in `src/shared/sim/*` with no side effects.
+
+### Interest Management
+
+Control what each client receives to reduce bandwidth and prevent information leaks.
+
+#### Per-Player Replication Filters
+
+- **Filter by relevance**: Send each client only state relevant to that player (proximity, line-of-sight, team, or game phase).
+- **Shooters and action games**: Limit replication by proximity and optional field-of-view checks.
+- **Server-side only**: Clients should never receive data they should not see.
+
+#### Sharded Worlds
+
+- **Partition large worlds**: Use chunk actors keyed by `worldId:chunkX:chunkY`.
+- **Subscribe to nearby chunks**: Clients connect only to nearby partitions (for example a 3x3 chunk window).
+- **Use sparingly**: Only when the world is large and state-heavy (sandbox builders, MMOs), not as a default for small matches.
+
+## Backend Infrastructure
+
+### Persistence
+
+- **In-memory state**: Best for realtime game state that changes every tick (player positions, inputs, match phase, scores).
+- **SQLite (`rivetkit/db`)**: Better for large or table-like state that needs queries, indexes, or long-term persistence (tiles, inventory, matchmaking pools). Serialize DB work through a queue since multiple actions can hit the same actor concurrently.
+
+### Matchmaking Patterns
+
+Common building blocks used across the architecture patterns below.
+
+#### Actor Topology
+
+| Primitive                               | Use When                                                                    | Typical Ownership                                                              |
+| --------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `matchmaker["main"]` + `match[matchId]` | Session-based multiplayer (battle royale, arena, ranked, party, turn-based) | Matchmaker owns discovery/assignment. Match owns lifecycle and gameplay state. |
+| `chunk[worldId,chunkX,chunkY]`          | Large continuous worlds that need sharding                                  | Each chunk owns local players, chunk state, and local simulation.              |
+| `world[playerId]`                       | Per-player progression loops (idle/solo world state)                        | Per-player resources, buildings, timers, and progression.                      |
+| `player[username]`                      | Canonical profile/rating reused across matches                              | Durable player stats (for example rating and win/loss).                        |
+| `leaderboard["main"]`                   | Shared rankings across many matches/players                                 | Global ordered score rows and top lists.                                       |
+
+#### Queueing Strategy
+
+- Multiple players can hit the matchmaker at the same time, so actions like find/create, queue/unqueue, and close need to be serialized through actor queues to avoid races.
+- Match-local actions (gameplay, scoring) do not need queueing unless they write back to the matchmaker.
+
+## Security And Anti-Cheat
+
+Start with this baseline, then harden further for competitive or high-risk environments.
+
+### Baseline Checklist
+
+- **Identity**: Use `c.conn.id` as the authoritative transport identity. Treat `playerId`/`username` in params as untrusted input and bind through server-issued assignment/join tickets.
+- **Authorization**: Validate the caller is allowed to mutate the target entity (room membership, turn ownership, host-only actions).
+- **Input validation**: Clamp sizes/lengths, validate enums, and validate usernames (length, allowed chars, avoid unbounded Unicode).
+- **Rate limiting**: Per-connection rate limits for spammy actions (chat, join/leave, fire, movement updates).
+- **State integrity**: Server recomputes derived state (scores, win conditions, placements). Never allow client-authoritative changes to inventory/currency/leaderboard totals.
+
+### Movement Validation
+
+For any mode with client-authoritative movement (hybrid flows), clients may send position/rotation updates for smoothness, but the server must:
+
+- Enforce max delta per update (speed cap) based on elapsed time.
+- Reject or clamp teleports.
+- Enforce world bounds (and basic collision if applicable).
+- Rate limit update frequency (for example 20Hz max).
+
+## Architecture Patterns
+
+Each game type below starts with a quick summary table, then details actors and lifecycle.
+
+### Battle Royale
+
+| Topic       | Summary                                                                                                                                                                                  |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Matchmaking | Immediate routing to the fullest non-started lobby (oldest tie-break); players wait in lobby until capacity, then the match starts.                                                      |
+| Netcode     | Hybrid. Client owns movement, camera, and local prediction. Server owns zone state, projectiles, hit resolution, eliminations, loot, and final placement.                                |
+| Tick Rate   | 10 ticks/sec (`100ms`) with a fixed loop for zone progression and lifecycle checks.                                                                                                      |
+| Physics     | Client owns movement with server anti-cheat validation; projectiles, hits, and damage are server-authoritative. Use `@dimforge/rapier3d` for 3D or `@dimforge/rapier2d` for top-down 2D. |
+
+**Actors**
+
+- **Key**: `matchmaker["main"]`
+- **Responsibility**: Finds or creates lobbies, tracks pending reservations, and maintains occupancy.
+- **Actions**
+  - `findMatch`
+  - `pendingPlayerConnected`
+  - `updateMatch`
+  - `closeMatch`
+- **Queues**
+  - `findMatch`
+  - `pendingPlayerConnected`
+  - `updateMatch`
+  - `closeMatch`
+- **State**
+  - SQLite
+  - `matches`
+  - `pending_players`
+  - `player_count` includes connected and pending players
+
+- **Key**: `match[matchId]`
+- **Responsibility**: Runs lobby/live/finished phases, owns player state, zone progression, and eliminations.
+- **Actions**
+  - `connect`
+  - Movement and combat actions
+- **Queues**
+  - None
+- **State**
+  - JSON
+  - `phase`
+  - `players`
+  - `zone`
+  - `eliminations`
+  - `snapshot data`
+
+**Lifecycle**
+
+```mermaid
+sequenceDiagram
+	participant C as Client
+	participant MM as matchmaker
+	participant M as match
+
+	C->>MM: findMatch()
+	alt no open lobby
+		MM->>M: create(matchId)
+	end
+	MM-->>C: {matchId, playerId}
+	C->>M: connect(playerId)
+	M->>MM: pendingPlayerConnected(matchId, playerId)
+	MM-->>M: accepted
+	Note over M: lobby countdown -> live
+	M-->>C: snapshot + shoot events
+	M->>MM: closeMatch(matchId)
+```
+
+### Arena
+
+| Topic       | Summary                                                                                                                                                      |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Matchmaking | Mode-based fixed-capacity queues (`duo`, `squad`, `ffa`) that build only full matches and pre-assign teams (except FFA).                                     |
+| Netcode     | Hybrid. Client owns movement plus prediction and smoothing. Server owns team or FFA assignment, projectiles, hit resolution, phase transitions, and scoring. |
+| Tick Rate   | 20 ticks/sec (`50ms`) with a tighter loop for live team and FFA snapshots.                                                                                   |
+| Physics     | Medium to high intensity; client movement with server validation and server-authoritative combat/entities.                                                   |
+
+**Actors**
+
+- **Key**: `matchmaker["main"]`
+- **Responsibility**: Runs mode queues, builds full matches, assigns teams, and publishes assignments.
+- **Actions**
+  - `queueForMatch`
+  - `unqueueForMatch`
+  - `matchCompleted`
+- **Queues**
+  - `queueForMatch`
+  - `unqueueForMatch`
+  - `matchCompleted`
+- **State**
+  - SQLite
+  - `player_pool`
+  - `matches`
+  - `assignments` keyed by connection and player
+
+- **Key**: `match[matchId]`
+- **Responsibility**: Runs match phases and in-match player/team state for score and win conditions.
+- **Actions**
+  - `connect`
+  - Gameplay actions
+- **Queues**
+  - None
+- **State**
+  - JSON
+  - `phase`
+  - `players`
+  - `team assignments`
+  - `score and win state`
+
+**Lifecycle**
+
+```mermaid
+sequenceDiagram
+	participant C as Client
+	participant MM as matchmaker
+	participant M as match
+
+	C->>MM: queueForMatch(mode)
+	Note over MM: enqueue in player_pool
+	Note over MM: fill when capacity reached
+	MM->>M: create(matchId, assignments)
+	Note over MM: persist assignments
+	MM-->>C: assignmentReady
+	C->>M: connect(playerId)
+	Note over M: waiting -> live when all players connect
+	M->>MM: matchCompleted(matchId)
+```
+
+### IO Style
+
+| Topic       | Summary                                                                                                                                                       |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Matchmaking | Open-lobby routing to the fullest room below capacity; room counts are heartbeated and new lobbies are auto-created when needed.                              |
+| Netcode     | Server-authoritative with interpolation. Client sends input intents and interpolates. Server owns movement, bounds, room membership, and canonical snapshots. |
+| Tick Rate   | 10 ticks/sec (`100ms`) with lightweight periodic room snapshots.                                                                                              |
+| Physics     | Low to medium intensity; server-authoritative kinematic movement, escalating to a physics engine only when collisions get complex.                            |
+
+**Actors**
+
+- **Key**: `matchmaker["main"]`
+- **Responsibility**: Routes players into the fullest open lobby and tracks reservations and occupancy.
+- **Actions**
+  - `findLobby`
+  - `pendingPlayerConnected`
+  - `updateMatch`
+  - `closeMatch`
+- **Queues**
+  - `findLobby`
+  - `pendingPlayerConnected`
+  - `updateMatch`
+  - `closeMatch`
+- **State**
+  - SQLite
+  - `matches`
+  - `pending_players`
+  - Occupancy includes pending reservations
+
+- **Key**: `match[matchId]`
+- **Responsibility**: Runs per-match movement simulation and broadcasts snapshots.
+- **Actions**
+  - `connect`
+  - `setInput`
+- **Queues**
+  - None
+- **State**
+  - JSON
+  - `players`
+  - `inputs`
+  - `movement state`
+  - `snapshot cache`
+
+**Lifecycle**
+
+```mermaid
+sequenceDiagram
+	participant C as Client
+	participant MM as matchmaker
+	participant M as match
+
+	C->>MM: findLobby()
+	alt no open lobby
+		MM->>M: create(matchId)
+	end
+	MM-->>C: {matchId, playerId}
+	C->>M: connect(playerId)
+	M->>MM: pendingPlayerConnected(matchId, playerId)
+	MM-->>M: accepted
+	Note over M: fixed tick simulation
+	M-->>C: snapshot events
+	M->>MM: closeMatch(matchId)
+```
+
+### Open World
+
+| Topic       | Summary                                                                                                                                                             |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Matchmaking | Client-driven chunk routing from world coordinates, with nearby chunk windows preloaded via adjacent chunk connections.                                             |
+| Netcode     | Hybrid for sandbox (client movement with validation) or server-authoritative for MMO-like flows. Server owns chunk routing, persistence, and canonical world state. |
+| Tick Rate   | 10 ticks/sec per chunk actor (`100ms`), so load scales with active chunks.                                                                                          |
+| Physics     | Medium to high at scale; chunk-local simulation can be server-authoritative (MMO-like) or client movement with server validation (sandbox-like).                    |
+
+**Actors**
+
+- **Key**: `chunk[worldId,chunkX,chunkY]`
+- **Responsibility**: Owns chunk-local players, blocks, movement tick, and chunk membership.
+- **Actions**
+  - `connect`
+  - `enterChunk`
+  - `addPlayer`
+  - `setInput`
+  - `leaveChunk`
+  - `removePlayer`
+- **Queues**
+  - None
+- **State**
+  - JSON
+  - `connections`
+  - `players`
+  - `blocks` scoped to one chunk key
+
+**Lifecycle**
+
+```mermaid
+sequenceDiagram
+	participant C as Client
+	participant CH as chunk
+
+	Note over C: resolve chunk keys from world position
+	loop each visible chunk
+		C->>CH: connect(worldId, chunkX, chunkY, playerId)
+		Note over CH: store connection metadata
+	end
+	C->>CH: enterChunk/addPlayer
+	loop movement updates
+		C->>CH: setInput(...)
+		CH-->>C: snapshot
+	end
+	C->>CH: leaveChunk/removePlayer or disconnect
+	Note over CH: remove membership and metadata
+```
+
+### Party
+
+| Topic       | Summary                                                                                                           |
+| ----------- | ----------------------------------------------------------------------------------------------------------------- |
+| Matchmaking | Host-created private party flow using party codes and explicit joins.                                             |
+| Netcode     | Server-authoritative (basic logic). Server owns membership, host permissions, and phase transitions.              |
+| Tick Rate   | No continuous tick; updates are event-driven (`join`, `start`, `finish`).                                         |
+| Physics     | Low intensity for lobby-first flows; usually no dedicated physics or indexing unless you add realtime mini-games. |
+
+**Actors**
+
+- **Key**: `matchmaker["main"]`
+- **Responsibility**: Handles party create/join flow, validates join tickets, and tracks party size.
+- **Actions**
+  - `createParty`
+  - `joinParty`
+  - `verifyJoin`
+  - `updatePartySize`
+  - `closeParty`
+- **Queues**
+  - `createParty`
+  - `joinParty`
+  - `verifyJoin`
+  - `updatePartySize`
+  - `closeParty`
+- **State**
+  - SQLite
+  - `parties`
+  - `join_tickets` for party lookup and join validation
+
+- **Key**: `match[matchId]`
+- **Responsibility**: Owns party members, host role, ready flags, and phase transitions.
+- **Actions**
+  - `connect`
+  - `startGame`
+  - `finishGame`
+- **Queues**
+  - None
+- **State**
+  - JSON
+  - `members`
+  - `host`
+  - `ready state`
+  - `phase`
+  - `party events`
+
+**Lifecycle**
+
+### Host Flow
+
+```mermaid
+sequenceDiagram
+	participant H as Host Client
+	participant MM as matchmaker
+	participant M as match
+
+	H->>MM: createParty()
+	MM-->>H: {matchId, partyCode, playerId, joinToken}
+	H->>M: connect(playerId, joinToken)
+	M->>MM: verifyJoin(...)
+	MM-->>M: allowed
+	M->>MM: updatePartySize(playerCount)
+	H->>M: startGame() / finishGame()
+	M->>MM: closeParty(matchId)
+```
+
+### Joiner Flow
+
+```mermaid
+sequenceDiagram
+	participant J as Joiner Client
+	participant MM as matchmaker
+	participant M as match
+
+	J->>MM: joinParty(partyCode)
+	MM-->>J: {matchId, playerId, joinToken}
+	J->>M: connect(playerId, joinToken)
+	M->>MM: verifyJoin(...)
+	MM-->>M: allowed / denied
+	M->>MM: updatePartySize(playerCount)
+```
+
+### Ranked
+
+| Topic       | Summary                                                                                                                                           |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Matchmaking | ELO-based queue pairing with a widening search window as wait time increases.                                                                     |
+| Netcode     | Hybrid. Client owns movement with local prediction and interpolation. Server owns projectiles, hit resolution, match results, and rating updates. |
+| Tick Rate   | 20 ticks/sec (`50ms`) with fixed live ticks for deterministic pacing and broadcast cadence.                                                       |
+| Physics     | Medium to high intensity; client movement with server validation and server-authoritative combat/hit resolution.                                  |
+
+**Actors**
+
+- **Key**: `matchmaker["main"]`
+- **Responsibility**: Runs rating-based queueing, pairing, assignment persistence, and completion fanout.
+- **Actions**
+  - `queueForMatch`
+  - `unqueueForMatch`
+  - `matchCompleted`
+- **Queues**
+  - `queueForMatch`
+  - `unqueueForMatch`
+  - `matchCompleted`
+- **State**
+  - SQLite
+  - `player_pool`
+  - `matches`
+  - `assignments` with rating window and connection scoping
+
+- **Key**: `match[matchId]`
+- **Responsibility**: Runs ranked match phase, score, and winner reporting.
+- **Actions**
+  - `connect`
+  - Gameplay actions
+- **Queues**
+  - None
+- **State**
+  - JSON
+  - `phase`
+  - `players`
+  - `score`
+  - `winner`
+  - `completion payload`
+
+- **Key**: `player[username]`
+- **Responsibility**: Stores canonical player MMR and win/loss profile.
+- **Actions**
+  - `initialize`
+  - `getRating`
+  - `applyMatchResult`
+- **Queues**
+  - None
+- **State**
+  - JSON
+  - `rating`
+  - `wins`
+  - `losses`
+  - `match counters`
+
+- **Key**: `leaderboard["main"]`
+- **Responsibility**: Stores and serves top-ranked players.
+- **Actions**
+  - `updatePlayer`
+- **Queues**
+  - None
+- **State**
+  - SQLite
+  - Leaderboard score rows
+  - Top-list ordering
+
+**Lifecycle**
+
+```mermaid
+sequenceDiagram
+	participant C as Client
+	participant MM as matchmaker
+	participant P as player
+	participant M as match
+	participant LB as leaderboard
+
+	C->>MM: queueForMatch(username)
+	MM->>P: initialize/getRating
+	P-->>MM: rating
+	Note over MM: store queue row + retry pairing
+	MM->>M: create(matchId, assigned players)
+	MM-->>C: assignmentReady
+	C->>M: connect(username)
+	M->>MM: matchCompleted(...)
+	MM->>P: applyMatchResult(...)
+	MM->>LB: updatePlayer(...)
+	Note over MM: remove matches + assignments rows
+```
+
+### Turn-Based
+
+| Topic       | Summary                                                                                                                                                     |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Matchmaking | Async private-invite and public-queue pairing in the same pattern.                                                                                          |
+| Netcode     | Server-authoritative (basic logic). Client can draft moves before submit. Server owns turn ownership, committed move log, turn order, and completion state. |
+| Tick Rate   | No continuous tick; move submission and turn transitions drive updates.                                                                                     |
+| Physics     | Very low intensity; no realtime physics loop, just discrete rules validation. Indexing is optional and mostly for board or query convenience at scale.      |
+
+**Actors**
+
+- **Key**: `matchmaker["main"]`
+- **Responsibility**: Handles private invite and public queue pairing for async matches.
+- **Actions**
+  - `createGame`
+  - `joinByCode`
+  - `queueForMatch`
+  - `unqueueForMatch`
+  - `closeMatch`
+- **Queues**
+  - `createGame`
+  - `joinByCode`
+  - `queueForMatch`
+  - `unqueueForMatch`
+  - `closeMatch`
+- **State**
+  - SQLite
+  - `matches`
+  - `player_pool`
+  - `assignments` for invite and queue mapping
+
+- **Key**: `match[matchId]`
+- **Responsibility**: Owns board state, turn order, move validation, and final result.
+- **Actions**
+  - `connect`
+  - `makeMove`
+- **Queues**
+  - None
+- **State**
+  - JSON
+  - `board`
+  - `turns`
+  - `players`
+  - `connection presence`
+  - `result`
+
+**Lifecycle**
+
+### Public Queue
+
+```mermaid
+sequenceDiagram
+	participant A as Client A
+	participant B as Client B
+	participant MM as matchmaker
+	participant M as match
+
+	A->>MM: queueForMatch()
+	B->>MM: queueForMatch()
+	Note over MM: pair first two queued players
+	MM->>M: create(matchId) + seed X/O players
+	MM-->>A: assignment/match info
+	MM-->>B: assignment/match info
+	A->>M: connect(playerId)
+	B->>M: connect(playerId)
+	A->>M: makeMove()
+	B->>M: makeMove()
+	opt all players disconnected for timeout
+		Note over M: destroy after idle timeout
+	end
+	M->>MM: closeMatch(matchId)
+```
+
+### Private Invite
+
+```mermaid
+sequenceDiagram
+	participant A as Client A
+	participant B as Client B
+	participant MM as matchmaker
+	participant M as match
+
+	A->>MM: createGame()
+	MM-->>A: {matchId, playerId, inviteCode}
+	B->>MM: joinByCode(inviteCode)
+	MM->>M: create(matchId) + seed X/O players
+	MM-->>A: assignment/match info
+	MM-->>B: assignment/match info
+	A->>M: connect(playerId)
+	B->>M: connect(playerId)
+	A->>M: makeMove()
+	B->>M: makeMove()
+	M->>MM: closeMatch(matchId)
+```
+
+### Idle
+
+| Topic       | Summary                                                                                                                                                    |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Matchmaking | No matchmaker; each player uses a direct per-player actor and a shared leaderboard actor.                                                                  |
+| Netcode     | Server-authoritative (basic logic). Client owns UI and build intent. Server owns resources, production rates, building validation, and leaderboard totals. |
+| Tick Rate   | No continuous tick; use `c.schedule.after(...)` for coarse intervals and compute offline catch-up from elapsed wall time.                                  |
+| Physics     | None for standard idle loops; transitions are discrete (`build`, `collect`, `upgrade`) and do not need spatial indexing.                                   |
+
+**Actors**
+
+- **Key**: `world[playerId]`
+- **Responsibility**: Owns one player's progression, buildings, production scheduling, and state updates.
+- **Actions**
+  - `initialize`
+  - `build`
+  - `collectProduction`
+- **Queues**
+  - None
+- **State**
+  - JSON
+  - Per-player buildings
+  - `resources`
+  - `timers`
+  - `progression state`
+
+- **Key**: `leaderboard["main"]`
+- **Responsibility**: Stores global scores and serves leaderboard updates.
+- **Actions**
+  - `updateScore`
+- **Queues**
+  - `updateScore`
+- **State**
+  - SQLite
+  - `scores` table keyed by player
+  - Current leaderboard totals
+
+**Lifecycle**
+
+```mermaid
+sequenceDiagram
+	participant C as Client
+	participant W as world
+	participant LB as leaderboard
+
+	C->>W: getOrCreate(playerId) + initialize()
+	Note over W: seed state + schedule collection
+	W-->>C: stateUpdate
+	loop gameplay loop
+		C->>W: build() / collectProduction()
+		W->>LB: updateScore(...)
+	Note over LB: upsert scores
+	LB-->>C: leaderboardUpdate
+	W-->>C: stateUpdate
+	end
+```
+
+_Source doc path: /cookbook/multiplayer-game_