WebXRInterface

继承： XRInterface < RefCounted < Object

使用 WebXR 的 AR/VR 接口。

描述

WebXR is an open standard that allows creating VR and AR applications that run in the web browser.

As such, this interface is only available when running in Web exports.

WebXR supports a wide range of devices, from the very capable (like Valve Index, HTC Vive, Oculus Rift and Quest) down to the much less capable (like Google Cardboard, Oculus Go, GearVR, or plain smartphones).

Since WebXR is based on JavaScript, it makes extensive use of callbacks, which means that WebXRInterface is forced to use signals, where other XR interfaces would instead use functions that return a result immediately. This makes WebXRInterface quite a bit more complicated to initialize than other XR interfaces.

Here’s the minimum code required to start an immersive VR session:

extends Node3D
var webxr_interface
var vr_supported = false
func _ready():
    # We assume this node has a button as a child.
    # This button is for the user to consent to entering immersive VR mode.
    $Button.pressed.connect(self._on_button_pressed)
    webxr_interface = XRServer.find_interface("WebXR")
    if webxr_interface:
        # WebXR uses a lot of asynchronous callbacks, so we connect to various
        # signals in order to receive them.
        webxr_interface.session_supported.connect(self._webxr_session_supported)
        webxr_interface.session_started.connect(self._webxr_session_started)
        webxr_interface.session_ended.connect(self._webxr_session_ended)
        webxr_interface.session_failed.connect(self._webxr_session_failed)
        # This returns immediately - our _webxr_session_supported() method
        # (which we connected to the "session_supported" signal above) will
        # be called sometime later to let us know if it's supported or not.
        webxr_interface.is_session_supported("immersive-vr")
func _webxr_session_supported(session_mode, supported):
    if session_mode == 'immersive-vr':
        vr_supported = supported
func _on_button_pressed():
    if not vr_supported:
        OS.alert("Your browser doesn't support VR")
        return
    # We want an immersive VR session, as opposed to AR ('immersive-ar') or a
    # simple 3DoF viewer ('viewer').
    webxr_interface.session_mode = 'immersive-vr'
    # 'bounded-floor' is room scale, 'local-floor' is a standing or sitting
    # experience (it puts you 1.6m above the ground if you have 3DoF headset),
    # whereas as 'local' puts you down at the XROrigin.
    # This list means it'll first try to request 'bounded-floor', then
    # fallback on 'local-floor' and ultimately 'local', if nothing else is
    # supported.
    webxr_interface.requested_reference_space_types = 'bounded-floor, local-floor, local'
    # In order to use 'local-floor' or 'bounded-floor' we must also
    # mark the features as required or optional. By including 'hand-tracking'
    # as an optional feature, it will be enabled if supported.
    webxr_interface.required_features = 'local-floor'
    webxr_interface.optional_features = 'bounded-floor, hand-tracking'
    # This will return false if we're unable to even request the session,
    # however, it can still fail asynchronously later in the process, so we
    # only know if it's really succeeded or failed when our
    # _webxr_session_started() or _webxr_session_failed() methods are called.
    if not webxr_interface.initialize():
        OS.alert("Failed to initialize")
        return
func _webxr_session_started():
    $Button.visible = false
    # This tells Godot to start rendering to the headset.
    get_viewport().use_xr = true
    # This will be the reference space type you ultimately got, out of the
    # types that you requested above. This is useful if you want the game to
    # work a little differently in 'bounded-floor' versus 'local-floor'.
    print("Reference space type: ", webxr_interface.reference_space_type)
    # This will be the list of features that were successfully enabled
    # (except on browsers that don't support this property).
    print("Enabled features: ", webxr_interface.enabled_features)
func _webxr_session_ended():
    $Button.visible = true
    # If the user exits immersive mode, then we tell Godot to render to the web
    # page again.
    get_viewport().use_xr = false
func _webxr_session_failed(message):
    OS.alert("Failed to initialize: " + message)

There are a couple ways to handle “controller” input:

• Using XRController3D nodes and their XRController3D.button_pressed and XRController3D.button_released signals. This is how controllers are typically handled in XR apps in Godot, however, this will only work with advanced VR controllers like the Oculus Touch or Index controllers, for example.

