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](scripts/vr_locomotion_handler.gd). Smooth turn only with vignette + comfort toggle.
3. Play area / focus: load [vr_safety_guardian_warner.gd](scripts/vr_safety_guardian_warner.gd) + [vr_headset_focus_guard.gd](scripts/vr_headset_focus_guard.gd) before shipping any locomotion.
4. Session bootstrap / actions / FPS: then load [vr_openxr_initializer.gd](scripts/vr_openxr_initializer.gd), [vr_input_action_mapper.gd](scripts/vr_input_action_mapper.gd), [vr_performance_config.gd](scripts/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](scripts/vr_openxr_initializer.gd)

Expert OpenXR initialization with driver support and feature verification.

[vr_hand_gesture_detector.gd](scripts/vr_hand_gesture_detector.gd)

Pinch and Grab recognition using XRHandModifier3D for hand tracking.

[vr_locomotion_handler.gd](scripts/vr_locomotion_handler.gd)

Snap turn, comfort vignette, and accessibility teleport_to() with guardian/focus failure modes.

[vr_passthrough_manager.gd](scripts/vr_passthrough_manager.gd)

Alpha blending and underlay setup for Mixed Reality (AR/VR) transitions.

[vr_performance_config.gd](scripts/vr_performance_config.gd)

Expert Foveated Rendering and Variable Rate Shading (VRS) setup.

[vr_haptic_sequencer.gd](scripts/vr_haptic_sequencer.gd)

Complex haptic pulse sequencing using XRController3D triggers.

[vr_physics_hand_controller.gd](scripts/vr_physics_hand_controller.gd)

Non-clipping, physics-following hands that respect environmental solid.

[vr_safety_guardian_warner.gd](scripts/vr_safety_guardian_warner.gd)

Guardian/Chaperone boundary distance warning logic using XRServer.

[vr_headset_focus_guard.gd](scripts/vr_headset_focus_guard.gd)

Headset-aware pause logic for focus loss (System Menu / Headset Off).

[vr_input_action_mapper.gd](scripts/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](scripts/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](scripts/vr_safety_guardian_warner.gd).
• Focus pause — never teleport while the tree is paused / headset focus lost; [vr_headset_focus_guard.gd](scripts/vr_headset_focus_guard.gd) owns pause/mute.

1. 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](scripts/mixed_reality_manager.gd) / [vr_passthrough_manager.gd](scripts/vr_passthrough_manager.gd).
2. Composition-layer UI — OpenXRCompositionLayerQuad + SubViewport bypasses lens blur → [xr_performance_overlay.gd](scripts/xr_performance_overlay.gd).
3. Universal grab — OpenXR action map + central reparent manager → [universal_grab_manager.gd](scripts/universal_grab_manager.gd) + [vr_input_action_mapper.gd](scripts/vr_input_action_mapper.gd).

Deep dives (on demand)

• Extended OpenXR bootstrap, motion-control samples → [xr-comfort-patterns.md](references/xr-comfort-patterns.md)

Reference

> 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.
• godot-performance-optimization — draw-call and GPU budgets that decide whether 90/120 Hz holds under foveation and VRS.
• godot-physics-3d — CharacterBody3D/RigidBody3D grab-and-throw hands that must not clip through static world geometry.
• godot-audio-systems — mute/duck buses when headset focus is lost so system menus never leave game audio blasting.
• godot-shaders-basics — comfort vignettes and spatial overlays during locomotion without fighting the XR compositor.
• godot-ui-containers — layout inside SubViewports projected through composition layers at 1–3 m.
• godot-export-builds — Android/desktop export presets and OpenXR loader packaging for Quest and PCVR.
• godot-platform-mobile — standalone headset Android constraints (thermal, resolution scale, touchless UX) that overlap Quest shipping.

Downstream / consumers

• godot-platform-web — WebXR session_started/ended flows that reuse the same XRServer interface patterns for browser VR.
• godot-scene-management — pause trees and scene swaps when focus_lost or session_ended fires mid-experience.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.