Files
tidewall/docs/ARCHITECTURE.md
T
claudeandClaude Opus 5.5 70e88cec8a W1: Third-person character controller and camera
Simulation (src/sim/):
- SimGround holds the terrain heightfield (bilinear heights, normals)
  and axis-aligned box solids, with support, body-overlap, point and
  ray queries. The island generator and building will fill it.
- Movement steps a player per tick: walk, sprint (forward only),
  crouch (lower body, slower, no jump), jump with exact constant-gravity
  integration, air control, step-up onto ledges up to STEP_HEIGHT,
  ground snapping on downhill walks, slopes over MAX_SLOPE_DEGREES that
  block walking and jumping uphill and make players slide (speed capped),
  ceiling bumps, sliding along walls, and fall damage from impact speed.
- Gravity now applies on ticks with no command. on_ground and crouching
  are part of the state hash. New movement numbers are in Tuning.
- Fixed the strafe direction: right is forward x up in Godot's frame,
  (-cos yaw, 0, sin yaw). Documented the look convention.

Client (src/client/):
- CameraRig places an over-the-shoulder camera with an eased
  aim-down-sights blend (closer, narrower FOV), casting against the same
  SimGround: pivot to shoulder, shoulder back, then a straight line from
  the pivot, with a final clearance pull-in so the near plane never
  enters geometry.
- InputSettings: mouse sensitivity, aim sensitivity scale and invert-Y,
  clamped and saved to user://settings.cfg. PlayerCamera applies both.

Tests: 46 new across movement, ground queries, camera and settings,
including a 24,480-view scripted camera sweep through five arenas (wall,
corridor, low roof, corner, steep bank) that checks the eye and every
near-plane corner stay out of geometry with a clear line to the pivot.
The hash test now flips a high stick bit, because a 1/127 nudge to an
airborne player moves them less than the hash's millimetre.
Capture scenarios camera, camera_wall and camera_aim.

Closes #8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-09 20:24:02 -05:00

6.4 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", "bots", "worldgen", and so on, on one SimRng. 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

Performance budgets

Budget Target
Server tick Under 12 ms with 24 players
Client 60 fps on a GTX 1060-class GPU at medium settings

Software rendering in CI can't verify the client budget. It needs a real GPU playtest.