Files
tidewall/docs/ARCHITECTURE.md
T
claudeandClaude Opus 5.5 1d3bee3c8d F3: Architecture document
Add docs/ARCHITECTURE.md covering the tick rate, simulation and presentation split,
command stream, entity IDs, snapshot format, seeded RNG rules, module map and
performance budgets. A test scans src/sim for presentation dependencies and unseeded
randomness, so the separation is enforced.

Closes #3

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

118 lines
5.5 KiB
Markdown

# 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.
The binary encoding is a fixed 15 bytes per command. See `src/sim/player_command.gd`.
## 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: `SimRng.stream("loot")`, `"weapons"`, `"bots"`, `"worldgen"`, and so on.
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.
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 `PlayerCommand`s | `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.