xr-development

在 Godot 4.3+ 中开发 XR

所有示例均面向 Godot 4.3+，不使用已弃用的 API。先展示 GDScript，再展示 C#。

相关技能： 3d-essentials 用于 3D 渲染和环境，physics-system 用于 3D 物理交互，input-handling 用于非 XR 输入模式，export-pipeline 用于平台导出。

---

1. XR 设置

启用 OpenXR

1. OpenXR 已内置于引擎中，无需启用插件。
2. Project Settings → XR → OpenXR → Enabled → true
3. Project Settings → XR → Shaders → Enabled → true（用于支持 XR 着色器）
4. 渲染：
   • 使用 Forward+ 或 Mobile 渲染器（更简单的场景也可以使用 Compatibility）
   • 将 Project Settings → Display → Window → VSync Mode 设为 Disabled（帧时序由 XR 运行时控制）

核心场景结构

Main (Node3D)
├── XROrigin3D                    ← Player's physical space origin
│   ├── XRCamera3D                ← Head-mounted display
│   ├── XRController3D (left)     ← Left controller
│   │   └── LeftHandModel (MeshInstance3D or hand tracking)
│   ├── XRController3D (right)    ← Right controller
│   │   └── RightHandModel
│   └── (XRBodyTracker via XRServer — optional full body tracking)
├── WorldEnvironment
└── GameWorld (Node3D)
    └── ... level geometry

启动 XR 会话

extends Node3D

func _ready() -> void:
    var xr_interface: XRInterface = XRServer.find_interface("OpenXR")
    if xr_interface and xr_interface.is_initialized():
        get_viewport().use_xr = true
    else:
        push_error("OpenXR not available")

public partial class XRMain : Node3D
{
    public override void _Ready()
    {
        var xrInterface = XRServer.FindInterface("OpenXR");
        if (xrInterface != null && xrInterface.IsInitialized())
            GetViewport().UseXR = true;
        else
            GD.PushError("OpenXR not available");
    }
}

---

2. 控制器和输入

XRController3D 节点（每只手一个，作为 XROrigin3D 的子节点）通过 OpenXR 动作映射提供按钮。默认动作映射名称：扳机（trigger float、trigger_click）、握持（grip、grip_click）、摇杆（primary Vector2、primary_click）。将摇杆移动速度应用于 XROrigin3D（而不是摄像机）。

请参阅 references/controllers-and-input.md，了解完整的 XRController3D 接线方式、OpenXR 按钮参考和摇杆移动方案。

---

3. 手部追踪

当头显支持手部追踪时（Quest 2+、Pico 4、部分 SteamVR 配置），运行时会发布 XRHandTracker（/user/hand_tracker/left / right）；XRHandModifier3D 会据此驱动手部骨架姿势，而 XRController3D 仍通过手部交互配置文件接收 select / grip 动作。采样手指关节以检测手势。

请参阅 references/hand-tracking.md，了解手部追踪节点设置、关节采样和手势驱动交互。

---

4. 抓取物体

标准做法：在控制器上放置一个 Area3D，用于检测附近的 RigidBody3D 物体；按下握持键时，将物体设为控制器的子节点并冻结；松开握持键时，还原父节点并施加控制器的速度以发射物体。

请参阅 references/grabbing-objects.md，了解完整的基于物理的抓取实现（GDScript + C#）。

---

5. XR UI 交互

要在 VR 中显示 UI，请将 Control 树渲染到 SubViewport，并将其纹理映射到放置在 3D 空间中的 Quad 网格上。指针：从控制器发射 RayCast3D 并检测其是否击中四边形，将命中位置转换回视口的 2D 坐标，再将 InputEventMouseMotion 转发到 SubViewport。

请参阅 references/xr-ui.md，了解将 SubViewport 映射到四边形的方案，以及指针和射线交互。

---

6. 透视（混合现实）

