Godot Platform Vr

Platform: VR

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.

---

Comfort Decision Tree (start here)

1. Can the player opt out of continuous locomotion? → If no, stop and add teleport + seated mode before any smooth locomotion code.
2. Turning: snap turn default → load vr_locomotion_handler.gd. Smooth turn only with vignette + comfort toggle.
3. Play area / focus: load vr_safety_guardian_warner.gd + vr_headset_focus_guard.gd before shipping any locomotion.
4. Session bootstrap / actions / FPS: then load vr_openxr_initializer.gd, vr_input_action_mapper.gd, vr_performance_config.gd.

Available Scripts

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.

1. MANDATORY read vr_locomotion_handler.gd — teleport_to(target_global).
2. Raycast from controller aim to floor/navmesh; pass the hit point into teleport_to.
3. Failure modes (must handle):
   • Guardian clip — reject targets outside play-area bounds; warn via vr_safety_guardian_warner.gd.
   • Focus pause — never teleport while the tree is paused / headset focus lost; vr_headset_focus_guard.gd owns pause/mute.
4. Pair teleport with snap turn + vignette from the same locomotion handler.

Comfort Gates (NEVER-adjacent)

These are hard comfort gates, not soft preferences:

1. 90+ FPS before any optional VFX — nausea risk outweighs polish.
2. Teleport or snap-turn path always available — never ship smooth-only locomotion.
3. Guardian + focus handlers live before first public playtest.
4. UI at 1–3 m on composition layers / static quads — never billboarded close-range HUD.

Expert patterns (script pointers)

1. Mixed-Reality passthrough (Quest 3) — environment_blend_mode = ALPHA_BLEND + transparent_bg exposes the camera feed through scene alpha → mixed_reality_manager.gd / vr_passthrough_manager.gd.
2. Composition-layer UI — OpenXRCompositionLayerQuad + SubViewport bypasses lens blur → xr_performance_overlay.gd.
3. Universal grab — OpenXR action map + central reparent manager → universal_grab_manager.gd + vr_input_action_mapper.gd.