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>
This commit is contained in:
@@ -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.
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user