对于支持此功能的头显（Quest 2+、Pico 4），将接口的 environment_blend_mode 设为 XRInterface.XR_ENV_BLEND_MODE_ALPHA_BLEND，并将 WorldEnvironment 背景清除为透明。用户会看到叠加了虚拟内容的真实世界。

请参阅 references/passthrough.md，了解完整的启用步骤和 Quest 专属说明。

---

7. 导出到 Meta Quest

设置

1. 安装 Android 构建模板：Project → Install Android Build Template
2. 安装 OpenXR Vendors 插件：Project → Project Settings → Plugins → Enable Godot OpenXR Vendors（或从 AssetLib 安装）
3. Export → Add → Android
4. 在 Android 导出预设中：
   • XR Features → XR Mode → OpenXR
   • Meta XR Features → Hand Tracking / Passthrough（由 Vendors 插件添加；启用对应的 OpenXR 扩展后显示）
   • Architectures → arm64 → 启用（Quest 使用 ARM）
5. 将最低 SDK 设为 Meta 商店要求的版本（本文撰写时为 29+）

Quest 性能设置

设置	推荐值
渲染器	Mobile
MSAA	2x 或 4x（VR 需要抗锯齿）
纹理压缩	ETC2/ASTC
目标 FPS	72（Quest 2）或 90（Quest 3）

重要： VR 必须保持稳定的帧率。掉帧会导致恶心。请积极进行性能分析，并尽量减少绘制调用。

⚠️ Godot 4.7 中的变更： 新项目设置 xr/openxr/foveation_eye_tracked 和 xr/openxr/foveation_with_subsampled_images 的默认值均为 true——当注视点渲染级别不是“Disabled”时，如果头显支持，就会使用眼动追踪注视点渲染；在 Vulkan 上则会使用子采样图像，以获得更显著的注视点渲染效果。子采样图像与许多屏幕空间功能（例如 FXAA、辉光）不兼容；如果启用了其中任何功能，子采样图像就会自动禁用，并记录日志警告。将任一设置设为 false 即可选择不使用。参见 GH-117868。

---

8. Godot 4.5+ XR 功能

Godot 4.5 在 Windows 上新增 D3D12 OpenXR 后端（作为 Quest Link / SteamVR 的 Vulkan 替代方案）、Mobile Vulkan 渲染器上的注视点渲染、适用于 Quest/Pico 的 Application SpaceWarp 帧合成、用于平台原生控制器网格的 OpenXR Render Models，以及通过专用 visionOS 预设导出窗口化 visionOS 应用。除 SpaceWarp 需要 Godot OpenXR Vendors 插件外，这些功能都只需配置核心项目设置，无需更改引擎级代码。

请参阅 references/godot-4-5-features.md，了解启用步骤、GDScript + C# 渲染模型代码片段以及各项功能的注意事项。

---

9. Godot 4.6+ XR 功能

OpenXR 1.1 支持（Godot 4.6+）

Godot 4.6 会向运行时请求 OpenXR 1.1，从而解锁 1.1 功能（已升级的交互配置文件和路径等），无需更改项目设置；如果运行时拒绝，则会回退到 1.0。

注意： 若要强制指定版本，请设置 xr/openxr/target_api_version（例如 1.0.48；默认值为空）。

---

空间实体 — 锚点、平面追踪、标记追踪（Godot 4.6+）

Godot 4.6 新增 OpenXR Spatial Entities 扩展（实验性 API）：空间锚点可在不同会话间保存虚拟对象的位置；平面检测可检测地板、墙壁和天花板；标记追踪可追踪 QR 码和图像标记。在 XR → OpenXR → Extensions → Spatial Entity 下启用这些功能（默认全部关闭；使用默认 RID() 上下文的锚点还需要启用 Enable Spatial Anchors 和 Enable Builtin Anchor Detection）。使用 OpenXRSpatialAnchorCapability.create_new_anchor(local_transform, RID()) 创建锚点，该方法会返回一个 OpenXRAnchorTracker；然后创建一个 XRAnchor3D，并将其 tracker 设为该追踪器的名称，即可显示锚点。不存在 XRSpatialAnchor 类。

