godot-platform-vr

平台：VR

90+ FPS、以舒适度为先的设计和精准的运动控制是 VR 开发的关键。

绝对不要做（VR 专家规则）

渲染与舒适度

• 绝对不要低于 90 FPS — 在 VR 中，72 FPS 或更低会立即引发恶心感。你必须至少保持 90 FPS（Meta Quest 2/3 的典型帧率），并尽量减少渲染卡顿。
• 绝对不要在没有渐晕效果（舒适遮罩）的情况下使用平滑转向 — 平滑转向会导致晕动症。务必提供瞬间转向或动态渐晕效果。
• 启用注视点渲染时，绝对不要强制启用 3D MSAA — 在某些硬件上，注视点渲染可能会与 OpenXR 管线中的 MSAA 原生冲突。

移动与交互

• 绝对不要省略传送移动选项 — 对许多人来说，平滑移动难以忍受。务必提供传送作为无障碍替代方案。
• 绝对不要将公告板效果用于 VR UI — BILLBOARD_ENABLED 会破坏立体深度线索。请使用带有 SubViewports 的静态 MeshInstance3D 平面。
• 绝对不要将 UI 放得过近或过远 — 0.5m 会造成眼部疲劳；10m 则无法看清。与玩家保持 1-3 米的距离最为理想。

安全与系统

• 绝对不要忽略实际游玩区域的边界 — 踏入现实中的物体会造成安全风险。使用 XRServer 获取 Guardian 边界。
• 绝对不要忽略 focus_lost 或 session_ended 信号 — 通过暂停模拟，妥善处理断连或系统菜单覆盖层。
• 绝对不要将 XRControllerTracker 名称硬编码 — 使用 OpenXR Action Map 系统，将游戏逻辑与特定硬件标签解耦。

---

舒适度决策树（从这里开始）

1. 玩家能否选择退出连续移动？ → 如果不能，先停止并添加传送和坐姿模式，再编写任何平滑移动代码。
2. 转向： 默认使用瞬间转向 → 加载 vr_locomotion_handler.gd。仅在搭配渐晕效果和舒适度开关时使用平滑转向。
3. 游玩区域 / 焦点： 在发布任何移动功能之前，加载 vr_safety_guardian_warner.gd + vr_headset_focus_guard.gd。
4. 会话初始化 / 操作 / FPS： 然后加载 vr_openxr_initializer.gd、vr_input_action_mapper.gd、vr_performance_config.gd。

可用脚本

必须遵循：完成舒适度决策树后，在实现对应模式之前先阅读匹配的脚本。不要自行编写一个简单的 use_xr = true / XRController3D.is_button_pressed 示例——请从以下脚本着手。

vr_openxr_initializer.gd

具备驱动支持和功能验证的专家级 OpenXR 初始化。

vr_hand_gesture_detector.gd

使用 XRHandModifier3D 识别手部追踪中的捏合和抓握动作。

vr_locomotion_handler.gd

瞬间转向、舒适渐晕效果，以及带有 Guardian / 焦点失效处理的无障碍 teleport_to()。

vr_passthrough_manager.gd

用于混合现实（AR/VR）转换的 Alpha 混合和底层设置。

vr_performance_config.gd

专家级注视点渲染和可变速率着色（VRS）设置。

vr_haptic_sequencer.gd

使用 XRController3D 触发器进行复杂的触觉脉冲编排。

vr_physics_hand_controller.gd

不会穿模、跟随物理运动并遵循环境实体物体的手部控制器。

vr_safety_guardian_warner.gd

使用 XRServer 实现 Guardian / Chaperone 边界距离警告逻辑。

vr_headset_focus_guard.gd

在焦点丢失（系统菜单 / 头显摘下）时，根据头显状态暂停的逻辑。

vr_input_action_mapper.gd

OpenXR Action Map 抽象层，用于将逻辑与硬件按钮解耦。

传送无障碍路径

始终将传送（或仅限房间尺度移动）作为平滑移动的替代方案。

1. 必须阅读 vr_locomotion_handler.gd — teleport_to(target_global)。
2. 射线检测从控制器瞄准方向射向地面／导航网格；将命中点传入 teleport_to。
3. 必须处理的故障模式：
   • 越出 Guardian 边界 — 拒绝游玩区域边界之外的目标；通过 vr_safety_guardian_warner.gd 发出警告。
   • 焦点暂停 — 场景树暂停或头显失去焦点时，绝不传送；暂停／静音由 vr_headset_focus_guard.gd 负责。
4. 将传送与同一移动处理器中的快速转向和渐晕效果配套使用。

