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...

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 遊戲

屬性

String	enabled_features
String	optional_features
String	reference_space_type
String	requested_reference_space_types
String	required_features
String	session_mode
String	visibility_state

方法

Array	get_available_display_refresh_rates() const
float	get_display_refresh_rate() const
TargetRayMode	get_input_source_target_ray_mode(input_source_id: int) const
XRControllerTracker	get_input_source_tracker(input_source_id: int) const
bool	is_input_source_active(input_source_id: int) const
void	is_session_supported(session_mode: String)
void	set_display_refresh_rate(refresh_rate: float)

---

訊號

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

We don't know the target ray mode.

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.

See the MDN documentation on WebXR's session features for a list of possible values.

---

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()

A comma-seperated list of reference space types used by XRInterface.initialize() when setting up the WebXR session.

The reference space types are requested in order, and the first one supported by the user's device or browser will be used. The reference_space_type property contains the reference space type that was ultimately selected.

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

Possible values come from WebXR's XRReferenceSpaceType. If you want to use a particular reference space type, it must be listed in either required_features or 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.

See the MDN documentation on WebXR's session features for a list of possible values.

---

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 🔗

Gets an XRControllerTracker for the given input_source_id.

In the context of WebXR, an input source can be an advanced VR controller like the Oculus Touch or Index controllers, or even a tap on the screen, a spoken voice command or a button press on the device itself. When a non-traditional input source is used, interpret the position and orientation of the XRPositionalTracker as a ray pointing at the object the user wishes to interact with.

Use this method to get information about the input source that triggered one of these signals:

• 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 訊號後才會生效。