threejs-webxr

何时使用此技能

用户提到以下内容时，始终使用此技能：

• 进入 VR/AR、navigator.xr、参考空间、通过渲染器运行会话 requestAnimationFrame 循环
• 示例中的 VRButton、ARButton、XRButton 创建模式
• 控制器模型、手部追踪网格、估算真实世界光照的探针

重要：webxr 与渲染器、摄像机的区别

主题	技能
在渲染器上启用 XR、设置尺寸	threejs-renderers（基础知识）+ threejs-webxr（会话）
桌面投影	threejs-camera

触发短语包括：

• “WebXR”、“VRButton”、“ARButton”、“XRControllerModelFactory”、“手部追踪”
• “虚拟现实”、“增强现实”、“沉浸式”

如何使用此技能

1. XR 可用性所需的 HTTPS 和功能检测。
2. 按钮：使用官方按钮工厂创建 DOM 入口；处理会话结束。
3. 渲染器：按照文档中的模式调用 renderer.xr.enabled = true；XR 循环优先使用 setAnimationLoop。
4. 控制器：通过工厂附加模型；谨慎读取游戏手柄轴和按钮，并提供回退方案。
5. 手部：仅在运行时支持时启用手部模型；注意性能影响。
6. 光照：使用 XREstimatedLight 增强 AR 真实感，并谨慎结合 threejs-lights。
7. 退出：会话结束时恢复非 XR 渲染循环并处理尺寸调整。

参见 examples/workflow-xr-button.md。

文档索引（官方）

文档部分	代表性链接
渲染器 XR	https://threejs.org/docs/WebXRManager.html
Webxr 附加组件	https://threejs.org/docs/VRButton.html
Webxr 附加组件	https://threejs.org/docs/ARButton.html
Webxr 附加组件	https://threejs.org/docs/XRControllerModelFactory.html

范围

• 涵盖范围： 文档记录的 WebXR 管理器，以及列出的按钮、控制器、手部和平面附加组件。
• 不涵盖范围： 商店提交、OpenXR 运行时特定内容、自定义原生图层。

常见问题与最佳实践

• 桌面测试需要 XR 模拟或硬件；出现问题时应优雅降级。
• 参考空间不匹配会导致地板偏移——请验证使用的是 stage 还是 local-floor。
• 繁重的后期处理链可能无法满足 VR 帧时间要求——请进行全面性能分析。

文档与版本

WebXR 入口位于 Addons → Webxr，渲染器文档中也包含 WebXRManager，详见 three.js 文档。浏览器和设备的能力各不相同——回答应尽可能注明官方示例名称和 three.js 版本。

Agent 回复检查清单

使用此技能回答时，优先采用以下做法：

1. 根据需要链接 WebXRManager、VRButton、ARButton 或控制器工厂。
2. 使用 threejs-renderers 中的 setAnimationLoop 模式处理 XR 渲染循环。
3. 避免重复提供桌面 threejs-camera 的投影建议，XR 眼睛的投影另有不同。
4. 概述参考空间的选择（如 local-floor），并附上文档链接。
5. 提醒 VR 中与 threejs-postprocessing 的性能交互影响。

参考资料

• https://threejs.org/docs/WebXRManager.html
• https://threejs.org/docs/VRButton.html
• https://threejs.org/docs/ARButton.html
• https://threejs.org/docs/XRControllerModelFactory.html

关键词

英文： webxr、vr、ar、xr session、controller、hand tracking、three.js

中文： WebXR、VR、AR、VRButton、手柄、手部追踪、沉浸式、three.js