Files
tidewall/src/net/net_snapshot.gd
T
claudeandClaude Opus 5.5 05c7568ec1 N8: 24-client network soak, and the server fixes it found
make soak runs a real server and 24 headless clients in three processes for
two whole matches in real time. Each client reaches the server through its own
UdpRelay, which adds 60 ms, +/-20 ms jitter and 2% loss each way, so ENet runs
unchanged over a bad link. SoakPlayer drives each client from what a client
knows: it drops, glides, heads for high ground, harvests and tries to build.
tools/soak_report.gd checks world hashes against the server's, errors,
unreadable packets, every client playing every match with its connection
intact, memory between matches, and the p99 tick with the network's share.
make soak-selfcheck proves a drifted client world is caught.

Server changes: --matches=N, --world-hash-every=N, tick timing that includes
after_tick, and memory in match and progress lines.

What the soak found and fixed:
- Snapshot building for 24 clients took the p99 tick to 13.8 ms, over the
  12 ms budget, against a 2.8 ms simulation. Encoded records are now shared
  between clients for the tick, unchanged records skip the field diff, and
  clients are spread over the snapshot interval by handle. p99 is 7.3 ms.
- ENet peers had a timeout limit of 0, which gives up on a peer as soon as any
  reliable message has waited the minimum timeout. Now ENet's default, 32.

Not fixed: one or two clients still lose their connection about 15 s into the
second match's drop in each run (see the issue), so the soak still fails and
N8 stays open.

Refs #39

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 21:56:01 -05:00

477 lines
18 KiB
GDScript