请参阅 references/spatial-entities.md，了解 GDScript + C# 锚点放置方法、C# 单例查找、跨会话锚点持久化，以及 Godot 4.7 中 create_new_anchor() 的 next 参数。

---

10. Godot 4.7+ XR 功能

Godot 4.7 新增 OpenXR 用户在场扩展：佩戴或摘下头显时（启动或关闭期间不会触发），会触发 OpenXRInterface.user_presence_changed(is_user_present: bool)；可使用 is_user_presence_supported() 和 is_user_present() 进行检查和查询。典型用途：头显摘下时暂停游戏并静音。OpenXRCompositionLayer 还新增了 eye_visibility（EYE_VISIBILITY_BOTH、_LEFT、_RIGHT），可仅向一只眼睛显示图层；create_new_anchor() 则新增了可选的 next 参数，用于传入厂商创建信息结构体。

请参阅 references/godot-4-7-features.md，了解用户在场和眼睛可见性用法（GDScript + C#）；另请参阅 references/spatial-entities.md，了解锚点的 next 参数。

---

11. 常见陷阱

现象	原因	修复方法
头显中黑屏	未在视口上设置 use_xr = true	检查 XR 接口后，在 _ready() 中设置
控制器输入未触发	平台对应的信号名称错误	在 Project Settings 中检查 OpenXR 操作映射绑定
VR 中物体比例不正确	场景未按真实世界比例构建	在整个场景中统一使用 1 个单位 = 1 米
移动导致晕动症	平滑旋转	使用分段转向（每次 30°），或在移动期间添加暗角效果
VR 中 UI 难以辨认	面板太远或太小	将 UI 放在 1–2m 处，并使用分辨率为 1024+ 的 SubViewport
手部追踪抖动	直接使用原始关节数据	应用平滑处理（每帧向新位置插值）
导出到 Quest 失败	缺少 Android 构建模板或架构错误	安装 Android Build Template；启用 arm64；设置 API level 29+

---

12. 实现检查清单

• 在 Project Settings 中启用 OpenXR
• 场景使用 XROrigin3D → XRCamera3D + XRController3D 层级结构
• 检查接口后，通过 get_viewport().use_xr = true 启动 XR 会话
• 世界按 1 个单位 = 1 米的比例构建
• 控制器输入使用 OpenXR 操作名称（trigger_click、grip_click 等）
• 已实现从手部追踪回退到控制器追踪的机制
• UI 面板使用渲染到 3D 网格上的 SubViewport
• 移动方式包含舒适度选项（分段转向、暗角效果）
• 禁用 VSync（XR 运行时负责帧时序）
• Quest 导出使用 Mobile 渲染器、arm64 架构和 API level 29+
• 在 Windows Quest Link / SteamVR 构建中，如果 Vulkan 驱动程序存在问题，请考虑使用 D3D12 后端（Godot 4.5+）
• 在 Mobile 渲染器上通过 xr/openxr/foveation_level 启用注视点渲染，适用于独立运行的 Quest/Pico 目标（Godot 4.5+）
• 针对 Meta Quest / Pico 目标，评估 Application SpaceWarp 是否符合性能预算（Godot 4.5+）
• 在支持的情况下，使用 OpenXRRenderModelManager + xr/openxr/extensions/render_model 显示控制器模型（Godot 4.5+）
• visionOS 导出使用专用的 visionOS 预设；仅窗口化应用支持至 4.7（Godot 4.5+）
• 使用 OpenXRSpatialAnchorCapability 创建空间锚点，并通过 XRAnchor3D 显示；同时启用空间实体扩展（Godot 4.6+）
• 通过 OpenXRInterface.user_presence_changed 处理头显佩戴与摘下状态——用户离开时暂停或静音（Godot 4.7+）
• 检查注视点渲染默认设置——默认启用 xr/openxr/foveation_eye_tracked 和 xr/openxr/foveation_with_subsampled_images；如果依赖 FXAA/glow，请禁用子采样图像（Godot 4.7+）