tools/capture.sh <scene-or-scenario> <out.png> renders the real client in a throwaway tidewall-capture-* Docker container (debian:13, Xvfb, Mesa software rendering), with no network, no host display, GPU or audio, and removes the container afterwards. The tidewall-capture image rebuilds only when its recipe changes. Forward+ through Lavapipe is the default, matching the game; CAPTURE_RENDERER=compatibility uses OpenGL through llvmpipe. The script fails if Godot silently falls back to another renderer, and fails on a blank frame, judged by ImageStats (luminance variance and colour count). make capture-test renders the shore test scene with both renderers and proves an empty scene is rejected. ImageStats has unit tests in make check. CLAUDE.md now requires a capture for visual issues, and requires that it be opened and looked at. Closes #7 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.8 KiB
3.8 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 ... |
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. |
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.