Godot's --headless mode does not render, and automated runs must never open windows on Eric's desktop. Build a harness that renders the real client inside a container.
Acceptance
tools/capture.sh <scene-or-scenario> <out.png> runs Godot in a Docker container with Xvfb and Mesa software rendering (OpenGL Compatibility renderer, or Lavapipe for Forward+).
Container and image names use the prefix tidewall-, and the container is removed after each run.
A test scene produces a non-blank PNG, checked by pixel variance.
Documented in CLAUDE.md: every visual issue attaches or describes a capture, and captures are actually looked at.
**Depends on:** F1
Godot's `--headless` mode does not render, and automated runs must never open windows on Eric's desktop. Build a harness that renders the real client inside a container.
**Acceptance**
- `tools/capture.sh <scene-or-scenario> <out.png>` runs Godot in a Docker container with Xvfb and Mesa software rendering (OpenGL Compatibility renderer, or Lavapipe for Forward+).
- Container and image names use the prefix `tidewall-`, and the container is removed after each run.
- A test scene produces a non-blank PNG, checked by pixel variance.
- Documented in `CLAUDE.md`: every visual issue attaches or describes a capture, and captures are actually looked at.
claude
added this to the v0.1 Foundations milestone 2026-11-09 05:26:04 +00:00
tools/capture.sh <scene-or-scenario> <out.png> renders in a throwaway container named tidewall-capture-<pid>-<rand>, built from image tidewall-capture (debian:13 with Xvfb and Mesa). The container runs with --rm, --network none, the host user's uid, a 3 GB memory cap and nice 15, and a trap removes it even on failure. The image rebuilds only when tools/capture/Dockerfile or its entrypoint changes.
The default renderer is Forward+ on Lavapipe, which is what the game uses. CAPTURE_RENDERER=compatibility gives OpenGL on llvmpipe. Godot silently falls back to OpenGL when Vulkan init fails, which happened at first because of a wrong ICD path, so the script now fails if the renderer it got isn't the one it asked for.
A scenario name such as smoke resolves to res://test/capture/smoke.tscn. tools/capture.gd renders 30 frames, saves the last one, and prints a JSON line of image stats.
ImageStats measures luminance variance and the number of distinct colours. The capture fails if the frame is blank (variance under 0.0005 or no more than 16 colours).
CLAUDE.md has a new "Visual work" section: every visual issue attaches or describes a capture, captures must be opened and looked at, compare captures only within one renderer, and never report frame rates from software rendering.
Testing
make capture-test: the shore scene passes on Forward+ (variance 0.021) and on Compatibility (0.025). An empty scene is rejected with exit 1 (variance ~0). No tidewall- containers are left afterwards.
I opened both captures. They show a gradient sky, a dark blue sea to the horizon, a sand shore with soft shadows, a six-block stone breakwater, and a wooden post with a red cap casting a long shadow. My first Compatibility render had blown-out white sand, so I lowered the lighting until both renderers looked right.
6 new ImageStats unit tests. make check passes: 57 tests, 8 self-check fixtures, and the smoke run.
Notes for later: Compatibility renders noticeably brighter than Forward+, so H2 (graphics presets) should check both. One render takes about 5 to 10 s here.
Done in 68635d5.
**What changed**
- `tools/capture.sh <scene-or-scenario> <out.png>` renders in a throwaway container named `tidewall-capture-<pid>-<rand>`, built from image `tidewall-capture` (`debian:13` with Xvfb and Mesa). The container runs with `--rm`, `--network none`, the host user's uid, a 3 GB memory cap and `nice 15`, and a trap removes it even on failure. The image rebuilds only when `tools/capture/Dockerfile` or its entrypoint changes.
- The default renderer is **Forward+ on Lavapipe**, which is what the game uses. `CAPTURE_RENDERER=compatibility` gives OpenGL on llvmpipe. Godot silently falls back to OpenGL when Vulkan init fails, which happened at first because of a wrong ICD path, so the script now fails if the renderer it got isn't the one it asked for.
- A scenario name such as `smoke` resolves to `res://test/capture/smoke.tscn`. `tools/capture.gd` renders 30 frames, saves the last one, and prints a JSON line of image stats.
- `ImageStats` measures luminance variance and the number of distinct colours. The capture fails if the frame is blank (variance under 0.0005 or no more than 16 colours).
- `CLAUDE.md` has a new "Visual work" section: every visual issue attaches or describes a capture, captures must be opened and looked at, compare captures only within one renderer, and never report frame rates from software rendering.
**Testing**
- `make capture-test`: the shore scene passes on Forward+ (variance 0.021) and on Compatibility (0.025). An empty scene is rejected with exit 1 (variance ~0). No `tidewall-` containers are left afterwards.
- I opened both captures. They show a gradient sky, a dark blue sea to the horizon, a sand shore with soft shadows, a six-block stone breakwater, and a wooden post with a red cap casting a long shadow. My first Compatibility render had blown-out white sand, so I lowered the lighting until both renderers looked right.
- 6 new `ImageStats` unit tests. `make check` passes: 57 tests, 8 self-check fixtures, and the smoke run.
**Notes for later:** Compatibility renders noticeably brighter than Forward+, so H2 (graphics presets) should check both. One render takes about 5 to 10 s here.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Depends on: F1
Godot's
--headlessmode does not render, and automated runs must never open windows on Eric's desktop. Build a harness that renders the real client inside a container.Acceptance
tools/capture.sh <scene-or-scenario> <out.png>runs Godot in a Docker container with Xvfb and Mesa software rendering (OpenGL Compatibility renderer, or Lavapipe for Forward+).tidewall-, and the container is removed after each run.CLAUDE.md: every visual issue attaches or describes a capture, and captures are actually looked at.Done in
68635d5.What changed
tools/capture.sh <scene-or-scenario> <out.png>renders in a throwaway container namedtidewall-capture-<pid>-<rand>, built from imagetidewall-capture(debian:13with Xvfb and Mesa). The container runs with--rm,--network none, the host user's uid, a 3 GB memory cap andnice 15, and a trap removes it even on failure. The image rebuilds only whentools/capture/Dockerfileor its entrypoint changes.CAPTURE_RENDERER=compatibilitygives OpenGL on llvmpipe. Godot silently falls back to OpenGL when Vulkan init fails, which happened at first because of a wrong ICD path, so the script now fails if the renderer it got isn't the one it asked for.smokeresolves tores://test/capture/smoke.tscn.tools/capture.gdrenders 30 frames, saves the last one, and prints a JSON line of image stats.ImageStatsmeasures luminance variance and the number of distinct colours. The capture fails if the frame is blank (variance under 0.0005 or no more than 16 colours).CLAUDE.mdhas a new "Visual work" section: every visual issue attaches or describes a capture, captures must be opened and looked at, compare captures only within one renderer, and never report frame rates from software rendering.Testing
make capture-test: the shore scene passes on Forward+ (variance 0.021) and on Compatibility (0.025). An empty scene is rejected with exit 1 (variance ~0). Notidewall-containers are left afterwards.ImageStatsunit tests.make checkpasses: 57 tests, 8 self-check fixtures, and the smoke run.Notes for later: Compatibility renders noticeably brighter than Forward+, so H2 (graphics presets) should check both. One render takes about 5 to 10 s here.