WebXRInterface

Inherits: ARVRInterface < Reference < Object

AR/VR interface using WebXR.

Description

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 an HTML5 export.

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 AR/VR interfaces would instead use functions that return a result immediately. This makes WebXRInterface quite a bit more complicated to initialize than other AR/VR interfaces.

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

  1. extends Spatial
  2. var webxr_interface
  3. var vr_supported = false
  4. func _ready():
  5. # We assume this node has a button as a child.
  6. # This button is for the user to consent to entering immersive VR mode.
  7. $Button.connect("pressed", self, "_on_Button_pressed")
  8. webxr_interface = ARVRServer.find_interface("WebXR")
  9. if webxr_interface:
  10. # Map to the standard button/axis ids when possible.
  11. webxr_interface.xr_standard_mapping = true
  12. # WebXR uses a lot of asynchronous callbacks, so we connect to various
  13. # signals in order to receive them.
  14. webxr_interface.connect("session_supported", self, "_webxr_session_supported")
  15. webxr_interface.connect("session_started", self, "_webxr_session_started")
  16. webxr_interface.connect("session_ended", self, "_webxr_session_ended")
  17. webxr_interface.connect("session_failed", self, "_webxr_session_failed")
  18. # This returns immediately - our _webxr_session_supported() method
  19. # (which we connected to the "session_supported" signal above) will
  20. # be called sometime later to let us know if it's supported or not.
  21. webxr_interface.is_session_supported("immersive-vr")
  22. func _webxr_session_supported(session_mode, supported):
  23. if session_mode == 'immersive-vr':
  24. vr_supported = supported
  25. func _on_Button_pressed():
  26. if not vr_supported:
  27. OS.alert("Your browser doesn't support VR")
  28. return
  29. # We want an immersive VR session, as opposed to AR ('immersive-ar') or a
  30. # simple 3DoF viewer ('viewer').
  31. webxr_interface.session_mode = 'immersive-vr'
  32. # 'bounded-floor' is room scale, 'local-floor' is a standing or sitting
  33. # experience (it puts you 1.6m above the ground if you have 3DoF headset),
  34. # whereas as 'local' puts you down at the ARVROrigin.
  35. # This list means it'll first try to request 'bounded-floor', then
  36. # fallback on 'local-floor' and ultimately 'local', if nothing else is
  37. # supported.
  38. webxr_interface.requested_reference_space_types = 'bounded-floor, local-floor, local'
  39. # In order to use 'local-floor' or 'bounded-floor' we must also
  40. # mark the features as required or optional.
  41. webxr_interface.required_features = 'local-floor'
  42. webxr_interface.optional_features = 'bounded-floor'
  43. # This will return false if we're unable to even request the session,
  44. # however, it can still fail asynchronously later in the process, so we
  45. # only know if it's really succeeded or failed when our
  46. # _webxr_session_started() or _webxr_session_failed() methods are called.
  47. if not webxr_interface.initialize():
  48. OS.alert("Failed to initialize")
  49. return
  50. func _webxr_session_started():
  51. $Button.visible = false
  52. # This tells Godot to start rendering to the headset.
  53. get_viewport().arvr = true
  54. # This will be the reference space type you ultimately got, out of the
  55. # types that you requested above. This is useful if you want the game to
  56. # work a little differently in 'bounded-floor' versus 'local-floor'.
  57. print ("Reference space type: " + webxr_interface.reference_space_type)
  58. func _webxr_session_ended():
  59. $Button.visible = true
  60. # If the user exits immersive mode, then we tell Godot to render to the web
  61. # page again.
  62. get_viewport().arvr = false
  63. func _webxr_session_failed(message):
  64. OS.alert("Failed to initialize: " + message)

There are several ways to handle “controller” input:

You can use one or all of these 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.

Tutorials

Properties

PoolVector3Array

bounds_geometry

String

optional_features

String

reference_space_type

String

requested_reference_space_types

String

required_features

String

session_mode

String

visibility_state

bool

