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:
Executable
+117
@@ -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
|
||||
Reference in New Issue
Block a user