TerrainView draws the island as 16 x 16 chunks of 64 m, each at one of four detail levels (2, 4, 8 and 16 m spacing) chosen by distance to the camera. TerrainChunkBuilder builds chunk geometry on WorkerThreadPool threads; the main thread only uploads finished meshes, within a 2 ms per-frame budget, nearest chunks first. - Seams: every chunk hangs skirts deeper than twice the most any level strays from the full-resolution edge, so neighbours at any two levels meet without a crack. Normals come from the full-resolution heightfield at every level, and back faces light like the ground above them. - Splat material: a procedural shader blends sand, marsh, grass and rock with weights from the island's bands, averaged over 4 m so borders blend. Steep ground turns to rock and summits weather pale. - Collision stays SimGround's heightfield, with no renderer involved. - Capture scenarios terrain, terrain_lod (tinted by level) and terrain_cracks (magenta sky). tools/crack_check.gd counts sky pixels seen through the ground; make terrain-capture requires cracks in a skirtless control and none in the real terrain. Tests: chunk vertices sit on the heightfield; skirts cover every pairing of levels on sampled shared edges; detail falls with distance; flying across the island at 30 m/s for 2,037 frames streams 661 chunk rebuilds with the worst main-thread frame at 0.8 to 1.4 ms (headless, CPU only); 24 players over 900 ticks on two generated islands never sink into the ground, and a player sprints up towards a summit unharmed. make terrain-capture: control 437 crack pixels, terrain 0. Closes #10 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.3 KiB
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
- The simulation decides everything that affects the match. Clients ask; the server rules.
- 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. - The simulation advances only in fixed ticks of 30 Hz, and takes no input other than commands and the seed.
- 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/): plainRefCountedobjects 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
u64seed, always logged. - Gameplay randomness comes only from named streams, created from the match seed and a
stable name:
rng.stream("loot"),"weapons","bots","worldgen", and so on, on oneSimRng. One system's extra rolls can't disturb another's. - 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.
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 |
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.
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.