Files
tidewall/docs/ARCHITECTURE.md
T
claudeandClaude Opus 5.5 4111a285f0 N3: Client prediction, reconciliation and interpolation
The client's side of a networked match, in src/net/:

- ClientGame takes the server's notices and snapshots, generates the island
  from the seed and answers with commands. It works on packets, so it runs
  over a NetClient or a test's simulated link.
- ClientClock decides which tick the next command is for, from the server's
  echo of the newest command tick it has received, holding three commands
  waiting at the server.
- ClientPrediction runs each command on a copy of the client's own player
  with the server's movement code, and compares every snapshot with what it
  predicted. A difference is replayed from the server's state and eased in.
- SnapshotInterpolator draws everyone else four ticks in the past, between
  snapshots, on a clock steered gently by arrivals.

Snapshots now carry the client's own block: exact position and velocity,
the water around the player, stamina and state flags, so a prediction can
match the server to the bit. The command echo is now the newest tick
received rather than taken. Protocol version 2.

Snapshots go out every second tick. The interval was three ticks, which is
10 a second, not the 20 the documents claimed; 15 a second is the nearest
even spacing and what interpolation is tuned for.

Drop.ride() holds the barge ride for the server and the client alike, and
NetGame's joining, input and snapshot steps can be called without a socket.

Measured in test/net/test_prediction_link.gd over a simulated link with
100 ms each way, 20 ms jitter and 2% loss: no corrections to own movement
in about 1,400 snapshots per client, and the other player drawn 0.4 mm on
average from where a perfect link would draw them.

Closes #34

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 11:30:00 -05:00