• Using the select, squeeze and related signals. This method will work for both advanced VR controllers, and non-traditional input sources like a tap on the screen, a spoken voice command or a button press on the device itself.

You can use both methods to allow your game or app to support a wider or narrower set of devices and input methods, or to allow more advanced interactions with more advanced devices.

教程

• 如何使用 Godot 4 制作 WebXR 的 VR 游戏

属性

方法

信号

display_refresh_rate_changed() 🔗

显示器的刷新率发生改变后触发。

reference_space_reset() 🔗

发射以表明参考空间已被重置或重新配置。

何时（或是否）发射取决于用户的浏览器或设备，但可能包括用户改变了他们的游戏空间的大小（可以通过 XRInterface.get_play_area 访问），或按下/按住一个按钮来重新定位他们的位置。

有关详细信息，请参阅 WebXR 的 XRReferenceSpace 重置事件。

select(input_source_id: int) 🔗

某个输入源完成其“主要动作”后发出。

请使用 get_input_source_tracker 和 get_input_source_target_ray_mode 获取关于该输入源的更多信息。

selectend(input_source_id: int) 🔗

某个输入源完成其“主要动作”时发出。

请使用 get_input_source_tracker 和 get_input_source_target_ray_mode 获取关于该输入源的更多信息。

selectstart(input_source_id: int) 🔗

某个输入源开始其“主要动作”时发出。

请使用 get_input_source_tracker 和 get_input_source_target_ray_mode 获取关于该输入源的更多信息。

session_ended() 🔗

用户结束 WebXR 会话时发出（可以使用浏览器或设备的 UI 结束会话）。

此时，你应该执行 get_viewport().use_xr = false，让 Godot 继续渲染至屏幕。

session_failed(message: String) 🔗

由 XRInterface.initialize 在该会话启动失败时发出。

message 可能会包含 WebXR 的错误信息，如果没有可用信息则为空字符串。

session_started() 🔗

由 XRInterface.initialize 在该会话启动成功时发出。

此时，可以安全地执行 get_viewport().use_xr = true，让 Godot 开始渲染至 XR 设备。

session_supported(session_mode: String, supported: bool) 🔗

由 is_session_supported 触发，表示是否支持指定的 session_mode。

squeeze(input_source_id: int) 🔗

某个输入源完成其“主要紧握动作”后发出。

请使用 get_input_source_tracker 和 get_input_source_target_ray_mode 获取关于该输入源的更多信息。

squeezeend(input_source_id: int) 🔗

某个输入源完成其“主要紧握动作”时发出。

请使用 get_input_source_tracker 和 get_input_source_target_ray_mode 获取关于该输入源的更多信息。

squeezestart(input_source_id: int) 🔗

某个输入源开始其“主要紧握动作”时发出。

请使用 get_input_source_tracker 和 get_input_source_target_ray_mode 获取关于该输入源的更多信息。

visibility_state_changed() 🔗

当 visibility_state 已更改时触发。

枚举

enum TargetRayMode: 🔗

TargetRayMode TARGET_RAY_MODE_UNKNOWN = 0

不知道目标射线模式。

TargetRayMode TARGET_RAY_MODE_GAZE = 1

目标射线从观察者的眼睛出发，指向所观察的方向。

TargetRayMode TARGET_RAY_MODE_TRACKED_POINTER = 2

目标射线由手持指示器发射，很可能是 VR 触摸控制器。

TargetRayMode TARGET_RAY_MODE_SCREEN = 3

目标射线由触摸屏、鼠标等触觉输入设备发射。

属性说明

String enabled_features 🔗

• String get_enabled_features()

A comma-separated list of features that were successfully enabled by XRInterface.initialize when setting up the WebXR session.

This may include features requested by setting required_features and optional_features, and will only be available after session_started has been emitted.

Note: This may not be support by all web browsers, in which case it will be an empty string.

String optional_features 🔗

• void set_optional_features(value: String)

• String get_optional_features()

A comma-seperated list of optional features used by XRInterface.initialize when setting up the WebXR session.

