Add Delta-updates design plan for multi-player state deltas

This commit is contained in:
Shard
2026-03-27 12:02:58 +00:00
parent d2575837ab
commit bd640c1eee
+214
View File
@@ -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<string, UnitDeltaOrSnapshot>`
- `PlayerStatsByAccount: Dictionary<string, PlayerStatsDelta>`
- `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.