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>
This commit is contained in:
2026-11-12 21:56:01 -05:00
co-authored by Claude Opus 5.5
parent 65b1fe015c
commit 05c7568ec1
25 changed files with 1135 additions and 39 deletions
+73
View File
@@ -0,0 +1,73 @@
## The script a soak-test client plays by. It only sees what a network client sees: its
## own predicted player and its copy of the island. It leaps from the barge over land,
## glides, heads for the island's highest ground (where the tide leaves people last),
## swings the boathook at whatever is in front of it, which harvests trees and crates,
## and every few seconds tries to put up a wall. So a soak match has movement, world
## changes and building from every client, not just walking.
##
## Each client's script is offset by its `number`, so they don't all act on the same tick.
class_name SoakPlayer
extends RefCounted
const TICKS: int = Tuning.TICK_RATE_HZ
## Within this many metres of the high ground, wander instead of heading for it.
const NEAR_TOP_METRES: float = 24.0
const BUILD: int = PlayerCommand.BUTTON_BUILD | PlayerCommand.BUTTON_FIRE
var number: int = 0
## Build attempts made, for the report.
var build_attempts: int = 0
var _world: Simulation = null
var _top: Vector2 = Vector2.ZERO
func _init(client_number: int) -> void:
number = client_number
## The command for `tick`, for the player `me` on the client's `world`.
func command(tick: int, me: SimEntity, world: Simulation) -> PlayerCommand:
if world != _world:
_world = world
_top = _highest_point(world.ground)
var seconds: float = float(tick + number * 37) / TICKS
var to_top: Vector2 = _top - Vector2(me.position.x, me.position.z)
var yaw: float = atan2(to_top.x, to_top.y)
if me.drop_state == Drop.ABOARD:
var wait: int = (3 + number % 8) * TICKS
var over_land: bool = world.ground.terrain_height(me.position.x, me.position.z) > Tuning.ISLAND_BEACH_TOP + 2.0
return PlayerCommand.from_input(tick, Vector2.ZERO, yaw, 0.0, PlayerCommand.BUTTON_JUMP if tick > wait and over_land else 0)
if me.drop_state != Drop.NONE:
return PlayerCommand.from_input(tick, Vector2(0.0, 1.0), yaw, 0.0)
var phase: int = (tick + number * 11) % (6 * TICKS)
if phase == 0 and Building.is_allowed(me):
build_attempts += 1
# A wall on one side or another of the cell it stands in.
return PlayerCommand.from_input(tick, Vector2.ZERO, (number + build_attempts) % 4 * PI * 0.5, 0.0, BUILD, StructureSet.WALL, Materials.DRIFTWOOD)
var move: Vector2 = Vector2(0.0, 1.0)
if to_top.length() < NEAR_TOP_METRES:
yaw += sin(seconds * 0.5) * 1.5
move = Vector2(0.0, 1.0) if fmod(seconds, 8.0) < 5.0 else Vector2.ZERO
var buttons: int = 0
if phase > 3 * TICKS:
# Swing at what is in front: trees and crates give materials to build with.
buttons |= PlayerCommand.BUTTON_FIRE
move = Vector2.ZERO
if (tick + number) % (3 * TICKS) == 0:
buttons |= PlayerCommand.BUTTON_JUMP
return PlayerCommand.from_input(tick, move, yaw, deg_to_rad(-10.0), buttons, 0)
static func _highest_point(ground: SimGround) -> Vector2:
var best: Vector2 = Vector2.ONE * Tuning.WORLD_SIZE_METRES * 0.5
var best_height: float = -INF
var step: float = SafeGround.STRIDE_METRES
var cells: int = floori(Tuning.WORLD_SIZE_METRES / step)
for gz: int in cells:
for gx: int in cells:
var height: float = ground.terrain_height(gx * step, gz * step)
if height > best_height:
best_height = height
best = Vector2(gx * step, gz * step)
return best
+1
View File
@@ -0,0 +1 @@
uid://crrcpgj0w1l6j
+5
View File
@@ -44,6 +44,9 @@ var outbox: Array[PackedByteArray] = []
var net: NetClient = null
## Packets that made no sense, so far.
var bad_packets: int = 0
## Called after each snapshot has been taken in, with no arguments. Soak tests use it
## to compare the client's world with the server's at that moment.
var on_snapshot: Callable = Callable()
var _recent: Array[PlayerCommand] = []
var _ack_due: bool = false
@@ -91,6 +94,8 @@ func receive(channel: int, bytes: PackedByteArray) -> void:
_take_notice(notice)
elif receiver.apply(bytes):
_take_snapshot()
if on_snapshot.is_valid():
on_snapshot.call()
## Runs the client for `delta` seconds: makes and predicts the commands that are due,
+1 -1
View File
@@ -82,7 +82,7 @@ func poll(now_msec: int = -1) -> void:
break
match kind:
ENetConnection.EVENT_CONNECT:
_peer.set_timeout(0, peer_timeout_min_msec, peer_timeout_max_msec)
_peer.set_timeout(NetProtocol.PEER_TIMEOUT_LIMIT, peer_timeout_min_msec, peer_timeout_max_msec)
_peer.send(NetProtocol.CHANNEL_CONTROL, NetProtocol.encode_hello(_wanted_name, protocol_version), ENetPacketPeer.FLAG_RELIABLE)
state = HANDSHAKING
_since_msec = now
+8
View File
@@ -28,6 +28,14 @@ const MSG_WELCOME: int = 2
const MSG_REJECT: int = 3
## Why a connection ended. Sent in REJECT and as disconnect data.
## ENet's timeout limit for every peer: a reliable message is given up on after this
## many round-trip timeouts' worth of resends (and at least the peer's minimum timeout),
## or after its maximum timeout. ENet's own default. 0, which this once was, gives up as
## soon as any reliable message has waited the minimum timeout: over a link losing 2%
## of datagrams each way, a run of unlucky resends then dropped a few soak clients a
## match (issue N8).
const PEER_TIMEOUT_LIMIT: int = 32
const REASON_NONE: int = 0
const REASON_VERSION: int = 1
const REASON_FULL: int = 2
+1 -1
View File
@@ -107,7 +107,7 @@ func poll(now_msec: int = -1) -> void:
var peer: ENetPacketPeer = event[1]
match kind:
ENetConnection.EVENT_CONNECT:
peer.set_timeout(0, peer_timeout_min_msec, peer_timeout_max_msec)
peer.set_timeout(NetProtocol.PEER_TIMEOUT_LIMIT, peer_timeout_min_msec, peer_timeout_max_msec)
var address: String = peer.get_remote_address()
if not connect_limiter.allow(address, now) or _guests_from(address) >= max_guests_per_address:
_refuse(peer, NetProtocol.REASON_BUSY)
+28 -20
View File
@@ -263,26 +263,34 @@ static func encode_snapshot(header: Dictionary, removed: PackedInt32Array, recor
_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])
# 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
+23 -6
View File
@@ -24,6 +24,10 @@ var _records: Dictionary = {}
var _records_tick: int = -1
## Every entity at that tick, listed once for all clients.
var _entities: Array[SimEntity] = []
## Also shared for the tick: entity ID * 64 + mask -> the record encoded with that mask
## (NetSnapshot.encode_record()), and entity ID -> its record's position.
var _encoded: Dictionary = {}
var _positions: Dictionary = {}
func add_client(handle: int) -> void:
@@ -68,6 +72,8 @@ func reset() -> void:
client["last_sent"] = {}
client["command_tick"] = -1
_records.clear()
_encoded.clear()
_positions.clear()
_entities.clear()
_records_tick = -1
@@ -123,6 +129,8 @@ func build(handle: int, sim: Simulation, viewer_id: int, tick: int, match_phase:
var viewer: SimEntity = sim.entities.find(viewer_id) if viewer_id > 0 else null
if _records_tick != tick:
_records.clear()
_encoded.clear()
_positions.clear()
_records_tick = tick
_entities = sim.entities.entities()
@@ -146,13 +154,19 @@ func build(handle: int, sim: Simulation, viewer_id: int, tick: int, match_phase:
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)
var before: PackedInt32Array = base[entity_id]
# Most entities, standing still, compare equal: skip the field-by-field diff.
if before == record:
continue
mask = NetSnapshot.diff_mask(before, 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
if not _positions.has(entity_id):
_positions[entity_id] = NetSnapshot.position_of(record)
score = (_positions[entity_id] as Vector3).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])
@@ -172,12 +186,15 @@ func build(handle: int, sim: Simulation, viewer_id: int, tick: int, match_phase:
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:
var key: int = int(entry[1]) * 64 + int(entry[2])
if not _encoded.has(key):
_encoded[key] = NetSnapshot.encode_record(entry[1], entry[2], record)
var encoded: PackedByteArray = _encoded[key]
if encoded.size() > budget:
client["deferred"] += 1
continue
budget -= cost
records.append([entry[1], entry[2], record])
budget -= encoded.size()
records.append([entry[1], entry[2], record, encoded])
state[entry[1]] = record
last_sent[entry[1]] = tick
+122
View File
@@ -0,0 +1,122 @@
## A bad network in a box, for soak tests: a UDP relay that sits between one client and
## a server and passes datagrams both ways after a delay of `latency_ms` plus or minus
## `jitter_ms`, losing a `loss` fraction of them. Packets can overtake each other, as on
## a real link. Seeded, so a run can be repeated.
##
## The client connects to the relay's port instead of the server's. The first datagram
## to arrive there says where the client is; later ones from anywhere else are ignored.
## ENet runs over UDP, so the game's own transport is tested unchanged.
##
## Call poll() often (every frame). Delays are only as fine as the gap between polls.
class_name UdpRelay
extends RefCounted
var latency_ms: float = 0.0
var jitter_ms: float = 0.0
var loss: float = 0.0
## Datagrams and payload bytes, each way, that came in, and the datagrams lost.
## "up" is client to server, "down" server to client.
var up_packets: int = 0
var up_bytes: int = 0
var up_lost: int = 0
var down_packets: int = 0
var down_bytes: int = 0
var down_lost: int = 0
## When a datagram last came in from each side, in msec (Time.get_ticks_msec()), or -1.
var last_up_msec: int = -1
var last_down_msec: int = -1
var _rng: RandomNumberGenerator = RandomNumberGenerator.new()
var _downstream: PacketPeerUDP = PacketPeerUDP.new()
var _upstream: PacketPeerUDP = PacketPeerUDP.new()
var _client_ip: String = ""
var _client_port: int = 0
## [due msec, true when bound for the server, bytes], in no particular order.
var _queue: Array = []
func _init(latency: float = 0.0, jitter: float = 0.0, loss_fraction: float = 0.0, relay_seed: int = 1) -> void:
latency_ms = latency
jitter_ms = jitter
loss = loss_fraction
_rng.seed = relay_seed
## Listens for the client on `port` (0 picks a free one) and forwards to the server at
## `server_ip`:`server_port`.
func open(port: int, server_ip: String, server_port: int, bind_address: String = "127.0.0.1") -> Error:
var error: Error = _downstream.bind(port, bind_address)
if error != OK:
return error
error = _upstream.connect_to_host(server_ip, server_port)
if error != OK:
_downstream.close()
return error
## The port the client should connect to.
func port() -> int:
return _downstream.get_local_port()
func close() -> void:
_downstream.close()
_upstream.close()
_queue.clear()
## Takes what has arrived on both sides and sends on whatever is due.
func poll(now_msec: int = -1) -> void:
var now: int = now_msec if now_msec >= 0 else Time.get_ticks_msec()
while _downstream.get_available_packet_count() > 0:
var bytes: PackedByteArray = _downstream.get_packet()
var ip: String = _downstream.get_packet_ip()
var from_port: int = _downstream.get_packet_port()
if _client_ip.is_empty():
_client_ip = ip
_client_port = from_port
_downstream.set_dest_address(_client_ip, _client_port)
elif ip != _client_ip or from_port != _client_port:
continue
up_packets += 1
up_bytes += bytes.size()
last_up_msec = now
if _rng.randf() < loss:
up_lost += 1
else:
_queue.append([now + _delay(), true, bytes])
while _upstream.get_available_packet_count() > 0:
var bytes: PackedByteArray = _upstream.get_packet()
down_packets += 1
down_bytes += bytes.size()
last_down_msec = now
if _rng.randf() < loss:
down_lost += 1
else:
_queue.append([now + _delay(), false, bytes])
if _queue.is_empty():
return
var waiting: Array = []
var due: Array = []
for entry: Array in _queue:
if int(entry[0]) <= now:
due.append(entry)
else:
waiting.append(entry)
_queue = waiting
due.sort_custom(func(a: Array, b: Array) -> bool: return int(a[0]) < int(b[0]))
for entry: Array in due:
if entry[1]:
_upstream.put_packet(entry[2])
elif not _client_ip.is_empty():
_downstream.put_packet(entry[2])
## Datagrams waiting to be sent on.
func in_flight() -> int:
return _queue.size()
func _delay() -> int:
return maxi(roundi(latency_ms + _rng.randf_range(-jitter_ms, jitter_ms)), 0)
+1
View File
@@ -0,0 +1 @@
uid://cq3gv5durd8x6
+27 -4
View File
@@ -26,6 +26,10 @@ var _errors: ErrorCounter = ErrorCounter.new()
var _accumulator: float = 0.0
var _started_usec: int = 0
var _finished: bool = false
var _matches_ended: int = 0
## When listening: microseconds each tick took including the network's share (after_tick:
## world messages and snapshots), which ServerLoop's own timing leaves out.
var _net_tick_usec: PackedInt64Array = PackedInt64Array()
func _init(server_config: ServerConfig) -> void:
@@ -91,10 +95,10 @@ func _process(delta: float) -> void:
# Too far behind to catch up: drop the backlog rather than spiral.
_accumulator = minf(_accumulator, 1.0 / Tuning.TICK_RATE_HZ)
for _index: int in due:
if config.ticks > 0 and loop.ticks >= config.ticks:
if _done():
break
_tick()
if config.ticks > 0 and loop.ticks >= config.ticks:
if _done():
_finish(0)
@@ -104,6 +108,11 @@ func _exit_tree() -> void:
_finish(0)
## True once the run has done what it was asked: its ticks, or its matches.
func _done() -> bool:
return (config.ticks > 0 and loop.ticks >= config.ticks) or (config.matches > 0 and _matches_ended >= config.matches)
func _open_beacon() -> void:
if not config.lan and config.lists.is_empty():
return
@@ -131,19 +140,26 @@ func _open_beacon() -> void:
func _tick() -> void:
if config.fault == "script-error" and loop.ticks == FAULT_TICK:
_deliberate_script_error()
var began: int = Time.get_ticks_usec()
loop.run_tick()
if game != null:
game.after_tick()
_net_tick_usec.append(Time.get_ticks_usec() - began)
if config.world_hash_every > 0 and loop.sim.tick > 0 and loop.sim.tick % config.world_hash_every < Tuning.NET_SNAPSHOT_INTERVAL_TICKS:
_log("world_hash", {"match": NetSnapshot.decode_match(game.match_notice())["index"], "sim_tick": loop.sim.tick, "hash": NetWorld.world_hash(loop.sim)})
for event: Dictionary in loop.match_flow.events:
if event["type"] in ["phase", "match_started", "match_ended"]:
_log("match", event)
var fields: Dictionary = event.duplicate()
fields["mem_bytes"] = OS.get_static_memory_usage()
_log("match", fields)
elif event["type"] == "placed":
_log("eliminated", event)
if event["type"] == "match_ended":
_log("results", {"match": event["match"], "summary": loop.match_flow.summary()})
_matches_ended += 1
if config.log_every > 0 and loop.ticks % config.log_every == 0:
var stats: Dictionary = loop.timing_stats()
_log("progress", {"tick": loop.ticks, "p95_us": stats["p95_us"], "max_us": stats["max_us"]})
_log("progress", {"tick": loop.ticks, "p95_us": stats["p95_us"], "max_us": stats["max_us"], "mem_bytes": OS.get_static_memory_usage()})
func _finish(requested_code: int) -> void:
@@ -157,6 +173,13 @@ func _finish(requested_code: int) -> void:
var stats: Dictionary = loop.timing_stats()
stats["state_hash"] = loop.sim.state_hash()
stats["entities"] = loop.sim.entities.count()
if not _net_tick_usec.is_empty():
var sorted: PackedInt64Array = _net_tick_usec.duplicate()
sorted.sort()
stats["with_net_p50_us"] = ServerLoop._percentile(sorted, 0.50)
stats["with_net_p99_us"] = ServerLoop._percentile(sorted, 0.99)
stats["with_net_max_us"] = sorted[sorted.size() - 1]
stats["mem_bytes"] = OS.get_static_memory_usage()
_log("stats", stats)
if code == 0 and _errors.count() > 0:
code = 1
+11 -4
View File
@@ -138,18 +138,25 @@ func after_tick() -> void:
if not bytes.is_empty():
own_changes[handle] = bytes
net.send(handle, NetProtocol.CHANNEL_CONTROL, bytes, true)
if not snapshot_due():
return
for handle: int in net.handles():
if sender.has_client(handle):
if sender.has_client(handle) and snapshot_due_for(handle):
net.send(handle, NetProtocol.CHANNEL_STATE, snapshot_for(handle), false)
## True on the ticks a snapshot goes out.
## True on the ticks a snapshot goes out to an owner that carries packets for a single
## client itself (LocalServer and tests).
func snapshot_due() -> bool:
return loop.ticks % Tuning.NET_SNAPSHOT_INTERVAL_TICKS == 0
## True on the ticks a networked client's snapshot goes out. Clients are spread over
## the ticks of the interval by handle, so the cost of building snapshots, the largest
## share of a busy server's tick, is split between them instead of landing on one.
func snapshot_due_for(handle: int) -> bool:
var interval: int = Tuning.NET_SNAPSHOT_INTERVAL_TICKS
return (loop.ticks + posmod(handle, interval)) % interval == 0
## The snapshot for a participant as things stand: what they may see, and their own
## block while they are playing.
func snapshot_for(handle: int) -> PackedByteArray:
+18 -1
View File
@@ -2,7 +2,7 @@
##
## 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]
## [--unthrottled] [--log-every=N] [--matches=N] [--world-hash-every=N]
## [--name=NAME] [--list=HOST[:PORT]]... [--no-lan]
##
## With `--listen` the server takes network players on UDP `--port`, waits in the lobby
@@ -38,6 +38,12 @@ var bots: int = 0
var bot_difficulty: int = -1
## Ticks to run before exiting. 0 runs until the process is stopped.
var ticks: int = 0
## Stops after this many matches have ended. 0 doesn't stop for matches.
var matches: int = 0
## On the simulation ticks from each multiple of this many up to the snapshot interval
## (never tick 0, which lasts the whole lobby), logs NetWorld.world_hash() of the match's
## world, so a soak test can compare it with its clients' copies. 0 turns it off.
var world_hash_every: int = 0
## Runs ticks back to back instead of at the real tick rate. For tests and smoke runs.
var unthrottled: bool = false
## Logs a progress line every this many ticks. 0 turns progress lines off.
@@ -81,6 +87,7 @@ func to_dictionary() -> Dictionary:
"bots": bots,
"bot_difficulty": "mixed" if bot_difficulty < 0 else String(Tuning.BOT_DIFFICULTIES[bot_difficulty]["name"]),
"ticks": ticks,
"matches": matches,
"unthrottled": unthrottled,
"name": server_name,
"lan": lan and listen,
@@ -124,6 +131,12 @@ func _parse_one(arg: String) -> void:
"--log-every":
if _check_int(key, value):
log_every = value.to_int()
"--matches":
if _check_int(key, value):
matches = value.to_int()
"--world-hash-every":
if _check_int(key, value):
world_hash_every = value.to_int()
"--bot-difficulty":
var found: bool = value == "mixed"
for index: int in Tuning.BOT_DIFFICULTIES.size():
@@ -195,6 +208,10 @@ func _validate() -> void:
errors.append("--ticks can't be negative")
if log_every < 0:
errors.append("--log-every can't be negative")
if matches < 0 or world_hash_every < 0:
errors.append("--matches and --world-hash-every can't be negative")
if world_hash_every > 0 and not listen:
errors.append("--world-hash-every is for a server started with --listen")
if not listen and (not lists.is_empty() or not lan):
errors.append("--list and --no-lan are for a server started with --listen")
if fault not in FAULTS: