| name | demo-povshot |
| description | Grab ONE real ezQuake first-person POV screenshot (full HUD) of a QuakeWorld demo at an exact player + demo-second, rendered headless on servexeri (the always-on Linux hub) and pulled to aws-dev for Claude to read. The single-moment / Linux-headless sibling of the demo-eyecheck skill (which renders a whole 1-fps POV sweep on the Windows GPU box). Use when you need to SEE exactly what a player saw at a moment in a demo — validate a route START/END spot, a spawn position, a trick frame, "is this the right place?", "show me <player>'s POV at T". Wraps the owner's proven clipsmith render.cfg recipe (f_spawn -> demo_jump -> track -> screenshot). Triggers: "screenshot this demo at second N", "grab <player>'s POV", "in-game shot of <demo> at T".
|
demo-povshot — one real ezQuake POV frame from a demo (headless, on servexeri)
scripts/grab.sh <demo-rel-to-qw> <player|-|userid> <demo_sec> <local-out.png>
…then Read the PNG. One real in-engine POV with the full spectator HUD.
When to use
- Validate a position from a demo by EYE: route START/END, a spawn, a contact, a trick frame.
- "What did see at match-time T?" — the closest-to-truth, real-client check.
- Prefer demo-eyecheck instead when you need a whole 1-fps sweep over an event window (it renders
on the Windows GPU box); use demo-povshot for a SINGLE moment, fully headless on the always-on hub.
Architecture
- Renders on servexeri (192.168.86.33, always-on Ubuntu hub, Intel HD 530): it holds the nQuake
client (
~/nquake, paks+maps), the ezQuake AppImage, the demo archive (/mnt/usb-ssd), and Xvfb.
- Reached from aws-dev via pinnacle:
aws-dev → ssh winnacle (pinnacle Windows) → ssh xerial@192.168.86.33. Do NOT use winnacle → wsl → ssh servexeri — that lands on a pinnacle-local
WSL (a different box with a 4090), not the real servexeri hub.
scripts/povshot.sh is the servexeri-side driver (auto-deployed by grab.sh to ~/nquake/);
scripts/grab.sh is the aws-dev orchestrator (deploy → run → base64-pull the PNG).
The recipe (proven demoshots engine — two cfgs)
loop cfg — at the demo's first spawn (f_spawn): turn the engine's auto-POV overrides OFF
(mvd_autotrack 0 / demo_autotrack 0 / cl_hightrack 0), ruleset default, cl_demospeed 5→1,
track <player>, then exec the shots cfg. shots cfg — demo_jump <sec> → a few waits →
screenshot <name> → quit. Output lands in ~/nquake/qw/matchinfo/screenshots/<name>.png.
Engine gotchas (encoded in povshot.sh — do not relearn the hard way)
- ★Tracking a SPECIFIC player needs the auto-POV overrides OFF + an
exec boundary. Without
mvd_autotrack 0 / demo_autotrack 0 / cl_hightrack 0, ezQuake's Cam_Track (cl_cam.c) silently
re-locks the POV to the high-frag / first-present player — track Milton shows ParadokS/niw instead.
AND track must run in a SEPARATE cbuf pass from demo_jump (the loop cfg tracks, then execs the
shots cfg) so Cam_Track latches the player BEFORE the seek; track+jump in one alias does NOT stick.
ruleset default lifts the qcon wait-cap(10); cl_demospeed 5→1 fast-forwards warmup so f_spawn
fires with players loaded. (Verified: this is exactly what the demoshots/demo-eyecheck engine does.)
- Run the AppImage with
APPIMAGE_EXTRACT_AND_RUN=1, NOT the bare extracted binary. servexeri's
system glibc is OLDER than the AppImage's bundled libs, so mixing them dies with
GLIBC_ABI_DT_X86_64_PLT not found. AppRun's "appimage libc" branch loads the bundled glibc
loader; the owner's logs literally say "executing with appimage libc" — that is the working path.
- AppRun SIGSEGVs on a post-run qwurl-desktop fixup AFTER ezQuake quits and the shot is written,
so the process exit code is junk → gate success on the PNG existing, not on rc.
- Headless render:
xvfb-run -a -s "-screen 0 WxHx24" + LIBGL_ALWAYS_SOFTWARE=1 (llvmpipe;
Intel HD 530, no GPU accel needed). Default 1280×720; bump via POV_W/POV_H env.
- player must be a single token: a QW name w/o spaces, or a numeric userid (color-byte names
need the userid — get it from a roster), or
- for the default POV (no track).
- ★Identity is verified by reading the frame, not a fragile self-check. The cfg sets
scr_newhud 0 + scr_tracking "Tracking %t %n", so every shot burns the tracked player's name
into the image (e.g. TRACKING BOOK MILTON). The caller READS it to confirm the rendered POV is
the requested player — robust and unambiguous (no misreading an abbreviated MIL). ezQuake exposes
NO console/cfg signal for the tracked player's identity (WhoIsSpectated is C-only; the name lives
only in the HUD), so a programmatic per-second identity check isn't possible — and the
f_trackspectate re-lock trick is FLAKY (non-deterministic, false-positives on valid active
captures) — do not use it. What IS deterministic + kept: povshot.sh greps qconsole.log (via
-condebug) for the CL_Track resolution error and fails closed on a bad name/userid (no
SHOT=, PNG deleted). The dead/absent-at-exact-second case (engine silently re-locks) shows up as a
different name in the burned-in Tracking … line → the caller catches it by eye. Default POV (-)
has no Tracking line.
Input safety (validated at both layers)
The args flow through a 2-hop ssh chain and into the ezQuake config, so both scripts reject injection
before acting: SEC must be numeric; outname/POV_W/H are whitelisted ([A-Za-z0-9._-] /
digits); demo/player reject whitespace + the shell/cfg metachars " ' ; $ \ \ and newlines (demo/player go bare intoplaydemo/track, mirroring the owner's render.cfg — a space-containing name needs the numeric userid). grab.shadditionally marshals the remote command withprintf %q+ base64 (no raw user byte ever reaches the ssh string — the value stays inert data through the Windows middle hop). Real[dm3] demo names are fine ([/]are allowed and%q-escaped for the shell). A rejected value exits non-zero with a clear FATAL:` line and renders nothing.
Concurrency: the cfg files (_povshot.cfg/_povshot_shots.cfg) + qconsole.log are shared fixed
paths, so povshot.sh takes an exclusive flock ($NQ/.povshot.lock, held cfg-gen → shot check):
overlapping captures serialize instead of clobbering each other's cfg and returning a wrong frame. One
ezQuake at a time also matches the single Intel GPU — parallel grab.sh calls are safe, they just queue.
Clock offset (match-time vs demo-second) — IMPORTANT
demo_jump <sec> uses the demo clock (includes warmup/prewar), NOT match-time. The in-game HUD
match-clock is burned into the shot, so calibrate by reading it back: demo_sec = match_sec + warmup
(book_vs_mix warmup ≈ +11 s; see memory headless-visual-self-validation CH4 + demo-eyecheck).
Demos
On servexeri: the live test demo is matchinfo/demos/4on4_hx_vs_018_dm3.mvd (relative to qw/); the
full archive is /mnt/usb-ssd/demo-archive/demos + /mnt/usb-ssd/4on4-corpus (memory
servexeri-demo-archive). To shoot an archive demo, stage/symlink it under ~/nquake/qw/ (or pass a
path playdemo can resolve) first.
Lineage
Built from the owner's clipsmith project + ~/nquake/qw/render.cfg. Sibling skill: demo-eyecheck.
Box facts: vault infrastructure/machines/servexeri.md; reachability uses the pinnacle Windows hop
(vault ssh-keys / network-topology).
