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
+47 -10
View File
@@ -145,19 +145,56 @@ and dropped.
## Snapshot format
A snapshot is a binary, little-endian packet:
`NetSnapshot` (`src/net/`) owns the layouts. An entity travels as a **record**: a list
of whole numbers, already quantized, laid out per archetype. The server compares
records to see what changed, the wire carries only the changed field groups, and the
client keeps records as its picture of the world.
A snapshot is a binary, little-endian packet on channel 1, unreliable:
| Part | Contents |
|---|---|
| Header | Protocol version (u8), server tick (u32), baseline tick (u32, 0 = full), last command tick applied for this client (u32) |
| Tide | Phase (u8), level in centimetres (u16) |
| Entities | Count, then records of ID (varint), archetype (u8), changed-field mask (u8), then only the fields that changed |
| Removed | Count, then IDs |
| Header | Message type (u8), server tick (u32), baseline tick (u32, 0 = builds on nothing), simulation tick (u32), last command tick taken from this client (u32), the entity the client is watching (varint) |
| Match and tide | Match phase (u8), tide phase (u8), sea level in centimetres (s16) |
| Removed | Count (u8), then IDs (varint) |
| Entities | Count (u16), then records of ID (varint), archetype and changed-group mask (u8), then only the groups that changed |
Positions are quantized to 1.5 cm (u16 per axis, 1,024 m range), yaw to u16, health to u8.
Snapshots are deltas against the latest baseline the client acknowledged, and fall back to a full
snapshot if none. Players only receive entities in their relevance range. Building changes are also
sent on a reliable ordered event stream, since a dropped wall is a gameplay lie.
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 clock commands name.
Positions are quantized to 1/64 m (u16 per axis: 1,024 m across, heights from -128 m),
yaw to u16, pitch to s8, health and armour to u8. Field groups: players have position,
look, vitals, state flags and held item; pickups and shots have position and item.
**Deltas and loss.** `SnapshotSender` remembers what it told each client in its last 40
snapshots. Each snapshot is a delta against the newest one that client has
acknowledged (its input packets carry that tick), or builds on nothing if there is
none or it is too old. A delta only ever builds on something the client confirmed
holding, so a lost snapshot is never resent: the next one covers it.
`SnapshotReceiver` ignores snapshots older than its newest, and if it is ever sent a
delta on something it doesn't hold, acknowledges 0 to ask for a fresh start.
**Interest.** A client is told only about entities near the player it is watching
(its own, or the one it spectates): players and shots within
`Tuning.NET_INTEREST_PLAYERS_METRES` (380 m, a little past the longest weapon) and
items on the ground within `NET_INTEREST_PICKUPS_METRES` (90 m), measured on the map.
An entity that leaves range is removed from the client's picture and nothing more is
said about it. Outside a match there is no viewer and a snapshot is only its header.
**Budget.** A snapshot is at most `Tuning.NET_SNAPSHOT_MAX_BYTES` (1,200), so 20 a
second is at most 24 KB/s before packet headers and never fragments. When more has
changed than fits, the client's own player goes first, then the nearest, and each
snapshot an update has waited counts as 6 m closer, so nothing waits for ever. What
didn't fit is still owed and goes in a later snapshot.
**Input.** The client answers on channel 1 with the snapshot tick it holds and its
last few commands (`Tuning.NET_INPUT_REDUNDANCY`), oldest first. `NetGame`
(`src/server/`) offers each tick's command to `ServerLoop.submit()` once.
**Match notice.** On joining and at every change of phase the server sends, reliably
on channel 0, the match phase, index and seed, so the client can generate the island.
Building changes will also travel on a reliable ordered event stream (N5), since a
dropped wall is a gameplay lie.
## Module map
@@ -166,7 +203,7 @@ sent on a reliable ordered event stream, since a dropped wall is a gameplay lie.
| `src/sim/` | Tick loop, entities, RNG, commands, tide, combat, building | `src/sim/` only |
| `src/bots/` | Bot brains that produce `PlayerCommand`s | `src/sim/` |
| `src/net/` | Transport, snapshot encoding, prediction, lag compensation | `src/sim/` |
| `src/server/` | Headless and listen-server hosting | `src/sim/`, `src/bots/`, `src/net/` |
| `src/server/` | Headless and listening servers, joining the network to the match | `src/sim/`, `src/bots/`, `src/net/` |
| `src/client/` | World rendering, camera, input, effects | `src/sim/`, `src/net/` |
| `src/ui/` | HUD, menus, map | `src/sim/` (read only), `src/client/` |
| `src/audio/` | Sound playback, music | `src/sim/` (read only) |