Add Delta-Sync-flow.md: end-to-end delta sync reference
Documents the complete delta lifecycle from server action handler through GameStateDiffer computation, PushStateToPlayersAsync dispatch, Redis transport, and client-side application in Game.gd/_apply_delta. Includes line numbers, code snippets, wire types, and design invariants. Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
@@ -0,0 +1,607 @@
|
||||
# Delta Sync Flow -- End-to-End Reference
|
||||
|
||||
This document traces the full lifecycle of a game state delta: from the moment
|
||||
a player action is received on the server, through delta computation,
|
||||
serialisation, transport, and final application on the client.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#1-overview-)
|
||||
2. [Wire Types](#2-wire-types-)
|
||||
3. [Server -- Action Handler](#3-server----action-handler-)
|
||||
4. [Server -- State Persistence (SaveStateAsync)](#4-server----state-persistence-savestateasync-)
|
||||
5. [Server -- Delta Computation (GameStateDiffer)](#5-server----delta-computation-gamestatediffer-)
|
||||
6. [Server -- Push Decision (PushStateToPlayersAsync)](#6-server----push-decision-pushstatetoplayersasync-)
|
||||
7. [Transport -- Redis Pub/Sub via IClientPush](#7-transport----redis-pubsub-via-iclientpush-)
|
||||
8. [Client -- WebSocket Reception (Network.gd)](#8-client----websocket-reception-networkgd-)
|
||||
9. [Client -- Push Dispatch (Game.gd)](#9-client----push-dispatch-gamegd-)
|
||||
10. [Client -- Delta Application (_apply_delta)](#10-client----delta-application-applydelta-)
|
||||
11. [Client -- Unit Merge (_merge_unit_delta)](#11-client----unit-merge-mergeunitdelta-)
|
||||
12. [Fallback and Resync Paths](#12-fallback-and-resync-paths-)
|
||||
13. [Design Invariants](#13-design-invariants-)
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
```
|
||||
Player action (WebSocket request)
|
||||
| v
|
||||
[Handler] load session (FOR UPDATE lock)
|
||||
| capture prevStateJson BEFORE mutation
|
||||
| v
|
||||
[GameEngine] apply action -> newState
|
||||
| v
|
||||
[SaveStateAsync] serialize newState -> DB, commit tx
|
||||
| v
|
||||
[PushStateToPlayersAsync] compute per-viewer deltas
|
||||
| (or fallback to full state)
|
||||
+---> player A delta ---> Redis channel push:{accountA}
|
||||
+---> player B delta ---> Redis channel push:{accountB}
|
||||
+---> spectators ---> full state_update (never delta)
|
||||
| v (gateway subscribes to Redis and forwards)
|
||||
WebSocket push -> client
|
||||
| v
|
||||
[Network.gd] parse JSON, emit message_received signal
|
||||
| v
|
||||
[Game.gd _on_server_push] match game.state_delta
|
||||
| version guard: too old -> drop; gap -> fetch full
|
||||
| v
|
||||
[_apply_delta] 10-section merge loop -> state_updated.emit(state)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Wire Types
|
||||
|
||||
**File:** `Server/src/SOR.Game/GameMessages.cs`
|
||||
|
||||
### Envelope (line 506)
|
||||
```csharp
|
||||
public sealed record GameStateDeltaPush(GameStateDelta Delta);
|
||||
```
|
||||
Sent as the payload of a `game.state_delta` push message.
|
||||
|
||||
### GameStateDelta (lines 512-523)
|
||||
```csharp
|
||||
public sealed record GameStateDelta(
|
||||
int StateVersion,
|
||||
IReadOnlyList<TileDelta>? ChangedTiles,
|
||||
IReadOnlyList<UnitSnapshot>? UnitsAdded,
|
||||
IReadOnlyList<string>? UnitsRemoved,
|
||||
IReadOnlyList<UnitDelta>? UnitsChanged,
|
||||
IReadOnlyDictionary<string, ArchSpiritUpdate>? ArchSpiritByAccount,
|
||||
IReadOnlyDictionary<string, PlayerStatsDelta>? PlayerStatsByAccount,
|
||||
IReadOnlyDictionary<string, PublicCountsDelta>? PublicCountsByAccount,
|
||||
PrivateViewerDelta? PrivateByViewer,
|
||||
GameMetaDelta? MetaDelta,
|
||||
IReadOnlyList<ActiveEffectDto>? ActiveEffects = null);
|
||||
```
|
||||
**Sparse pattern:** a `null` collection means no change in that category.
|
||||
`ActiveEffects` is always populated when effects exist -- full replacement, not delta.
|
||||
|
||||
### Sub-types
|
||||
|
||||
| Type | Lines | Description |
|
||||
|---|---|---|
|
||||
| `TileDelta` | 525-536 | Board coord + changed base1/base2/affinity/occupant/ruin. `OccupantCleared` and `RuinCleared` are explicit booleans to distinguish set-to-null from no-change. |
|
||||
| `UnitSnapshot` | 538-540 | Full `CardInstanceDto` with `OwnerAccountId` -- used for newly placed units. |
|
||||
| `UnitDelta` | 542-561 | Partial unit update; nullable fields; `null` = unchanged. |
|
||||
| `PublicCountsDelta` | 563-566 | Hand/deck/discard counts visible to opponents (not actual cards). |
|
||||
| `ArchSpiritUpdate` | 568-570 | Either a `Full` snapshot or a `Delta` -- server sends full on first sight, delta thereafter. |
|
||||
| `PrivateViewerDelta` | 572-575 | Own hand additions, removals by ID, discard additions. Never sent to opponents. |
|
||||
| `PlayerStatsDelta` | 577-582 | SP, ST, and zone counts per account. |
|
||||
| `GameMetaDelta` | 584-587 | Phase, active player account ID, turn number. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Server -- Action Handler
|
||||
|
||||
**Example file:** `Server/src/SOR.Game/Handlers/GameDrawHandler.cs`
|
||||
|
||||
Every game-action handler follows the same four-step skeleton:
|
||||
|
||||
```csharp
|
||||
// GameDrawHandler.cs lines 36-48
|
||||
var session = await LoadActiveSessionAsync(_gameDb, req.SessionId, actorId, ct);
|
||||
var prevStateJson = session.StateJson!; // <- capture BEFORE mutation
|
||||
var state = GameEngine.Deserialize(prevStateJson);
|
||||
var (newState, _) = GameEngine.Draw(state, actorId); // <- engine returns new object
|
||||
await SaveStateAsync(_gameDb, session, newState, actorId, "game.draw",
|
||||
JsonSerializer.Serialize(req), ct); // <- persist + commit tx
|
||||
await PushStateToPlayersAsync(_clientPush, session, newState, ct, prevStateJson);
|
||||
```
|
||||
**Critical ordering:**
|
||||
- `prevStateJson` captured from `session.StateJson` **before** calling `SaveStateAsync`.
|
||||
- `SaveStateAsync` overwrites `session.StateJson` with the new state.
|
||||
- `PushStateToPlayersAsync` receives both snapshots to compute the diff.
|
||||
|
||||
### LoadActiveSessionAsync (GameHandlerBase.cs lines 29-61)
|
||||
|
||||
Begins a PostgreSQL transaction and issues `SELECT ... FOR UPDATE` to serialize
|
||||
concurrent mutations on the same session row. Lock held until `SaveStateAsync` commits.
|
||||
|
||||
```csharp
|
||||
var session = await gameDb.GameSessions
|
||||
.FromSqlInterpolated($"""
|
||||
SELECT * FROM game.game_sessions
|
||||
WHERE "Id" = {sessionId}
|
||||
FOR UPDATE
|
||||
""")
|
||||
.SingleOrDefaultAsync(ct);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Server -- State Persistence (SaveStateAsync)
|
||||
|
||||
**File:** `Server/src/SOR.Game/Handlers/GameHandlerBase.cs`, lines 68-90
|
||||
|
||||
```csharp
|
||||
internal static async Task SaveStateAsync(
|
||||
GameDbContext gameDb, GameSession session, GameState state,
|
||||
string actorId, string actionType, string? payloadJson,
|
||||
CancellationToken ct, string? resultJson = null)
|
||||
{
|
||||
var seqNum = state.NextActionSequence++; // increment; saved JSON reflects consumed number
|
||||
session.StateJson = GameEngine.Serialize(state);
|
||||
session.LastActionAt = DateTimeOffset.UtcNow;
|
||||
gameDb.ActionLogs.Add(new GameActionLog { SequenceNumber = seqNum, ... });
|
||||
await gameDb.SaveChangesAsync(ct);
|
||||
await gameDb.Database.CommitTransactionAsync(ct);
|
||||
}
|
||||
```
|
||||
`state.NextActionSequence` becomes the `StateVersion` carried in deltas --
|
||||
the client uses this integer to detect gaps.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 5. Server -- Delta Computation (GameStateDiffer)
|
||||
|
||||
**File:** `Server/src/SOR.Game/GameStateDiffer.cs`
|
||||
|
||||
### ComputeDelta -- viewer-specific (line 21)
|
||||
|
||||
```csharp
|
||||
public static GameStateDelta ComputeDelta(GameState prev, GameState next, string viewerAccountId)
|
||||
{
|
||||
var changedTiles = DiffTiles(prev, next);
|
||||
var (unitsAdded, unitsRemoved, unitsChanged) = DiffAllFieldUnits(prev, next);
|
||||
|
||||
// Private data: only this viewer's hand / discard changes
|
||||
PrivateViewerDelta? privateByViewer = null;
|
||||
if (prevViewer != null && nextViewer != null)
|
||||
{
|
||||
var added = nextHandIds.Except(prevHandIds); // hand diff: set operations
|
||||
var removed = prevHandIds.Except(nextHandIds);
|
||||
// discard: append-only via Skip(prevCount)
|
||||
if (handAdded != null || handRemovedIds != null || discardAdded != null)
|
||||
privateByViewer = new PrivateViewerDelta(handAdded, handRemovedIds, discardAdded);
|
||||
}
|
||||
return new GameStateDelta(
|
||||
StateVersion: next.NextActionSequence,
|
||||
ChangedTiles: changedTiles,
|
||||
UnitsAdded: unitsAdded,
|
||||
UnitsRemoved: unitsRemoved,
|
||||
UnitsChanged: unitsChanged,
|
||||
ArchSpiritByAccount: DiffArchByAccount(prev, next),
|
||||
PlayerStatsByAccount: DiffStatsByAccount(prev, next),
|
||||
PublicCountsByAccount: DiffPublicCountsByAccount(prev, next, viewerAccountId),
|
||||
PrivateByViewer: privateByViewer,
|
||||
MetaDelta: DiffMeta(prev, next),
|
||||
ActiveEffects: DiffActiveEffects(next));
|
||||
}
|
||||
```
|
||||
### ComputeSpectatorDelta (line 82)
|
||||
|
||||
Same structure but `PrivateByViewer = null` and `viewerAccountId = null` -- spectators see
|
||||
all public counts, no private zone data.
|
||||
|
||||
### Diff Helpers
|
||||
|
||||
| Method | Lines | What it diffs |
|
||||
|---|---|---|
|
||||
| `DiffTiles` | 123-181 | Board tiles; emits `TileDelta` for each coord where base1/base2/affinity/occupant/ruin changed. |
|
||||
| `DiffAllFieldUnits` | 184-229 | Builds prev/next unit maps by `InstanceId` across all players; splits into added/removed/changed. |
|
||||
| `DiffUnit` | 231-288 | Compares individual `CardInstance` fields; returns `null` when nothing changed. |
|
||||
| `DiffPlayerStats` | 290-307 | Compares SP, ST, deck/hand/discard counts; returns `null` when unchanged. |
|
||||
| `DiffArchByAccount` | 309-343 | Per-account ArchSpirit: `Full` snapshot if prev had none, otherwise `Delta` from `DiffUnit`. |
|
||||
| `DiffStatsByAccount` | 345-363 | Calls `DiffPlayerStats` per account; omits null results. |
|
||||
| `DiffPublicCountsByAccount` | 365-392 | Hand/deck/discard counts for players other than the viewer. |
|
||||
| `DiffMeta` | 407-419 | Phase, active player, turn number. |
|
||||
| `DiffActiveEffects` | 112-120 | Always returns the full active-effects list (full replacement, never sparse). |
|
||||
|
||||
---
|
||||
|
||||
## 6. Server -- Push Decision (PushStateToPlayersAsync)
|
||||
|
||||
**File:** `Server/src/SOR.Game/Handlers/GameHandlerBase.cs`, lines 291-393
|
||||
|
||||
```csharp
|
||||
internal static async Task PushStateToPlayersAsync(
|
||||
IClientPush clientPush, GameSession session, GameState state,
|
||||
CancellationToken ct, string? prevStateJson = null)
|
||||
{
|
||||
if (prevStateJson != null)
|
||||
{
|
||||
var prevState = GameEngine.Deserialize(prevStateJson);
|
||||
var allIds = GetAllPlayerIds(session); // P1, P2, + any AdditionalPlayers
|
||||
|
||||
// ActiveEffects excluded from IsEmpty: it is always populated even when empty,
|
||||
// so including it would always trigger the full-state fallback. (line 313)
|
||||
static bool IsEmpty(GameStateDelta d) =>
|
||||
d.MetaDelta == null && d.ChangedTiles == null && d.UnitsAdded == null &&
|
||||
d.UnitsRemoved == null && d.UnitsChanged == null &&
|
||||
d.ArchSpiritByAccount == null && d.PlayerStatsByAccount == null &&
|
||||
d.PublicCountsByAccount == null && d.PrivateByViewer == null;
|
||||
|
||||
// lines 315-317: one viewer-specific delta per player
|
||||
var deltas = allIds.ToDictionary(
|
||||
pid => pid,
|
||||
pid => GameStateDiffer.ComputeDelta(prevState, state, pid));
|
||||
|
||||
if (deltas.Values.Any(IsEmpty)) // line 321 -- any player sees no change?
|
||||
{
|
||||
// Fallback: push full game.state_update to everyone
|
||||
foreach (var pid in allIds)
|
||||
tasks.Add(clientPush.PushAsync(pid,
|
||||
ServerMessage.Push("game.state_update",
|
||||
new GameStateUpdatePush(GameEngine.ToDto(state, pid))), ct));
|
||||
}
|
||||
else
|
||||
{
|
||||
// Happy path: viewer-specific delta to each player (lines 344-346)
|
||||
foreach (var (pid, delta) in deltas)
|
||||
tasks.Add(clientPush.PushAsync(pid,
|
||||
ServerMessage.Push("game.state_delta",
|
||||
new GameStateDeltaPush(delta)), ct));
|
||||
}
|
||||
// Spectators always receive full public state, never a delta (lines 348-360)
|
||||
foreach (var specId in spectators)
|
||||
tasks.Add(clientPush.PushAsync(specId.ToString(),
|
||||
ServerMessage.Push("game.state_update",
|
||||
new GameStateUpdatePush(GameEngine.ToDtoSpectator(state))), ct));
|
||||
await Task.WhenAll(tasks);
|
||||
}
|
||||
else
|
||||
{
|
||||
// No prevStateJson: initial connect / reconnect / timer expiry -> full state
|
||||
}
|
||||
await PushPendingPromptsAsync(clientPush, state, ct); // ability pause prompts
|
||||
}
|
||||
```
|
||||
**Decision tree:**
|
||||
|
||||
```
|
||||
prevStateJson present?
|
||||
+-- NO -> full game.state_update to all players
|
||||
+-- YES -> compute per-player deltas
|
||||
any delta IsEmpty?
|
||||
+-- YES -> full game.state_update to all players
|
||||
+-- NO -> game.state_delta (viewer-specific) to each player
|
||||
spectators always -> game.state_update (public DTO, no delta)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Transport -- Redis Pub/Sub via IClientPush
|
||||
|
||||
**Interface:** `Server/src/SOR.Networking.Abstractions/Push/IClientPush.cs`
|
||||
|
||||
```csharp
|
||||
Task PushAsync(string userId, IServerMessage message, CancellationToken ct);
|
||||
```
|
||||
**Implementation:** `Server/src/SOR.Networking.Redis/RedisClientPush.cs`
|
||||
|
||||
- Serialises the `IServerMessage` to bytes via `IMessageSerializer`.
|
||||
- Publishes to Redis channel `push:{userId}`.
|
||||
- The gateway (SOR.Host) subscribes to these channels and forwards bytes over the player's active WebSocket connection.
|
||||
- Best-effort delivery: if the player is disconnected the publish is dropped silently.
|
||||
|
||||
**Wire JSON format:**
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "game.state_delta",
|
||||
"ref": 0,
|
||||
"payload": {
|
||||
"delta": {
|
||||
"stateVersion": 42,
|
||||
"changedTiles": [...],
|
||||
"unitsChanged": [...],
|
||||
"privateByViewer": { "handAdded": [...] },
|
||||
"metaDelta": { "phase": "combat" },
|
||||
"activeEffects": [...]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
`ref: 0` indicates an unsolicited push (not a reply to a client request).
|
||||
|
||||
---
|
||||
|
||||
## 8. Client -- WebSocket Reception (Network.gd)
|
||||
|
||||
**File:** `Client/origin-client/autoloads/Network.gd`
|
||||
|
||||
```gdscript
|
||||
## Emitted for server-pushed messages that do not match a pending request.
|
||||
signal message_received(type: String, payload: Variant) # line 35
|
||||
```
|
||||
All incoming WebSocket packets are polled in `_process`. Each packet is parsed as JSON
|
||||
and its `ref` sequence number checked against `_pending` (outstanding requests):
|
||||
|
||||
```gdscript
|
||||
# Network.gd lines 283-284
|
||||
# Not a reply to a known request -- broadcast/push to listeners.
|
||||
message_received.emit(type, payload)
|
||||
```
|
||||
Push messages (`ref == 0`) bypass the request-reply correlation table and are broadcast
|
||||
via `message_received` to any connected listener.
|
||||
|
||||
---
|
||||
|
||||
## 9. Client -- Push Dispatch (Game.gd)
|
||||
|
||||
**File:** `Client/origin-client/autoloads/Game.gd`
|
||||
|
||||
### Subscription (line 109)
|
||||
|
||||
```gdscript
|
||||
func _ready() -> void:
|
||||
Network.message_received.connect(_on_server_push)
|
||||
```
|
||||
### Version-guarded dispatch (lines 702-755)
|
||||
|
||||
```gdscript
|
||||
func _on_server_push(type: String, payload: Variant) -> void:
|
||||
match type:
|
||||
"game.state_delta": # line 739
|
||||
var d := payload as Dictionary
|
||||
var delta := d.get("delta", {}) as Dictionary
|
||||
if delta.is_empty(): return
|
||||
var v := int(delta.get("stateVersion", -1))
|
||||
# Already up to date (acting player got full state in their ACK reply)
|
||||
if _state_version >= 0 and v <= _state_version: # line 744
|
||||
return
|
||||
# Gap detected: missed one or more deltas
|
||||
if _state_version >= 0 and v > _state_version + 1: # line 747
|
||||
print("[Game] WARN: missed delta (have %d, got %d) -- requesting full sync"
|
||||
% [_state_version, v])
|
||||
_fetch_state() # sends game.get_state request to server
|
||||
return
|
||||
_apply_delta(delta) # line 755 -- happy path
|
||||
```
|
||||
`_state_version` (line 104) initialised to `-1`; updated on full state receipt (line 727)
|
||||
and after each applied delta (line 669).
|
||||
|
||||
---
|
||||
|
||||
## 10. Client -- Delta Application (_apply_delta)
|
||||
|
||||
**File:** `Client/origin-client/autoloads/Game.gd`, lines 512-674
|
||||
|
||||
Ten sections processed in order. Each guarded with `is Array` / `is Dictionary`
|
||||
so a missing or null section is safely skipped.
|
||||
|
||||
### Section 1 -- Changed Tiles (lines 517-536)
|
||||
|
||||
```gdscript
|
||||
var changed_tiles = delta.get("changedTiles")
|
||||
if changed_tiles is Array:
|
||||
var tiles: Array = state.get("board", {}).get("tiles", [])
|
||||
for td: Dictionary in changed_tiles:
|
||||
var tx := int(td.get("x", -1))
|
||||
var ty := int(td.get("y", -1))
|
||||
for tile: Dictionary in tiles:
|
||||
if c.get("x") == tx and c.get("y") == ty:
|
||||
if td.has("base1") and td["base1"] != null: tile["base1"] = td["base1"]
|
||||
if td.has("occupantCleared") and bool(td["occupantCleared"]):
|
||||
tile["occupantId"] = null; tile["occupantOwner"] = null
|
||||
elif td.has("occupantId") and td["occupantId"] != null:
|
||||
tile["occupantId"] = td["occupantId"]
|
||||
# ... base2, resolvedAffinity, ruinId, ruinOwner, occupantOwner
|
||||
break
|
||||
```
|
||||
`OccupantCleared` and `RuinCleared` booleans handle the set-to-null case
|
||||
that a plain nullable field cannot express.
|
||||
|
||||
### Section 2 -- Added Units (lines 538-556)
|
||||
|
||||
```gdscript
|
||||
var added_units = delta.get("unitsAdded")
|
||||
if added_units is Array:
|
||||
for add_entry: Dictionary in added_units:
|
||||
var owner_id := str(add_entry.get("ownerAccountId", ""))
|
||||
var unit := add_entry.get("unit", {}) as Dictionary
|
||||
var field: Array = _player_by_id(owner_id).get("field", [])
|
||||
if not exists: # idempotency guard: skip if instanceId already present
|
||||
field.append(unit)
|
||||
```
|
||||
### Section 3 -- Removed Units (lines 558-567)
|
||||
|
||||
```gdscript
|
||||
var removed_ids = delta.get("unitsRemoved")
|
||||
if removed_ids is Array:
|
||||
for iid: String in removed_ids:
|
||||
for p: Dictionary in state.get("players", []):
|
||||
var field: Array = p.get("field", [])
|
||||
for i in range(field.size() - 1, -1, -1):
|
||||
if field[i].get("instanceId", "") == iid:
|
||||
field.remove_at(i); break
|
||||
```
|
||||
### Section 4 -- Changed Units (lines 569-576)
|
||||
|
||||
```gdscript
|
||||
var changed_units = delta.get("unitsChanged")
|
||||
if changed_units is Array:
|
||||
for ud: Dictionary in changed_units:
|
||||
var iid := str(ud.get("instanceId", ""))
|
||||
var unit := get_unit_by_id(iid)
|
||||
if not unit.is_empty():
|
||||
_merge_unit_delta(unit, ud) # see Section 11
|
||||
```
|
||||
### Section 5 -- Private Viewer Data (lines 578-600)
|
||||
|
||||
```gdscript
|
||||
var private_delta = delta.get("privateByViewer")
|
||||
if private_delta is Dictionary and not private_delta.is_empty():
|
||||
# handAdded -> append new cards to own hand
|
||||
# handRemovedIds -> remove by instanceId from own hand
|
||||
# discardAdded -> append to own discard
|
||||
```
|
||||
Never present in another player's delta -- the server sets `PrivateByViewer` only for the owning account.
|
||||
|
||||
### Section 6 -- Public Counts (lines 602-613)
|
||||
|
||||
```gdscript
|
||||
var public_counts = delta.get("publicCountsByAccount")
|
||||
if public_counts is Dictionary:
|
||||
for aid_v in public_counts.keys():
|
||||
var player := _player_by_id(str(aid_v))
|
||||
if counts.has("handCount") ...: player["handCount"] = int(counts["handCount"])
|
||||
if counts.has("deckCount") ...: player["deckCount"] = int(counts["deckCount"])
|
||||
if counts.has("discardCount") ...: player["discardCount"] = int(counts["discardCount"])
|
||||
```
|
||||
Opponents see card **counts** here; their actual cards are never transmitted.
|
||||
|
||||
### Section 7 -- ArchSpirit Updates (lines 615-638)
|
||||
|
||||
```gdscript
|
||||
var arch_by_account = delta.get("archSpiritByAccount")
|
||||
if arch_by_account is Dictionary:
|
||||
var full_arch: Variant = arch_update.get("full")
|
||||
if full_arch is Dictionary and not full_arch.is_empty():
|
||||
player["archSpirit"] = full_arch # full replacement on first sight
|
||||
continue
|
||||
var arch_delta := arch_update.get("delta") as Dictionary
|
||||
if arch.is_empty():
|
||||
request_sync() # missing baseline -> fetch full state
|
||||
continue
|
||||
_merge_unit_delta(arch, arch_delta)
|
||||
```
|
||||
Server sends `Full` on first sight of an arch spirit (e.g. just placed), `Delta` thereafter.
|
||||
|
||||
### Section 8 -- Player Stats (lines 640-655)
|
||||
|
||||
```gdscript
|
||||
var stats_by_account = delta.get("playerStatsByAccount")
|
||||
if stats_by_account is Dictionary:
|
||||
if stats.has("currentSp") and stats["currentSp"] != null:
|
||||
player["currentSp"] = int(stats["currentSp"])
|
||||
if stats.has("currentSt") and stats["currentSt"] != null:
|
||||
player["currentSt"] = int(stats["currentSt"])
|
||||
# also: deckCount, handCount, discardCount
|
||||
```
|
||||
### Section 9 -- Meta (lines 657-662)
|
||||
|
||||
```gdscript
|
||||
var meta = delta.get("metaDelta")
|
||||
if meta is Dictionary and not meta.is_empty():
|
||||
if meta.has("phase") ...: state["phase"] = meta["phase"]
|
||||
if meta.has("activePlayerAccountId") ...: state["activePlayerAccountId"] = ...
|
||||
if meta.has("turnNumber") ...: state["turnNumber"] = int(meta["turnNumber"])
|
||||
```
|
||||
### Section 10 -- Active Effects (lines 664-667)
|
||||
|
||||
```gdscript
|
||||
var active_effects = delta.get("activeEffects")
|
||||
if active_effects is Array:
|
||||
state["activeEffects"] = active_effects # full replacement
|
||||
```
|
||||
### Version Update and Signal (lines 669-674)
|
||||
|
||||
```gdscript
|
||||
_state_version = int(delta.get("stateVersion", _state_version))
|
||||
state_updated.emit(state) # triggers UI rebuild
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Client -- Unit Merge (_merge_unit_delta)
|
||||
|
||||
**File:** `Client/origin-client/autoloads/Game.gd`, lines 677-699
|
||||
|
||||
Used by sections 4 (field units) and 7 (arch spirits). Merges only non-null fields:
|
||||
|
||||
```gdscript
|
||||
func _merge_unit_delta(unit: Dictionary, ud: Dictionary) -> void:
|
||||
if ud.has("currentHealth") and ud["currentHealth"] != null:
|
||||
unit["currentHealth"] = int(ud["currentHealth"])
|
||||
if ud.has("maxHealth") and ud["maxHealth"] != null:
|
||||
unit["maxHealth"] = int(ud["maxHealth"])
|
||||
if ud.has("currentDefense") and ud["currentDefense"] != null:
|
||||
unit["currentDefense"] = int(ud["currentDefense"])
|
||||
if ud.has("maxDefense") and ud["maxDefense"] != null:
|
||||
unit["maxDefense"] = int(ud["maxDefense"])
|
||||
if ud.has("damage") and ud["damage"] != null:
|
||||
unit["damage"] = int(ud["damage"])
|
||||
if ud.has("isExhausted") and ud["isExhausted"] != null:
|
||||
unit["isExhausted"] = bool(ud["isExhausted"])
|
||||
if ud.has("canMove") and ud["canMove"] != null:
|
||||
unit["canMove"] = bool(ud["canMove"])
|
||||
if ud.has("canAttack") and ud["canAttack"] != null:
|
||||
unit["canAttack"] = bool(ud["canAttack"])
|
||||
if ud.has("canBeAttacked") and ud["canBeAttacked"] != null:
|
||||
unit["canBeAttacked"] = bool(ud["canBeAttacked"])
|
||||
if ud.has("canUseAbility") and ud["canUseAbility"] != null:
|
||||
unit["canUseAbility"] = bool(ud["canUseAbility"])
|
||||
if ud.has("currentMp") and ud["currentMp"] != null:
|
||||
unit["currentMp"] = int(ud["currentMp"])
|
||||
if ud.has("maxMp") and ud["maxMp"] != null:
|
||||
unit["maxMp"] = int(ud["maxMp"])
|
||||
if ud.has("extraAttacksRemaining") and ud["extraAttacksRemaining"] != null:
|
||||
unit["extraAttacksRemaining"] = int(ud["extraAttacksRemaining"])
|
||||
if ud.has("position") and ud["position"] != null:
|
||||
unit["position"] = ud["position"]
|
||||
if ud.has("abilitiesJson") and ud["abilitiesJson"] != null:
|
||||
unit["abilitiesJson"] = ud["abilitiesJson"]
|
||||
if ud.has("abilityUsesJson") and ud["abilityUsesJson"] != null:
|
||||
unit["abilityUsesJson"] = ud["abilityUsesJson"]
|
||||
# art2dUrl / Art2dUrl and modelUrl / ModelUrl / modelurl all checked (capitalisation guard)
|
||||
if ud.has("art2dUrl") and ud["art2dUrl"] != null: unit["art2dUrl"] = ud["art2dUrl"]
|
||||
if ud.has("modelUrl") and ud["modelUrl"] != null: unit["modelUrl"] = ud["modelUrl"]
|
||||
```
|
||||
The `ud.has(k) and ud[k] != null` pattern distinguishes JSON `null` (no change) from a missing key.
|
||||
|
||||
---
|
||||
|
||||
## 12. Fallback and Resync Paths
|
||||
|
||||
| Trigger | Behaviour |
|
||||
|---|---|
|
||||
| `prevStateJson == null` passed to handler | Full `game.state_update` pushed to all players (initial connect, reconnect, timer expiry). |
|
||||
| Any player's delta `IsEmpty()` | All players receive full `game.state_update` instead of deltas. |
|
||||
| Spectator | Always receives full `game.state_update` (public DTO, no private data, no delta). |
|
||||
| Client: `v <= _state_version` | Delta dropped -- acting player already received the new state in their ACK reply. |
|
||||
| Client: `v > _state_version + 1` | Gap in sequence -- client calls `_fetch_state()` which sends `game.get_state`; server replies with full state. |
|
||||
| Client: arch spirit `is_empty()` | Missing baseline -- client calls `request_sync()` for the same full-state recovery. |
|
||||
|
||||
---
|
||||
|
||||
## 13. Design Invariants
|
||||
|
||||
1. **`prevStateJson` must be captured before `SaveStateAsync`.**
|
||||
Breaking this produces an empty diff (state compared to itself).
|
||||
|
||||
2. **`StateVersion` == `state.NextActionSequence` at time of push.**
|
||||
Incremented inside `SaveStateAsync` before serialisation, so the value baked into the delta exactly matches what is stored in the DB.
|
||||
|
||||
3. **`ActiveEffects` is always a full replacement, never sparse.**
|
||||
Comment at `GameStateDiffer.cs:109`: the collection is small, ordering matters, and partial diffs of effect lists would be error-prone.
|
||||
|
||||
4. **`PrivateByViewer` is viewer-exclusive.**
|
||||
`ComputeDelta` is called once per player with that player's account ID. Each player's delta contains only their own private zone data.
|
||||
|
||||
5. **Spectators never receive deltas.**
|
||||
`ComputeSpectatorDelta` exists but `PushStateToPlayersAsync` always pushes a full `game.state_update` to spectators (lines 348-360).
|
||||
|
||||
6. **FOR UPDATE lock serialises concurrent mutations.**
|
||||
All action handlers call `LoadActiveSessionAsync` which opens a transaction and locks the session row. Concurrent requests for the same session queue up in PostgreSQL.
|
||||
|
||||
7. **IsEmpty check excludes `ActiveEffects`.**
|
||||
Comment at `GameHandlerBase.cs:313`: `ActiveEffects` is always populated (even when it is an empty list), so including it in the emptiness check would always trigger the full-state fallback.
|
||||
|
||||
Reference in New Issue
Block a user