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 focuslost or sessionended 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 [vrlocomotionhandler.gd](scripts/vrlocomotionhandler.gd). Smooth turn only with vignette + comfort toggle.
3. Play area / focus: load [vrsafetyguardianwarner.gd](scripts/vrsafetyguardianwarner.gd) + [vrheadsetfocusguard.gd](scripts/vrheadsetfocusguard.gd) before shipping any locomotion.
4. Session bootstrap / actions / FPS: then load [vropenxrinitializer.gd](scripts/vropenxrinitializer.gd), [vrinputactionmapper.gd](scripts/vrinputactionmapper.gd), [vrperformanceconfig.gd](scripts/vrperformanceconfig.gd).

Available Scripts

MANDATORY: After the comfort decision tree, read the matching script before implementing that pattern. Do not invent a bare usexr = true / XRController3D.isbutton_pressed demo — start from the scripts below.

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

Expert OpenXR initialization with driver support and feature verification.

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

Pinch and Grab recognition using XRHandModifier3D for hand tracking.

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

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

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

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

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

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

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

Complex haptic pulse sequencing using XRController3D triggers.

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

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

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

Guardian/Chaperone boundary distance warning logic using XRServer.

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

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

[vrinputactionmapper.gd](scripts/vrinputactionmapper.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 [vrlocomotionhandler.gd](scripts/vrlocomotionhandler.gd) — teleportto(targetglobal).
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 [vrsafetyguardianwarner.gd](scripts/vrsafetyguardianwarner.gd). - Focus pause — never teleport while the tree is paused / headset focus lost; [vrheadsetfocusguard.gd](scripts/vrheadsetfocusguard.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) — environmentblendmode = ALPHABLEND + transparentbg exposes the camera feed through scene alpha → [mixedrealitymanager.gd](scripts/mixedrealitymanager.gd) / [vrpassthroughmanager.gd](scripts/vrpassthroughmanager.gd).
2. Composition-layer UI — OpenXRCompositionLayerQuad + SubViewport bypasses lens blur → [xrperformanceoverlay.gd](scripts/xrperformanceoverlay.gd).
3. Universal grab — OpenXR action map + central reparent manager → [universalgrabmanager.gd](scripts/universalgrabmanager.gd) + [vrinputactionmapper.gd](scripts/vrinputactionmapper.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 focuslost or sessionended fires mid-experience.

Master

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