171 lines
6.3 KiB
Markdown
171 lines
6.3 KiB
Markdown
# 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.
|