Godot VR

Build & headless-verify Godot 4.7 OpenXR/VR apps — room-scale workflow, Pimax Crystal tested in-visor, controller-binding pitfalls covered.

Build a Godot 4 (OpenXR) VR app and verify it headlessly on a Windows host (no editor, no headset needed during the build/verify loop). Deliver a real, running project verified by execution — not a description. (Sibling of blender-headless; different engine, same headless-verify discipline.)

When to Use

• The user wants a Godot 4 VR/AR or OpenXR app (headset target like Pimax Crystal — works on either Pimax runtime once the action-map/tracker binding is right; see the reference).
• You must headless-verify a Godot 4 scene without the editor: import → headless run → non-headless screenshot.
• You hit Godot 4.7 parse/runtime errors on render / particles / physics / XR APIs — the reference holds the working forms.

Environment (Windows)

• Godot 4.7.x win64 standard build (standard, not .NET — it has OpenXR compiled in) from the godotengine releases page; use the _console exe for scriptable runs. Reuse an existing install (confirm with --version) before downloading.
• Headless build/verify needs no OpenXR runtime installed. For in-visor testing on a Pimax Crystal: the first-party runtime ships inside Pimax Play (C:\Program Files\Pimax\, Pimax OpenXR 0.1.0). Pimax Crystal controllers work in Godot on BOTH Pimax OpenXR 0.1.0 and PimaxXR (Unofficial) 0.4.4 once the action map + tracker binding are correct (see references/xr-controller-troubleshooting.md); SteamVR unverified.
• Put the project on a local drive with room to grow (assets + import cache).
• In Hermes's bash terminal on Windows, argument path conversion is off: pass drive-letter paths (C:/...) to native binaries (Godot, Blender, python) — MSYS /c/... forms work for bash builtins (cd, ls) only.

Workflow (in order)

