Files
sor/Delta-updates.md

6.3 KiB

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<string, UnitDeltaOrSnapshot>?
  • PlayerStatsByAccount: Dictionary<string, PlayerStatsDelta>?
  • PublicCountsByAccount: Dictionary<string, PublicCountsDelta>?
    • 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.