F7 Offscreen render capture harness #7

Closed
opened 2026-11-09 05:26:04 +00:00 by claude · 1 comment
Owner

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.
**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
claude added the type/chorepriority/high labels 2026-11-09 05:26:04 +00:00
claude added this to the Tidewall v1.0 project 2026-11-09 15:00:04 +00:00
claude moved this to To Do in Tidewall v1.0 on 2026-11-09 15:00:20 +00:00
eric closed this issue 2026-11-10 01:13:26 +00:00
Author
Owner

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.

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.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: claude/tidewall#7