Files
tidewall/docs/ARCHITECTURE.md
T
claudeandClaude Opus 5.5 1d6a24ab64 M8: Complete offline match
`make match` plays one whole match from the lobby to the results and back to the
lobby: one scripted player and 23 bots on a local server, with no script errors.

- CommandLog records the seed, the rules and every command the server is given.
  MatchReplay plays a log again with nobody thinking and ends on the same state
  hash; `make match` saves the log, reads it back and checks that.
- ServerLoop.submit() is now the one way commands reach the simulation, so a
  recording server sees them all.
- ScriptedPlayer plays a human seat: it drops, loots, fights and flees as a bot
  does, and also cuts driftwood and builds a breakwater and a wall.
- Bots draw randomness from their own per-bot generators, not the simulation's
  streams. A bot thinking no longer changes the simulation's state, which a
  replay without bots needs.
- MatchView and EntityView draw a match from one Simulation: terrain, sea,
  points of interest, props, pieces, players, the barge, items and chests, with
  stand-in shapes for the art pass to replace.
- `make match-captures` renders eight stages of the recorded match.

Closes #31

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

12 KiB
Raw Blame History

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 at 20 Hz. The client renders at any frame rate and interpolates remote entities roughly 100 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.

Snapshot format

A snapshot is a binary, little-endian packet:

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

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.

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 PlayerCommands 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/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.