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>
62 lines
3.8 KiB
Markdown
62 lines
3.8 KiB
Markdown
# 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](docs/DEVLOG.md) and the Gitea issues are the
|
|
continuity.
|
|
|
|
## Read these first
|
|
|
|
- [docs/DEVLOG.md](docs/DEVLOG.md): what happened, newest entries at the bottom.
|
|
- [docs/GDD.md](docs/GDD.md): the game design.
|
|
- [docs/ORIGINALITY.md](docs/ORIGINALITY.md): binding rules for everything we make.
|
|
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): server-authoritative design and module map.
|
|
- [src/sim/tuning.gd](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 in `test/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=compatibility` uses 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 by
|
|
`tools/engine.version` and `tools/engine.sha512`. Never download or replace it casually.
|
|
- Never open a window on the host desktop. `tools/godot.sh` forces `--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 `TestCase` in a file named `test_*.gd` under `test/`. Any engine or
|
|
script error during a test fails it, unless the test calls `expect_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, with `Closes #N`. Scheduled
|
|
runs use `git -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.
|