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>
131 lines
6.4 KiB
Markdown
131 lines
6.4 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"`, `"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 `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.
|