90+ FPS, comfort-first design, and motion control accuracy define VR development.
NEVER Do (Expert VR Rules)
Rendering & Comfort
NEVER drop below 90 FPS — In VR, 72 FPS or less causes instant nausea. You MUST maintain at least 90 FPS (Meta Quest 2/3 typical) and minimize rendering jank.
NEVER use smooth rotation without a vignette (comfort mask) — Smooth rotation causes motion sickness. Always provide snap turning OR dynamic vignetting.
NEVER force 3D MSAA if Foveated Rendering is enabled — Foveation can conflict with MSAA natively in the OpenXR pipeline on some hardware.
Locomotion & Interaction
NEVER skip a teleport locomotion option — Smooth movement is intolerable for many. Always offer teleportation as an accessibility alternative.
NEVER use billboarding for VR UI — BILLBOARD_ENABLED breaks stereoscopic depth cues. Use static MeshInstance3D planes with SubViewports.
NEVER place UI too close or too far — 0.5m causes eye strain; 10m is unreadable. Optimal distance is 1-3 meters from the player.
Safety & System
NEVER forget to respect physical play area boundaries — Stepping into real-world objects is a safety risk. Use XRServer to fetch guardian bounds.
NEVER ignore focus_lost or session_ended signals — Gracefully handle disconnections or system menu overlays by pausing the simulation.
NEVER hardcode XRControllerTracker names — Use the OpenXR Action Map system to decouple gameplay from specific hardware labels.
Godot 4.7: OpenXR
OpenXRExtensionWrapper._on_register_metadata adds interaction_profile_metadata parameter — update all extension wrappers.
Comfort Decision Tree (start here)
Can the player opt out of continuous locomotion? → If no, stop and add teleport + seated mode before any smooth locomotion code.
Turning: snap turn default → load vr_locomotion_handler.gd. Smooth turn only with vignette + comfort toggle.
Play area / focus: load vr_safety_guardian_warner.gd + vr_headset_focus_guard.gd before shipping any locomotion.
> MANDATORY: After the comfort decision tree, read the matching script before implementing that pattern. Do not invent a bare use_xr = true / XRController3D.is_button_pressed demo — start from the scripts below.
vr_openxr_initializer.gd
Expert OpenXR initialization with driver support and feature verification.
vr_hand_gesture_detector.gd
Pinch and Grab recognition using XRHandModifier3D for hand tracking.
vr_locomotion_handler.gd
Snap turn, comfort vignette, and accessibility teleport_to() with guardian/focus failure modes.
vr_passthrough_manager.gd
Alpha blending and underlay setup for Mixed Reality (AR/VR) transitions.
vr_performance_config.gd
Expert Foveated Rendering and Variable Rate Shading (VRS) setup.
vr_haptic_sequencer.gd
Complex haptic pulse sequencing using XRController3D triggers.
vr_physics_hand_controller.gd
Non-clipping, physics-following hands that respect environmental solid.
vr_safety_guardian_warner.gd
Guardian/Chaperone boundary distance warning logic using XRServer.
vr_headset_focus_guard.gd
Headset-aware pause logic for focus loss (System Menu / Headset Off).
vr_input_action_mapper.gd
OpenXR Action Map abstraction to decouple logic from hardware buttons.
Teleport Accessibility Path
Always ship teleport (or room-scale only) as an alternative to smooth locomotion.
> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.
Official Documentation
Setting up XR — OpenXR project enablement, XROrigin3D/XRCamera3D tree, and first headset session bootstrap.
A better XR start script — robust initialize → use_xr sequencing, focus signals, and failure paths before viewport XR mode.
The XR action map — hardware-agnostic actions so gameplay never hardcodes controller button strings.
Basic XR locomotion — teleport vs continuous movement and comfort-oriented turning patterns.
OpenXR hand tracking — XRHandModifier3D / joint tracking and controller fallback expectations.
OpenXR composition layers — crisp SubViewport UI via OpenXRCompositionLayerQuad instead of billboarded 3D quads.
AR / passthrough — environment blend modes and transparent viewport setup for mixed reality.
OpenXR settings — foveation, render target multiplier, and other headset performance knobs.
XR room-scale — play-area / guardian bounds via XRServer for physical safety.
Deploying XR on Android — Quest-class Android export, permissions, and OpenXR loader packaging.
Variable rate shading — VRS / foveated shading tradeoffs that pair with OpenXR foveation for 90+ FPS.
XRInterface — initialize, focus, passthrough, haptics, and blend-mode APIs shared by OpenXR/WebXR.
Related Skills
Prerequisites
godot-project-foundations — project settings, scene tree, and viewport basics required before enabling OpenXR and use_xr.
godot-input-handling — action/event mental model that the OpenXR Action Map extends for motion controllers.
godot-gdscript-mastery — typed XR scripts, await timers for snap-turn comfort, and signal wiring for focus/haptics.
Complements
godot-camera-systems — XRCamera3D is still a Camera3D; comfort UI distance and head-relative framing reuse camera placement rules.