`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>
222 lines
12 KiB
Markdown
222 lines
12 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.
|
||
|
||
**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 `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 |
|
||
|
||
## 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.
|