- Section 11: add missing effectsJson field to _merge_unit_delta snippet - Section 11: add note that line numbers drift; prefer symbol names for navigation 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>
26 KiB
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
- Overview
- Wire Types
- Server -- Action Handler
- Server -- State Persistence (SaveStateAsync)
- Server -- Delta Computation (GameStateDiffer)
- Server -- Push Decision (PushStateToPlayersAsync)
- Transport -- Redis Pub/Sub via IClientPush
- Client -- WebSocket Reception (Network.gd)
- Client -- Push Dispatch (Game.gd)
- Client -- Delta Application (_apply_delta)
- Client -- Unit Merge (_merge_unit_delta)
- Fallback and Resync Paths
- 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)
public sealed record GameStateDeltaPush(GameStateDelta Delta);
Sent as the payload of a game.state_delta push message.
GameStateDelta (lines 512-523)
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:
// 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:
prevStateJsoncaptured fromsession.StateJsonbefore callingSaveStateAsync.SaveStateAsyncoverwritessession.StateJsonwith the new state.PushStateToPlayersAsyncreceives 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.
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
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)
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
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
Task PushAsync(string userId, IServerMessage message, CancellationToken ct);
Implementation: Server/src/SOR.Networking.Redis/RedisClientPush.cs
- Serialises the
IServerMessageto bytes viaIMessageSerializer. - 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:
{
"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
## 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):
# 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)
func _ready() -> void:
Network.message_received.connect(_on_server_push)
Version-guarded dispatch (lines 702-755)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
var active_effects = delta.get("activeEffects")
if active_effects is Array:
state["activeEffects"] = active_effects # full replacement
Version Update and Signal (lines 669-674)
_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 -- function _merge_unit_delta
Note on line numbers throughout this document: line references were accurate at time of writing but drift as code evolves. Prefer the method/symbol name for navigation; treat line numbers as a starting hint only.
Used by sections 4 (field units) and 7 (arch spirits). Merges only non-null fields:
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("effectsJson") and ud["effectsJson"] != null:
unit["effectsJson"] = ud["effectsJson"]
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
-
prevStateJsonmust be captured beforeSaveStateAsync. Breaking this produces an empty diff (state compared to itself). -
StateVersion==state.NextActionSequenceat time of push. Incremented insideSaveStateAsyncbefore serialisation, so the value baked into the delta exactly matches what is stored in the DB. -
ActiveEffectsis always a full replacement, never sparse. Comment atGameStateDiffer.cs:109: the collection is small, ordering matters, and partial diffs of effect lists would be error-prone. -
PrivateByVieweris viewer-exclusive.ComputeDeltais called once per player with that player's account ID. Each player's delta contains only their own private zone data. -
Spectators never receive deltas.
ComputeSpectatorDeltaexists butPushStateToPlayersAsyncalways pushes a fullgame.state_updateto spectators (lines 348-360). -
FOR UPDATE lock serialises concurrent mutations. All action handlers call
LoadActiveSessionAsyncwhich opens a transaction and locks the session row. Concurrent requests for the same session queue up in PostgreSQL. -
IsEmpty check excludes
ActiveEffects. Comment atGameHandlerBase.cs:313:ActiveEffectsis always populated (even when it is an empty list), so including it in the emptiness check would always trigger the full-state fallback.