Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

OpenXR 设置

OpenXR 有一套自己的设置，这些设置会在 OpenXR 启动时应用。尽管能通过插件实现的 OpenXR 扩展以添加额外设置，但在这里我们只讨论 Godot 核心中的设置。

../../_images/openxr_settings.webp

通用设置

Enabled

此设置决定了在 Godot 启动时是否启用 OpenXR。当使用 Vulkan 后端时，该选项必须打开。对于其他后端，可随时通过调用 OpenXRInterface 类的 initialize 来启用 OpenXR。

如果要访问动作映射编辑器，该选项也需启用。

你可以使用 --xr-mode on 命令行指令以强制启用该模式。

默认动作映射

该选项指定了 OpenXR 将加载并与 XR 运行时通信的操作映射文件的路径。

构成因素

该选项指定了你的游戏是为以下哪种设备设计的：

  • Head Mounted 头戴式设备，如 Meta Quest、Valve Index 或 Magic Leap，

  • Handheld 手持设备，例如手机。

如果运行游戏的设备与此处不匹配，OpenXR 将无法初始化。

视图配置

该选项指定了游戏是为哪种视图配置而设计的：

  • Mono，你的游戏只提供单张图像输出。例如基于手机的 AR（增强现实）;

  • Stereo ：你的游戏会提供立体图像输出。比如，头戴式显示设备。

如果运行游戏的设备与此处不匹配，OpenXR 将无法初始化。

备注

Godot 暂不支持 OpenXR 中针对特定设备的额外视图配置。例如，Varjo 头显有一个四视图配置，可以输出两组立体图像。这些特例可能会在不久的将来得到支持。

参照空间

在 XR 中，玩家的头部和手部等所有元素的追踪都在一个追踪体积内进行。这个追踪体积的基点是将虚拟空间映射到现实空间的原点。根据使用的 XR 系统的不同，该点会被放置在不同的位置。在 OpenXR 中，这些场景被明确定义，并通过设置参考空间来选择。

Local（本地）

本地参照空间默认将原点放置在玩家的头部。一些 XR 运行时会在游戏启动时重设该位置，而其他则会让该位置在多个会话中保持不变。

然而，这种参照空间并不会阻止用户走开，因此如果你希望阻止用户离开他们正在控制的部件（这可能会破坏游戏），则需要检测用户是否离开。

本地参照空间是飞行模拟器或赛车模拟器的最佳选择，这类游戏通常希望将 XROrigin3D 节点放置在玩家头部应在的位置。

当用户在其耳机上启用重新居中选项时（该方法因 XR 运行时而异），XR 运行时会将 XRCamera3D 移动到 XROrigin3D 节点。OpenXRInterface 还将发出 pose_recentered 信号，以便你的游戏可以做出相应的反应。

备注

其他 XR 追踪元素，如控制器、锚点，也将相应调整，以保持和重置后的玩家位置一致。

警告

在使用此参照空间时，不应调用 center_on_hmd。

Stage（暂存区）

Stage 参照空间是默认参照空间设置，此选项将原点放置在游戏空间的中心。对于允许用户绘制防护边界的 XR 运行时来说，这个位置及其方向通常由用户设置，而其他 XR 运行时可能会通过其他方式来决定该点位置。不过原点在现实世界中还是静态不动的。

该参照空间最适合用于房间尺度游戏，即用户需要在较大空间中走动的游戏。或者是需要在不同游戏模式之间切换的游戏。有关详细信息，请参见 房间尺度。

当用户在其头戴设备上执行重置时（重置在不同 XR 运行时中有所不同）， XR 运行时不会更改原点。OpenXRInterface 将发出 pose_recentered 信号，游戏需要根据此信号做出适当反应。未正确处理可能导致游戏无法通过分销平台的完整性审核。

在 Godot 中，可以调用 XRServer 上的 center_on_hmd 函数来实现：

  • 调用 XRServer.center_on_hmd(XRServer.RESET_BUT_KEEP_TILT, false) 这行代码，会将 XRCamera3D 节点移动到 XROrigin3D 节点的位置，其效果类似于‘本地（ Local ）’参考空间。

  • 调用 XRServer.center_on_hmd(XRServer.RESET_BUT_KEEP_TILT, true) 这行代码，会移动位于 XROrigin3D 节点上方的 XRCamera3D 节点，同时保留玩家的真实身高，这与‘本地地面（ Local Floor ）’参考空间的效果非常相似。

备注

其他 XR 追踪元素，如控制器、锚点，也将相应调整，以保持和重置后的玩家位置一致。

Local Floor