xr_standard_mapping

Methods

ARVRPositionalTracker

get_controller ( int controller_id ) const

TargetRayMode

get_controller_target_ray_mode ( int controller_id ) const

void

is_session_supported ( String session_mode )

Signals

  • reference_space_reset ( )

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 bounds_geometry) or pressed/held a button to recenter their position.

See WebXR’s XRReferenceSpace reset event for more information.


  • select ( int controller_id )

Emitted after one of the “controllers” has finished its “primary action”.

Use get_controller to get more information about the controller.


  • selectend ( int controller_id )

Emitted when one of the “controllers” has finished its “primary action”.

Use get_controller to get more information about the controller.


  • selectstart ( int controller_id )

Emitted when one of the “controllers” has started its “primary action”.

Use get_controller to get more information about the controller.


  • session_ended ( )

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().arvr = false to instruct Godot to resume rendering to the screen.


  • session_failed ( String message )

Emitted by ARVRInterface.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.


  • session_started ( )

Emitted by ARVRInterface.initialize if the session is successfully started.

At this point, it’s safe to do get_viewport().arvr = true to instruct Godot to start rendering to the AR/VR device.


  • session_supported ( String session_mode, bool supported )

Emitted by is_session_supported to indicate if the given session_mode is supported or not.


  • squeeze ( int controller_id )

Emitted after one of the “controllers” has finished its “primary squeeze action”.

Use get_controller to get more information about the controller.


  • squeezeend ( int controller_id )

Emitted when one of the “controllers” has finished its “primary squeeze action”.

Use get_controller to get more information about the controller.


  • squeezestart ( int controller_id )

Emitted when one of the “controllers” has started its “primary squeeze action”.

Use get_controller to get more information about the controller.


  • visibility_state_changed ( )

Emitted when visibility_state has changed.

Enumerations

enum TargetRayMode:

  • TARGET_RAY_MODE_UNKNOWN = 0 —- We don’t know the target ray mode.

  • TARGET_RAY_MODE_GAZE = 1 —- Target ray originates at the viewer’s eyes and points in the direction they are looking.

  • TARGET_RAY_MODE_TRACKED_POINTER = 2 —- Target ray from a handheld pointer, most likely a VR touch controller.

  • TARGET_RAY_MODE_SCREEN = 3 —- Target ray from touch screen, mouse or other tactile input device.

Property Descriptions

Getter

get_bounds_geometry()

The vertices of a polygon which defines the boundaries of the user’s play area.

This will only be available if reference_space_type is "bounded-floor" and only on certain browsers and devices that support it.

The reference_space_reset signal may indicate when this changes.


Setter

set_optional_features(value)

Getter

get_optional_features()

A comma-seperated list of optional features used by ARVRInterface.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 required_features or optional_features.


Getter

get_reference_space_type()

The reference space type (from the list of requested types set in the requested_reference_space_types property), that was ultimately used by ARVRInterface.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 required_features or optional_features.


  • String requested_reference_space_types

Setter

set_requested_reference_space_types(value)

Getter

get_requested_reference_space_types()

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

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

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.


Setter

set_required_features(value)

Getter

get_required_features()

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


Setter

set_session_mode(value)

Getter

get_session_mode()

The session mode used by ARVRInterface.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".


Getter

get_visibility_state()

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


  • bool xr_standard_mapping

Setter

set_xr_standard_mapping(value)

Getter

get_xr_standard_mapping()

If set to true, the button and axes ids will be converted to match the standard ids used by other AR/VR interfaces, when possible.

Otherwise, the ids will be passed through unaltered from WebXR.

Method Descriptions

Gets an ARVRPositionalTracker for the given controller_id.

In the context of WebXR, a “controller” 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 controller is used, interpret the position and orientation of the ARVRPositionalTracker as a ray pointing at the object the user wishes to interact with.

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


Returns the target ray mode for the given controller_id.

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


  • void is_session_supported ( String session_mode )

Checks if the given session_mode 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 session_supported signal with the result.