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,OpponentDeckCountOwnArchSpiritDelta,OpponentArchSpiritDeltaOwnStatsDelta,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: intChangedTiles: TileDelta[]?UnitsAdded: UnitSnapshot[]?(must includeownerAccountId)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/opponentnaming 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
- Replace current
GameStateDeltarecord fields with new account-scoped fields. - Add/rename DTOs:
UnitSnapshot(for new units with owner context)PublicCountsDeltaPrivateViewerDelta
- Keep
TileDelta,UnitDelta,PlayerStatsDelta,GameMetaDeltawhere reusable.
Acceptance check
- JSON payload for
game.state_deltacan represent updates for any number of players in one push.
2) Server/src/SOR.Game/GameStateDiffer.cs
Required edits
- Rewrite
ComputeDelta(prev, next, viewerAccountId)to:- Diff all players by
accountId. - Build per-account maps for archspirit/stats/public counts.
- Build
PrivateByVieweronly from viewer's own hidden zones.
- Diff all players by
- Replace single-opponent logic (
FirstOrDefault) entirely. - Ensure
UnitsAddedcarries ownership deterministically. - 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
- Remove split strategy (delta for seats 1/2, full-state for seats 3+).
- For normal action updates, send
game.state_deltato all session players. - Build each player's delta from same prev/next snapshots but viewer-specific private section.
- Spectators receive public-only delta (same message type, private section omitted/null).
- Keep full
game.state_updatefor 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
- Replace
_apply_delta()implementation to consume the newGameStateDeltashape. - Remove assumptions based on
get_opponent()for delta application. - Apply updates by account map:
- locate player in
state.playersbyaccountId - apply arch stats/unit updates per-account
- apply viewer private hand/discard updates only from
PrivateByViewer
- locate player in
- Keep state-version guards and full-sync fallback on gap/malformed payload.
- 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
- Audit for any implicit “single opponent” rendering assumptions tied to delta-fed data.
- Ensure ownership/highlight lists are rebuilt from full
state.playerseach update (already mostly true). - 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:
- 2-player baseline action
- 3-player arch placements in sequence
- 4-player mixed action turn
- 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)
- Update DTO contract (
GameMessages.cs). - Update differ generation (
GameStateDiffer.cs). - Update push fanout (
GameHandlerBase.cs). - Update client delta apply (
Game.gd). - Run fixture + replay validation.
- Remove obsolete code paths/fields referencing own-vs-opponent deltas.
Done criteria
game.state_deltanatively 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.