本地地面（local floor）参考空间与本地（local）参考空间非常相似，它同样会把原点定位在玩家当前所在的位置。不过，在这种模式下，玩家的真实身高（高度）会被完整保留下来。和本地参考空间一样，部分 XR 运行时会把这个位置信息保存在多次会话之间（也就是你退出再进游戏，位置依然会被记住）。

因此，不能保证玩家会站在原点上，唯一的保证是当用户最后一次回到中心时，他们站在那里。玩家因此也可以自由离开。

该参考空间是期望用户站在相同位置的游戏的最佳选项，或者对于 AR 类型的游戏，其中用户的界面元素被绑定到原点节点，并被快速放置在玩家的位置上。

当用户在头显上执行重定位（recenter）操作时（具体的操作方式因不同的 XR 运行时而异），XR 运行时会移动位于 XROrigin3D 节点上方的 XRCamera3D ，但会保持玩家的真实身高高度不变。同时， OpenXRInterface 还会发出 pose_recentered 信号，以便你的游戏能够做出相应的反应。

警告

当玩家进行虚拟移动时，使用此模式一定要格外小心。除非你在处理重定位（recenter）信号时主动抵消掉位移，否则玩家的重定位效果可能会变得完全不可预测。这甚至可能导致游戏崩溃（game breaking）。因为在这种情况下，玩家会直接瞬移到虚拟移动期间设定的那个抽象原点位置——这甚至可能让玩家瞬移进本应无法进入的禁区。因此，在这种场景下，最好使用‘舞台（Stage）’模式，并且在接收到 pose_recentered 信号时，将重置操作限制为仅重置朝向（orientation）。

备注

其他 XR 追踪元素，如控制器、锚点，也将相应调整，以保持和重置后的玩家位置一致。

警告

在使用此参照空间时，不应调用 center_on_hmd。

环境混合模式

环境混合模式定义了我们的渲染输出如何混合到“真实世界”中，前提是头显设备支持。

  • 不透明（ Opaque ）模式：意味着我们的输出画面会完全遮挡住真实世界，也就是我们处于 VR（虚拟现实）模式。

  • Additive 意味着我们的输出被添加到真实世界，这是一种 AR 模式，其中光学系统不允许我们完全模糊真实世界(例如全息透镜)，

  • Alpha （阿尔法/透明度）模式：意味着我们的输出画面会通过 Alpha 通道（透明度）与真实世界进行混合（因此视口需要开启透明背景）。这是一种 AR（增强现实）模式，其光学显示可以完全遮挡住真实世界（例如 Magic Leap 以及所有的视频透视设备等）。

如果选定的模式头显设备不支持，将回调至首个可用模式。

备注

部分 OpenXR 设备拥有独立的系统来控制透视（passthrough）功能的开启与关闭。从 Godot 4.3 版本开始，只要你选择 Alpha 混合模式，引擎就会自动帮你执行这些额外的启用步骤。不过，这需要你安装最新的厂商插件才能生效。

注视点级别

在硬件支持该功能的前提下，此选项用于设置渲染时的注视点级别。注视点渲染是一种技术，简单来说就是：离视口中心越远的地方，渲染的分辨率就越低。目前大多数 XR 运行时只支持固定位置的注视点渲染，但也有部分设备会结合眼球追踪技术，直接以你目光的聚焦点作为这项效果的视觉中心。

级别越高，性能提升越明显，但用户余光（周边视野）区域的画质下降也会越严重。

备注

仅限兼容性渲染器。如果你使用的是移动端（Mobile）或前进（Forward+）渲染器，请在 Viewport 类中将 vrs_mode 属性设置为 VRS_XR 。

警告

如果使用了辉光（glow）、泛光（bloom）或景深（DOF）等后期特效，此功能将被禁用。

动态注视点

启用后，视野水平将根据当前的GPU负载自动调整。它将在低和先前设置中选择的视野水平之间调整。因此，最好将此设置与设置为高的视野等级相结合。

备注

仅限兼容性渲染器

提交深度缓冲区

如果启用，将在渲染时使用 OpenXR 提供的深度缓冲区，该缓冲区与渲染图像一起提交。XR 运行时可以利用这一点来改进重新投影。

备注

启用此功能后，在渲染过程中将不再支持模板缓冲区（stencil support）。不过，目前很少有 XR 运行时（runtime）会用到这个功能，因此建议你保持该选项关闭，除非它确实能为你的具体使用场景带来明显的好处。

启动警报

如果启用了此选项，当 OpenXR 启动失败时，会向用户弹出一条警告提示。不过，XR 系统并不总是会告诉我们启动失败的具体原因。如果它提供了原因，我们会将其记录在控制台（console）里。常见的失败原因包括：

  • 主机系统上没有安装 OpenXR 运行时。

  • 微软的WMR OpenXR运行时当前处于活动状态，它仅支持 DirectX，如果使用 OpenGL 或 Vulkan 将会失败。

  • 使用了 SteamVR，但没有连接/打开头显设备。

