# Delta-updates ## Context Current `game.state_delta` is structurally 2-player (viewer + one opponent). In 3+ player sessions this causes partial updates (e.g., tile updates arrive, but a third player's ArchSpirit/unit visual lags until another action). Because we're still in dev with no active production players, this plan is a **direct cutover** of the existing delta system (no v1/v2 dual-run, no compatibility scaffolding). --- ## Current system constraints (what must change) ### Contract constraints (`GameMessages.cs`) Current `GameStateDelta` includes single-opponent fields: - `OpponentHandCount`, `OpponentDeckCount` - `OwnArchSpiritDelta`, `OpponentArchSpiritDelta` - `OwnStatsDelta`, `OpponentStatsDelta` These fields cannot represent N-player state. ### Differ constraints (`GameStateDiffer.cs`) `ComputeDelta(prev, next, viewerAccountId)` chooses one opponent via `FirstOrDefault(...)`, so only one non-viewer player can be represented in several categories. ### Push constraints (`GameHandlerBase.cs`) P1/P2 receive deltas while seats 3+ receive full state, causing mixed consistency and harder debugging. ### Client constraints (`Client/autoloads/Game.gd`) Delta apply path assumes only local + one opponent (`get_opponent()` / own vs opponent fields). --- ## Full cutover target (replace current delta contract) Replace the **existing** `GameStateDelta` payload shape with an account-scoped, multi-entity schema. ## New `GameStateDelta` shape (post-cutover) - `StateVersion: int` - `ChangedTiles: TileDelta[]?` - `UnitsAdded: UnitSnapshot[]?` (must include `ownerAccountId`) - `UnitsRemoved: string[]?` (instance IDs) - `UnitsChanged: UnitDelta[]?` (instance ID keyed) - `ArchSpiritByAccount: Dictionary?` - `PlayerStatsByAccount: Dictionary?` - `PublicCountsByAccount: Dictionary?` - `handCount`, `deckCount`, `discardCount` (optional as needed) - `PrivateByViewer: PrivateViewerDelta?` - `HandAdded`, `HandRemovedIds`, `DiscardAdded` - `MetaDelta: GameMetaDelta?` ### Design rules - No `own/opponent` naming anywhere in wire payload. - All public/player state keyed by `accountId`. - Private info strictly isolated under `PrivateByViewer`. - Delta remains sparse (null = no change). --- ## Component-by-component change list ## 1) `Server/src/SOR.Game/GameMessages.cs` ### Required edits 1. Replace current `GameStateDelta` record fields with new account-scoped fields. 2. Add/rename DTOs: - `UnitSnapshot` (for new units with owner context) - `PublicCountsDelta` - `PrivateViewerDelta` 3. Keep `TileDelta`, `UnitDelta`, `PlayerStatsDelta`, `GameMetaDelta` where reusable. ### Acceptance check - JSON payload for `game.state_delta` can represent updates for any number of players in one push. --- ## 2) `Server/src/SOR.Game/GameStateDiffer.cs` ### Required edits 1. Rewrite `ComputeDelta(prev, next, viewerAccountId)` to: - Diff all players by `accountId`. - Build per-account maps for archspirit/stats/public counts. - Build `PrivateByViewer` only from viewer's own hidden zones. 2. Replace single-opponent logic (`FirstOrDefault`) entirely. 3. Ensure `UnitsAdded` carries ownership deterministically. 4. Update spectator computation to use same core diff machinery with no private section. ### Acceptance check - In 3+ player test fixtures, a single delta includes all changed players' arch/unit/stat transitions. --- ## 3) `Server/src/SOR.Game/Handlers/GameHandlerBase.cs` ### Required edits 1. Remove split strategy (delta for seats 1/2, full-state for seats 3+). 2. For normal action updates, send `game.state_delta` to **all session players**. 3. Build each player's delta from same prev/next snapshots but viewer-specific private section. 4. Spectators receive public-only delta (same message type, private section omitted/null). 5. Keep full `game.state_update` for bootstrap/reconnect/missed-version recovery only. ### Acceptance check - All active participants receive delta path uniformly for same stateVersion progression. --- ## 4) `Client/origin-client/autoloads/Game.gd` ### Required edits 1. Replace `_apply_delta()` implementation to consume the new `GameStateDelta` shape. 2. Remove assumptions based on `get_opponent()` for delta application. 3. Apply updates by account map: - locate player in `state.players` by `accountId` - apply arch stats/unit updates per-account - apply viewer private hand/discard updates only from `PrivateByViewer` 4. Keep state-version guards and full-sync fallback on gap/malformed payload. 5. Update helper methods as needed (e.g., utility to get player dict by account id quickly). ### Acceptance check - Any opponent (not just “first opponent”) placing ArchSpirit appears immediately on all clients after one delta. --- ## 5) `Client/origin-client/scenes/game/game_screen.gd` ### Required edits 1. Audit for any implicit “single opponent” rendering assumptions tied to delta-fed data. 2. Ensure ownership/highlight lists are rebuilt from full `state.players` each update (already mostly true). 3. Verify no UI panel relies on old opponent-only count fields. ### Acceptance check - 3+ player HUD and board visuals remain consistent after each delta without waiting for secondary actions. --- ## 6) Tests and fixtures ### Server tests - Add golden prev/next snapshots for: 1. 2-player baseline action 2. 3-player arch placements in sequence 3. 4-player mixed action turn 4. spectator-visible transitions - Assert delta JSON contains correct account-scoped maps and no hidden-info leaks. ### Client tests (or scripted replay harness) - Feed ordered deltas and verify convergence. - Feed version gaps/out-of-order and verify fallback `request_sync()` behavior. ### Acceptance check - No repro of delayed ArchSpirit/unit appearance in 3+ session replay. --- ## Implementation order (cutover) 1. Update DTO contract (`GameMessages.cs`). 2. Update differ generation (`GameStateDiffer.cs`). 3. Update push fanout (`GameHandlerBase.cs`). 4. Update client delta apply (`Game.gd`). 5. Run fixture + replay validation. 6. Remove obsolete code paths/fields referencing own-vs-opponent deltas. --- ## Done criteria - `game.state_delta` natively supports N-player + spectators. - No own/opponent delta fields remain. - No mixed per-seat push strategy in active sessions. - 3+ player ArchSpirit/unit updates are immediate and deterministic on all clients.