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