threejs-webxr

## When to use this skill **ALWAYS use this skill when the user mentions:** - Entering VR/AR, `navigator.xr`, reference spaces, session `requestAnimationFrame` loop via renderer - `VRButton`, `ARButton`, `XRButton` creation patterns from examples - Controller models, hand tracking meshes, estimated real-world lighting probes **IMPORTANT: webxr vs renderers vs camera** | Topic | Skill | |-------|--------| | Enable XR on renderer, sizing | **threejs-renderers** (basics) + **threejs-webxr** (session) | | Desktop projection | **threejs-camera** | **Trigger phrases include:** - "WebXR", "VRButton", "ARButton", "XRControllerModelFactory", "hand tracking" - "虚拟现实", "增强现实", "沉浸式" ## How to use this skill 1. **HTTPS** requirement and feature detection for XR availability. 2. **Buttons**: use official button factories to create DOM entry points; handle session end. 3. **Renderer**: call `renderer.xr.enabled = true` patterns per docs; prefer `setAnimationLoop` for XR loops. 4. **Controllers**: attach models via factories; read gamepad axes/buttons carefully with fallbacks. 5. **Hands**: opt-in hand models when runtime supports; performance implications. 6. **Lighting**: `XREstimatedLight` for AR realism—combine with **threejs-lights** cautiously. 7. **Exit**: restore non-XR render loop and resize handling on session end. See [examples/workflow-xr-button.md](examples/workflow-xr-button.md). ## Doc map (official) | Docs section | Representative links | |--------------|----------------------| | Renderer XR | https://threejs.org/docs/WebXRManager.html | | Webxr addons | https://threejs.org/docs/VRButton.html | | Webxr addons | https://threejs.org/docs/ARButton.html | | Webxr addons | https://threejs.org/docs/XRControllerModelFactory.html | ## Scope - **In scope:** Documented WebXR manager + listed addons for buttons/controllers/hands/planes. - **Out of scope:** Store submission, OpenXR runtime specifics, custom native layers. ## Common pitfalls and best practices - Desktop testing requires XR emulation or hardware; fail gracefully. - Mismatched reference space causes floor offset—validate stage vs local-floor. - Heavy post chains may not meet VR frame time—profile aggressively. ## Documentation and version WebXR entry points span **Addons → Webxr** and renderer [`WebXRManager`](https://threejs.org/docs/WebXRManager.html) in [three.js docs](https://threejs.org/docs/). Browser and device capabilities vary—answers should cite the official example name and three.js version when possible. ## Agent response checklist When answering under this skill, prefer responses that: 1. Link `WebXRManager`, `VRButton`, `ARButton`, or controller factories as relevant. 2. Use `setAnimationLoop` patterns with **threejs-renderers** for XR render loops. 3. Avoid duplicating desktop **threejs-camera** projection advice for XR eyes. 4. Mention reference space choice (local-floor, etc.) at a high level with docs link. 5. Flag performance interaction with **threejs-postprocessing** in VR. ## References - https://threejs.org/docs/WebXRManager.html - https://threejs.org/docs/VRButton.html - https://threejs.org/docs/ARButton.html - https://threejs.org/docs/XRControllerModelFactory.html ## Keywords **English:** webxr, vr, ar, xr session, controller, hand tracking, three.js **中文：** WebXR、VR、AR、VRButton、手柄、手部追踪、沉浸式、three.js