F7: Offscreen render capture harness

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>
This commit is contained in:
2026-11-09 20:13:22 -05:00
co-authored by Claude Opus 5.5
parent d9d4c04312
commit 68635d5fba
16 changed files with 453 additions and 1 deletions
+117
View File
@@ -0,0 +1,117 @@
#!/usr/bin/env bash
# Renders the real client offscreen and saves a PNG, without touching the host display,
# GPU or audio. Godot runs in a throwaway Docker container with a private Xvfb and Mesa
# software rendering.
#
# tools/capture.sh <scene-or-scenario> <out.png> [--frames=N] [--allow-blank]
#
# <scene-or-scenario> is a res:// path to a .tscn, or the name of a scenario in
# test/capture/ (for example `smoke` means res://test/capture/smoke.tscn).
#
# Environment:
# CAPTURE_SIZE=1280x720 frame size
# CAPTURE_RENDERER=forward_plus Vulkan via Lavapipe (default, the shipping renderer), or
# compatibility for OpenGL via llvmpipe
#
# Exits 0 when the PNG was written and isn't blank (pixel variance and colour count),
# 1 when the render failed or came out blank, 2 on bad usage. Open the image and look
# at it anyway: these checks only catch the obvious failures.
set -euo pipefail
repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
image="tidewall-capture"
context="$repo/tools/capture"
usage() {
sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' >&2
exit 2
}
[[ $# -ge 2 ]] || usage
target="$1"
out="$2"
shift 2
extra=()
for arg in "$@"; do
case "$arg" in
--frames=* | --allow-blank) extra+=("$arg") ;;
*) echo "capture.sh: unknown option '$arg'" >&2; usage ;;
esac
done
if [[ "$target" == res://* ]]; then
scene="$target"
else
[[ "$target" =~ ^[a-z0-9_]+$ ]] || { echo "capture.sh: bad scenario name '$target'" >&2; exit 2; }
scene="res://test/capture/$target.tscn"
fi
[[ -f "$repo/${scene#res://}" ]] || { echo "capture.sh: no such scene: $scene" >&2; exit 2; }
size="${CAPTURE_SIZE:-1280x720}"
[[ "$size" =~ ^[0-9]+x[0-9]+$ ]] || { echo "capture.sh: bad CAPTURE_SIZE '$size'" >&2; exit 2; }
case "${CAPTURE_RENDERER:-forward_plus}" in
compatibility) render=(--rendering-method gl_compatibility --rendering-driver opengl3) ;;
forward_plus) render=(--rendering-method forward_plus --rendering-driver vulkan) ;;
*) echo "capture.sh: CAPTURE_RENDERER must be compatibility or forward_plus" >&2; exit 2 ;;
esac
# Rebuild the image only when its recipe changes.
recipe_hash="$(cat "$context/Dockerfile" "$context/entrypoint.sh" | sha256sum | cut -c1-16)"
current="$(docker image inspect "$image" --format '{{ index .Config.Labels "tidewall.recipe" }}' 2>/dev/null || true)"
if [[ "$current" != "$recipe_hash" ]]; then
echo "capture.sh: building $image" >&2
docker build --quiet --label "tidewall.recipe=$recipe_hash" -t "$image" "$context" >/dev/null
fi
# Refresh the global class cache headless on the host, so class_name lookups resolve.
"$repo/tools/godot.sh" --import --quit >/dev/null 2>&1 || true
# The container can only write inside the repo, so render to a scratch file there.
mkdir -p "$repo/captures"
# Keep Godot from importing captures as project resources.
touch "$repo/captures/.gdignore"
scratch="captures/.capture-$$-$RANDOM.png"
name="tidewall-capture-$$-$RANDOM"
cleanup() {
docker rm -f "$name" >/dev/null 2>&1 || true
rm -f "$repo/$scratch"
}
trap cleanup EXIT
set +e
output="$(timeout --signal=KILL 300 nice -n 15 docker run --rm --name "$name" \
--network none \
--user "$(id -u):$(id -g)" \
--memory 3g --cpus 4 \
-e "CAPTURE_SCREEN=${size}x24" \
-v "$repo:/repo" \
"$image" \
"${render[@]}" --resolution "$size" \
--script res://tools/capture.gd -- --scene="$scene" --out="res://$scratch" "${extra[@]}" 2>&1)"
code=$?
set -e
report="$(grep -m1 '^CAPTURE ' <<<"$output" | cut -c9- || true)"
if [[ -z "$report" ]]; then
echo "capture.sh: render failed (exit $code)" >&2
tail -n 30 <<<"$output" >&2
exit 1
fi
if [[ -f "$repo/$scratch" ]]; then
mkdir -p "$(dirname "$out")"
mv "$repo/$scratch" "$out"
fi
echo "$report"
# Godot silently falls back to OpenGL when Vulkan fails; that is not the requested capture.
wanted="${render[1]}"
if ! grep -q "\"renderer\":\"$wanted\"" <<<"$report"; then
echo "capture.sh: asked for the $wanted renderer, but Godot fell back to another" >&2
grep -iE 'vulkan|error' <<<"$output" | tail -n 10 >&2 || true
exit 1
fi
if [[ "$code" -ne 0 ]]; then
echo "capture.sh: capture of $scene failed or came out blank (exit $code)" >&2
grep -iE 'error|fail' <<<"$output" | grep -v '^CAPTURE ' | tail -n 15 >&2 || true
exit 1
fi
echo "capture.sh: wrote $out" >&2