341 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Tidewall architecture
Tidewall is **server-authoritative from day one**. A match is always a server plus
clients. Offline play starts a local server with bots and connects to it through the
same interfaces, so there is one code path, and multiplayer is never a retrofit.
## Rules that do not bend
1. The simulation decides everything that affects the match. Clients ask; the server rules.
2. **Simulation code has no dependency on rendering, audio or UI.** `src/sim/` doesn't
use any nodes or servers from those engine areas, and a test scans it to enforce this.
3. The simulation advances only in fixed ticks of 30 Hz, and takes no input other than
commands and the seed.
4. Gameplay numbers live in `src/sim/tuning.gd`.
## Simulation and presentation
```
commands snapshots, events
Humans ─┐ ┌─ Renderer
Bots ──┼──> Server simulation (30 Hz, authoritative) ──> ├─ Audio
Net ──┘ └─ UI / HUD
```
- **Simulation (`src/sim/`)**: plain `RefCounted` objects and data arrays. Testable
without a scene tree. Runs identically on the server and in prediction on clients.
- **Presentation (`src/client/`, `src/ui/`, `src/audio/`)**: reads snapshots and events
and draws them, interpolating between ticks. It never changes simulation state.
- The simulation emits **events** (shot fired, piece built, player downed) in a per-tick
list. Presentation turns them into effects and sound.
## Tick rate
The simulation runs at `Tuning.TICK_RATE_HZ` (30 Hz, 33.33 ms). The server runs a fixed
accumulator and may run several ticks to catch up, with no more than 5 per frame.
Snapshots go out every second tick, 15 a second. The client renders at any frame rate,
predicts its own player and draws everyone else about 130 ms in the past.
## Player command stream
A `PlayerCommand` is one tick of one player's intent. Humans, bots and the network all
produce the same struct, so the simulation can't tell them apart.
| Field | Type | Meaning |
|---|---|---|
| `tick` | u32 | Tick the command applies to |
| `move_x`, `move_y` | i8 | Movement axes, scaled to -1..1 |
| `yaw` | u16 | Look yaw, full turn over 65536 steps |
| `pitch` | i16 | Look pitch, ±90° over ±32767 steps |
| `buttons` | u16 | Bit flags: fire, aim, jump, crouch, sprint, reload, interact, build |
| `selection` | u8 | Active inventory slot or build piece |
| `material` | u8 | Active build material |
Clients stamp commands for the tick they predict, and each packet repeats recent
commands to survive loss. The server applies the command for each tick, or a neutral
command with the player's last look direction if none has arrived.
**Look convention.** At yaw 0 the player faces +z; forward is `(sin yaw, 0, cos yaw)`.
Right is forward × up, `(-cos yaw, 0, sin yaw)`, matching Godot's right-handed, y-up
frame, so turning right *decreases* yaw. Positive pitch looks up. `Movement` and the
client's `CameraRig` both follow this, and a test checks that strafing right moves
towards the camera's screen-right.
The binary encoding is a fixed 14 bytes per command, little-endian, in the order of
the table above. See `src/sim/player_command.gd`. Decoding a truncated buffer returns
nothing, and out-of-range values are clamped, so bad input can't reach the simulation.
The player a command belongs to comes from its connection, never from the packet.
## Entity IDs
Every entity has a `u32` ID, allocated from a counter starting at 1 and **never reused
within a match**. ID 0 means "none". Snapshots refer only to IDs, which removes a whole
class of stale-reference bugs. Iteration is always in ascending ID order, so it's
deterministic.
## Seeded RNG rules
- A match has one `u64` seed, always logged.
- Gameplay randomness comes only from named streams, created from the match seed and a
stable name: `rng.stream("loot")`, `"weapons"`, `"drop"`, `"worldgen"`, and so on, on one `SimRng`.
One system's extra rolls can't disturb another's.
- Bots don't draw from those streams. Each bot has its own generator, seeded from the
match seed and its player ID, so nothing a bot thinks changes the simulation's state.
- Simulation code **never** calls `randf`, `randi`, `Time`, or anything else that varies
between runs. Presentation can use whatever randomness it likes, for effects.
- The same seed and the same command log produce the same state hash, on the same engine
build. Worldgen runs on both ends from the same seed, so the terrain itself is never sent.
`Simulation.state_hash()` is a SHA-256 over a canonical encoding of the tick, the next
entity ID, every RNG stream's state and every entity in ID order, with positions rounded
to millimetres.
Determinism is for tests, replays and worldgen. Clients don't rely on bit-exact matches
with the server. Reconciliation corrects any difference.
## Command log and replay
`CommandLog` (`src/server/`) holds a match's seed, its rules and every command the
server was given: the simulation tick it arrived on, the handle it came from and the
command's 14 bytes. `ServerLoop.submit()` is the one way commands get in, for people,
scripts and bots alike, so a recording server logs them all, accepted or not. On disk
it is a JSON header and the records compressed with Zstandard, about 0.6 MB for a
24-player match.
`MatchReplay` plays a log again: the same seed and rules, the same commands on the same
ticks, and nobody thinking. It ends on the same state hash as the recording, which
`make match` checks after every run. A replay can stop at any tick, which is how the
match captures draw a moment of a real match. Replays are exact only on the same engine
build, like everything else that relies on determinism.
`ScriptedPlayer` (`src/bots/`) is a stand-in for a person at the controls. It plays a
human seat as a bot would, and also cuts driftwood and builds a breakwater and a wall,
so a scripted match covers the drop, loot, combat, harvesting, building and the tide
from a player's seat. `ServerLoop.play_humans_by_script()` turns it on; no shipped mode
uses it.
## Transport and handshake
The transport is ENet over UDP, used directly through `ENetConnection` (not Godot's
high-level multiplayer API, so the server controls every byte it accepts). Channel 0
is reliable control traffic; channel 1 is for commands and snapshots.
`NetServer` and `NetClient` (`src/net/`) own the two ends, and `NetProtocol` the
message layouts and the protocol version. A new connection is a guest until its HELLO
is accepted:
1. The client sends HELLO: a magic number, its protocol version and the name it wants.
2. The server answers WELCOME (the player's handle, the match seed, tick rate, player
limit and the name as accepted) or REJECT with a reason, then disconnects.
A guest gets one try. A HELLO that is malformed, on the wrong channel or too long is
refused as such; a different protocol version, a full server and silence past the
handshake timeout each have their own reason, and the client turns the reason into a
sentence for the player (`NetProtocol.reason_text`). The reason also rides on the
disconnect itself, in case the REJECT is lost. Names are cleaned on both ends: control
and invisible characters removed, 16 characters at most, never empty, and a number
added if someone already has it. Handles are positive, count up and are never reused
while the server runs.
Leaving cleanly tells the server at once. A client that vanishes is dropped by ENet's
timeout (5 to 15 seconds without an acknowledgement), and the owner sees the same
"left" event with a different reason. Decoders return nothing for bad input and never
raise an engine error; anything a joined player sends that isn't understood is counted
and dropped.
## Snapshot format
`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 | Message type (u8), server tick (u32), baseline tick (u32, 0 = builds on nothing), simulation tick (u32), the newest command tick received from this client plus one (u32, 0 = none yet), the entity the client is watching (varint) |
| Match and tide | Match phase (u8), tide phase (u8), sea level in centimetres (s16) |
| Own block | A flag (u8), then, while the client's own player is alive and is who it watches, 37 bytes nobody else is sent: position and velocity as f32, the water level around the player as f64, which of the nine flood cells around the player that water reaches (u16), swimming stamina (u16) and state flags (u8) |
| 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 |
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 15 a
second is at most 18 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, and echoes
the newest tick it has received in every snapshot, taken or not.
**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.
## The client: prediction, reconciliation and interpolation
`ClientGame` (`src/net/`) is a client's side of a match. It works on packets, so it
runs the same over a `NetClient` or a test's simulated link. From the seed in the
MATCH notice it generates the island itself (a `Simulation` it never steps) and plans
the same barge route, so it can run the server's movement code on the server's ground.
**The command clock.** A command must reach the server before the tick it names, so
the client's tick runs ahead of the server's by the trip there plus a margin. Nobody
measures the trip. Each snapshot says which tick the server was about to run and the
newest command tick it had received; the difference is how many commands were
waiting. `ClientClock` holds that at `Tuning.NET_COMMAND_MARGIN_TICKS` (3): it jumps
ahead if commands arrive late two snapshots running, waits if they are far too early,
and otherwise runs up to 2% fast or slow. With three commands waiting and each packet
repeating the last three, jitter and a lost packet or two cost nothing.
**Prediction.** `ClientPrediction` keeps a copy of the client's own player and runs
every command on it as it is made, through `Movement.step`, `Water.update` and
`Drop.ride`, the same code the server runs. The player moves at once, not a round trip
later.
**Reconciliation.** The own block in each snapshot is the player's exact state before
the snapshot's simulation tick: 32-bit floats, as the server holds them, not the
quantized record. If that equals what was predicted before that tick, nothing happens,
which is the normal case. If not, the copy is put where the server says, every command
since is run again, and the distance the player's present position moved is the
correction. A correction is never shown at once: the drawn position keeps an offset
that fades at `NET_CORRECTION_SMOOTH_RATE`, unless it is over 3 m, which is shown as
the teleport it is. What the client can't predict yet: built pieces and broken props
(not replicated until N5), a basin still filling after a breach, and anything another
player does to it.
**Interpolation.** `SnapshotInterpolator` draws every other entity
`Tuning.NET_INTERP_DELAY_TICKS` (4 ticks, two snapshots) in the past, on a straight
line between the snapshots either side of that moment, with yaw turning the short way.
The moment drawn is a clock of its own, steered gently towards where arrivals say it
should be, so jitter in the network never becomes jitter on screen. When a snapshot is
lost the entity carries on along its last heading for up to 3 ticks; if that guess was
wrong, the difference is blended away when the news arrives.
**Measured** (`test/net/test_prediction_link.gd`, simulated link, headless): two
players through the drop and 75 s of walking, sprinting, strafing, jumping and
crouching on a real island, each with 100 ms of latency each way, 20 ms of jitter and
2% loss. Own movement: about 1,400 snapshots compared per client and none needed a
correction. The other player was drawn on average 0.4 mm from where a perfect link
would draw them, and 9 mm from where the server had them at that moment; a lost
snapshot during a sudden stop or start showed as at most 13 cm of drift, eased out. At
150 ms, 40 ms and 10% loss a client took 3 to 7 corrections of at most 22 cm, all
blended. These are measurements of the netcode's arithmetic, not of how it feels in
the hand, which needs a real playtest.
## Module map
| Path | Holds | May depend on |
|---|---|---|
| `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, the client's side of a match (prediction, interpolation), lag compensation | `src/sim/` |
| `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) |
| `src/app/` | Startup and mode selection | Everything |
## Bots
Bots live in `src/bots/` and play through the same door as humans: each tick a bot
reads the simulation and returns one `PlayerCommand`, which the server submits like
any other. They never write to the simulation.
`NavGrid` is the shared map they plan on: one point per 2 m terrain sample, solid
where the ground is a cliff or a solid stands between step and head height, and eight
times as costly where the water is deeper than wading. Path search is Godot's
`AStarGrid2D`. The server builds the grid while the lobby waits (about 0.4 s, next to
the island's own generation) and syncs it every tick before bots think: new solids
block points at once, removed solids are found by a rolling scan within a few ticks,
and points turn wet as the tide and flood reach them. Every change is stamped with its
tick, and each bot checks its remaining path against the stamps twice a second, so a
new wall or rising water across a path makes it plan again. Only one path is planned
per server tick across all bots; others wait their turn.
`NavBot` follows a path: it steers at the next waypoint, sprints on long dry stretches,
jumps when it stops making progress, and after a few tries marks the point blocked and
plans around it. A goal the grid's regions show to be cut off (inside a ring of rock,
behind a hut's walls) is turned down without a search, which would otherwise cover the
whole island before giving up.
`BotBrain` decides where a bot goes and what it presses, and gives `NavBot` its goals.
It knows what a player would: the map (`BotWorld`: loot markers at the points of
interest and the ground each tide level will leave dry), the tide forecast, items
within a few metres, opponents in view with a clear line to them, and who just hit it.
Each tick, in order of urgency, it gets to ground the coming tide won't reach, fights a
visible opponent if it is armed, bandages itself when nobody is in view, picks up
useful items and opens chests, walks to the next loot marker, and otherwise wanders the
safe ground. Difficulty (`Tuning.BOT_DIFFICULTIES`) sets its reaction time, how far it
sees and how far its aim wanders.
Two things the brain handles itself, because the grid is flat terrain only:
- Huts, lofts and piers. Their doors and steps are finer than the grid, so a bot walks
to the foot of the point of interest's own walking route and follows its points in,
then back out the same way, before anything else, even if it must flee.
- Safe ground. For each tide phase it is the dry land joined to the island's highest
walkable ground, so it only shrinks, each phase's inside the last. A bot off it
leaves when the time before the next rise only just covers the walk.
`tools/bot_matches.gd` (`make bot-matches`) plays whole bot-only matches on a run of
seeds and reports winners, causes of death and how each difficulty placed.
## Terrain
The island's heightfield (`Island`, in `src/sim/`) is the only terrain collision, on
the server and in client prediction. Nothing in the renderer is ever used for collision.
The client draws it with `TerrainView` (`src/client/terrain/`): 64 m chunks at four
levels of detail chosen by distance to the camera. `TerrainChunkBuilder` builds chunk
geometry on `WorkerThreadPool` threads, and the main thread only uploads finished meshes,
within a per-frame budget. Each chunk hangs skirts from its edges deeper than any two
levels can disagree, so a level boundary never opens a crack. Normals come from the
full-resolution heightfield at every level, so lighting doesn't change across a boundary.
The terrain shader blends procedural sand, marsh, grass and rock layers using splat
weights from the island's elevation bands, with rock on steep ground.
## The match view
`MatchView` (`src/client/`) is the client's picture of one match: sky, sun, terrain,
sea, points of interest, props, built pieces and `EntityView`, which draws players, the
barge, items and chests. All of it reads one `Simulation` and never writes to it, and a
new match gets a new view. The camera sits on a player's shoulder through `CameraRig`.
Until snapshots arrive, the simulation it reads is a local server's or a replay's; the
figures, barge and items are stand-in shapes for the art pass to replace.
## Performance budgets
| Budget | Target |
|---|---|
| Server tick | Under **12 ms** with 24 players |
| Client | **60 fps** on a GTX 1060-class GPU at medium settings |
| Terrain streaming | Under **8 ms** of main-thread work in any frame (measured headless; GPU upload unmeasured) |
Software rendering in CI can't verify the client budget. It needs a real GPU playtest.