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
+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 "$@"