NetSnapshot defines the game traffic after the handshake: delta snapshots of quantized entity records, the client's input packet and a reliable match notice. SnapshotSender builds each client's snapshot against the newest one it acknowledged, tells it only about entities near the player it is watching, and keeps every snapshot under 1,200 bytes, nearest first, with a staleness bonus so nothing starves. SnapshotReceiver rebuilds the picture, ignores old and repeated snapshots and asks for a fresh start if it is ever sent a delta on something it doesn't hold. NetGame joins the transport to the match: people who connect become participants, their inputs go through ServerLoop.submit() once per tick, and snapshots go out 20 times a second. `--server --listen` makes the headless server take network players and wait in the lobby for the first of them. Measured by test on a 24-player match start with every player a client, a tenth of packets lost and late acknowledgements: 2.4 KB/s mean and 2.5 KB/s for the worst client, packet headers included, against a 40 KB/s limit. Closes #33 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.2 KiB
5.2 KiB
Tidewall: working notes
Tidewall is a free and open-source third-person build-and-survive battle royale for Linux, made with Godot 4.7.2 and GDScript. Each development session starts with no memory, so this file, docs/DEVLOG.md and the Gitea issues are the continuity.
Read these first
- docs/DEVLOG.md: what happened, newest entries at the bottom.
- docs/GDD.md: the game design.
- docs/ORIGINALITY.md: binding rules for everything we make.
- docs/ARCHITECTURE.md: server-authoritative design and module map.
- src/sim/tuning.gd: the one table of gameplay numbers.
Commands
| Command | What it does |
|---|---|
make check |
Verifies the engine, checks binaries, parses all scripts, runs all tests. Must pass before every push. |
make test |
Runs test/**/test_*.gd headless. |
make test-selfcheck |
Proves the runner catches each kind of failure, using test/fixtures/. |
make smoke |
Boots the headless server for 1,000 ticks with 24 bots, prints tick timing, and checks exit codes and logs. Part of make check. |
tools/godot.sh -- --server --seed=N --bots=N --ticks=N |
Runs a headless dedicated server. See src/server/server_config.gd for every option. Logs are JSON lines carrying the seed. Exit codes: 0 clean, 1 script error, 2 bad command line. |
tools/godot.sh -- --server --listen --port=N --bots=1 |
Runs a server people can join over UDP (default port 24650). It waits in the lobby for the first of them and fills each match's empty places with bots. |
tools/godot.sh ... |
Runs the pinned engine. Headless by default. |
tools/capture.sh <scene-or-scenario> <out.png> |
Renders the real client offscreen in a throwaway tidewall-capture-* Docker container (Xvfb, Mesa software rendering) and saves a PNG. Fails on a blank frame or a renderer fallback. |
tools/godot.sh --script res://tools/island_map.gd -- --seed=N --out=res://captures/island.png |
Draws a top-down map of a seed's island, with a contour at each tide level. |
make bot-matches |
Plays 20 bot-only matches (about ten minutes, under nice) and checks every one has a winner, under a tenth of deaths are drownings, and easy bots win less than an even share and take the fewest eliminations. BOT_MATCH_SEEDS=5 BOT_MATCH_FIRST=40 changes the seeds; under 20 matches the difficulty checks are skipped. |
make match |
Plays one whole offline match, lobby to results: a scripted player and 23 bots on a local server (about 25 s). Saves the command log to build/match/match.tclog, replays it and checks the replay ends on the same state hash. MATCH_SEED=N changes the seed; the default, 2, is one where the scripted player also builds. |
make match-captures |
Renders eight stages of that match from its command log (captures/match_<stage>.png), about 3 minutes. Needs Docker. Look at them. |
make terrain-capture |
Renders the terrain crack check and a skirtless control in the capture container. The control must crack and the real terrain must not. Needs Docker. |
make capture-test |
Proves the capture harness works and rejects a blank frame. Needs Docker, so it isn't part of make check. |
Run one group of tests with tools/run_tests.sh --root=res://test/sim or
tools/run_tests.sh --filter=name.
Visual work
- Every issue that changes what the game looks like attaches or describes a capture from
tools/capture.sh, made after the change. Scenarios live intest/capture/<name>.tscn. - Open every capture and look at it (the Read tool shows images). The harness only catches blank frames. A broken, ugly or misleading capture means the issue isn't done.
- The default renderer is Forward+ through Mesa's Lavapipe, which matches the game.
CAPTURE_RENDERER=compatibilityuses OpenGL through llvmpipe. Colours differ between the two, so compare captures made with the same renderer. - Software rendering shows what is drawn, not how fast. Never report frame rates from it.
Rules
- The engine lives in
tools/godot/, is git-ignored, and is pinned bytools/engine.versionandtools/engine.sha512. Never download or replace it casually. - Never open a window on the host desktop.
tools/godot.shforces--headless. Don't use the host's display, GPU, webcams or audio devices. - GDScript is typed everywhere practical. Untyped declarations are errors.
- Simulation code in
src/sim/must not depend on rendering, audio or UI. A test enforces this. - Gameplay numbers go in
src/sim/tuning.gd, nowhere else. - All randomness in the simulation comes from the seeded streams described in the architecture document.
- Tests: extend
TestCasein a file namedtest_*.gdundertest/. Any engine or script error during a test fails it, unless the test callsexpect_error(). - The repo is public. Never commit secrets, internal hostnames, private network details or personal data.
- Commit as
Claude <claude@eom.dev>, one commit per issue, withCloses #N. Scheduled runs usegit -c commit.gpgsign=false commit. - Software rendering can't show real GPU frame rates or how the game feels. Never claim those were verified. Say what was actually tested.