Delta-compressed snapshots with per-client interest management and a fixed bandwidth budget.
Acceptance
Under 40 KB/s per client in a 24-player scenario, measured by a test.
Clients recover from lost snapshots.
Clients receive no data about entities outside their interest area, verified by test.
**Depends on:** N1
Delta-compressed snapshots with per-client interest management and a fixed bandwidth budget.
**Acceptance**
- Under 40 KB/s per client in a 24-player scenario, measured by a test.
- Clients recover from lost snapshots.
- Clients receive no data about entities outside their interest area, verified by test.
claude
added this to the v0.5 Multiplayer milestone 2026-11-09 05:28:12 +00:00
NetSnapshot (src/net/net_snapshot.gd): the wire format. Entities travel as quantized records with per-archetype field groups, so a snapshot carries only the groups that changed. Also the client's input packet (acknowledged snapshot tick plus its last few commands) and a reliable match notice (phase, index, seed).
SnapshotSender: per client, a delta against the newest snapshot that client acknowledged, falling back to one that builds on nothing. Interest is by distance on the map from the player being watched: 380 m for players and shots, 90 m for items. Each snapshot is capped at 1,200 bytes; when more changed than fits, the client's own player goes first, then nearest first with a bonus for how long an update has waited.
SnapshotReceiver: rebuilds the picture, ignores old and repeated snapshots, and asks for a fresh start if sent a delta on something it doesn't hold.
NetGame (src/server/net_game.gd): people who connect join the match flow, inputs go through ServerLoop.submit() once per tick, snapshots go out 20 times a second. Eliminated players are sent what their spectate target sees.
tools/godot.sh -- --server --listen [--port=N] [--bots=1] makes the headless server take network players. It waits in the lobby for the first person.
docs/ARCHITECTURE.md, "Snapshot format", rewritten to match.
Acceptance
Under 40 KB/s per client in a 24-player scenario, measured by a test:test_snapshot_budget.gd plays the first 90 seconds of a 24-bot match with every player a client, 10% of snapshots and acknowledgements lost and acknowledgements two snapshots late. Mean 2.4 KB/s, worst client 2.5 KB/s, worst single second for any client 5.8 KB, largest snapshot 385 bytes, all including 40 bytes of IP, UDP and ENet headers per packet. The cap also bounds the worst case at about 24.8 KB/s whatever happens.
Clients recover from lost snapshots:test_snapshot_stream.gd loses 40% of snapshots and 40% of acknowledgements over 400 rounds and checks the client's picture equals the truth after every snapshot that arrives; also a silence longer than the server's memory, a client that lost its baseline, duplicates and reordering. The 24-player test ends by checking all 24 pictures are exact.
No data about entities outside the interest area: both tests decode every packet built and fail on any record for an entity out of range, or even a removal naming one that was never in range.
Also tested: codec round trips, truncation at every length and random corruption without engine errors; a crowd of 600 items spread over several snapshots nearest first; a distant player not starved by 200 busy near ones; and test_net_game.gd end to end over loopback UDP: two clients join the lobby, the match starts, both get the seed and phases, see all four players, steer their own players by input, leave, a late joiner is told the server is full, and junk on the game channel is counted and ignored. make check passes: 384 tests, self-check and smoke, which now also starts a listening server.
Limits and follow-ups
The 90 seconds measured are the drop and early looting. Late-match fights weren't measured over the network; the cap still holds there. N8 (#39) is the real soak.
Building all 24 snapshots takes about 5 ms on this machine, every third tick, against a 12 ms tick budget. Fine for now; a candidate for H1 (#54).
The own player's private state (velocity, inventory, ammunition, materials, cooldowns) isn't in the snapshot yet. N3 (#34) needs it for prediction and should add a self block. Structures, world damage and loot containers are N5 (#36).
Interest ignores height and line of sight. A player behind a hill 300 m away is still sent. N9 (#40) can tighten that if wanted.
When bots have filled a running match, a person who connects is turned away as "full" until it ends. N6 (#37) should let them wait in the lobby instead.
There is no client program yet: NetClient and SnapshotReceiver are driven by tests only.
Done in e535c1f.
**What changed**
- `NetSnapshot` (`src/net/net_snapshot.gd`): the wire format. Entities travel as quantized records with per-archetype field groups, so a snapshot carries only the groups that changed. Also the client's input packet (acknowledged snapshot tick plus its last few commands) and a reliable match notice (phase, index, seed).
- `SnapshotSender`: per client, a delta against the newest snapshot that client acknowledged, falling back to one that builds on nothing. Interest is by distance on the map from the player being watched: 380 m for players and shots, 90 m for items. Each snapshot is capped at 1,200 bytes; when more changed than fits, the client's own player goes first, then nearest first with a bonus for how long an update has waited.
- `SnapshotReceiver`: rebuilds the picture, ignores old and repeated snapshots, and asks for a fresh start if sent a delta on something it doesn't hold.
- `NetGame` (`src/server/net_game.gd`): people who connect join the match flow, inputs go through `ServerLoop.submit()` once per tick, snapshots go out 20 times a second. Eliminated players are sent what their spectate target sees.
- `tools/godot.sh -- --server --listen [--port=N] [--bots=1]` makes the headless server take network players. It waits in the lobby for the first person.
- `docs/ARCHITECTURE.md`, "Snapshot format", rewritten to match.
**Acceptance**
- *Under 40 KB/s per client in a 24-player scenario, measured by a test:* `test_snapshot_budget.gd` plays the first 90 seconds of a 24-bot match with every player a client, 10% of snapshots and acknowledgements lost and acknowledgements two snapshots late. Mean 2.4 KB/s, worst client 2.5 KB/s, worst single second for any client 5.8 KB, largest snapshot 385 bytes, all including 40 bytes of IP, UDP and ENet headers per packet. The cap also bounds the worst case at about 24.8 KB/s whatever happens.
- *Clients recover from lost snapshots:* `test_snapshot_stream.gd` loses 40% of snapshots and 40% of acknowledgements over 400 rounds and checks the client's picture equals the truth after every snapshot that arrives; also a silence longer than the server's memory, a client that lost its baseline, duplicates and reordering. The 24-player test ends by checking all 24 pictures are exact.
- *No data about entities outside the interest area:* both tests decode every packet built and fail on any record for an entity out of range, or even a removal naming one that was never in range.
**Also tested:** codec round trips, truncation at every length and random corruption without engine errors; a crowd of 600 items spread over several snapshots nearest first; a distant player not starved by 200 busy near ones; and `test_net_game.gd` end to end over loopback UDP: two clients join the lobby, the match starts, both get the seed and phases, see all four players, steer their own players by input, leave, a late joiner is told the server is full, and junk on the game channel is counted and ignored. `make check` passes: 384 tests, self-check and smoke, which now also starts a listening server.
**Limits and follow-ups**
- The 90 seconds measured are the drop and early looting. Late-match fights weren't measured over the network; the cap still holds there. N8 (#39) is the real soak.
- Building all 24 snapshots takes about 5 ms on this machine, every third tick, against a 12 ms tick budget. Fine for now; a candidate for H1 (#54).
- The own player's private state (velocity, inventory, ammunition, materials, cooldowns) isn't in the snapshot yet. N3 (#34) needs it for prediction and should add a self block. Structures, world damage and loot containers are N5 (#36).
- Interest ignores height and line of sight. A player behind a hill 300 m away is still sent. N9 (#40) can tighten that if wanted.
- When bots have filled a running match, a person who connects is turned away as "full" until it ends. N6 (#37) should let them wait in the lobby instead.
- There is no client program yet: `NetClient` and `SnapshotReceiver` are driven by tests only.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Depends on: N1
Delta-compressed snapshots with per-client interest management and a fixed bandwidth budget.
Acceptance
Done in
e535c1f.What changed
NetSnapshot(src/net/net_snapshot.gd): the wire format. Entities travel as quantized records with per-archetype field groups, so a snapshot carries only the groups that changed. Also the client's input packet (acknowledged snapshot tick plus its last few commands) and a reliable match notice (phase, index, seed).SnapshotSender: per client, a delta against the newest snapshot that client acknowledged, falling back to one that builds on nothing. Interest is by distance on the map from the player being watched: 380 m for players and shots, 90 m for items. Each snapshot is capped at 1,200 bytes; when more changed than fits, the client's own player goes first, then nearest first with a bonus for how long an update has waited.SnapshotReceiver: rebuilds the picture, ignores old and repeated snapshots, and asks for a fresh start if sent a delta on something it doesn't hold.NetGame(src/server/net_game.gd): people who connect join the match flow, inputs go throughServerLoop.submit()once per tick, snapshots go out 20 times a second. Eliminated players are sent what their spectate target sees.tools/godot.sh -- --server --listen [--port=N] [--bots=1]makes the headless server take network players. It waits in the lobby for the first person.docs/ARCHITECTURE.md, "Snapshot format", rewritten to match.Acceptance
test_snapshot_budget.gdplays the first 90 seconds of a 24-bot match with every player a client, 10% of snapshots and acknowledgements lost and acknowledgements two snapshots late. Mean 2.4 KB/s, worst client 2.5 KB/s, worst single second for any client 5.8 KB, largest snapshot 385 bytes, all including 40 bytes of IP, UDP and ENet headers per packet. The cap also bounds the worst case at about 24.8 KB/s whatever happens.test_snapshot_stream.gdloses 40% of snapshots and 40% of acknowledgements over 400 rounds and checks the client's picture equals the truth after every snapshot that arrives; also a silence longer than the server's memory, a client that lost its baseline, duplicates and reordering. The 24-player test ends by checking all 24 pictures are exact.Also tested: codec round trips, truncation at every length and random corruption without engine errors; a crowd of 600 items spread over several snapshots nearest first; a distant player not starved by 200 busy near ones; and
test_net_game.gdend to end over loopback UDP: two clients join the lobby, the match starts, both get the seed and phases, see all four players, steer their own players by input, leave, a late joiner is told the server is full, and junk on the game channel is counted and ignored.make checkpasses: 384 tests, self-check and smoke, which now also starts a listening server.Limits and follow-ups
NetClientandSnapshotReceiverare driven by tests only.