diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..59b283f --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,117 @@ +# 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. diff --git a/test/project/test_sim_isolation.gd b/test/project/test_sim_isolation.gd new file mode 100644 index 0000000..ce1f3de --- /dev/null +++ b/test/project/test_sim_isolation.gd @@ -0,0 +1,42 @@ +extends TestCase + +## Identifiers from the engine's rendering, audio, UI and scene-tree areas. +const FORBIDDEN: Array[String] = [ + "RenderingServer", "PhysicsServer3D", "AudioServer", "AudioStream", "DisplayServer", + "Node2D", "Node3D", "MeshInstance3D", "Camera3D", "Control", "CanvasItem", "Viewport", + "SceneTree", "get_tree", "Input.", +] +const NONDETERMINISTIC: Array[String] = [ + "randf(", "randi(", "randf_range(", "randi_range(", "randomize(", "Time.", "OS.get_ticks", +] + + +func test_simulation_has_no_presentation_dependency() -> void: + _scan(FORBIDDEN) + + +func test_simulation_has_no_unseeded_randomness() -> void: + _scan(NONDETERMINISTIC) + + +func _scan(needles: Array[String]) -> void: + var paths: Array[String] = _scripts_under("res://src/sim") + assert_true(not paths.is_empty(), "expected scripts in src/sim") + for path: String in paths: + var source: String = FileAccess.get_file_as_string(path) + for needle: String in needles: + # Comments may mention these; only code counts. + for line: String in source.split("\n"): + var code: String = line.get_slice("#", 0) + if code.contains(needle): + fail("%s uses %s: %s" % [path, needle, line.strip_edges()]) + + +func _scripts_under(dir_path: String) -> Array[String]: + var found: Array[String] = [] + for name: String in DirAccess.get_files_at(dir_path): + if name.ends_with(".gd"): + found.append(dir_path.path_join(name)) + for name: String in DirAccess.get_directories_at(dir_path): + found.append_array(_scripts_under(dir_path.path_join(name))) + return found