N2: Snapshot replication and interest management

NetSnapshot defines the game traffic after the handshake: delta snapshots of
quantized entity records, the client's input packet and a reliable match
notice. SnapshotSender builds each client's snapshot against the newest one
it acknowledged, tells it only about entities near the player it is watching,
and keeps every snapshot under 1,200 bytes, nearest first, with a staleness
bonus so nothing starves. SnapshotReceiver rebuilds the picture, ignores old
and repeated snapshots and asks for a fresh start if it is ever sent a delta
on something it doesn't hold.

NetGame joins the transport to the match: people who connect become
participants, their inputs go through ServerLoop.submit() once per tick, and
snapshots go out 20 times a second. `--server --listen` makes the headless
server take network players and wait in the lobby for the first of them.

Measured by test on a 24-player match start with every player a client, a
tenth of packets lost and late acknowledgements: 2.4 KB/s mean and 2.5 KB/s
for the worst client, packet headers included, against a 40 KB/s limit.

Closes #33

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-12 08:26:02 -05:00
co-authored by Claude Opus 5.5
parent 881f449d10
commit e535c1f39c
26 changed files with 1695 additions and 24 deletions
+397
View File
@@ -0,0 +1,397 @@
## 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 last command tick taken from this client, 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 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 14-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 = 17
const MATCH_BYTES: int = 14
## 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)
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
record[R_FLAGS] = flags
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
## 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", 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))
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:
var record: PackedInt32Array = entry[2]
var archetype: int = record[R_ARCHETYPE]
var mask: int = entry[1]
var types: Array = _TYPES[archetype]
var groups: Array = _GROUPS[archetype]
_put_varint(out, int(entry[0]))
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", "own_id", "match_phase", "tide_phase", "sea_cm", "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 + 7 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] + 5 > 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),
"own_id": own_id, "match_phase": bytes[at], "tide_phase": bytes[at + 1], "sea_cm": bytes.decode_s16(at + 2),
}
var removed_count: int = bytes[at + 4]
cursor[0] = at + 5
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