## Game traffic after the handshake: what a snapshot of the world looks like on the
## wire, the input packet a client answers with, and the match notice.
##
## An entity travels as a **record**: a PackedInt32Array of whole numbers, already
## quantized, laid out per archetype (see the R_ constants). The server compares records
## to decide what changed, the wire carries only the changed field groups, and the
## client keeps records as its picture of the world. Everything is little-endian.
##
## server -> SNAPSHOT (channel 1, unreliable)
## u8 type, u32 server tick, u32 baseline tick (0 = none), u32 simulation tick,
## u32 newest command tick received from this client plus one (0 = none yet),
## u32 the sequence number of the newest WORLD message made (see NetWorld),
## varint the entity the client is watching (its own player, or the one it
## spectates; 0 = none), u8 match phase, u8 tide phase, s16 sea level in centimetres,
## u8 1 if the client's own block follows, then that block (see SELF_BYTES),
## u8 removed count, then entity IDs as varints,
## u16 record count, then per record: varint ID, u8 (archetype << 5 | group mask),
## then the fields of each group in the mask
## client -> INPUT (channel 1, unreliable)
## u8 type, u32 tick of the newest snapshot it holds (0 = send a full one),
## u8 command count, then that many 15-byte PlayerCommands, oldest first
## server -> MATCH (channel 0, reliable)
## u8 type, u8 match phase, u32 match index, s64 match seed
##
## Decoders return an empty Dictionary for anything malformed and never raise an error.
class_name NetSnapshot
extends RefCounted
const MSG_MATCH: int = 4
const MSG_SNAPSHOT: int = 16
const MSG_INPUT: int = 17
## The server tick counts every tick the server has run and never goes back, so it
## orders snapshots across matches. The simulation tick is the one commands name.
const HEADER_BYTES: int = 21
const MATCH_BYTES: int = 14
## The client's own block: what it needs to predict its own player and nobody else is
## told. Exact, not quantized, so a prediction made from it matches the server's to the
## bit: position and velocity (three f32 each, which is all a Vector3 holds), the water
## level around the player (f64), which of the nine flood cells around the player that
## water reaches (u16), swimming stamina in ticks (u16) and the player's FLAG_ bits (u8).
const SELF_BYTES: int = 37
## Every bit of the nine-cell water mask.
const WATER_EVERYWHERE: int = 0x1FF
## The most commands one INPUT may carry. Clients send fewer; see Tuning.
const MAX_INPUT_COMMANDS: int = 8
## Positions are quantized to 1/64 m (about 1.5 cm) in a u16 per axis: 1,024 m across,
## and heights from Y_OFFSET metres below zero to 1,024 less that above.
const POSITION_STEPS_PER_METRE: float = 64.0
const Y_OFFSET_METRES: float = 128.0
# Record layouts. Index 0 is always the archetype and 1 to 3 the position.
const R_ARCHETYPE: int = 0
const R_X: int = 1
const R_Y: int = 2
const R_Z: int = 3
# Players.
const R_YAW: int = 4
## Pitch in steps of 1/127 of a right angle.
const R_PITCH: int = 5
const R_HEALTH: int = 6
const R_ARMOR: int = 7
const R_FLAGS: int = 8
## The held item's catalog code plus one; 0 is the boathook.
const R_HELD: int = 9
# Pickups and projectiles: the item's catalog code plus one.
const R_ITEM: int = 4
# Pickups.
const R_COUNT: int = 5
const R_TIER: int = 6
# Projectiles: the entity that fired it.
const R_OWNER: int = 5
const FLAG_ON_GROUND: int = 1 << 0
const FLAG_CROUCHING: int = 1 << 1
const FLAG_SWIMMING: int = 1 << 2
const FLAG_ELIMINATED: int = 1 << 3
## Two bits: Drop.NONE, ABOARD, FREEFALL or GLIDING.
const FLAG_DROP_SHIFT: int = 4
const FLAG_RELOADING: int = 1 << 6
const FLAG_USING: int = 1 << 7
const _U8: int = 0
const _S8: int = 1
const _U16: int = 2
const _U32: int = 3
const _WIDTH: Array[int] = [1, 1, 2, 4]
## Per archetype: the wire type of every record index.
const _TYPES: Dictionary = {
SimEntity.ARCHETYPE_PLAYER: [_U8, _U16, _U16, _U16, _U16, _S8, _U8, _U8, _U8, _U8],
SimEntity.ARCHETYPE_PICKUP: [_U8, _U16, _U16, _U16, _U8, _U16, _U8],
SimEntity.ARCHETYPE_PROJECTILE: [_U8, _U16, _U16, _U16, _U8, _U32],
}
## Per archetype: the record indices in each field group. Bit n of a mask is group n.
const _GROUPS: Dictionary = {
SimEntity.ARCHETYPE_PLAYER: [[1, 2, 3], [4, 5], [6, 7], [8], [9]],
SimEntity.ARCHETYPE_PICKUP: [[1, 2, 3], [4, 5, 6]],
SimEntity.ARCHETYPE_PROJECTILE: [[1, 2, 3], [4, 5]],
}
static func known_archetype(archetype: int) -> bool:
return _TYPES.has(archetype)
## The mask with every group of `archetype` set.
static func full_mask(archetype: int) -> int:
return (1 << (_GROUPS[archetype] as Array).size()) - 1
## The record for an entity as it stands, or an empty array for an archetype that isn't
## replicated.
static func record_of(entity: SimEntity) -> PackedInt32Array:
var record: PackedInt32Array = PackedInt32Array()
if not _TYPES.has(entity.archetype):
return record
record.resize((_TYPES[entity.archetype] as Array).size())
record[R_ARCHETYPE] = entity.archetype
record[R_X] = _quantize(entity.position.x)
record[R_Y] = _quantize(entity.position.y + Y_OFFSET_METRES)
record[R_Z] = _quantize(entity.position.z)
match entity.archetype:
SimEntity.ARCHETYPE_PLAYER:
record[R_YAW] = posmod(entity.yaw, PlayerCommand.YAW_STEPS)
record[R_PITCH] = clampi(roundi(float(entity.pitch) / PlayerCommand.PITCH_MAX * 127.0), -127, 127)
record[R_HEALTH] = clampi(entity.health, 0, 255)
record[R_ARMOR] = clampi(entity.armor, 0, 255)
record[R_FLAGS] = flags_of(entity)
var held: int = -1
if entity.selected >= 1 and entity.selected <= entity.slot_items.size():
held = entity.slot_items[entity.selected - 1]
record[R_HELD] = clampi(held + 1, 0, 255)
SimEntity.ARCHETYPE_PICKUP:
record[R_ITEM] = clampi(entity.item + 1, 0, 255)
record[R_COUNT] = clampi(entity.item_count, 0, 65535)
record[R_TIER] = clampi(entity.item_tier, 0, 255)
SimEntity.ARCHETYPE_PROJECTILE:
record[R_ITEM] = clampi(entity.item + 1, 0, 255)
record[R_OWNER] = entity.owner_id & 0xFFFFFFFF
return record
## A player's FLAG_ bits.
static func flags_of(entity: SimEntity) -> int:
var flags: int = (entity.drop_state & 3) << FLAG_DROP_SHIFT
if entity.on_ground:
flags |= FLAG_ON_GROUND
if entity.crouching:
flags |= FLAG_CROUCHING
if entity.swimming:
flags |= FLAG_SWIMMING
if entity.eliminated:
flags |= FLAG_ELIMINATED
if entity.reload_ticks > 0:
flags |= FLAG_RELOADING
if entity.use_ticks > 0:
flags |= FLAG_USING
return flags
## The client's own block for `player`. `water` is the level of the water around it and
## `water_mask` says which of the nine flood cells around it that water reaches: bit
## (dz + 1) * 3 + (dx + 1) for the cell dx, dz away from the player's.
static func self_of(player: SimEntity, water: float, water_mask: int) -> Dictionary:
return {
"position": player.position, "velocity": player.velocity, "water": water,
"water_mask": water_mask, "stamina": player.stamina_ticks, "flags": flags_of(player),
}
## Puts a client's own block into `player`: everything movement depends on.
static func apply_self(player: SimEntity, own: Dictionary) -> void:
var flags: int = own["flags"]
player.position = own["position"]
player.velocity = own["velocity"]
player.stamina_ticks = own["stamina"]
player.on_ground = flags & FLAG_ON_GROUND != 0
player.crouching = flags & FLAG_CROUCHING != 0
player.swimming = flags & FLAG_SWIMMING != 0
player.eliminated = flags & FLAG_ELIMINATED != 0
player.drop_state = (flags >> FLAG_DROP_SHIFT) & 3
## Where a record's entity is, to the nearest 1/64 m.
static func position_of(record: PackedInt32Array) -> Vector3:
return Vector3(
record[R_X] / POSITION_STEPS_PER_METRE,
record[R_Y] / POSITION_STEPS_PER_METRE - Y_OFFSET_METRES,
record[R_Z] / POSITION_STEPS_PER_METRE,
)
static func yaw_radians_of(record: PackedInt32Array) -> float:
return float(record[R_YAW]) / PlayerCommand.YAW_STEPS * TAU
static func pitch_radians_of(record: PackedInt32Array) -> float:
return float(record[R_PITCH]) / 127.0 * (PI * 0.5)
## The groups in which two records of one archetype differ.
static func diff_mask(before: PackedInt32Array, after: PackedInt32Array) -> int:
var groups: Array = _GROUPS[after[R_ARCHETYPE]]
var mask: int = 0
for group: int in groups.size():
for index: int in groups[group]:
if before[index] != after[index]:
mask |= 1 << group
break
return mask
## Bytes one record takes on the wire with `mask`.
static func record_bytes(entity_id: int, archetype: int, mask: int) -> int:
var types: Array = _TYPES[archetype]
var groups: Array = _GROUPS[archetype]
var total: int = varint_bytes(entity_id) + 1
for group: int in groups.size():
if mask & (1 << group) != 0:
for index: int in groups[group]:
total += _WIDTH[types[index]]
return total
static func varint_bytes(value: int) -> int:
var total: int = 1
while value >= 0x80:
value >>= 7
total += 1
return total
## Builds a SNAPSHOT. `removed` are entity IDs; `records` is an array of
## [entity ID, mask, record] in the order they should travel.
static func encode_snapshot(header: Dictionary, removed: PackedInt32Array, records: Array) -> PackedByteArray:
var out: StreamPeerBuffer = StreamPeerBuffer.new()
out.big_endian = false
out.put_u8(MSG_SNAPSHOT)
out.put_u32(int(header["tick"]) & 0xFFFFFFFF)
out.put_u32(int(header.get("baseline", 0)) & 0xFFFFFFFF)
out.put_u32(int(header.get("sim_tick", 0)) & 0xFFFFFFFF)
out.put_u32((int(header.get("command_tick", -1)) + 1) & 0xFFFFFFFF)
out.put_u32(int(header.get("world_seq", 0)) & 0xFFFFFFFF)
_put_varint(out, int(header.get("own_id", 0)))
out.put_u8(int(header.get("match_phase", 0)))
out.put_u8(int(header.get("tide_phase", 0)))
out.put_16(clampi(int(header.get("sea_cm", 0)), -32768, 32767))
var own: Dictionary = header.get("self", {})
out.put_u8(0 if own.is_empty() else 1)
if not own.is_empty():
for vector: Vector3 in [own["position"], own["velocity"]]:
out.put_float(vector.x)
out.put_float(vector.y)
out.put_float(vector.z)
out.put_double(own["water"])
out.put_u16(int(own["water_mask"]) & WATER_EVERYWHERE)
out.put_u16(clampi(int(own["stamina"]), 0, 65535))
out.put_u8(int(own["flags"]) & 0xFF)
out.put_u8(removed.size())
for entity_id: int in removed:
_put_varint(out, entity_id)
out.put_u16(records.size())
for entry: Array in records:
# A record may come already encoded (encode_record()), shared between clients.
out.put_data(entry[3] if entry.size() > 3 else encode_record(int(entry[0]), int(entry[1]), entry[2]))
return out.data_array
## One record as a snapshot carries it: the entity ID, the archetype and mask byte, and
## the fields of each group in `mask`. The same for every client that is sent it.
static func encode_record(entity_id: int, mask: int, record: PackedInt32Array) -> PackedByteArray:
var out: StreamPeerBuffer = StreamPeerBuffer.new()
out.big_endian = false
var archetype: int = record[R_ARCHETYPE]
var types: Array = _TYPES[archetype]
var groups: Array = _GROUPS[archetype]
_put_varint(out, entity_id)
out.put_u8(archetype << 5 | mask)
for group: int in groups.size():
if mask & (1 << group) == 0:
continue
for index: int in groups[group]:
match types[index]:
_U8:
out.put_u8(record[index])
_S8:
out.put_8(record[index])
_U16:
out.put_u16(record[index])
_U32:
out.put_u32(record[index])
return out.data_array
## Reads a SNAPSHOT's header and lists, without applying them: {"tick", "baseline",
## "sim_tick", "command_tick" (-1 = none yet), "world_seq", "own_id", "match_phase", "tide_phase",
## "sea_cm", "self": the client's own block as self_of() made it, or empty, "removed":
## PackedInt32Array, "records": [[entity ID, archetype, mask, values]]}, where `values`
## holds the fields present, in record order. Empty if malformed.
static func decode_snapshot(bytes: PackedByteArray) -> Dictionary:
if bytes.size() < HEADER_BYTES + 8 or bytes[0] != MSG_SNAPSHOT:
return {}
var cursor: Array[int] = [HEADER_BYTES]
var own_id: int = _read_varint(bytes, cursor)
if own_id < 0 or cursor[0] + 6 > bytes.size():
return {}
var at: int = cursor[0]
var result: Dictionary = {
"tick": bytes.decode_u32(1), "baseline": bytes.decode_u32(5), "sim_tick": bytes.decode_u32(9),
"command_tick": bytes.decode_u32(13) - 1, "world_seq": bytes.decode_u32(17),
"own_id": own_id, "match_phase": bytes[at], "tide_phase": bytes[at + 1], "sea_cm": bytes.decode_s16(at + 2),
}
var own: Dictionary = {}
at += 5
if bytes[at - 1] > 1:
return {}
if bytes[at - 1] == 1:
if at + SELF_BYTES + 1 > bytes.size():
return {}
own = {
"position": Vector3(bytes.decode_float(at), bytes.decode_float(at + 4), bytes.decode_float(at + 8)),
"velocity": Vector3(bytes.decode_float(at + 12), bytes.decode_float(at + 16), bytes.decode_float(at + 20)),
"water": bytes.decode_double(at + 24),
"water_mask": bytes.decode_u16(at + 32) & WATER_EVERYWHERE,
"stamina": bytes.decode_u16(at + 34),
"flags": bytes[at + 36],
}
for value: float in [own["position"].x, own["position"].y, own["position"].z, own["velocity"].x, own["velocity"].y, own["velocity"].z, own["water"]]:
if not is_finite(value):
return {}
at += SELF_BYTES
result["self"] = own
var removed_count: int = bytes[at]
cursor[0] = at + 1
var removed: PackedInt32Array = PackedInt32Array()
for _index: int in removed_count:
var entity_id: int = _read_varint(bytes, cursor)
if entity_id <= 0:
return {}
removed.append(entity_id)
if cursor[0] + 2 > bytes.size():
return {}
var record_count: int = bytes.decode_u16(cursor[0])
cursor[0] += 2
var records: Array = []
for _index: int in record_count:
var entity_id: int = _read_varint(bytes, cursor)
if entity_id <= 0 or cursor[0] >= bytes.size():
return {}
var tag: int = bytes[cursor[0]]
cursor[0] += 1
var archetype: int = tag >> 5
var mask: int = tag & 0x1F
if not _TYPES.has(archetype) or mask == 0 or mask > full_mask(archetype):
return {}
var types: Array = _TYPES[archetype]
var groups: Array = _GROUPS[archetype]
var values: PackedInt32Array = PackedInt32Array()
for group: int in groups.size():
if mask & (1 << group) == 0:
continue
for index: int in groups[group]:
var type: int = types[index]
var offset: int = cursor[0]
if offset + _WIDTH[type] > bytes.size():
return {}
match type:
_U8:
values.append(bytes[offset])
_S8:
values.append(bytes.decode_s8(offset))
_U16:
values.append(bytes.decode_u16(offset))
_U32:
values.append(bytes.decode_u32(offset))
cursor[0] = offset + _WIDTH[type]
records.append([entity_id, archetype, mask, values])
if cursor[0] != bytes.size():
return {}
result["removed"] = removed
result["records"] = records
return result
## Lays decoded `values` over `base` (an existing record, or empty for a new entity,
## which needs every group). Returns the new record, or an empty array if it can't be.
static func merge_record(base: PackedInt32Array, archetype: int, mask: int, values: PackedInt32Array) -> PackedInt32Array:
var types: Array = _TYPES[archetype]
var groups: Array = _GROUPS[archetype]
var record: PackedInt32Array = base.duplicate()
if record.is_empty():
if mask != full_mask(archetype):
return PackedInt32Array()
record.resize(types.size())
record[R_ARCHETYPE] = archetype
elif record[R_ARCHETYPE] != archetype:
return PackedInt32Array()
var next: int = 0
for group: int in groups.size():
if mask & (1 << group) == 0:
continue
for index: int in groups[group]:
record[index] = values[next]
next += 1
return record
static func encode_input(ack_tick: int, commands: Array[PlayerCommand]) -> PackedByteArray:
var count: int = mini(commands.size(), MAX_INPUT_COMMANDS)
var bytes: PackedByteArray = PackedByteArray()
bytes.resize(6)
bytes[0] = MSG_INPUT
bytes.encode_u32(1, ack_tick & 0xFFFFFFFF)
bytes[5] = count
for index: int in range(commands.size() - count, commands.size()):
bytes.append_array(commands[index].encode())
return bytes
## {"ack", "commands": Array[PlayerCommand]} or empty.
static func decode_input(bytes: PackedByteArray) -> Dictionary:
if bytes.size() < 6 or bytes[0] != MSG_INPUT:
return {}
var count: int = bytes[5]
if count > MAX_INPUT_COMMANDS or bytes.size() != 6 + count * PlayerCommand.ENCODED_SIZE:
return {}
var commands: Array[PlayerCommand] = []
for index: int in count:
commands.append(PlayerCommand.decode(bytes, 6 + index * PlayerCommand.ENCODED_SIZE))
return {"ack": bytes.decode_u32(1), "commands": commands}
static func encode_match(phase: int, match_index: int, match_seed: int) -> PackedByteArray:
var bytes: PackedByteArray = PackedByteArray()
bytes.resize(MATCH_BYTES)
bytes[0] = MSG_MATCH
bytes[1] = phase
bytes.encode_u32(2, match_index & 0xFFFFFFFF)
bytes.encode_s64(6, match_seed)
return bytes
## {"phase", "index", "seed"} or empty.
static func decode_match(bytes: PackedByteArray) -> Dictionary:
if bytes.size() != MATCH_BYTES or bytes[0] != MSG_MATCH or bytes[1] >= Match.PHASE_NAMES.size():
return {}
return {"phase": bytes[1], "index": bytes.decode_u32(2), "seed": bytes.decode_s64(6)}
static func _quantize(metres: float) -> int:
return clampi(roundi(metres * POSITION_STEPS_PER_METRE), 0, 65535)
static func _put_varint(out: StreamPeerBuffer, value: int) -> void:
value &= 0xFFFFFFFF
while value >= 0x80:
out.put_u8(value & 0x7F | 0x80)
value >>= 7
out.put_u8(value)
## Reads a varint of at most five bytes at cursor[0] and moves the cursor past it.
## Returns -1 if the buffer ends first or the number is too long.
static func _read_varint(bytes: PackedByteArray, cursor: Array[int]) -> int:
var value: int = 0
for shift: int in range(0, 35, 7):
if cursor[0] >= bytes.size():
return -1
var byte: int = bytes[cursor[0]]
cursor[0] += 1
value |= (byte & 0x7F) << shift
if byte & 0x80 == 0:
return value & 0xFFFFFFFF
return -1