Table of Contents

Class WebXRInterface

Namespace
Godot
Assembly
GodotSharp.dll

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.
  webxr_interface.required_features = 'local-floor'
  webxr_interface.optional_features = 'bounded-floor'

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


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 ButtonPressed and ButtonReleased 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.

public class WebXRInterface : XRInterface, IDisposable
Inheritance
WebXRInterface
Implements
Inherited Members

Properties

OptionalFeatures

A comma-seperated list of optional features used by 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. If you want to use a particular reference space type, it must be listed in either RequiredFeatures or OptionalFeatures.

public string OptionalFeatures { get; set; }

Property Value

string

ReferenceSpaceType

The reference space type (from the list of requested types set in the RequestedReferenceSpaceTypes property), that was ultimately used by Initialize() when setting up the WebXR session.

Possible values come from WebXR's XRReferenceSpaceType. If you want to use a particular reference space type, it must be listed in either RequiredFeatures or OptionalFeatures.

public string ReferenceSpaceType { get; }

Property Value

string

RequestedReferenceSpaceTypes

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

The reference space types are requested in order, and the first one supported by the users device or browser will be used. The ReferenceSpaceType 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 RequiredFeatures or OptionalFeatures.

public string RequestedReferenceSpaceTypes { get; set; }

Property Value

string

RequiredFeatures

A comma-seperated list of required features used by 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 SessionFailed will be emitted.

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 RequiredFeatures or OptionalFeatures.

public string RequiredFeatures { get; set; }

Property Value

string

SessionMode

The session mode used by Initialize() when setting up the WebXR session.

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

Possible values come from WebXR's XRSessionMode, including: "immersive-vr", "immersive-ar", and "inline".

public string SessionMode { get; set; }

Property Value

string

VisibilityState

Indicates if the WebXR session's imagery is visible to the user.

Possible values come from WebXR's XRVisibilityState, including "hidden", "visible", and "visible-blurred".

public string VisibilityState { get; }

Property Value

string

Methods

GetAvailableDisplayRefreshRates()

Returns display refresh rates supported by the current HMD. Only returned if this feature is supported by the web browser and after the interface has been initialized.

public Array GetAvailableDisplayRefreshRates()

Returns

Array

GetDisplayRefreshRate()

Returns the display refresh rate for the current HMD. Not supported on all HMDs and browsers. It may not report an accurate value until after using SetDisplayRefreshRate(float).

public float GetDisplayRefreshRate()

Returns

float

GetInputSourceTargetRayMode(int)

Returns the target ray mode for the given inputSourceId.

This can help interpret the input coming from that input source. See XRInputSource.targetRayMode for more information.

public WebXRInterface.TargetRayMode GetInputSourceTargetRayMode(int inputSourceId)

Parameters

inputSourceId int

Returns

WebXRInterface.TargetRayMode

GetInputSourceTracker(int)

Gets an XRPositionalTracker for the given inputSourceId.

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

public XRPositionalTracker GetInputSourceTracker(int inputSourceId)

Parameters

inputSourceId int

Returns

XRPositionalTracker

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

IsInputSourceActive(int)

Returns true if there is an active input source with the given inputSourceId.

public bool IsInputSourceActive(int inputSourceId)

Parameters

inputSourceId int

Returns

bool

IsSessionSupported(string)

Checks if the given sessionMode is supported by the user's browser.

Possible values come from WebXR's XRSessionMode, including: "immersive-vr", "immersive-ar", and "inline".

This method returns nothing, instead it emits the SessionSupported signal with the result.

public void IsSessionSupported(string sessionMode)

Parameters

sessionMode string

SetDisplayRefreshRate(float)

Sets the display refresh rate for the current HMD. Not supported on all HMDs and browsers. It won't take effect right away until after DisplayRefreshRateChanged is emitted.

public void SetDisplayRefreshRate(float refreshRate)

Parameters

refreshRate float

Events

DisplayRefreshRateChanged

Emitted after the display's refresh rate has changed.

public event Action DisplayRefreshRateChanged

Event Type

Action

ReferenceSpaceReset

Emitted to indicate that the reference space has been reset or reconfigured.

When (or whether) this is emitted depends on the user's browser or device, but may include when the user has changed the dimensions of their play space (which you may be able to access via GetPlayArea()) or pressed/held a button to recenter their position.

See WebXR's XRReferenceSpace reset event for more information.

public event Action ReferenceSpaceReset

Event Type

Action

Select

Emitted after one of the input sources has finished its "primary action".

Use GetInputSourceTracker(int) and GetInputSourceTargetRayMode(int) to get more information about the input source.

public event WebXRInterface.SelectEventHandler Select

Event Type

WebXRInterface.SelectEventHandler

Selectend

Emitted when one of the input sources has finished its "primary action".

Use GetInputSourceTracker(int) and GetInputSourceTargetRayMode(int) to get more information about the input source.

public event WebXRInterface.SelectendEventHandler Selectend

Event Type

WebXRInterface.SelectendEventHandler

Selectstart

Emitted when one of the input source has started its "primary action".

Use GetInputSourceTracker(int) and GetInputSourceTargetRayMode(int) to get more information about the input source.

public event WebXRInterface.SelectstartEventHandler Selectstart

Event Type

WebXRInterface.SelectstartEventHandler

SessionEnded

Emitted when the user ends the WebXR session (which can be done using UI from the browser or device).

At this point, you should do get_viewport().use_xr = false to instruct Godot to resume rendering to the screen.

public event Action SessionEnded

Event Type

Action

SessionFailed

Emitted by Initialize() if the session fails to start.

message may optionally contain an error message from WebXR, or an empty string if no message is available.

public event WebXRInterface.SessionFailedEventHandler SessionFailed

Event Type

WebXRInterface.SessionFailedEventHandler

SessionStarted

Emitted by Initialize() if the session is successfully started.

At this point, it's safe to do get_viewport().use_xr = true to instruct Godot to start rendering to the XR device.

public event Action SessionStarted

Event Type

Action

SessionSupported

Emitted by IsSessionSupported(string) to indicate if the given sessionMode is supported or not.

public event WebXRInterface.SessionSupportedEventHandler SessionSupported

Event Type

WebXRInterface.SessionSupportedEventHandler

Squeeze

Emitted after one of the input sources has finished its "primary squeeze action".

Use GetInputSourceTracker(int) and GetInputSourceTargetRayMode(int) to get more information about the input source.

public event WebXRInterface.SqueezeEventHandler Squeeze

Event Type

WebXRInterface.SqueezeEventHandler

Squeezeend

Emitted when one of the input sources has finished its "primary squeeze action".

Use GetInputSourceTracker(int) and GetInputSourceTargetRayMode(int) to get more information about the input source.

public event WebXRInterface.SqueezeendEventHandler Squeezeend

Event Type

WebXRInterface.SqueezeendEventHandler

Squeezestart

Emitted when one of the input sources has started its "primary squeeze action".

Use GetInputSourceTracker(int) and GetInputSourceTargetRayMode(int) to get more information about the input source.

public event WebXRInterface.SqueezestartEventHandler Squeezestart

Event Type

WebXRInterface.SqueezestartEventHandler

VisibilityStateChanged

Emitted when VisibilityState has changed.

public event Action VisibilityStateChanged

Event Type

Action
Edit this page