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
+61
View File
@@ -0,0 +1,61 @@
## Renders a scene for a number of frames and saves the last one as a PNG.
## Runs inside the tidewall-capture container via tools/capture.sh, never on the host
## display. Prints one JSON line with the image statistics and exits:
## 0 saved and not blank, 1 blank or failed, 2 bad arguments.
##
## --scene=res://...tscn --out=res://captures/x.png [--frames=N] [--allow-blank]
extends SceneTree
var _scene: String = ""
var _out: String = ""
var _frames: int = 30
var _allow_blank: bool = false
func _initialize() -> void:
for arg: String in OS.get_cmdline_user_args():
if arg.begins_with("--scene="):
_scene = arg.trim_prefix("--scene=")
elif arg.begins_with("--out="):
_out = arg.trim_prefix("--out=")
elif arg.begins_with("--frames=") and arg.trim_prefix("--frames=").is_valid_int():
_frames = maxi(arg.trim_prefix("--frames=").to_int(), 1)
elif arg == "--allow-blank":
_allow_blank = true
else:
printerr("capture: unknown argument '%s'" % arg)
quit(2)
return
if _scene.is_empty() or _out.is_empty():
printerr("capture: --scene and --out are required")
quit(2)
return
if DisplayServer.get_name() == "headless":
printerr("capture: no display; run this through tools/capture.sh")
quit(2)
return
_capture.call_deferred()
func _capture() -> void:
var packed: PackedScene = load(_scene) as PackedScene
if packed == null:
printerr("capture: can't load scene '%s'" % _scene)
quit(1)
return
root.add_child(packed.instantiate())
for _index: int in _frames:
await process_frame
await RenderingServer.frame_post_draw
var image: Image = root.get_texture().get_image()
var stats: Dictionary = ImageStats.measure(image)
var blank: bool = ImageStats.is_blank(stats)
var error: Error = image.save_png(_out)
stats["scene"] = _scene
stats["size"] = [image.get_width(), image.get_height()]
stats["renderer"] = RenderingServer.get_current_rendering_method()
stats["adapter"] = RenderingServer.get_video_adapter_name()
stats["blank"] = blank
stats["saved"] = error == OK
print("CAPTURE " + JSON.stringify(stats))
quit(0 if error == OK and (not blank or _allow_blank) else 1)
+1
View File
@@ -0,0 +1 @@
uid://00d2aqely5kg
+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
+23
View File
@@ -0,0 +1,23 @@
# Offscreen render harness for tools/capture.sh: a private X server (Xvfb) and Mesa's
# software rasterizers, so Godot can render the real client without any host display,
# GPU or audio device. Built as image tidewall-capture.
FROM debian:13
RUN apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
xvfb xauth \
libgl1 libgl1-mesa-dri libglx-mesa0 libegl1 libgles2 \
mesa-vulkan-drivers libvulkan1 \
libx11-6 libxcursor1 libxinerama1 libxrandr2 libxi6 libxext6 libxrender1 \
libxkbcommon0 libxkbcommon-x11-0 \
libfontconfig1 libdbus-1-3 libasound2t64 libpulse0 libudev1 \
&& rm -rf /var/lib/apt/lists/*
# Never touch a real GPU, even if a device were passed in by mistake.
ENV LIBGL_ALWAYS_SOFTWARE=1 \
GALLIUM_DRIVER=llvmpipe \
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/lvp_icd.json \
HOME=/tmp/home
COPY entrypoint.sh /usr/local/bin/tidewall-capture
ENTRYPOINT ["/usr/local/bin/tidewall-capture"]
+25
View File
@@ -0,0 +1,25 @@
#!/usr/bin/env bash
# Runs inside the tidewall-capture container. Starts a private Xvfb, then runs the
# repo's pinned Godot against it. Arguments go to Godot after the repo's own flags.
set -euo pipefail
mkdir -p "$HOME"
export DISPLAY=:77
Xvfb "$DISPLAY" -screen 0 "${CAPTURE_SCREEN:-1280x720x24}" -nolisten tcp -noreset \
>/tmp/xvfb.log 2>&1 &
xvfb_pid=$!
trap 'kill "$xvfb_pid" 2>/dev/null || true' EXIT
for _ in $(seq 1 50); do
[[ -e /tmp/.X11-unix/X77 ]] && break
sleep 0.1
done
if [[ ! -e /tmp/.X11-unix/X77 ]]; then
echo "tidewall-capture: Xvfb did not start" >&2
cat /tmp/xvfb.log >&2
exit 3
fi
# This container's X server is private, so a window here is allowed.
export TIDEWALL_GODOT_DISPLAY=1
/repo/tools/godot.sh --display-driver x11 --audio-driver Dummy "$@"
+36
View File
@@ -0,0 +1,36 @@
#!/usr/bin/env bash
# Proves the capture harness works and catches blank renders. Needs Docker; not part of
# `make check`, because it builds an image and renders in software. Run: make capture-test
set -uo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")/.."
status=0
dir="captures/selfcheck"
mkdir -p "$dir"
# expect <exit> <renderer> <scenario>
expect() {
local wanted="$1" renderer="$2" scenario="$3" code
CAPTURE_RENDERER="$renderer" tools/capture.sh "$scenario" "$dir/$scenario-$renderer.png" \
>"$dir/$scenario-$renderer.log" 2>&1
code=$?
if [[ "$code" -ne "$wanted" ]]; then
echo "capture-test FAIL $scenario ($renderer): exit $code, expected $wanted"
tail -n 15 "$dir/$scenario-$renderer.log"
status=1
else
echo "capture-test ok $scenario ($renderer): exit $code, $(head -n 1 "$dir/$scenario-$renderer.log" | grep -oE '"variance":[0-9.e-]+')"
fi
}
expect 0 forward_plus smoke
expect 0 compatibility smoke
expect 1 forward_plus blank
leftover="$(docker ps -a --filter name=tidewall-capture- --format '{{.Names}}')"
if [[ -n "$leftover" ]]; then
echo "capture-test FAIL: containers left behind: $leftover"
status=1
fi
[[ "$status" -eq 0 ]] && echo "capture-test: ok. Now open $dir/smoke-forward_plus.png and look at it."
exit "$status"
+45
View File
@@ -0,0 +1,45 @@
## Measures a captured image, so a blank or broken render fails automatically.
## A capture still has to be looked at by a person or agent; this only catches the
## obvious failures.
class_name ImageStats
extends RefCounted
## Below this luminance variance (on a 0..1 scale) an image counts as blank.
const BLANK_VARIANCE: float = 0.0005
## A real scene has far more distinct colours than a cleared or broken frame.
const BLANK_MAX_COLOURS: int = 16
## Sampling stride, in pixels. Enough for a 1280x720 frame in milliseconds.
const STRIDE: int = 4
## Returns mean and variance of luminance, and the number of distinct sampled colours.
static func measure(image: Image) -> Dictionary:
var source: Image = image
if source.is_compressed():
source = image.duplicate() as Image
source.decompress()
var sum: float = 0.0
var sum_squares: float = 0.0
var samples: int = 0
var colours: Dictionary = {}
for y: int in range(0, source.get_height(), STRIDE):
for x: int in range(0, source.get_width(), STRIDE):
var colour: Color = source.get_pixel(x, y)
var luminance: float = colour.get_luminance()
sum += luminance
sum_squares += luminance * luminance
samples += 1
colours[colour.to_rgba32()] = true
if samples == 0:
return {"samples": 0, "mean": 0.0, "variance": 0.0, "colours": 0}
var mean: float = sum / samples
return {
"samples": samples,
"mean": mean,
"variance": maxf(sum_squares / samples - mean * mean, 0.0),
"colours": colours.size(),
}
static func is_blank(stats: Dictionary) -> bool:
return stats["variance"] < BLANK_VARIANCE or stats["colours"] <= BLANK_MAX_COLOURS
+1
View File
@@ -0,0 +1 @@
uid://dwf5l8spiiso2