如果你在项目中支持回退模式（fallback mode），也就是在没有连接 VR 头显时允许游戏以桌面模式运行，或者你打算通过检查 OpenXRInterface.is_initialized() 来自己处理初始化失败的情况，那么请关闭此选项。

拓展选项

这个子栏目允许你启用各种可选的 OpenXR 扩展。但请记住，只有当你项目运行的 OpenXR 运行时环境（比如 SteamVR、Oculus 等）支持这些扩展时，它们才会真正生效。

调试工具

启用此项后，将会记录来自 XR 运行时的调试信息。

调试信息类型

这允许你选择要记录哪些调试信息。

帧合成

启用此功能后，只要 XR 运行时支持，就会渲染较低分辨率的运动矢量和深度缓冲区，并将其提供给 XR 运行时。这样，XR 运行时就可以注入重投影帧以补偿较低的帧速率。

它目前还有以下几个限制：

  • 在 Forward+ 渲染器中无法正常工作。

  • 仅适用于立体渲染。

手部跟踪

当使用的设备支持时，此选项将启用手部追踪扩展。出于历史遗留原因（legacy reasons），该选项默认是开启的。手部追踪扩展能够提供数据，让你可以按照正确的手指姿态来可视化（还原）用户的双手。根据平台能力的不同，手部追踪数据可以通过控制器输入推算得出，也可以来自数据手套、光学手部追踪传感器，或者其他任何适用的数据源。

如果你的游戏只支持控制器，这应该被关闭。

关于更多详细信息，请参阅 hand tracking 页面。

手部追踪无遮挡数据源

启用该选项意味着，手部追踪将直接使用手指的精确位置，通常也就是指头显摄像头实际捕捉到的画面数据。

手部追踪控制器数据源

启用该选项意味着，手部追踪可能会直接利用手柄本身，并根据手柄的输入数据或其自带的传感器，来推算（推断）手指的具体位置。

手部交互配置文件

启用这个扩展后，就可以使用两种全新的手部追踪姿态了。一种是‘捏合姿态’（Pinch pose），它的位置在大拇指和食指之间，并且朝向正前方；另一种是‘戳指姿态’（Poke pose），它的位置就在食指的指尖处。

这也额外带来了三种基于手势的输入方式：捏合（Pinch），也就是当用户把大拇指和食指捏在一起时触发；瞄准激活（Aim activation），当食指完全伸直时触发；以及抓握（Grasps），当用户握拳时触发。

当同时提供了手部交互配置文件和控制器交互配置文件时，运行时会根据当前是使用光学追踪，还是用户正握着手柄，来在这两种配置文件之间自动切换。

如果只提供了手部交互配置文件（hand interaction profile），那么无论用户手里是否拿着手柄，任何运行时都应该强制使用手部交互。

空间实体

此拓展及其设置被用于获取用户真实世界的环境信息并与之进行交互。在空间实体页面中你可以发现更多关于它如何运作的细节。

眼动交互

当所使用的设备支持时，该选项会启用‘视线交互扩展’。启用后，我们将通过一个位于用户双眼之间、并朝向用户视线方向的姿态（pose）来获取视线追踪的反馈数据。这将会是一个统一的朝向数据。

为了使用这个功能，你需要编辑你的动作映射（action map），并添加一个新的姿态动作（pose action），比如命名为 eye_pose 。然后，为视线追踪交互（eye gaze interaction）添加一个新的交互配置文件（interaction profile），并将 eye_pose 映射进去。

../../_images/openxr_eye_gaze_interaction.webp

别忘了保存！

接下来，在你的 Origin（原点）节点下添加一个新的 XRController3D 节点。然后，将它的 tracker （追踪器）属性设置为 /user/eyes_ext ，并将它的 pose （姿态）属性设置为 eye_pose 。

现在你可以添加一些东西到这个控制器节点，比如光线投射，并且用你的眼睛控制东西。

渲染模型

此扩展用于向 XR 运行时查询所用硬件（通常是控制器）的 3D 资产及其位置信息。有关如何使用该扩展的详细指南，请参阅：here。

绑定修改器

这些选项用来控制是否可以使用‘绑定修饰符’（Binding modifiers）。绑定修饰符的作用是应用阈值或偏移值。关于如何使用和设置它们，你可以在 XR 动作映射页面找到相关信息，点击这里 here 即可查看。

模拟阈值

允许模拟阈值绑定修饰符。

十字键绑定

允许十字键绑定修饰符。