From bd640c1eee011a19867dcbd39f9309118a94cb1f Mon Sep 17 00:00:00 2001 From: Shard Date: Fri, 27 Mar 2026 12:02:58 +0000 Subject: [PATCH] Add Delta-updates design plan for multi-player state deltas --- Delta-updates.md | 214 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 Delta-updates.md diff --git a/Delta-updates.md b/Delta-updates.md new file mode 100644 index 0000000..e108079 --- /dev/null +++ b/Delta-updates.md @@ -0,0 +1,214 @@ +# Delta-updates + +## Context + +Current `game.state_delta` infrastructure was designed around a 2-player worldview (viewer + one opponent). That assumption now leaks in custom lobbies with 3+ players and will become more problematic with larger sessions and spectators. + +Observed symptom in 3-player custom game: +- Client 3 places ArchSpirit. +- Other clients see tile occupancy update immediately. +- ArchSpirit visual/unit state does not appear until a later action triggers another state update. + +This is a data-shape mismatch, not just a rendering issue. + +--- + +## Current design structure + +### Message contract (server → client) +`Server/src/SOR.Game/GameMessages.cs` + +`GameStateDelta` currently includes (abridged): +- `ChangedTiles` +- `AddedUnits` / `RemovedUnitIds` / `ChangedUnits` +- `HandAdded` / `HandRemovedIds` / `DiscardAdded` +- `OpponentHandCount` / `OpponentDeckCount` +- `OwnArchSpiritDelta` / `OpponentArchSpiritDelta` +- `OwnStatsDelta` / `OpponentStatsDelta` +- `MetaDelta` + +This schema encodes exactly one “opponent lane”. + +### Differ logic +`Server/src/SOR.Game/GameStateDiffer.cs` + +`ComputeDelta(prev, next, viewerAccountId)` selects one opponent via: +- `FirstOrDefault(p => p.AccountId != viewerAccountId)` + +So for N-player sessions, only one non-viewer player is represented in opponent fields. + +### Push strategy +`Server/src/SOR.Game/Handlers/GameHandlerBase.cs` + +Current approach after action: +- P1/P2 receive `game.state_delta` (viewer-specific deltas). +- Additional players (seats 3+) receive full `game.state_update`. +- Spectators receive delta/full based on branch and emptiness checks. + +This creates inconsistent data fidelity across participants in >2-player sessions. + +### Client delta application +`Client/origin-client/autoloads/Game.gd` + +`_apply_delta()` applies: +- own arch via `ownArchSpiritDelta` to local player +- opponent arch via `opponentArchSpiritDelta` to `get_opponent()` (first opponent) + +So multi-opponent updates are inherently lossy under current contract. + +--- + +## Why this will degrade at scale + +As player count and spectator count increase: +- A single-opponent delta shape cannot represent all relevant changes. +- Clients drift into “partially updated” state until a full-state sync occurs. +- UX appears nondeterministic (tiles updated, units missing, stale HUD numbers). +- Complexity increases in client-side heuristics trying to infer ownership/placement. + +The root issue is contract shape, not patchable with isolated client fixes. + +--- + +## Proposed revision + +## 1) Introduce a normalized multi-entity delta schema + +Add a v2 payload (`game.state_delta_v2`) with per-entity maps/lists keyed by accountId or instanceId. + +### Proposed `GameStateDeltaV2` +- `StateVersion` +- `ChangedTiles: TileDelta[]` +- `UnitsAdded: UnitSnapshot[]` (includes ownerAccountId) +- `UnitsRemoved: string[]` (instanceIds) +- `UnitsChanged: UnitDelta[]` (instanceId keyed) +- `ArchSpiritByAccount: Dictionary` +- `PlayerStatsByAccount: Dictionary` +- `PrivateByViewer` (viewer-only zones): + - `HandAdded` + - `HandRemovedIds` + - `DiscardAdded` +- `PublicCountsByAccount`: `{ handCount, deckCount, discardCount? }` +- `MetaDelta` + +Notes: +- Separate private and public sections to preserve hidden-information rules. +- Remove “own/opponent” field naming from wire format. + +## 2) Make generation player-count aware + +In `GameHandlerBase`: +- If `playerCount == 2` and both clients support v2: send `state_delta_v2`. +- If `playerCount > 2`: prefer v2 to all players. +- If client does not advertise v2 capability: fallback to full `game.state_update`. + +Do **not** mix “delta for some seats, full-state for other seats” in same session generation path except compatibility fallback. + +## 3) Add explicit capability negotiation + +Client declares capabilities on `game.ready` (or equivalent session-init message), e.g.: +- `clientCapabilities: ["state_delta_v2"]` + +Server records per-connection capability and chooses push format accordingly. + +## 4) Client application path changes + +In `Client/origin-client/autoloads/Game.gd`: +- Add `_apply_delta_v2()`. +- Resolve players by `accountId` directly (no `get_opponent()` assumptions). +- Apply arch/unit/stats updates from account-keyed structures. +- Keep existing `_apply_delta()` only for legacy format. + +## 5) Spectator model + +Spectators should receive one consistent public v2 stream: +- No private hand card identities. +- Public counts/states for all players. +- Full board/unit/arch state transitions for all players. + +This avoids extra spectator-specific shape forks over time. + +--- + +## Migration plan + +### Phase 0: Safety + diagnostics +- Add telemetry counters: + - push type used (full, delta v1, delta v2) + - out-of-order or version-gap resync rate + - client-requested full sync frequency +- Add logging guardrails around state-version discontinuities. + +### Phase 1: Add v2 in parallel +- Implement v2 DTOs and differ logic (`ComputeDeltaV2`). +- Keep existing v1 unchanged. +- Add capability handshake path. + +### Phase 2: Dual-serve with fallback +- Serve v2 to capable clients. +- Serve full-state to non-capable clients in >2-player sessions. +- Keep v1 only for 2-player legacy clients. + +### Phase 3: Client rollout +- Implement `_on_server_push("game.state_delta_v2")` and `_apply_delta_v2()`. +- Add strict validation and soft-fallback to `request_sync()` if malformed payload. + +### Phase 4: Default shift +- Make v2 default for all sessions where both ends support it. +- Remove v1-specific assumptions from gameplay UI code (`get_opponent()`-only paths). + +### Phase 5: Decommission v1 +- After adoption threshold and soak period, retire v1 delta contract. + +--- + +## Validation strategy + +### Deterministic scenario tests +1. 2-player baseline: parity with existing behavior. +2. 3-player FFA: each player places ArchSpirit in sequence. +3. 4+ player game: multiple simultaneous board/unit changes. +4. Spectator joins mid-match and remains consistent through turns. + +### Invariants to assert +- For each `stateVersion`, all clients converge to same public board/unit state. +- No missing unit/arch meshes after an acknowledged action. +- No client remains stale without either next delta or explicit resync. + +### Tooling +- Add golden JSON fixtures for prev/next snapshots and expected v2 deltas. +- Add replay harness to feed ordered/unordered pushes and verify convergence. + +--- + +## Risks and mitigations + +- **Risk:** Payload size growth in large sessions. + - **Mitigation:** Keep delta sparse; only changed entities; optional compression at transport layer. + +- **Risk:** Capability mismatch during deploy. + - **Mitigation:** Explicit negotiation + conservative full-state fallback. + +- **Risk:** Hidden-information leakage. + - **Mitigation:** Strict separation of `PrivateByViewer` and public account-scoped counts. + +- **Risk:** Complex migration bugs. + - **Mitigation:** Parallel-run v1/v2 in staging with differential checks. + +--- + +## Recommended immediate hotfix (before v2 lands) + +For sessions where `playerCount > 2`: +- Send full `game.state_update` to **all** players (including seats 1 and 2). + +This removes the current inconsistency immediately while v2 is implemented. + +--- + +## Success criteria + +- No delayed appearance of ArchSpirits/units in 3+ player sessions. +- Reduced full-resync requests during active games. +- Spectator views remain consistent without bespoke patch logic. +- Delta contract no longer encodes 1-opponent assumptions.