舒适度硬性门槛（绝不可忽视）

这些是舒适度硬性门槛，而非可选偏好：

1. 先达到 90+ FPS，再添加任何可选视觉特效 — 恶心风险高于画面润色。
2. 始终提供传送或快速转向路径 — 绝不只提供平滑移动。
3. 首次公开试玩前，Guardian 和焦点处理器必须就绪。
4. UI 位于 1–3 m 处，并使用合成层／静态四边形 — 绝不将 HUD 近距离面向镜头显示。

专家模式（脚本参考）

1. 混合现实透视（Quest 3） — environment_blend_mode = ALPHA_BLEND + transparent_bg 通过场景 Alpha 显示摄像头画面 → mixed_reality_manager.gd / vr_passthrough_manager.gd。
2. 合成层 UI — OpenXRCompositionLayerQuad + SubViewport 可绕过镜头模糊 → xr_performance_overlay.gd。
3. 通用抓取 — OpenXR 操作映射 + 集中式重新挂接管理器 → universal_grab_manager.gd + vr_input_action_mapper.gd。

深入了解（按需）

• 扩展的 OpenXR 引导流程、动作控制示例 → xr-comfort-patterns.md

参考

渐进式展开：仅在研究特定 API 时打开官方文档链接；在路由到相关领域时加载相关技能 — 不要预加载整个知识网络。

官方文档

• 设置 XR — 启用 OpenXR 项目、构建 XROrigin3D/XRCamera3D 场景树，以及启动首次头显会话。
• 改进 XR 启动脚本 — 可靠的 initialize → use_xr 调用顺序、焦点信号，以及启用视口 XR 模式前的失败处理路径。
• XR 动作映射 — 使用与硬件无关的动作，让游戏逻辑无需硬编码控制器按钮字符串。
• 基础 XR 移动 — 传送与连续移动的区别，以及注重舒适度的转向模式。
• OpenXR 手部追踪 — XRHandModifier3D / 关节追踪，以及控制器回退方案的预期行为。
• OpenXR 合成层 — 使用 OpenXRCompositionLayerQuad 呈现清晰的 SubViewport UI，而非将 3D 四边形设置为公告板效果。
• AR / 透视 — 混合现实的环境混合模式和透明视口设置。
• OpenXR 设置 — 注视点渲染、渲染目标倍率，以及其他头显性能调节选项。
• XR 房间尺度 — 通过 XRServer 获取游玩区域 / 安全边界，保障物理安全。
• 在 Android 上部署 XR — Quest 级别的 Android 导出、权限和 OpenXR 加载器打包。
• 可变速率着色 — VRS / 注视点着色的权衡，以及与 OpenXR 注视点渲染配合实现 90+ FPS。
• XRInterface — OpenXR/WebXR 共用的 initialize、焦点、透视、触觉和混合模式 API。

相关技能

前置条件

• godot-project-foundations — 项目设置、场景树和视口基础知识；启用 OpenXR 和 use_xr 前必须掌握。
• godot-input-handling — 动作 / 事件思维模型；OpenXR 动作映射会将其扩展到体感控制器。
• godot-gdscript-mastery — 类型化 XR 脚本、用于舒适瞬转的 await 计时器，以及用于焦点 / 触觉反馈的信号连接。

互补技能

• godot-camera-systems — XRCamera3D 仍然是 Camera3D；舒适 UI 距离和相对头部的构图可复用摄像机放置规则。
• godot-performance-optimization — 决定注视点渲染和 VRS 下能否维持 90/120 Hz 的绘制调用与 GPU 预算。
• godot-physics-3d — CharacterBody3D/RigidBody3D 抓取和投掷的手部交互，不应穿过静态世界几何体。
• godot-audio-systems — 头显失去焦点时静音或降低总线音量，避免系统菜单打开时游戏音频仍持续播放。
• godot-shaders-basics — 移动时使用舒适度渐晕效果和空间叠加层，同时避免与 XR 合成器冲突。
• godot-ui-containers — 在通过合成层投影、距离为 1–3 m 的 SubViewports 内进行布局。
• godot-export-builds — 用于 Quest 和 PCVR 的 Android/桌面导出预设与 OpenXR 加载器打包。
• godot-platform-mobile — 独立式头显的 Android 限制（热量、分辨率缩放、无触控交互体验），与 Quest 发布相关。

下游 / 使用方

• godot-platform-web — WebXR 的 session_started/ended 流程，可为浏览器 VR 复用相同的 XRServer 接口模式。
• godot-scene-management — 在体验过程中触发 focus_lost 或 session_ended 时暂停场景树并切换场景。

主模块

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。