If a user’s browser or device doesn’t support one of the given features, initialization will continue, but you won’t be able to use the requested feature.

This doesn’t have any effect on the interface when already initialized.

Possible values come from WebXR’s XRReferenceSpaceType, or include other features like "hand-tracking" to enable hand tracking.

String reference_space_type 🔗

• String get_reference_space_type()

参考空间类型（来自 requested_reference_space_types 属性中设置的请求类型列表），在设置 WebXR 会话时最终由 XRInterface.initialize 使用。

可能的值来自 WebXR 的 XRReferenceSpaceType。 如果想要使用特定的参考空间类型，则它必须列在 required_features 或 optional_features 中。

String requested_reference_space_types 🔗

• void set_requested_reference_space_types(value: String)

• String get_requested_reference_space_types()

XRInterface.initialize 在设置 WebXR 会话时使用的以逗号分隔的参考空间类型列表。

按顺序请求参考空间类型，将使用用户设备或浏览器支持的第一个。reference_space_type 属性包含最终选择的参考空间类型。

这对已经初始化的接口没有任何影响。

可能的值来自 WebXR 的 XRReferenceSpaceType。如果想要使用特定的参考空间类型，则它必须列在 required_features 或 optional_features 中。

String required_features 🔗

• void set_required_features(value: String)

• String get_required_features()

A comma-seperated list of required features used by XRInterface.initialize when setting up the WebXR session.

If a user’s browser or device doesn’t support one of the given features, initialization will fail and session_failed will be emitted.

This doesn’t have any effect on the interface when already initialized.

Possible values come from WebXR’s XRReferenceSpaceType, or include other features like "hand-tracking" to enable hand tracking.

String session_mode 🔗

• void set_session_mode(value: String)

• String get_session_mode()

建立 WebXR 会话时，XRInterface.initialize 使用的会话模式。

这对已经初始化的接口没有任何影响。

可能的值来自 WebXR 的 XRSessionMode，包括："immersive-vr" 、"immersive-ar" 和 "inline"。

String visibility_state 🔗

• String get_visibility_state()

指示用户是否可以看到 WebXR 会话的图像。

可能的值来自 WebXR 的 XRVisibilityState，包括 "hidden"、"visible" 和 "visible-blurred"。

方法说明

Array get_available_display_refresh_rates() const 🔗

返回当前 HMD 所支持的显示刷新率。网页浏览器支持该功能，并且该接口已初始化时才会返回。

float get_display_refresh_rate() const 🔗

返回当前 HMD 的显示刷新率。不是所有 HMD 和浏览器都支持。使用 set_display_refresh_rate 前可能不会汇报精确值。

TargetRayMode get_input_source_target_ray_mode(input_source_id: int) const 🔗

返回给定的 input_source_id 的目标射线模式。

可用于帮助解析来自该输入源的输入。详见 XRInputSource.targetRayMode。

XRControllerTracker get_input_source_tracker(input_source_id: int) const 🔗

获取给定 input_source_id 的 XRControllerTracker。

在 WebXR 上下文中，输入源可以是类似 Oculus Touch 和 Index 控制器的高级 VR 控制器，甚至也可以是屏幕上的点击、语音命令或按下设备本身的按钮。当使用非传统输入源时，会将 XRPositionalTracker 的位置和方向解释为指向用户希望与之交互的对象的射线。

可以使用此方法获取有关触发以下信号之一的输入源的信息：

• selectstart

• select

• selectend

• squeezestart

• squeeze

• squeezestart

bool is_input_source_active(input_source_id: int) const 🔗

如果存在具有给定 input_source_id 的活动输入源，则返回 true。

void is_session_supported(session_mode: String) 🔗

检查给定的 session_mode 是否被用户的浏览器支持。

可能的值来自 WebXR 的 XRSessionMode，包括："immersive-vr"、"immersive-ar" 和 "inline"。

此方法不返回任何东西，而是将结果发送给 session_supported 信号。

void set_display_refresh_rate(refresh_rate: float) 🔗

为当前的 HMD 设置屏幕刷新率。不是所有 HMD 和浏览器都支持。不会立即生效，发出 display_refresh_rate_changed 信号后才会生效。