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
+11 -1
View File
@@ -33,6 +33,10 @@ var match_seed: int = 0
var max_players: int = 0
var tick_rate: int = 0
## Packets from the server during the last poll(), once joined, in arrival order:
## {"channel", "bytes"}. Whoever owns the client decodes them.
var packets: Array[Dictionary] = []
var _host: ENetConnection = null
var _peer: ENetPacketPeer = null
var _wanted_name: String = ""
@@ -67,6 +71,7 @@ func connect_to(address: String, port: int, wanted_name: String, now_msec: int =
func poll(now_msec: int = -1) -> void:
packets.clear()
if _host == null:
return
var now: int = now_msec if now_msec >= 0 else Time.get_ticks_msec()
@@ -128,7 +133,12 @@ func status_text() -> String:
func _received(channel: int, bytes: PackedByteArray) -> void:
if channel != NetProtocol.CHANNEL_CONTROL or bytes.is_empty():
if bytes.is_empty():
return
if state == JOINED and (channel != NetProtocol.CHANNEL_CONTROL or bytes[0] != NetProtocol.MSG_REJECT):
packets.append({"channel": channel, "bytes": bytes})
return
if channel != NetProtocol.CHANNEL_CONTROL:
return
if state == HANDSHAKING and bytes[0] == NetProtocol.MSG_WELCOME:
var welcome: Dictionary = NetProtocol.decode_welcome(bytes)
+18 -2
View File
@@ -20,6 +20,11 @@ var match_seed: int = 0
## What happened during the last poll(): {"type": "joined", "handle", "name"},
## {"type": "left", "handle", "name", "reason"} and {"type": "refused", "reason"}.
var events: Array[Dictionary] = []
## Game packets from joined players during the last poll(), in arrival order:
## {"handle", "bytes"}. Whoever owns the server decodes them.
var packets: Array[Dictionary] = []
## The most game packets kept from one player in one poll(); the rest are dropped.
var max_packets_per_poll: int = 32
## Malformed or unexpected packets dropped so far.
var bad_packets: int = 0
@@ -33,6 +38,8 @@ var _players: Dictionary = {}
## ENetPacketPeer -> handle.
var _handle_of: Dictionary = {}
var _next_handle: int = 1
## Handle -> game packets kept from them during this poll().
var _packets_from: Dictionary = {}
## Starts listening on UDP `port` (0 picks a free one) on `address`. Returns OK or the
@@ -82,6 +89,8 @@ func name_of(handle: int) -> String:
## Call it every frame. `now_msec` is for tests; it defaults to the engine's clock.
func poll(now_msec: int = -1) -> void:
events.clear()
packets.clear()
_packets_from.clear()
if _host == null:
return
var now: int = now_msec if now_msec >= 0 else Time.get_ticks_msec()
@@ -147,8 +156,15 @@ func _received(peer: ENetPacketPeer, channel: int, bytes: PackedByteArray) -> vo
if _leaving.has(peer):
return
if _handle_of.has(peer):
# Game traffic arrives with N2. A second HELLO, or anything else, is dropped.
bad_packets += 1
# Game traffic goes to the owner. A second HELLO, anything on the control
# channel, and a flood are dropped.
var handle: int = _handle_of[peer]
var count: int = int(_packets_from.get(handle, 0))
if channel != NetProtocol.CHANNEL_STATE or bytes.is_empty() or count >= max_packets_per_poll:
bad_packets += 1
return
_packets_from[handle] = count + 1
packets.append({"handle": handle, "bytes": bytes})
return
if not _guests.has(peer):
return
+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
+1
View File
@@ -0,0 +1 @@
uid://bu03pks5esll4
+99
View File
@@ -0,0 +1,99 @@
## The client's side of snapshots: rebuilds the part of the world the server chose to
## tell it about, and says which snapshot it holds so the server can send changes only.
##
## Snapshots may arrive late, twice, out of order or not at all. One older than the
## newest applied is ignored. One built on a snapshot this client no longer holds can't
## be used, so the next acknowledgement asks the server to start again.
class_name SnapshotReceiver
extends RefCounted
## Snapshots kept to apply later ones against. More than the server keeps, so anything
## it builds on is still here.
const HISTORY: int = Tuning.NET_SNAPSHOT_HISTORY + 24
## The newest picture: entity ID -> record (see NetSnapshot for the layout).
var entities: Dictionary = {}
## The server tick of that picture, or 0 before the first snapshot.
var tick: int = 0
## The simulation tick of that picture: the clock commands are stamped against.
var sim_tick: int = 0
## This client's own entity, or the one it is spectating; 0 outside a match.
var own_id: int = 0
## The newest of this client's command ticks the server had taken.
var command_tick: int = 0
var match_phase: int = 0
var tide_phase: int = 0
var sea_level: float = 0.0
## Entities that appeared or went in the last applied snapshot.
var added: PackedInt32Array = PackedInt32Array()
var removed: PackedInt32Array = PackedInt32Array()
## Counts, for tests and the network graph.
var applied: int = 0
var ignored_old: int = 0
var missing_baseline: int = 0
var malformed: int = 0
var _history: Dictionary = {}
var _need_full: bool = false
## The tick to acknowledge in the next INPUT: the newest snapshot held, or 0 to ask
## for one that builds on nothing.
func ack_tick() -> int:
return 0 if _need_full else tick
## Applies one SNAPSHOT packet. Returns true if it became the newest picture.
func apply(bytes: PackedByteArray) -> bool:
var snapshot: Dictionary = NetSnapshot.decode_snapshot(bytes)
if snapshot.is_empty():
malformed += 1
return false
var new_tick: int = snapshot["tick"]
var baseline_tick: int = snapshot["baseline"]
if new_tick <= tick:
ignored_old += 1
return false
if baseline_tick != 0 and not _history.has(baseline_tick):
missing_baseline += 1
_need_full = true
return false
var state: Dictionary = (_history[baseline_tick] as Dictionary).duplicate() if baseline_tick != 0 else {}
var gone: PackedInt32Array = PackedInt32Array()
for entity_id: int in snapshot["removed"]:
state.erase(entity_id)
var fresh: PackedInt32Array = PackedInt32Array()
for entry: Array in snapshot["records"]:
var entity_id: int = entry[0]
var base: PackedInt32Array = state.get(entity_id, PackedInt32Array())
var record: PackedInt32Array = NetSnapshot.merge_record(base, entry[1], entry[2], entry[3])
if record.is_empty():
malformed += 1
_need_full = true
return false
state[entity_id] = record
for entity_id: int in state:
if not entities.has(entity_id):
fresh.append(entity_id)
for entity_id: int in entities:
if not state.has(entity_id):
gone.append(entity_id)
entities = state
added = fresh
removed = gone
tick = new_tick
sim_tick = snapshot["sim_tick"]
own_id = snapshot["own_id"]
command_tick = snapshot["command_tick"]
match_phase = snapshot["match_phase"]
tide_phase = snapshot["tide_phase"]
sea_level = int(snapshot["sea_cm"]) / 100.0
_need_full = false
applied += 1
_history[new_tick] = state
while _history.size() > HISTORY:
var oldest: int = new_tick
for kept: int in _history:
oldest = mini(oldest, kept)
_history.erase(oldest)
return true
+1
View File
@@ -0,0 +1 @@
uid://uw03hw8iwugs
+193
View File
@@ -0,0 +1,193 @@
## The server's side of snapshots: decides, for each client, which entities it may know
## about, what has changed since the last snapshot that client confirmed, and what fits
## in this one.
##
## Each client's snapshot is a delta against the newest snapshot it has acknowledged
## (its INPUT packets carry that tick). The server remembers what it told each client
## in the last Tuning.NET_SNAPSHOT_HISTORY snapshots; if the acknowledged one isn't
## among them, or the client asks, it starts again from nothing. Because a delta only
## ever builds on something the client confirmed holding, a lost snapshot needs no
## resend: the next one covers it.
##
## Interest: a client is told only about entities within range of the player it is
## watching, measured on the map (height is ignored). An entity that leaves range is
## removed from the client's picture, and nothing about it is sent until it returns.
class_name SnapshotSender
extends RefCounted
## Client handle -> {"acked": tick, "history": {tick: {entity ID: record}},
## "last_sent": {entity ID: tick}, "command_tick": int, "bytes": int, "snapshots": int,
## "full": int, "deferred": int}.
var _clients: Dictionary = {}
## Records made for the tick being sent, shared between clients: entity ID -> record.
var _records: Dictionary = {}
var _records_tick: int = -1
## Every entity at that tick, listed once for all clients.
var _entities: Array[SimEntity] = []
func add_client(handle: int) -> void:
_clients[handle] = {
"acked": 0, "history": {}, "last_sent": {}, "command_tick": 0,
"bytes": 0, "snapshots": 0, "full": 0, "deferred": 0,
}
func remove_client(handle: int) -> void:
_clients.erase(handle)
func has_client(handle: int) -> bool:
return _clients.has(handle)
## Notes the snapshot tick a client says it holds. 0 asks for a fresh start.
func acknowledge(handle: int, tick: int) -> void:
if not _clients.has(handle):
return
var client: Dictionary = _clients[handle]
if tick == 0 or tick > int(client["acked"]):
client["acked"] = tick
## Notes the newest command tick taken from a client, echoed in its snapshots.
func note_command(handle: int, command_tick: int) -> void:
if _clients.has(handle):
var client: Dictionary = _clients[handle]
client["command_tick"] = maxi(int(client["command_tick"]), command_tick)
## Forgets what every client was told: a new match has a new simulation, whose entity
## IDs start again.
func reset() -> void:
for handle: int in _clients:
var client: Dictionary = _clients[handle]
client["acked"] = 0
client["history"] = {}
client["last_sent"] = {}
client["command_tick"] = 0
_records.clear()
_entities.clear()
_records_tick = -1
## {"bytes", "snapshots", "full", "deferred"} sent to a client so far. "deferred"
## counts entity updates that had to wait for a later snapshot.
func stats(handle: int) -> Dictionary:
if not _clients.has(handle):
return {}
var client: Dictionary = _clients[handle]
return {"bytes": client["bytes"], "snapshots": client["snapshots"], "full": client["full"], "deferred": client["deferred"]}
## The entity IDs a client watching `viewer` may be told about now: the viewer, and
## everything replicated within range of it. Empty when there's no viewer.
## `among` is the list to choose from, when the caller already has every entity.
static func interest(sim: Simulation, viewer: SimEntity, among: Array[SimEntity] = []) -> Array[int]:
var visible: Array[int] = []
if viewer == null:
return visible
if among.is_empty():
among = sim.entities.entities()
var near: float = Tuning.NET_INTEREST_PICKUPS_METRES * Tuning.NET_INTEREST_PICKUPS_METRES
var far: float = Tuning.NET_INTEREST_PLAYERS_METRES * Tuning.NET_INTEREST_PLAYERS_METRES
var centre: Vector3 = viewer.position
for entity: SimEntity in among:
if not NetSnapshot.known_archetype(entity.archetype):
continue
var dx: float = entity.position.x - centre.x
var dz: float = entity.position.z - centre.z
var limit: float = near if entity.archetype == SimEntity.ARCHETYPE_PICKUP else far
if entity.id == viewer.id or dx * dx + dz * dz <= limit:
visible.append(entity.id)
return visible
## Builds the snapshot for a client at the simulation's current tick. `viewer_id` is
## the entity the client is watching (its own player, or the one it spectates), or 0
## outside a match. `tick` is the server's own tick count, which must grow with every
## call for the same client.
func build(handle: int, sim: Simulation, viewer_id: int, tick: int, match_phase: int) -> PackedByteArray:
if not _clients.has(handle):
return PackedByteArray()
var client: Dictionary = _clients[handle]
var history: Dictionary = client["history"]
var baseline_tick: int = int(client["acked"])
if not history.has(baseline_tick):
baseline_tick = 0
var base: Dictionary = history.get(baseline_tick, {})
var viewer: SimEntity = sim.entities.find(viewer_id) if viewer_id > 0 else null
if _records_tick != tick:
_records.clear()
_records_tick = tick
_entities = sim.entities.entities()
var header: Dictionary = {
"tick": tick, "baseline": baseline_tick, "sim_tick": sim.tick, "command_tick": client["command_tick"],
"own_id": viewer.id if viewer != null else 0, "match_phase": match_phase,
"tide_phase": sim.tide.phase_at(sim.tick) if sim.tide != null else 0,
"sea_cm": roundi(sim.sea_level * 100.0),
}
var visible: Dictionary = {}
# [score, entity ID, mask, record]: the lowest score travels first.
var changed: Array = []
var last_sent: Dictionary = client["last_sent"]
var interval: int = Tuning.NET_SNAPSHOT_INTERVAL_TICKS
for entity_id: int in interest(sim, viewer, _entities):
var record: PackedInt32Array = _record(sim, entity_id)
visible[entity_id] = true
var mask: int = NetSnapshot.full_mask(record[NetSnapshot.R_ARCHETYPE])
if base.has(entity_id):
mask = NetSnapshot.diff_mask(base[entity_id], record)
if mask == 0:
continue
var score: float = -1.0e9
if entity_id != viewer.id:
var waited: float = float(tick - int(last_sent.get(entity_id, tick - interval * 20))) / interval
score = NetSnapshot.position_of(record).distance_to(viewer.position) - waited * Tuning.NET_STALE_METRES_PER_SNAPSHOT
changed.append([score, entity_id, mask, record])
changed.sort_custom(func(a: Array, b: Array) -> bool: return a[0] < b[0] if a[0] != b[0] else a[1] < b[1])
var state: Dictionary = base.duplicate()
var budget: int = Tuning.NET_SNAPSHOT_MAX_BYTES - NetSnapshot.HEADER_BYTES - NetSnapshot.varint_bytes(int(header["own_id"])) - 7
var removed: PackedInt32Array = PackedInt32Array()
for entity_id: int in base:
if visible.has(entity_id):
continue
var cost: int = NetSnapshot.varint_bytes(entity_id)
if removed.size() >= 255 or cost > budget:
break
removed.append(entity_id)
state.erase(entity_id)
last_sent.erase(entity_id)
budget -= cost
var records: Array = []
for entry: Array in changed:
var record: PackedInt32Array = entry[3]
var cost: int = NetSnapshot.record_bytes(entry[1], record[NetSnapshot.R_ARCHETYPE], entry[2])
if cost > budget:
client["deferred"] += 1
continue
budget -= cost
records.append([entry[1], entry[2], record])
state[entry[1]] = record
last_sent[entry[1]] = tick
history[tick] = state
if history.size() > Tuning.NET_SNAPSHOT_HISTORY:
var oldest: int = tick
for kept: int in history:
oldest = mini(oldest, kept)
history.erase(oldest)
var bytes: PackedByteArray = NetSnapshot.encode_snapshot(header, removed, records)
client["bytes"] += bytes.size()
client["snapshots"] += 1
if baseline_tick == 0:
client["full"] += 1
return bytes
func _record(sim: Simulation, entity_id: int) -> PackedInt32Array:
if not _records.has(entity_id):
_records[entity_id] = NetSnapshot.record_of(sim.entities.find(entity_id))
return _records[entity_id]
+1
View File
@@ -0,0 +1 @@
uid://ngjmvhpqyy2g
+27 -3
View File
@@ -17,6 +17,8 @@ const FAULT_TICK: int = 10
var config: ServerConfig
var loop: ServerLoop
## The network side, when the server was started with --listen.
var game: NetGame = null
var _errors: ErrorCounter = ErrorCounter.new()
var _accumulator: float = 0.0
@@ -39,20 +41,38 @@ func _ready() -> void:
if not config.has_seed:
config.match_seed = _fresh_seed()
Engine.max_fps = 0 if config.unthrottled else REALTIME_MAX_FPS
loop = ServerLoop.new(config.match_seed, config.players, config.bots, null, config.bot_difficulty)
var rules: MatchRules = null
if config.listen:
rules = MatchRules.new()
rules.fill_with_bots = config.bots > 0
loop = ServerLoop.new(config.match_seed, config.players, config.bots, rules, config.bot_difficulty)
if config.listen:
var net: NetServer = NetServer.new()
var error: Error = net.listen(config.port)
if error != OK:
_log("listen_failed", {"port": config.port, "message": "couldn't listen on UDP port %d: %s" % [config.port, error_string(error)]})
_finish(2)
return
game = NetGame.new(loop, net)
var started: Dictionary = config.to_dictionary()
started["engine"] = Engine.get_version_info()["string"]
started["tick_rate_hz"] = Tuning.TICK_RATE_HZ
started["world_hash"] = loop.sim.island.heightmap_hash()
started["match_phase"] = loop.match_flow.phase_name()
started["listening"] = false
started["note"] = "networking arrives in v0.5; players join as idle slots until then"
started["listening"] = game != null
_log("start", started)
func _process(delta: float) -> void:
if _finished or loop == null:
return
if game != null:
game.poll()
for event: Dictionary in game.events:
var fields: Dictionary = {"handle": event["handle"], "name": event["name"], "players": game.net.player_count()}
if event["type"] == "left":
fields["reason"] = event["reason"]
_log("player_" + String(event["type"]), fields)
var due: int = UNTHROTTLED_BATCH
if not config.unthrottled:
_accumulator += delta
@@ -79,6 +99,8 @@ func _tick() -> void:
if config.fault == "script-error" and loop.ticks == FAULT_TICK:
_deliberate_script_error()
loop.run_tick()
if game != null:
game.after_tick()
for event: Dictionary in loop.match_flow.events:
if event["type"] in ["phase", "match_started", "match_ended"]:
_log("match", event)
@@ -94,6 +116,8 @@ func _tick() -> void:
func _finish(requested_code: int) -> void:
_finished = true
var code: int = requested_code
if game != null:
game.net.close()
if loop != null:
var stats: Dictionary = loop.timing_stats()
stats["state_hash"] = loop.sim.state_hash()
+111
View File
@@ -0,0 +1,111 @@
## Joins the transport to the match: people who connect become participants, their
## input packets become commands through ServerLoop.submit(), and everyone is sent
## snapshots of what they may see, 20 times a second.
##
## Call poll() once a frame before running ticks, and after_tick() after each tick.
class_name NetGame
extends RefCounted
var loop: ServerLoop
var net: NetServer
var sender: SnapshotSender = SnapshotSender.new()
## What happened during the last poll(): {"type": "joined" or "left", "handle", "name",
## "reason"}, for the server's log.
var events: Array[Dictionary] = []
## Input packets that couldn't be read, so far.
var bad_inputs: int = 0
## Handle -> the newest command tick taken from them this match.
var _last_command: Dictionary = {}
func _init(server_loop: ServerLoop, server_net: NetServer) -> void:
loop = server_loop
net = server_net
net.max_players = loop.match_flow.rules.max_players
net.match_seed = loop.match_flow.current_seed()
## Services the network: joins and leaves, then every input packet that arrived.
func poll() -> void:
events.clear()
net.poll()
# kick() adds to net.events, so walk a copy.
for event: Dictionary in net.events.duplicate():
var handle: int = int(event.get("handle", 0))
if event["type"] == "joined":
if loop.match_flow.join(handle):
sender.add_client(handle)
_last_command[handle] = -1
_send_match(handle)
events.append(event)
else:
net.kick(handle, NetProtocol.REASON_FULL)
elif event["type"] == "left" and sender.has_client(handle):
loop.match_flow.leave(handle)
sender.remove_client(handle)
_last_command.erase(handle)
events.append(event)
for packet: Dictionary in net.packets:
var handle: int = packet["handle"]
if not sender.has_client(handle):
continue
var input: Dictionary = NetSnapshot.decode_input(packet["bytes"])
if input.is_empty():
bad_inputs += 1
continue
sender.acknowledge(handle, int(input["ack"]))
if not loop.match_flow.in_match():
continue
# Packets repeat recent commands; each tick's command is offered once, whether
# or not the simulation takes it.
for command: PlayerCommand in input["commands"]:
if command.tick <= int(_last_command[handle]):
continue
_last_command[handle] = command.tick
if loop.submit(handle, command):
sender.note_command(handle, command.tick)
## Tells everyone about a change of phase, and sends snapshots when one is due.
func after_tick() -> void:
var flow: Match = loop.match_flow
var changed: bool = false
for event: Dictionary in flow.events:
if event["type"] == "phase":
changed = true
if event["to"] == "lobby":
# A new simulation: entity IDs and ticks start again.
sender.reset()
for handle: int in _last_command:
_last_command[handle] = -1
net.match_seed = flow.current_seed()
if changed:
for handle: int in net.handles():
_send_match(handle)
if loop.ticks % Tuning.NET_SNAPSHOT_INTERVAL_TICKS != 0:
return
for handle: int in net.handles():
if not sender.has_client(handle):
continue
var bytes: PackedByteArray = sender.build(handle, loop.sim, viewer_of(handle), loop.ticks, flow.phase)
net.send(handle, NetProtocol.CHANNEL_STATE, bytes, false)
## The entity a participant is watching: their own player, the player they spectate
## once eliminated, or 0 when they aren't in a match.
func viewer_of(handle: int) -> int:
var flow: Match = loop.match_flow
if flow.phase == Match.LOBBY or flow.phase == Match.COUNTDOWN or not flow.entity_of.has(handle):
return 0
var target: int = flow.spectate_target(handle)
if target != 0 and flow.entity_of.has(target):
return int(flow.entity_of[target])
return int(flow.entity_of[handle])
func _send_match(handle: int) -> void:
var flow: Match = loop.match_flow
var started: bool = flow.in_match() or flow.phase == Match.RESULTS
var index: int = flow.matches_started - 1 if started else flow.matches_started
net.send(handle, NetProtocol.CHANNEL_CONTROL, NetSnapshot.encode_match(flow.phase, index, flow.current_seed()), true)
+1
View File
@@ -0,0 +1 @@
uid://b3uihs71yhq6f
+15 -3
View File
@@ -1,9 +1,13 @@
## Command-line configuration for a headless server.
##
## tools/godot.sh -- --server [--seed=N] [--port=N] [--players=N] [--bots=N]
## tools/godot.sh -- --server [--listen] [--port=N] [--seed=N] [--players=N] [--bots=N]
## [--bot-difficulty=mixed|easy|normal|hard] [--ticks=N]
## [--unthrottled] [--log-every=N]
##
## With `--listen` the server takes network players on UDP `--port`, waits in the lobby
## for the first of them, and with any `--bots` above 0 fills each match's empty places
## with bots. Without it the match starts at once with `--players` idle slots.
##
## Unknown or malformed arguments are errors, so a typo can't silently run the wrong
## match. See `parse()`.
class_name ServerConfig
@@ -19,9 +23,11 @@ var server: bool = false
## The match seed. `has_seed` is false when none was given and the server must pick one.
var match_seed: int = 0
var has_seed: bool = false
## UDP port the server will listen on once networking lands (v0.5).
## True when `--listen` was given: take network players on `port`.
var listen: bool = false
## UDP port a listening server uses.
var port: int = DEFAULT_PORT
## Player slots for human clients. Until v0.5 they join as idle players.
## Idle player slots, for a server that isn't listening.
var players: int = 0
var bots: int = 0
## Every bot's difficulty, as an index into Tuning.BOT_DIFFICULTIES, or -1 to mix them.
@@ -59,6 +65,7 @@ func is_valid() -> bool:
func to_dictionary() -> Dictionary:
return {
"seed": match_seed,
"listen": listen,
"port": port,
"players": players,
"bots": bots,
@@ -72,6 +79,9 @@ func _parse_one(arg: String) -> void:
if arg == "--unthrottled":
unthrottled = true
return
if arg == "--listen":
listen = true
return
var parts: PackedStringArray = arg.split("=", true, 1)
if parts.size() != 2 or not arg.begins_with("--"):
errors.append("unknown argument '%s'" % arg)
@@ -129,6 +139,8 @@ func _validate() -> void:
"--players plus --bots is %d, more than the match size of %d"
% [players + bots, Tuning.SOLO_PLAYERS]
)
if listen and players > 0:
errors.append("--players is for a server that isn't listening; with --listen, people join over the network")
if ticks < 0:
errors.append("--ticks can't be negative")
if log_every < 0:
+19
View File
@@ -10,6 +10,25 @@ const MAX_COMMAND_LEAD_TICKS: int = 60
## Width and depth of the playable world. Positions are clamped inside it.
const WORLD_SIZE_METRES: float = 1024.0
# Network. See docs/ARCHITECTURE.md, "Snapshot format".
## Server ticks between snapshots: 20 a second.
const NET_SNAPSHOT_INTERVAL_TICKS: int = 3
## The most bytes in one snapshot. Keeps a packet inside one UDP datagram on any
## ordinary link, and a client under 24 KB/s before packet headers.
const NET_SNAPSHOT_MAX_BYTES: int = 1200
## A client is sent other players and shots within this many metres on the map of the
## player it is watching: a little further than the longest weapon reaches.
const NET_INTEREST_PLAYERS_METRES: float = 380.0
## And items lying on the ground within this many.
const NET_INTEREST_PICKUPS_METRES: float = 90.0
## Snapshots the server remembers per client, to send changes against.
const NET_SNAPSHOT_HISTORY: int = 40
## When a snapshot is full, each snapshot an entity has waited counts as this many
## metres closer, so nothing far away waits for ever.
const NET_STALE_METRES_PER_SNAPSHOT: float = 6.0
## Commands a client repeats in each input packet, so a lost packet costs nothing.
const NET_INPUT_REDUNDANCY: int = 3
# Match sizes
const SOLO_PLAYERS: int = 24
const DUO_TEAMS: int = 12