1. Scaffold project.godot: config/features=PackedStringArray("4.7","Forward Plus") (do NOT include "OpenXR" — it triggers a false-positive editor warning; runtime OpenXR is driven by [xr] openxr/enabled=true, not the feature tag), [rendering] renderer/rendering_method="forward_plus", an [xr] block with openxr/enabled=true, openxr/always_in_xr=true, shaders/enabled=true, and a 1600x900 viewport.
2. Build the scene procedurally in code — primitives only, no external assets (that is the default here). One main.gd on the root node builds: Environment (glow/bloom + fog), a directional "moon" light, OmniLight3D point lights for the glow, and the geometry (trees, props, a focal glowing centerpiece).
3. XR root: XROrigin3D → children XRCamera3D + two XRController3D, each tracker="left_hand" / "right_hand" (the tracker names OpenXRInterface::find_tracker() registers with XRServer), pose="grip" (or "aim"), show_when_tracked=true. ⚠️ XRController3D has NO auto-detect: an empty tracker → get_tracker("") → null → the node never binds (frozen pose, hand=0, invisible hands). Set tracker explicitly to "left_hand"/"right_hand". Never pose="default" (unreliably bound → controllers silently stop tracking). See references/xr-controller-troubleshooting.md.
4. Grab without a plugin: native XRController3D + a world-space ray (get_world_3d().direct_space_state.intersect_ray(PhysicsRayQueryParameters3D.create(from,to))). The GodotVR XR-Interaction plugin is unavailable (no such repo exists in the GodotVR org — its maintained grab toolkit is godot-xr-tools, but the native ray grab avoids the dependency) — do not block on it.
5. Fallback camera + self-screenshot so the scene is checkable without a headset: in _ready, if no XR session, add a Camera3D pointed at the scene; if the run was given a marker arg (e.g. --preview), wait ~12 frames then get_viewport().get_texture().get_image().save_png(path) and get_tree().quit().
6. Headless-verify (OpenXR OFF — see gate below) until 0 script errors; confirm the startup self-test print shows the XROrigin3D with its XRCamera3D + both controllers.
7. GPU screenshot: run NON-headless with the marker arg and --xr-mode off (on any machine with an OpenXR runtime installed, the runtime may init without a headset and silently blank the window) → PNG, then vision-check it (real geometry/lighting, not a blank/solid-color frame). Confirm the run exited and left no orphan godot process (see the reference's process-hygiene note).
8. Re-enable OpenXR for delivery (openxr/enabled=true; leave "OpenXR" out of config/features). The in-visor feel is the user's final check.

Pitfalls

• OpenXR + --headless stalls in the main loop, AFTER _ready — scene load and every _ready run and print normally, then the engine enters the main loop, detects the HMD, and hangs to timeout (no display/form factor). So a short-timeout headless run IS a valid no-headset check that a code edit landed: timeout 20 <bin> --headless --path <proj> 2>&1 | grep -iE "Parse Error|SCRIPT ERROR|not found in base|ready" surfaces scene-load parse errors and your _ready prints (e.g. [LeftHand] ready (tracker=… pose=…)) before the stall — use it to confirm a change took effect (and it is the only reliable way to catch native-method parse errors, since --import does not parse scene scripts against the native API). Use a full run with OpenXR OFF for real 0-error / self-test verification, then re-enable OpenXR for delivery. Do not chase a ticking "headless VR" main loop — it won't run past session start without a display.
• --headless never renders. Any visual check must run NON-headless (marker arg) so a window opens and GPU draws; the scene saves its own PNG.
• Godot 4.7 renamed/changed several 3.x-era APIs — the "obvious" form throws parse/runtime errors. Check references/godot-47-api.md before writing render/particles/physics/XR code; it lists the working forms and the errors they prevent.
• write_file refuses overwrite even after a full read. rm -f the target first, then write to the fresh path (same workaround works for re-writing scene .tscn/.gd).
• Don't trust import alone. Run the project headless after import — most errors here were runtime (wrong API shape), which --import does not surface.
• Headless-verify passing ≠ controllers work. A clean headless run + screenshot proves the scene runs and renders; it can't see the visor, so it says nothing about whether controllers track in it. When the user reports "no hands / can't interact," go straight to references/xr-controller-troubleshooting.md — do not re-tune the scene or chase a headless VR run.
• "No hands" on Pimax Crystal is the binding layer (case A), NOT the runtime. Verified in-visor: with the case A fixes in place, the same project works on both Pimax OpenXR 0.1.0 (Pimax Play built-in) and PimaxXR (Unofficial) 0.4.4. The case A fixes: (1) XRController3D.tracker must be set explicitly to "left_hand"/"right_hand" (no auto-detect — empty never binds), and (2) the OpenXR action map must be trimmed to only the profiles the runtime recognizes — for Crystal keep only oculus/touch_controller, drop the other three stock profiles (generic, pico4, hand) and every grip_surface/pose (OpenXR 1.1 palm-pose) binding. One unsupported path fails the whole xrSuggestInteractionProfileBindings call (XR_ERROR_PATH_UNSUPPORTED) → no controller binds, on any runtime. No openxr/default_action_map pin needed — the engine default is already res://openxr_action_map.tres (probe-verified); just keep the edited file at that path. (Early "no hands" on PiOpenXR/SteamVR predated the binding fix; the runtime switch that once seemed to fix it was coincidental. SteamVR was never re-tested after the fix — unverified.)
• "feature OpenXR not supported by this version" is a 4.7.2 editor false-positive when "OpenXR" is in config/features (the build has OpenXR; it initializes at runtime). Dismissable ("Open anyway"), but you can avoid it by leaving "OpenXR" out of config/features — runtime OpenXR is driven by [xr] openxr/enabled=true, not the feature tag. Confirm OpenXR actually loaded via the Running on OpenXR runtime: … Output line, not the feature list.
• Long/AFK builds: one small patch per response, then verify before the next — a response that hits the output-length cap is discarded whole (no partial action runs), so a batched multi-patch response stops the entire run and waits on the user.
• Wrap every non-headless run in timeout <N> — the scene self-quits on the marker arg, but a run that doesn't leaves a windowed Godot holding the user's machine; the orphan check after is tasklist | grep -ic godot = 0 (see references/godot-47-api.md). To kill a survivor, taskkill /PID <pid> /F — MSYS kill <pid> cannot reach a native Windows process at all, and when argument path conversion is off the double-slash form //PID is passed through literally and rejected.
• Regenerated .glb/.gltf assets are NOT re-imported by ordinary runs. The import cache (.godot/imported/*.scn) survives, and a normal --preview/headless run silently uses the STALE cached import — so after regenerating any imported asset you must run timeout N <bin> --path <proj> --headless --import and confirm the .scn mtimes moved (or that the stored source_md5 matches the source md5sum). Symptom: asset fixed and regenerated on disk, but screenshots still show the old broken geometry, and all further "fixes" debug phantom bugs (this cost a full investigation cycle in the forest project).
• -s standalone scripts: a script error before quit() runs the SceneTree forever — a windowed black Godot lingers on the user's machine. Standalone debug scripts must reach quit() even on failure (check results before the only quit() call, or run with --headless under timeout so a stall is bounded).
• Prove a visual fix quantitatively before reporting it to the user. A subtle change on a small object in a full-scene capture looks like "no change" — to the user and to your own vision check (twice reporting a working water mirror on weak evidence cost two user round-trips). A/B it: capture with the feature on and off, pixel-diff the region (PIL: mean/max abs diff + % pixels moved); a large region delta is proof, a faint tint is not. When the feature hides behind other geometry, measure geometry (vertex positions/distances) — the only reliable evidence a screenshot cannot give.
• User reports "no change" after a code fix → suspect a stale process before suspecting the fix. Script changes apply only on a fresh launch; an app left running from the last test keeps showing old behavior. Confirm the code on disk is the final version (no leftover debug lines) and that a clean capture run works, then have the user fully quit and relaunch before re-debugging the fix itself.
• In-visor mirror pool: a ReflectionProbe often contributes NOTHING (water shows glow wash but no reflected shapes — a probe at head height can't see low objects, and in-visor it frequently renders dark). The approach that works is the GEOMETRIC MIRROR TWIN: parent an inverted copy of each reflected object under a _mirror_root Node3D (scale (1,-1,1), at the waterline) so the reflection is real geometry seen through the TRANSLUCENT water (roughness ~0.15, alpha ~0.5); the twin is only visible in the style that uses it (hidden under opaque water/ground otherwise). Verified in-visor (user-confirmed). If you do use a probe instead, 4.7 has three silent killers (all defaults!): blend_distance defaults to 1.0 m and max_distance to 0.0 (older 4.x used 100) — a reflective surface farther than 1 m from the probe receives nothing from it; set both explicitly (e.g. blend 30, max 10). Second: a flat water surface only mirrors content ABOVE the probe's own height (reflected rays always point upward from the probe) — a probe at head height can never show mushrooms/rocks/low crystals; put it just above the water (~0.4 m). Third: the water albedo sets contrast (metal: reflection = reflected radiance × albedo) — a bright albedo makes a featureless pale disc in a dark scene; a deep dark-teal albedo makes the reflected glow shapes pop (night-pond look). Also: a strong point light directly above a near-mirror makes a wide specular wash that buries the mirror image (lower its energy). 4.7 exposes NO cubemap API on the probe (no cubemap property, no getter) — to verify the probe actually reflects, place a bright test sphere ABOVE probe height and look for its mirrored dot on the water. And capture water from standing eye-height close-ups (add a dedicated eye-height mode, e.g. --preview-close <azimuth_deg> <distance_m> — the camera stands ~1.55 m up, a couple of metres out, looking at the water), never the high overview camera.
• Mystery bright lines / streaks / "UV seams" crossing objects → suspect the XR controller visuals before hunting scene geometry. The classic culprit is the aim beam: a 3 m emissive box pointing forward from each hand crosses every object the user points at and reads exactly like a mismatched-UV hairline on a textured rock (two hands → two lines). It renders in windowed captures too — a plain --preview screenshot showed it (despite show_when_tracked=true). Fix: short beam (≈0.5 m, hand scale), dim (emission ≈0.2), brighten (≈2.5) only while hovering a grabbable; the grab RAY (raycast) length is separate from the visual beam length.
• Prove which asset causes a visual artifact by hiding, one class per capture — not by eyeballing. Tag nodes set_meta("hides", "<tag>") at every creation site; add a --hide <tag1>,<tag2> CLI flag that frees every tagged node before the screenshot. A class is guilty only if hiding it makes the artifact disappear.
• Runtime node names of repeated classes are unreliable — match on meta tags. Nodes added at runtime get renamed/deduped, so name matching (even a prefix) hits only the FIRST instance of a class (1 of 19 mushrooms). Tag at creation, match n.get_meta("hides", ""); tag every instance of a logical class, including unnamed twins/duplicate meshes (the style-2 ground twin needed its own tag). GDScript working forms: var stack: Array = get_children().duplicate() (:= infers Variant from an untyped Array) and for i in kill.size(): (kill[i] as Node).free().
• Bloom blowout is not geometry. A 0.2 m emissive cap (emission 2+, bloom 0.5, HDR threshold 0.9) renders as a glowing disc several times its geometry in captures — when a "giant glowing box/disc" appears, check emission_energy_multiplier × glow settings before concluding the mesh is broken.
• One texture appearing on several objects at once, or a surface texture that crawls as the head moves = a space bug, not per-object geometry (screen/camera-space artifacts move with the view and stay synchronized across surfaces). Check in order: (a) a shader sampling its noise in a camera-dependent space — in the fragment() function VERTEX is view space (model/object space only in vertex()), so MODEL_MATRIX * VERTEX AND raw _fbm3(VERTEX*…) in the fragment both crawl with the head — synchronized across every object sharing the shader (4.7 has no WORLD_MATRIX). True world-space noise: wp = MODEL_MATRIX * v_local, where v_local is a varying set to VERTEX in vertex(); INV_VIEW_MATRIX * VERTEX in the fragment is ALSO world space (it is the form the forest ground shader shipped with and it is correct). Verified in-visor: this is the difference between a texture that crawls as you turn your head and one that sits still. (b) glow bleed — a bright non-emissive surface (a ground washed by point lights) exceeds glow_hdr_threshold, so its mottled pattern is additively smeared onto nearby rocks/mushrooms/trees; levers: raise glow_hdr_threshold (0.9→~1.4 keeps emissive-1.5+ objects glowing while lit non-emissive surfaces stop blooming), tighten glow_bloom (~0.35–0.4), and dim light energy until the ground sits below the threshold. Verify with close-up captures of the affected objects, not the overview camera.
• Blender 5.3's glTF exporter writes "invalid" GLBs that Godot renders fine. Every exported GLB declares the index accessor componentType 5123 (uint32) while the index bufferView holds 2-byte indices — do not treat this as corruption when a file looks broken on disk (Godot infers the index type from the bufferView size). When a mesh renders wrong (spikes, streaks, stray far geometry), scan triangles directly with scripts/scan_glb.py <file.glb> (flags degenerate triangles and edges longer than N× the bbox extent); a clean scan means the geometry is fine and the artifact is elsewhere (shaders, bloom, controller visuals).

References

• references/godot-47-api.md — confirmed 4.7.2 API forms (Environment glow, GPUParticles3D, RigidBody3D, raycast, XR session state, XRController3D) + the XROrigin3D scene structure + the error→fix table that actually fired during the build + the exact verification commands.
• references/xr-controller-troubleshooting.md — controllers don't show / no interaction in the visor: the decisive diagnostic (which of 3 failure cases), the case A two-sub-fix detail (explicit tracker + trimmed action map — the real Pimax Crystal fix, works on both Pimax runtimes), OpenXR runtime selection on Windows (registry / env override / restart / verify line), and the benign warnings to ignore.
• references/style-swap-system.md — runtime-swappable graphics styles on one scene (e.g. B-button cycle): the typed-entry registry + _set_style walk, the hidden-twin MeshInstance3D pattern for alternate geometry with per-object transforms, the per-style ENV table, --style N verification, and the Blender-side canonical-asset pipeline.
• scripts/scan_glb.py — re-runnable GLB triangle scanner (degenerate + over-long-edge flags; tolerates the Blender 5.3 uint32/uint16 index quirk). Run it before blaming imported geometry for a visual artifact.