
## Teleportation Module

A lot of (native) VR games have a teleportation feature to allow movement in the scene. It is the most convenient way of moving in a scene without the user feeling dizzy or disoriented.

Babylon has supported teleportation in WebVR and has now upgraded the feature to have a lot of different abilities.

The teleportation feature enabled the following ways to interact with the camera's position:

1. Move forward using direct/indirect rays
2. Move backwards
3. Rotate in place.

Quick note about the **WebXR emulator** - Even thou it doesn't have support for it just yet, the WebXR emulator adds a Thumbstick to the emulated controller, making it impossible to simulate teleportation. To get teleportation working you will need to enable `useMainComponentOnly` (described below) to disable the thumbstick's teleportation. It is recommended to only enable this during development, unless this is the required behavior.

### Enabling teleportation

The teleportation module is turned on per default when using the [WebXR Default Experience Helper](/divingDeeper/webXR/webXRExperienceHelpers#the-basic-experience-helper). To turn it on or re-enable it use the following code:

```javascript
const featuresManager = xr.baseExperience.featuresManager; // or any other way to get a features manager
featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable" /* or latest */, {
    xrInput: xr.input,
    // add options here
    floorMeshes: [ground, secondFloor, thirdFloor],
});
```

The latest options can be found in the [WebXR teleportation feature's source code](https://github.com/BabylonJS/Babylon.js/blob/master/src/XR/features/WebXRControllerTeleportation.ts#L31).

Some teleportation parameters are needed during construction and are therefore only configurable in the constructor's `options` parameter. To reconfigure parameters which have no public getter/setter, re-enable the feature:

```javascript
var xrHelper = await scene.createDefaultXRExperienceAsync({
    xrInput: xrHelper.input,
    floorMeshes: [ground] /* Array of meshes to be used as landing points */,
});
// ...
// needs a reconfigure - re-enable the feature (will discard the old one and create a new one!)
xrHelper.teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable" /* or latest */, {
    xrInput: xrHelper.input,
    floorMeshes: [ground],
    renderingGroupId: 1,
});
```

Notice that the only obligatory option for the teleportation feature is the xrInput, which are the controllers it is going to use in order to teleport the user.

### Setting floor meshes

Floor meshes are most important for teleportation, as the module needs to know where the users are allowed to land and where not.

When using the [WebXR Default Experience Helper](/divingDeeper/webXR/webXRExperienceHelpers#the-basic-experience-helper) you can set the floorMeshes during initialization:

```javascript
var xrHelper = await scene.createDefaultXRExperienceAsync({
    xrInput: xr.input,
    floorMeshes: [ground] /* Array of meshes to be used as landing points */,
});
const teleportation = xrHelper.teleportation;
```

When enabling the feature yourself you can provide it in the options object:

```javascript
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
});
```

If you want to add a mesh after the teleportation feature was enabled, you can use the `addFloorMesh` function:

```javascript
teleportation.addFloorMesh(ground2);
```

And to remove simply use the `removeFloorMesh` function:

```javascript
teleportation.removeFloorMesh(ground2);
```

A simple example for enabling floor meshes: <Playground id="#B8D5Z6" title="Enable Floor Meshes" description="Simple example of enabling floor meshes." image=""/>

### Direct and indirect landing zones

The teleportation landing zone is defined by the person holding the controllers. There are two ways of teleportation: direct teleportation and indirect (parabolic) teleportation.

Direct teleportation means - the user aims at the position they want to land at (a straight line). This is used when the ground and the landing location is in sight and is the most convenient and straight-forward way of moving forward.

![Direct WebXR teleportation](/img/how_to/xr/xr-direct-teleportation.png)

An indirect line means the user aims up high and creates a parabolic path. This is used to go across obstacles, or to teleport from one floor to the other.

![Indirect WebXR teleportation](/img/how_to/xr/xr-indirect-teleportation.png)

The direct teleportation is always enabled. The indirect teleportation is enabled per default, but it is possible to disable it using a flag:

```javascript
// disable the parabolic (indirect) teleportation ray
teleportation.parabolicRayEnabled = false;
```

To make the parabolic ray go further you can set the radius that is used to create the inspection ray when pointing the ray at 90 degrees up (Default is 5):

```javascript
teleportation.parabolicCheckRadius = 10;
```

Note that the parabolic ray's radius is bigger, the lower the rotation angle of the controller. The compensation calculation is done using this formula:

```javascript
const compensation = 1 + (Math.PI / 2 - Math.abs(rotationOnTheXAxis));
```

The compensation is multiplied by the defined radius and changes the current ray intersection radius.

### Different input sources

The default input source is an XR headset with two handheld controllers. This input source in WebXR is called `TrackedPointer` .

When the input source has a thumbstick or a touchpad, moving the finger forward will trigger the ray-casting mode. Rotating the finger after seeing the ray casted will rotate the direction in which the user lands. Releasing the finger when seeing a landing zone will move the user there.

When no thumbstick or touchpad is available, the main component (usually a trigger) will be used. See [WebXR input sources](/divingDeeper/webXR/webXRInputControllerSupport) for more information about the main component. When using the main component, which is usually a button, you can define a certain amount of time in milliseconds after which the user will teleport, if still holding the trigger. The default is 3 seconds.

This configuration value can be found in the constructor's options and it is called `timeToTeleport` :

```javascript
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    timeToTeleport: 5000,
});
```

Note that when using a button, it is impossible to allow rotation, so the user's orientation will stay the same as it was before they teleported.

To force the user to use the main component only (even if a thumbstick is available) use the `useMainComponentOnly` flag when constructing:

```javascript
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    timeToTeleport: 5000,
    useMainComponentOnly: true,
});
```

### The teleportation landing zone

The teleportation landing zone is a group of meshes means to show the user where they are going to land and in which direction. Its default version looks like this:

![Indirect WebXR teleportation](/img/how_to/xr/xr-teleportation-landing-zone.png)

Each part of the teleportation landing zone is configurable:

#### The landing zone's material

The material of the landing zone (the dark circle on the floor) can be configured when constructing the feature using css colors:

```javascript
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    defaultTargetMeshOptions: {
        teleportationFillColor: "#55FF99",
        teleportationBorderColor: "blue",
    },
});
```

Which looks like this:

![WebXR Custom landing zone](/img/how_to/xr/xr-landing-zone-custom.png)

The example can be found here: <Playground id="#B8D5Z6#9" title="Custom Landing Zone" description="Simple example of a custom landing zone." image=""/>

#### The ring's material

The rotation ring's material can be provided by the user:

```javascript
let myCustomMaterial = new BABYLON.StandardMaterial("ground", scene);
myCustomMaterial.backFaceCulling = false;
myCustomMaterial.diffuseColor = BABYLON.Color3.Green();
myCustomMaterial.diffuseTexture = new BABYLON.Texture("textures/grass.png", scene);

const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    defaultTargetMeshOptions: {
        torusArrowMaterial: myCustomMaterial,
    },
});
```

Will look like this:

![Custom material for ring](/img/how_to/xr/xr-custom-material-turos-ring.png)

#### Disable the ring up-and-down animation

```javascript
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    defaultTargetMeshOptions: {
        disableAnimation: true,
    },
});
```

And now the ring won't animate up and down when the target zone is casted

#### Disable lighting on the ring

To make sure the ring is always visible no matter the lighting in the scene is, set the `disableLighting` flag when constructing the feature:

```javascript
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    defaultTargetMeshOptions: {
        disableLighting: true,
    },
});
```

This will look like this with light intensity 0.5:

![Disable lighting on ring](/img/how_to/xr/xr-ring-disable-lighting.png)

### Rotating while teleporting

It is possible to not allow the user to rotate after casting the initial ray. It is a flag straight on the teleportation object and it is called `rotationEnabled` :

```javascript
teleportation.rotationEnabled = false;
```

### Backwards movement

Backwards movement is on per default. When the user "pulls" the thumbstick or the touchpad backwards they will move a predefined distance, if this distance is available on any floor mesh behind them.

To configure the distance to move use the `backwardsTeleportationDistance` flag:

```javascript
teleportation.backwardsTeleportationDistance = 1.0; // Default is 0.7
```

To disable backwards moving use this flag:

```javascript
teleportation.backwardsMovementEnabled = false; // Default is 0.7
```

### Rotation in place

When moving the thumbstick left and right (X-Axis movement on the thumbstick/touchpad) the user will rotate a predefined amount. To default rotation is 22.5 degrees (in radians: `Math.PI / 8` ). To change this use the `rotationAngle` flag:

```javascript
// rotate 45 degrees
teleportation.rotationAngle = Math.PI / 4;
```

### Rendering to a different layer or rendering group

If you want the render the teleportation target zone on top of the rest of the meshes you can use one of two ways:

1. rendering group id (See [Rendering groups](/divingDeeper/materials/advanced/transparent_rendering))
2. Utility layer (See [UtilityLayerRenderer](/divingDeeper/mesh/utilityLayerRenderer))

To set the rendering group id :

```javascript
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    renderingGroupId: 1,
});
```

This will look like this (notice it renders on top of the ground that should hide it):

![Rendering group for target zone](/img/how_to/xr/xr-rendering-group-ring.png)

To set a utility layer:

```javascript
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    useUtilityLayer: true,
    // optional
    customUtilityLayerScene: customScene, // a different utility layer scene to use. If not the default utility layer scene will be used
});
```

### Snap-to (Hotspots)

Some XR experiences require the user to land at an exact location (and sometimes ONLY at exact locations). The teleportation snap-to feature allows you to define spots where the user can land and where the teleportation ray will snap (with a specific threshold).

To enable snap-to points you can use one of the two:

-   provide an array of hotspots (Vector3) to the options when enabling the feature:

```javascript
const interestingSpot = new BABYLON.Vector3(-4, 0, 4);
const interestingSpot2 = new BABYLON.Vector3(4, 0, 4);
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    snapPositions: [interestingSpot, interestingSpot2],
});
```

-   Add points after the feature is enabled:

```javascript
teleportation.addSnapPoint(new BABYLON.Vector3(0, 0, 6));
```

Note that it is always expected that the snap-to points will be on a mesh that is defined as a floor mesh. Babylon will not check that! If you put the hotspot too far away from a floor mesh, the results will be unexpected (for example, the user might hover).

To change the snap-to radius, use the `snapToPositionRadius` parameter. Default is 0.8 units or 80 cm and it cannot be 0:

```javascript
const interestingSpot = new BABYLON.Vector3(-4, 0, 4);
const interestingSpot2 = new BABYLON.Vector3(4, 0, 4);
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    snapPositions: [interestingSpot, interestingSpot2],
    snapToPositionRadius: 1.2,
});
```

Now any position of target zone within a 1.2 units (meters) radius of one of the snap-to points will change the target zoné location to be the close point. You can test it in this playground:

-   <Playground id="#DGS0NV#1" title="Snap To Point With Movement Freedom" description="Simple example of snapping to a point with movement freedom." image=""/>

If you want to disable the user's free movements and only let the user land on snap-to points, set the `snapPointsOnly` , either during construction:

```javascript
const interestingSpot = new BABYLON.Vector3(-4, 0, 4);
const interestingSpot2 = new BABYLON.Vector3(4, 0, 4);
const teleportation = featuresManager.enableFeature(WebXRFeatureName.TELEPORTATION, "stable", {
    xrInput: xr.input,
    floorMeshes: [ground],
    snapPositions: [interestingSpot, interestingSpot2],
    snapToPositionRadius: 1.2,
    snapPointsOnly: true,
});
```

or afterwards:

```javascript
teleportation.snapPointsOnly = true;
```

The feature will look like this:

![Rendering group for target zone](/img/how_to/xr/xr-snap-to-teleportation.gif)

You can play around in this playground:

<Playground id="#DGS0NV#3" title="Snap-to Hotspot Example" description="Simple example of snap-to hotspots." image=""/>


# WebXR

## Current state

The [WebXR W3C Proposal](https://immersive-web.github.io/webxr/) is currently in its draft phase. It is, however, already implemented in Chrome (check [caniuse.com](https://caniuse.com/#feat=webxr) to know about others browsers). Starting with version 79, WebVR has been deprecated and WebXR is enabled by default. Earlier browser versions had WebXR behind a configuration flag. 

As the API continuously changes, it is difficult to keep up with feature changes. The latest chrome canary is notably the most XR-feature-complete browser and Google continuously updates the browser with new features. This is the main reason we introduced the [Features Manager](/divingDeeper/webXR/webXRFeaturesManager), which allows us to implement the newest version of official features with internal versioning without breaking backwards compatibility.

Note that most of the time when we say WebXR, we actually mean WebXR **in VR immersive mode**. This is currently the most used mode of WebXR.

## Device and browser support

### PC

Chrome 79 on windows officially supports WebXR with all [Microsoft Mixed Reality](https://en.wikipedia.org/wiki/Windows_Mixed_Reality) Devices. Unofficially, WebXR is working well with the oculus SDK (Rift, Rift S, and Quest with Link). As of this writing, Oculus support is still behind a flag.

### Mobile and Quest

WebXR is supported on Google Daydream using Chrome.

WebXR AR features on Android's Chrome Browser (Stable and Canary) can be enabled behind a flag at [chrome://flags](chrome://flags), including AR features such as plane detection, hit-tests and anchors. Note that the AR features' architecture is constantly changing, so expect different results from version to version.

Oculus Quest supports WebXR (in VR mode) in the latest oculus browser. Babylon's specs implementation works well with the quest.

No official iOS/iPhone support is planed at the moment. Mozilla has built the [WebXR iOS Viewer](https://apps.apple.com/us/app/webxr-viewer/id1295998056) which is a (very) limited AR-oriented browser.

### Polyfill

For older browsers that support WebVR but not WebXR you can use the [WebXR Polyfill](https://github.com/immersive-web/webxr-polyfill) which is the WebXR API implementation using WebVR features. Some functions will not work (or will simply return without changes) but the basic functionality works well.

Babylon does not intend on integrating the polyfill in the framework itself or in the playground. We encourage the developer to offer the polyfill to users not using a WebXR-Supported browser.

To use the polyfill in the playground, please add the following to your playground (before 'createScene'):

```javascript
const xrPolyfillPromise = new Promise((resolve) => {
    if (navigator.xr) {
        return resolve();
    }
    define('polyfill', ['https://cdn.jsdelivr.net/npm/webxr-polyfill@latest/build/webxr-polyfill.js'], (polyfill) => { new polyfill(); resolve(); });
});
```

afterwards, make sure to `await` it before initializing WebXR:

```javascript
const xrPolyfillPromise = new Promise((resolve) => {
    if (navigator.xr) {
        return resolve();
    }
    define('polyfill', ['https://cdn.jsdelivr.net/npm/webxr-polyfill@latest/build/webxr-polyfill.js'], (polyfill) => { new polyfill(); resolve(); });
});

var createScene = async function () {
    // wait for the polyfill to kick in
    await xrPolyfillPromise;
    console.log(navigator.xr); // should be there!
    console.log(await BABYLON.WebXRSessionManager.IsSessionSupportedAsync('immersive-vr')) // should be true
    // create your scene
    var scene = new BABYLON.Scene(engine);
    var camera = new BABYLON.DeviceOrientationCamera("DevOr_camera", new BABYLON.Vector3(-30, -30, -30), scene);
    camera.setTarget(BABYLON.Vector3.Zero());
    camera.attachControl(canvas, true);
    var light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0, 0, 0), scene);
    scale = 100;
    // initialize XR
    var xr = await scene.createDefaultXRExperienceAsync();

    return scene;
};
```

If you experience low-resolution when using the polyfill, make sure to resize the canvas to a higher resolution. This is a limitation of WebVR (that required resizing the canvas) which we didn't integrate for WebXR.

### The WebXR Emulator

If you are developing and don't want to constantly test on a real device, use mozilla's [WebXR Emulator](https://blog.mozvr.com/webxr-emulator-extension/) which is available for [chrome](https://chrome.google.com/webstore/detail/webxr-api-emulator/mjddjgeghkdijejnciaefnkjmkafnnje) and [firefox](https://addons.mozilla.org/firefox/addon/webxr-api-emulator). We support it and actually use it during development. Highly recommended.

## Getting started

The simplest way to get started is using a WebXR-enabled browser and add a single line of code to your scene:

``` javascript
const xr = scene.createDefaultXRExperienceAsync();
```

This will enable WebXR **in VR immersive mode**, including session init, input sources, the camera, teleportation and scene interactions. All using our [WebXR Default Experience Helper](/divingDeeper/webXR/webXRExperienceHelpers#the-basic-experience-helper).

Note that the `xr` variable is a Promise. Using the async/await pattern will be simpler and more intuitive. It will also make sense to define floor meshes so we can define our ground and move on it. Here is a sphere in XR:

``` javascript
var createScene = async function() {

    var scene = new BABYLON.Scene(engine);
    var camera = new BABYLON.FreeCamera("camera1", new BABYLON.Vector3(0, 5, -10), scene);
    camera.setTarget(BABYLON.Vector3.Zero());
    camera.attachControl(canvas, true);
    var light = new BABYLON.HemisphericLight("light1", new BABYLON.Vector3(0, 1, 0), scene);
    light.intensity = 0.7;
    var sphere = BABYLON.Mesh.CreateSphere("sphere1", 16, 2, scene);
    sphere.position.y = 1;

    const env = scene.createDefaultEnvironment();

    // here we add XR support
    const xr = await scene.createDefaultXRExperienceAsync({
        floorMeshes: [env.ground]
    });

    return scene;
};
```

<Playground id="#F41V6N" title="Sphere In WebXR Using Babylon.js" description="Simple example of a sphere in WebXR using Babylon.js" image=""/>

And that's it!

Make sure to read more on the [WebXR Experience Helper](/divingDeeper/webXR/webXRExperienceHelpers) for further tips and tricks, and take a look at our [Demos and examples](/divingDeeper/webXR/webXRDemos) page.

## Migrating from WebVR

WebVR is deprecated and will soon end its life in most if not all browsers. It is highly recommended to port all WebVR implementations to WebXR.

### Migrating from the VR Experience helper

If you used our [VR experience helper](/divingDeeper/cameras/webVRHelper) remove the VR initializer and add the XR experience helper. So this:

``` javascript
var scene = new BABYLON.Scene(engine);
var vrHelper = scene.createDefaultVRExperience();
```

turns to this:

``` javascript
var scene = new BABYLON.Scene(engine);
var xrHelper = scene.createDefaultXRExperienceAsync();
```

The XR helper has full controller support per default, including interactions with the scene meshes, pointer events and more. Read more about the [XR Experience helper](/divingDeeper/webXR/webXRExperienceHelpers).

### Migrating controller support

Since WebXR controllers are no longer considered to be Gamepads the architecture is a bit different.

The most important feature that was added is the full pointer events support for the controllers. The controllers support all pointer events, so you can use [Pointer interactions](/divingDeeper/scene/interactWithScenes#pointer-interactions) just like you use to controller mouse interactions in your scene.

It is also important to note that it is now possible to query what features the controller has and act accordingly.

Here are the **VR** controllers' most used functions, and how to get them to work in **XR**:

``` javascript
// On new controller attached:

// WebVR:
webvrCamera.onControllersAttached = (vrController) => {
    // fun with the new controller, which is a gamepad!
}

// WebXR:
const webXRInput = xr.input; // if using the experience helper, otherwise, an instance of WebXRInput
input.onControllerAddedObservable.add((xrController /* WebXRInputSource instance */ ) => {
    // more fun with the new controller, since we are in XR!
    inputSource.onMotionControllerInitObservable.add((motionController) => {
        // get the motionController, which is similar to but NOT a gamepad:

    });
    // xr supports all types of inputs, so some won't have a motion controller
    if (!xrController.gamepad) {
        // using touch, hands, gaze, something else?
    }
});

// From this point we assume we have two variables: vrController and xrController.
// We also assume motionController is present!

// main button

// WebVR:
controller.onMainButtonStateChangedObservable.add((newState /* ExtendedGamepadButton */ ) => {
    // is the button pressed?
    if (newState.pressed) {
        // Do something
    }
});

// WebXR:
// get the main component (decided by the controller's vendor!)
const mainComponent = xrController.motionController.getMainComponent();
// or get the trigger component, if present:
const mainTrigger = xrController.motionController.getComponent(WebXRControllerComponent.TRIGGER);
mainComponent.onButtonStateChanged.add((component /* WebXRControllerComponent */ ) => {
    // check for changes:
    // pressed changed?
    if (component.changes.pressed) {
        // is it pressed?
        if (component.changes.pressed.current === true) {
            // pressed
        }
        // or a different way:
        if (component.pressed) {
            // component is pressed.
        }
    }
})

// thumbpad / touchpad

// in WebVR - you had to check what controller is being used, but in general this would work:
vrController.onPadValuesChangedObservable.add(function(stateObject) {
    console.log(stateObject); // {x: 0.1, y: -0.3}
});

// in webXR you can check if it is present and work accordingly:
const thumbstick = xrController.motionController.getComponent(WebXRControllerComponent.THUMBSTICK);
if (thumbstick) {
    // Huzza! we have a thumbstick:
    thumbstick.onButtonStateChanged // will trigger when the thumbstick is PRESSED or touched!

    thumbstick.onAxisValueChanged // will trigger when axes of the thumbstick changed
}

// touchpad

// in WebVR we had "pad" concept which was for both thumbstick and touchpad
controller.onPadValuesChangedObservable.add(function(stateObject) {
    console.log(stateObject); // {x: 0.1, y: -0.3}
});

// in WebXR, it is much much better:
const touchpad = xrController.motionController.getComponent(WebXRControllerComponent.TOUCHPAD);
if (touchpad) {
    // Finally, a controller with a touchpad
    touchpad.onButtonStateChanged // will trigger when the touchpad is touched or pressed

    touchpad.onAxisValueChanged // will trigger when axes of the touchpad changed
}
```

Read more about the [XR Controllers system](/divingDeeper/webXR/webXRInputControllerSupport).

### Legacy support

Thou we always encourage backwards compatibility **We recommend using WebXR directly** and stop using the WebVR experience helper. However:

The latest WebVR Experience helper has a new flag in its init options - `useXR` . This will check for XR support and will launch the VR session in WebXR, if possible. A working example can be found in <Playground id="#TAFSN0#323" title="WebVR Check for WebXR" description="Simple example of the WebVR -useXR check to create a VR session using WebXR instead." image=""/>

``` javascript
var createScene = function() {
    // Create scene
    var scene = new BABYLON.Scene(engine);

    // Create simple sphere
    var sphere = BABYLON.Mesh.CreateIcoSphere("sphere", {
        radius: 0.2,
        flat: true,
        subdivisions: 1
    }, scene);
    sphere.position.y = 3;
    sphere.material = new BABYLON.StandardMaterial("sphere material", scene)

    // Lights and camera
    var light = new BABYLON.DirectionalLight("light", new BABYLON.Vector3(0, -0.5, 1.0), scene);
    light.position = new BABYLON.Vector3(0, 5, -2);
    var camera = new BABYLON.ArcRotateCamera("camera", -Math.PI / 2, Math.PI / 4, 3, new BABYLON.Vector3(0, 3, 0), scene);
    camera.attachControl(canvas, true);
    scene.activeCamera.beta += 0.8;

    // Default Environment
    var environment = scene.createDefaultEnvironment({
        enableGroundShadow: true,
        groundYBias: 2.8
    });
    environment.setMainColor(BABYLON.Color3.FromHexString("#74b9ff"))

    // Shadows
    var shadowGenerator = new BABYLON.ShadowGenerator(1024, light);
    shadowGenerator.useBlurExponentialShadowMap = true;
    shadowGenerator.blurKernel = 32;
    shadowGenerator.addShadowCaster(sphere, true);

    // Enable VR, use XR when possible
    var vrHelper = scene.createDefaultVRExperience({
        createDeviceOrientationCamera: false,
        useXR: true, // This will enable XR if supported
        floorMeshes: [environment.ground]
    });

    // Runs every frame to rotate the sphere
    scene.onBeforeRenderObservable.add(() => {
        sphere.rotation.y += 0.0001 * scene.getEngine().getDeltaTime();
        sphere.rotation.x += 0.0001 * scene.getEngine().getDeltaTime();
    })

    // GUI
    var plane = BABYLON.Mesh.CreatePlane("plane", 1);
    plane.position = new BABYLON.Vector3(0.4, 4, 0.4)
    var advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateForMesh(plane);
    var panel = new BABYLON.GUI.StackPanel();
    advancedTexture.addControl(panel);
    var header = new BABYLON.GUI.TextBlock();
    header.text = "Color GUI";
    header.height = "100px";
    header.color = "white";
    header.textHorizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_CENTER;
    header.fontSize = "120"
    panel.addControl(header);
    var picker = new BABYLON.GUI.ColorPicker();
    picker.value = sphere.material.diffuseColor;
    picker.horizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_CENTER;
    picker.height = "350px";
    picker.width = "350px";
    // This will work in XR, since we are using native pointer events!
    picker.onValueChangedObservable.add(function(value) {
        sphere.material.diffuseColor.copyFrom(value);
    });
    panel.addControl(picker);

    vrHelper.onAfterEnteringVRObservable.add(() => {
        // This callback will still work! Would be better to use the XR native observables.
    })

    return scene;
};
```

The color picker works since it is using the pointer architecture. If XR is present, XR will be used. Otherwise, it will use WebVR as a fallback.

Note that some features will not work correctly or will not work at all. For example, camera gaze will not work at all. Controller will work, but since the interaction architecture is different, it is highly likely you will need to adjust a few observers in order to get it to work, especially if there are VR-specific callbacks.

We recommend using the WebXR polyfill instead.


## A bit about augmented reality

The idea behind augmented reality is simple - show the real world, but add information on top of it. As opposed to virtual reality where you are fully immersed in a different scene and have no actual contact to the real world, augmented reality lets you interact with it.

## Getting started with Augmented reality

### WebXR and AR

Augmented reality using Babylon.js will be heavily using WebXR, so I will recommend you to first start with the [getting started with WebXR](/divingDeeper/webXR/introToWebXR) guide. Most of the information that is valid for immersive VR sessions is also valid for immersive AR sessions. The few main differences between the two will be explained here.

### Supported devices

Immersive AR sessions are (currently) supported on two types of devices - mobile phones and firefox reality on the Hololens.

Mobile phones using android support immersive AR sessions on chrome (stable/canary). Note that you will need to install [AR Core](https://play.google.com/store/apps/details?id=com.google.ar.core), otherwise it will be a very short experience.

Hololens 2 supports WebXR and immersive AR sessions when using [Firefox Reality for hololens](https://www.microsoft.com/en-ca/p/firefox-reality/9npq78m7nb0r).

To check your scene on a desktop you can use the WebXR emulator, which supports a set of features of AR and lets you enter an immersive AR session when choosing the mobile mode.

### Simple scene in immersive AR

The simplest immersive AR sample is a port of an immersive VR scene:

```javascript
var createScene = async function () {
  var scene = new BABYLON.Scene(engine);
  var camera = new BABYLON.FreeCamera(
    "camera1",
    new BABYLON.Vector3(0, 5, -10),
    scene
  );
  camera.setTarget(BABYLON.Vector3.Zero());
  camera.attachControl(canvas, true);
  var light = new BABYLON.HemisphericLight(
    "light1",
    new BABYLON.Vector3(0, 1, 0),
    scene
  );
  light.intensity = 0.7;
  var sphere = BABYLON.Mesh.CreateSphere("sphere1", 16, 2, scene);
  sphere.position.y = 2;
  sphere.position.z = 5;

  const xr = await scene.createDefaultXRExperienceAsync({
    // ask for an ar-session
    uiOptions: {
      sessionMode: "immersive-ar",
    },
  });

  return scene;
};
```

Playground for a simple immersive AR scene: <Playground id="#F41V6N#32" title="Simple Immersive AR Scene" description="Simple example of an immersive AR scene." image=""/>

Notice that no environment was created. As opposed to immersive VR sessions, AR doesn't require a skybox or ground. If you want to define ground and remove it when entering AR (for example if you develop an experience for both desktop and AR) you can use the background remover feature, defined later in this page.

## Features

Some features require the Incubation flag in the latest chrome canary. Visit chrome://flags/ and enable WebXR incubation.

You will then need to ask WebXR to enable this feature. this can be done using the optionalFeature parameter in the default experience helper:

```javascript
const xr = await scene.createDefaultXRExperienceAsync({
  uiOptions: {
    sessionMode: "immersive-ar",
  },
  optionalFeatures: true,
});
```

This will enable all optional features that we support. You can also add individual features by using an array insteaf of a boolean:

```javascript
const xr = await scene.createDefaultXRExperienceAsync({
  uiOptions: {
    sessionMode: "immersive-ar",
  },
  optionalFeatures: ["hit-test", "anchors"],
});
```

### Hit test

Hit-test is used for sending a ray into the real world and receiving information about intersection in space. You can read about it in the [hit test w3c draft](https://immersive-web.github.io/hit-test/). Think about a ray that is broadcasted from your phone's screen towards to object you are looking for. If the device's AR capabilities allows it, it will let you know the position and orientation of the point relative to you.

To enable hit-testing, add this after initializing XR

```javascript
// featuresManager from the base webxr experience helper
const hitTest = featuresManager.enableFeature(BABYLON.WebXRHitTest, "latest");
```

In typescript you can also get the type set correctly:

```javascript
// featuresManager from the base webxr experience helper
const hitTest = featuresManager.enableFeature(BABYLON.WebXRHitTest, 'latest') as BABYLON.WebXRHitTest;
```

This will enable the default behavior of hit-testing which is sending a single hit-test ray from the center of the display forward on each frame.

The options that you can pass are descriped in this interface:

```javascript
export interface IWebXRHitTestOptions {
  /**
   * Do not create a permanent hit test. Will usually be used when only
   * transient inputs are needed.
   */
  disablePermanentHitTest?: boolean;
  /**
   * Enable transient (for example touch-based) hit test inspections
   */
  enableTransientHitTest?: boolean;
  /**
   * Offset ray for the permanent hit test
   */
  offsetRay?: Vector3;
  /**
   * Offset ray for the transient hit test
   */
  transientOffsetRay?: Vector3;
  /**
   * Instead of using viewer space for hit tests, use the reference space defined in the session manager
   */
  useReferenceSpace?: boolean;
}
```

`disablePermanentHitTest` will disable the constant hit-testing, while `enableTransientHitTest` will enable hit-tests when touching the screen. The offsets define the offset from which the ray will be sent (relative to the center of the device's view).

After enabling the feature, you can register to get updates using the `onHitTestResultObservable`:

```javascript
// a dot to show in the found position
const dot = BABYLON.SphereBuilder.CreateSphere(
  "dot",
  {
    diameter: 0.05,
  },
  scene
);
dot.isVisible = false;
hitTest.onHitTestResultObservable.add((results) => {
  if (results.length) {
    dot.isVisible = true;
    results[0].transformationMatrix.decompose(
      dot.scaling,
      dot.rotationQuaternion,
      dot.position
    );
  } else {
    dot.isVisible = false;
  }
});
```

This will show the dot only if hit-test worked, and will hide it if it didn't. The dot will be projected to the real world using the information provided by the system.

A simple example for WebXR hit-test using Babylon.js: <Playground id="#XWBES1" title="WebXR Hit-Test Using Babylon.js" description="Simple example of WebXR hit testing." image=""/>. Open this with your AR device (probably your android smartphone) and point the device at a textured plane (like your floor or door). The marker will be shown at the right location if/when the system scanned the plane correctly. 

### Anchors

Anchors are tracked points in space that the system will constantly update as you continue scanning your environment. The points' transformation will be constantly updated by the underlying system. You can read more about anchors at the [WebXR anchors module](https://immersive-web.github.io/anchors/) w3c proposal.

Enable the anchors system using:

```javascript
// featuresManager from the base webxr experience helper
const anchorSystem = featuresManager.enableFeature(BABYLON.WebXRAnchorSystem, 'latest');
```

or for typescript:

```javascript
// featuresManager from the base webxr experience helper
const anchorSystem = featuresManager.enableFeature(BABYLON.WebXRAnchorSystem, 'latest') as BABYLON.WebXRAnchorSystem;
```

Some options can be passed to the anchor system:

```javascript
export interface IWebXRAnchorSystemOptions {
    /**
     * a node that will be used to convert local to world coordinates
     */
    worldParentNode?: TransformNode;

    /**
     * If set to true a reference of the created anchors will be kept until the next session starts
     * If not defined, anchors will be removed from the array when the feature is detached or the session ended.
     */
    doNotRemoveAnchorsOnSessionEnded?: boolean;
}
```

Anchors are removed when exiting the XR session (note that the anchors are removed, and not meshed that are attached to them), which is the recommended behavior, as anchors cannot be referenced between sessions.

If you want to prevent that from happening, use the `doNotRemoveAnchorsOnSessionEnded` when initializing the anchor system:

```javascript
const anchorSystem = featuresManager.enableFeature(BABYLON.WebXRAnchorSystem, 'latest', { doNotRemoveAnchorsOnSessionEnded: true });
```

The anchor system fits perfectly to the hit-test feature if you want to add an anchor at a hit test position. To do that use the `addAnchorPointUsingHitTestResultAsync` function:

```javascript
const arTestResult = getMeTheResultINeed();
const anchorPromise = anchorSystem.addAnchorPointUsingHitTestResultAsync(lastHitTest);
```

To add an anchor in any position and rotation in the scene, use the `addAnchorAtPositionAndRotationAsync` function:

```javascript
const { position, rotationQuaternion } = anyRandomMesh;
const anchorPromise = anchorSystem.addAnchorAtPositionAndRotationAsync(position, rotationQuaternion);
```

Note that `anchorPromise` will return a *native XRAnchor* when fulfilled. This will provide you with what the browser returns. To work with anchors **in the babylon way**, we use the observables defined in the anchor module:

```javascript
anchorSystem.onAnchorAddedObservable.add((anchor) => {
    // ... do what you want with the anchor after it was added
})

anchorSystem.onAnchorRemovedObservable.add((anchor) => {
    // ... do what you want with the anchor after it was removed
})

anchorSystem.onAnchorUpdatedObservable.add((anchor) => {
    // ... do what you want with the anchor after it was updated
})
```

The anchor is of type `IWebXRAnchor`:

```javascript
export interface IWebXRAnchor {
    /**
     * A babylon-assigned ID for this anchor
     */
    id: number;
    /**
     * Transformation matrix to apply to an object attached to this anchor
     */
    transformationMatrix: Matrix;
    /**
     * The native anchor object
     */
    xrAnchor: XRAnchor;

    /**
     * if defined, this object will be constantly updated by the anchor's position and rotation
     */
    attachedNode?: TransformNode;
}
```

To attach an anchor to a node (for example a mesh that you want to always be in this location in the scene) use the `attachedNode` variable. This will also update the mesh's transformation when the anchor is updated:

```javascript
const mesh = //...

anchorSystem.onAnchorAddedObservable.add((anchor) => {
    anchor.attachedNode = mesh;
})
```

The mesh will now be tracked by the system and will be located at the requested point. 

You might ask yourself why use the anchor system with hit-test results, as hit-test results are returned by the system with a position defined by the device. Setting the mesh at the hit-test's location will work just fine. The difference is that the system might update the information it has about this position - maybe it found out the plane is at a different transformation, maybe it updated its position in space. Using the anchor system will keep the transformation updated even when the system updated its knowledge of the space.

### Plane detection

Your device is (usually) capable of detecting plane geometries in the real world. To read more about plane detection go to the [Plane detection explainer](https://github.com/immersive-web/real-world-geometry/blob/master/plane-detection-explainer.md). 

Babylon has an experimental plane detection module that works with the underlying system. To enable it:

```javascript
// featuresManager from the base webxr experience helper
const planeDetector = featuresManager.enableFeature(BABYLON.WebXRPlaneDetector, "latest");
```

Just like any module you can configure it using the options object, which is of this type:

```javascript
export interface IWebXRPlaneDetectorOptions {
    /**
     * The node to use to transform the local results to world coordinates
     */
    worldParentNode?: TransformNode;

    /**
     * If set to true a reference of the created planes will be kept until the next session starts
     * If not defined, planes will be removed from the array when the feature is detached or the session ended.
     */
    doNotRemovePlanesOnSessionEnded?: boolean;
}
```

Similar to the anchor system, planes do not stay between sessions. If you want to keep the native XRPlane objects, set the `doNotRemovePlanesOnSessionEnded` to true, and babylon will not delete them.

the plane detector works automatically and offers three observables for you to use:

```javascript
planeDetector.onPlaneAddedObservable.add((plane) => {
    // ... do what you want with the plane after it was added
})

planeDetector.onPlaneRemovedObservable.add((plane) => {
    // ... do what you want with the plane after it was removed
})

planeDetector.onPlaneUpdatedObservable.add((plane) => {
    // ... do what you want with the plane after it was updated
})
```

The plane object is of type IWebXRPlane:

```javascript
export interface IWebXRPlane {
    /**
     * a babylon-assigned ID for this polygon
     */
    id: number;
    /**
     * an array of vector3 points in babylon space. right/left hand system is taken into account.
     */
    polygonDefinition: Array<Vector3>;
    /**
     * A transformation matrix to apply on the mesh that will be built using the polygonDefinition
     * Local vs. World are decided if worldParentNode was provided or not in the options when constructing the module
     */
    transformationMatrix: Matrix;
    /**
     * the native xr-plane object
     */
    xrPlane: XRPlane;
}
```

To create a Babylon polygon from the plane information do the following:

```javascript
const plane = // a reference to an added plane
// add the starting point, so the polygon will close
plane.polygonDefinition.push(plane.polygonDefinition[0]);
// create a polygon mesh builder for the polygons returned from the system
var polygon_triangulation = new BABYLON.PolygonMeshBuilder("name", plane.polygonDefinition.map((p) => new BABYLON.Vector2(p.x, p.z)), scene);
// build the plane with specific thickness
var polygon = polygon_triangulation.build(false, 0.01);

```

A simple usecase for planes is showing them in your scene using polygons. An example for that can be found at the WebXR Plane Detection demo: <Playground id="#98TM63" title="WebXR Plane Dedication Demo" description="WebXR Plane Dedication Demo" image="/img/playgroundsAndNMEs/vrglasses.png"/>


### Background remover

When in AR you want to avoid environment meshes like a skybox and a ground (unless it was your goal to keep them). If you are creating a scene that should work on both regular devices and in AR, you will want the ability to disable certain meshes when entering AR, and re-enabling them when leaving AR. This module does exactly that. It receives a list of meshes, and disables/enables them when needed.

When using the babylon environment helper, the module can do the work for you automatically. In that case, the skybox and ground will be automatically removed if you enabled the feature. 

To enable it use:

```javascript
const xrBackgroundRemover = featuresManager.enableFeature(BABYLON.WebXRBackgroundRemover);
```

To customize the way the module works, use the following configuration object:

```javascript
export interface IWebXRBackgroundRemoverOptions {
    /**
     * Further background meshes to disable when entering AR
     */
    backgroundMeshes?: AbstractMesh[];
    /**
     * flags to configure the removal of the environment helper.
     * If not set, the entire background will be removed. If set, flags should be set as well.
     */
    environmentHelperRemovalFlags?: {
        /**
         * Should the skybox be removed (default false)
         */
        skyBox?: boolean;
        /**
         * Should the ground be removed (default false)
         */
        ground?: boolean;
    };
    /**
     * don't disable the environment helper
     */
    ignoreEnvironmentHelper?: boolean;
}
```

For example if you want the module to remove only the skybox and not the ground, when using the environment helper, enable the feature this way:

```javascript
const xrBackgroundRemover = featuresManager.enableFeature(BABYLON.WebXRBackgroundRemover, 'latest', {
  environmentHelperRemovalFlags: {
    skyBox: true,
    ground: false
  }
});
```

# Demos

<Playground id="#GG06BQ#3" title="XR Measurement Tape" description="XR Measurement Tape Demo" image="/img/playgroundsAndNMEs/vrglasses.png"/>
<Playground id="#KDWCZY" title="Placing A Mesh In Space" description="Simple example of placing a mesh in space." image="/img/playgroundsAndNMEs/vrglasses.png"/>


The WebXR Camera is an extension of the `FreeCamera` that includes an update loop from an XRFrame and the ability to create 1 or more rig cameras that will be used to render the XR session.

If you are not using the [XR Experience helper](/divingDeeper/webXR/webXRExperienceHelpers), you will need an [XR Session Manager](/divingDeeper/webXR/webXRSessionManagers) to construct a new WebXR Camera:

``` javascript
const xrCamera = new WebXRCamera("nameOfCamera", scene, xrSessionManager);
```

Notice that as opposed to the free and target cameras, the constructor does not accept an initial position. This has a few reasons, the main one being - the first frame will populate the camera's position with the real-world information which cannot be queried when creating the camera. In the next section(s) you will see how to get an initial position from a non-XR camera and how to control the user's position correctly.

## How positioning works

Just like any Babylon camera, the WebXR camera is an object with its own position and rotation that can be updated between frames. The WebXR camera's transformation is the current position of the device rendering the XR session (such as the HUD or the phone rendering the session) relative to the reference space currently used in the [Session Manager](/divingDeeper/webXR/webXRSessionManagers).

The camera's position will update every frame from the information sent to it by the XRFrame. The XRFrame contains a general position of the device, and, if available, the poses for each screen (or eye) that are used to update the position of the rig cameras (which are the ones actually rendering the scene).

Just like any other camera you can get its direction:

``` javascript
const direction = xrCamera.getDirection(Axis.Z);
```

Or a position in front of the camera in a certain distance:

``` javascript
// get the position 2 meters in front of the camera
const frontPosition = xrCamera.getFrontPosition(2);
```

If the camera's position changes between frames (manually by you, or by the [WebXR teleportation feature](/typedoc/classes/babylon.webxrmotioncontrollerteleportation)) a new reference space is being calculated (compensating for the position change). This reference space will now be used to update the camera's position.

The camera's Rig-system is the one responsible for rendering. The Rig-Camera's pose is always calculated based on the pose coming from the XR-Frame and **NOT** the WebXR Camera's pose. The main camera's pose is only a reference of the base transformation and is not directly influencing the rendered cameras.

## Current user's height

The WebXR camera can provide you with the height of the current user, unrelated to the ground. This is an important piece of information when ground level is not at 0. When ground level is 0, the user height and the camera's `position.y` will be the same.

To query the user's height from the real ground use the `realWorldHeight` of the camera:

```javascript
const userHeight = xrCamera.realWorldHeight();
```

This function will return the height of the user or 0 if not available.

Note that the user height depends on the type of reference space you chose to your experience. Reference space type `local-floor` will deliver the user's height, but `viewer` (for example) will deliver what you defined as a height compensation in the [XR Session Manager](/divingDeeper/webXR/webXRSessionManagers).

## Updating from a Non-VR Camera

When entering XR you might want to duplicate the Non-XR camera's position and use it as the base position of the XR Camera. To do that you will need to find the absolute transformation of the old camera and apply it to the new one. Babylon allows you to do that with a single function of the XR Camera:

``` javascript
// if scene.activeCamera is still the non-VR camera:
xrCamera.setTransformationFromNonVRCamera();

// Otherwise, provide the non-vr camera to copy the transformation from:

xrCamera.setTransformationFromNonVRCamera(otherCamera);

// If you want XR o also reset the XR Reference space, set the 2nd variable to true:

xrCamera.setTransformationFromNonVRCamera(otherCamera, true);
```

When executing this function the XR camera will copy the position of the old camera, and its rotation around the Y axis. The rest will be provided by the XR Frame. It is important to know that the height provided by the XR Frame (relative to the reference space) will be added to the position as a compensation for the position reset. Which means that it is possible that the XR camera's Y position will not be exactly equal to the other camera's Y position.


## Basic scene

This is a step-by-step guide on how to add XR features to a basic scene

## Basic Scene with XR Support

Here we just add an environment, a sphere, and XR support

``` javascript
const xrHelper = await scene.createDefaultXRExperienceAsync();
```

<Playground id="#9K3MRA" title="Basic Scene With WebXR Support" description="Simple example of a basic scene with WebXR support." image=""/>

### Adding teleportation

To get teleportation enabled, we want to provide the experience helper with an array of floor meshes:

``` javascript
const xrHelper = await scene.createDefaultXRExperienceAsync({
    // define floor meshes
    floorMeshes: [environment.ground]
});
```

<Playground id="#9K3MRA#1" title="Basic Scene With Teleportation" description="Simple example of a basic scene with teleportation enabled." image=""/>

### Adding a color picker to the basic scene

Add a color picker (from our GUI library) and use it to change the sphere's color.

Notice that no changes were made in the XR code, and that the scene works perfectly well outside VR as well.

``` javascript
// GUI
var plane = BABYLON.Mesh.CreatePlane("plane", 1);
plane.position = new BABYLON.Vector3(1.4, 1.5, 0.4)
var advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateForMesh(plane);
var panel = new BABYLON.GUI.StackPanel();
advancedTexture.addControl(panel);
var header = new BABYLON.GUI.TextBlock();
header.text = "Color GUI";
header.height = "100px";
header.color = "white";
header.textHorizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_CENTER;
header.fontSize = "120"
panel.addControl(header);
var picker = new BABYLON.GUI.ColorPicker();
picker.value = sphere.material.diffuseColor;
picker.horizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_CENTER;
picker.height = "350px";
picker.width = "350px";
picker.onValueChangedObservable.add(function(value) {
    sphere.material.diffuseColor.copyFrom(value);
});
panel.addControl(picker);
```

<Playground id="#9K3MRA#2" title="WebXR Color Picker" description="Simple WebXR color picker example." image=""/>

## Other demos

<Playground id="#PPM311#63" title="Goalkeeper Training" description="Goalkeeper Training" image=""/>
<Playground id="#B922X8#19" title="Physics Playground" description="Physics Playground" image=""/>

## Babylon.js scenes with XR support

<Playground id="#JA1ND3#161" title="Mansion" description="Mansion Demo" image=""/>
<Playground id="#TJIGQ1#3" title="Hill Valley" description="Hill Valley" image=""/>
<Playground id="#JA1ND3#164" title="Espilit" description="Espilit" image=""/>



## Introduction

In order to simplify development for WebXR we offer a WebXR helper that will initialize WebXR automatically for you and provide an environment with which you can develop your AR and VR experiences. Fully configurable, the WebXR experience helper is very flexible and easy to use.

We offer a basic set of functionalities with the WebXR experience helper, and offer a full XR experience, including UI, teleportation and more, with the Default WebXR experience helper.

We recommend using the [Default Experience](#the-webxr-default-experience) for ease of use, and the [Basic Experience Helper](#the-basic-experience-helper) when looking for more control over decisions.

*Note that you don't have to use the experience helper. Everything can be done outside of those helper on your own.*

## The basic Experience Helper

### Basic usage

The basic experience helper will:

* Initialize the XR scene
* Create an XR Camera
* Initialize the features manager

It also offers help functions to enter and exit the XR session.

The experience helper is promise-based, which technically means its help-functions are mostly asynchronous.

To use the WebXR Experience Helper, first Create one using the static factory:

``` javascript
const xrHelper = await WebXRExperienceHelper.CreateAsync(scene);
```

If the browser does not support XR an exception will be thrown and will you will need to catch it:

``` javascript
try {
    const xrHelper = await WebXRExperienceHelper.CreateAsync(scene);
} catch (e) {
    // no XR support
}

// or:
WebXRExperienceHelper.CreateAsync(scene).then((xrHelper) => {
    // great success
}, (error) => {
    // no xr...
})
```

### Entering XR

After initializing the XR helper, it is possible to enter an XR session, for example in immersive VR mode:

``` javascript
const sessionManager = await xrHelper.enterXRAsync("immersive-vr", "local-floor" /*, optionalRenderTarget */ );
```

To read more about session modes ( `immersive-vr` in this example), and reference type modes ( `local-floor` ), please read the [WebXR specs](https://immersive-web.github.io/webxr/). The most common scenario is VR in local floor mode, which is the one we are showing here.

If there is an error while creating the experience helper, the console will show it.

### Exiting XR

To exit, simply call the exitXRAsync function:

``` javascript
await xrHelper.exitXRAsync();
```

### Observables

#### The state observable

In this example, the session manager will be initialized if the XR session is ready to use. Alternatively, you can ignore the `await` and use the **state observable** of the xr helper:

``` javascript
xrHelper.onStateChangedObservable.add((state) => {
    switch (state) {
        case WebXRState.IN_XR:
            // XR is initialized and already submitted one frame
        case WebXRState.ENTERING_XR:
            // xr is being initialized, enter XR request was made
        case WebXRState.EXITING_XR:
            // xr exit request was made. not yet done.
        case WebXRState.NOT_IN_XR:
            // self explanatory - either our or not yet in XR
    }
})
```

#### Pose initialized observable

The `onInitialXRPoseSetObservable` will trigger all observers when the pose of the camera was set and before the first frame was rendered.

It can be used to define, for example, a height offset (if the ground is not at 0, or if the user starts in a different level):

``` javascript
xrBasicHelper.onInitialXRPoseSetObservable.add((xrCamera) => {
    // floor is at y === 2
    xrCamera.y = 2;
});
```

### Other features

The basic XR experience helper offers direct access to the following:

* An initialized [Session Manager](/divingDeeper/webXR/webXRSessionManagers)
* A configured [XR Camera](/divingDeeper/webXR/webXRCamera) that will have the non-VR camera's position when entering XR
* Initialized [Features Manager](/divingDeeper/webXR/webXRFeaturesManager)

# The WebXR Default Experience

### Basic usage of default experience

The default xr experience will:

* Create a [basic experience helper](#the-basic-experience-helper) and initialize it
* Create an HTML UI button to enter XR
* Init the input source class which will initialize controllers
* Enable the pointer selection and teleportation features

The simplest way to use the default experience is calling the help function of `scene` :

``` javascript
var defaultXRExperience = await scene.createDefaultXRExperienceAsync( /* optional configuration options */ );
```

This is equivalent to:

``` javascript
var defaultXRExperience = await WebXRDefaultExperience.CreateAsync(scene, /* optional configuration options */ )
```

After calling this and assuming the browser supports XR, you will see the Enter-XR GUI on the bottom right of the screen unless the browser **does not support XR**. The GUI will not be displayed. To check if the default experience initialized correctly, make sure the `baseExperience` variable was created:

``` javascript
var defaultXRExperience = await scene.createDefaultXRExperienceAsync( /* optional configuration options */ );
if (!defaultXRExperience.baseExperience) {
    // no xr support
} else {
    // all good, ready to go
}
```

### Configuration options

The default xr experience helper takes an options map for configuration. Everything, including the options itself is optional:

``` javascript
class WebXRDefaultExperienceOptions {
    /**
     * Floor meshes that will be used for teleporting
     */
    public floorMeshes ? : Array < AbstractMesh > ;

    /**
     * Enable or disable default UI to enter XR
     */
    public disableDefaultUI ? : boolean;

    /**
     * optional configuration for the output canvas
     */
    public outputCanvasOptions ? : WebXRManagedOutputCanvasOptions;

    /**
     * optional UI options. This can be used among other to change session mode and reference space type
     */
    public uiOptions ? : WebXREnterExitUIOptions;

    /**
     * Disable the controller mesh-loading. Can be used if you want to load your own meshes
     */
    public inputOptions ? : IWebXRInputOptions;

    /**
     * Should teleportation not initialize. defaults to false.
     */
    public disableTeleportation ? : boolean;
}
```

Check the code documentation for further details.

### Pointer selection and teleportation

The default experience initializes both pointer selection (laser pointer and interaction with the meshes in the scene) and teleportation features automatically. If floor meshes are provided in the options, the teleportation will include it when created. If not you can add meshes later or disable it.

To read more about both features, check the [Features Manager](/divingDeeper/webXR/webXRFeaturesManager)

To enable / disable the teleport and pointer selection:

``` javascript
// assuming xrHelper initialized correctly!

// disable:
defaultXRExperience.teleportation.detach();
defaultXRExperience.pointerSelection.detach();

// (re)enable:
defaultXRExperience.teleportation.attach();
defaultXRExperience.pointerSelection.attach();
```

### Configuring the GUI

The GUI is the right way to enter and exit the XR experience. Otherwise you can directly use the `baseExperience` Basic experience helper to enter and exit XR as mentioned [above](#the-basic-experience-helper). It defaults to a VR immersive session in local-floor reference mode.

If you want to change the session mode or reference mode (for example to enter an AR session instead of VR):

``` javascript
var defaultXRExperience = await scene.createDefaultXRExperienceAsync({
    uiOptions: {
        sessionMode: 'ar-immersive'
    }
});
```

Read more about the GUI in the [advanced WebXR tutorial]()

### Available Observables

Apart from those you can find in the `baseExperience` (The Basic XR experience helper) the default experience does not offer any observables.

### Further features

The default experience offers direct access to the following:

* `input` - initialized [WebXRInputSource]()
* `enterExitUI` - initialized [GUI]()
* `renderTarget` - The default WebXR render target



## Why is it needed

The Features manager, our XR plugin system, was born out of a simple need - stay backwards compatible, but still deliver cutting edge APIs in a production system.

Since APIs like [hit test](https://github.com/immersive-web/hit-test) and [anchors](https://github.com/immersive-web/anchors) are constantly changing, and currently still have different support in different browser versions, there was a need for "versioning" of the current development to keep up with API modifications over time.

If you are a bit impatient you can check the [selected WebXR features](/divingDeeper/webXR/WebXRSelectedFeatures) section, but it is recommended to at least read this section quickly.

## How to use

### Construct a new features manager

If you are using the [base WebXR experience helper](/divingDeeper/webXR/webXRExperienceHelpers) a features manager will be created for you and will be available in `xrBaseHelper.featuresManager` . If not, you only need to provide an XR session manager object to initialize a new one:

``` javascript
const fm = new FeaturesManager(xrSessionManager);
```

Note that even before creating the features manager you could call its static methods (check availability, register a new feature, etc').

### What is available

To check what feature is available, use the features manager's static `GetAvailableFeatures` function, which will return an array of strings corresponding to specific features:

``` javascript
const availableFeatures = featuresManager.GetAvailableFeatures();

// availableFeatures = ["xr-hit-test", "xr-pointer-selection", ...]
```

To find if a specific feature is available use this code:

``` javascript
const availableFeatures = featuresManager.GetAvailableFeatures();
// using indexOf, but you can use any other method - find, findIndex, in, etc'
if (availableFeatures.indexOf(WebXRFeatureName.POINTER_SELECTION)) {
    // Pointer selection is available
}
```

`WebXRFeatureName` will always contain the list of possible features.

When using ES6, make sure to import the feature you want to use, otherwise it won't be registered:

``` javascript
import {
    WebXRControllerPhysics
} from '@babylonjs/core/XR/features/WebXRControllerPhysics';

// The physics controller support will now be available and can be enabled:

fm.enableFeature(WebXRControllerPhysics.Name, "latest");
```

### Versioning

Just like any plugin system, the features are versioned numerically. The version is a number. Higher the number, the newer the version (pretty simple).

Two extra definitions available - `stable` for the latest stable version of this feature, and `latest` which is always updated with the plugin with the highest version number. Not that while `latest` will always be available, `stable` is not a must.

To get the available versions use the `GetAvailableVersions` static method. It will return an array of available versions, for example:

``` javascript
const availableVersions = featuresManager.GetAvailableVersions(WebXRFeatureName.POINTER_SELECTION);

// availableVersions = ["latest", "stable", "1", "2"];
```

This means that you can ask for version 1, but also for the stable version which will be one of the 2 - "1" or "2", depends on our definition. The "latest" version will load "2".

### Enable and disable a feature

Enabling a feature means that the feature is ready to be used in a working session. When a feature is enabled, it is ready to be attached, which technically means - influence the scene actively.

As an example, **enabling** the teleportation feature will register the "on controller added/removed" observer.**Attaching** it will register all observers required for each controller to work properly.**Detaching** it will remove this observers, and **disabling** it will make sure the meshes are invisible and the onControllerAdded (and Removed) observer will be removed.**Disposing** the feature will release everything, including all associated meshes.

To enable the feature use a constructed features manager's `enableFeature` function with the name and version you wish to load:

``` javascript
// get the features manager
const fm = xr.baseExperience.featuresManager;

// disable an already-enabled feature
fm.disableFeature(WebXRFeatureName.POINTER_SELECTION);

// enable latest hit-test
const xrHitTestLatest = fm.enableFeature(WebXRFeatureName.HIT_TEST, "latest");

// enable specific version of hit-test. This will disable an older implementation and enable the new one
const xrHitTest1 = fm.enableFeature(WebXRFeatureName.HIT_TES, 1);
```

### Configuring the feature

Every feature (as of now) has a different configuration options object that can be provided when enabling the feature. Each feature has an options interface. For example, Version 1 of Hit-Test has the following options configuration interface:

``` javascript
interface IWebXRHitTestOptions {
    /**
     * Only test when user interacted with the scene. Default - hit test every frame
     */
    testOnPointerDownOnly ? : boolean;
    /**
     * The node to use to transform the local results to world coordinates
     */
    worldParentNode ? : TransformNode;
}
```

To use it:

``` javascript
// get the features manager
const fm = xr.baseExperience.featuresManager;

// enable latest hit-test with a configuration object. Old enabled version will be disposed
const xrHitTestLatest = fm.enableFeature(WebXRFeatureName.HIT_TEST, "latest", {
    testOnPointerDownOnly: true
});

// enable specific version of hit-test with default configuration. Old config will be lost
const xrHitTest1 = fm.enableFeature(WebXRFeatureName.HIT_TES, 1);
```

### Attach and detach a feature

Once you have a feature enabled, you can use its synchronous attach and detach methods to attach (or detach) it to the scene:

``` javascript
// enable version 1 of hit-test
// Feature will be auto-attached once the session starts
const xrHitTest1 = fm.enableFeature(BABYLON.WebXRFeatureName.HIT_TEST, 1);

// detach the feature, but keep it enabled (for reattachment). This also disables auto-attach, if not already attached
xrHitTest1.detach();

// re-attach
xrHitTest1.attach();
```

Enabling a feature will attach it automatically when an XR session starts. If you want to only enable but not attach a feature (so you have full control of when it starts working), set the `attachIfPossible` variable to false (defaults to true):

``` javascript
// get the features manager
const fm = xr.baseExperience.featuresManager;
const xrHitTestLatest = fm.enableFeature(WebXRFeatureName.HIT_TEST, "latest", {
    testOnPointerDownOnly: true
}, false /* prevent attaching automatically */ );
```

## ES6 passive loader

When using the ES6 module loader you will notice that no features apart from transportation and pointer selection are available. That is because the features and their version must be imported by you. It is done so that unneeded code will not be included in the build and will be loaded only when your experience needs it. Wonderful for tree shaking!

So this won't work in ES6

``` javascript
const featuresManager = giveMeMyFeaturesManagerSomehow();
// No hit test is available is not available
const xrHitTest1 = featuresManager.enableFeature("xr-hit-test", 1);
// Error thrown, "feature not found"
```

Adding an import will make it work:

``` javascript
// other imports...
import {
    WebXRHitTestLegacy
} from "@babylonjs/core/Cameras/xr/features/WebXRHitTestLegacy";

const featuresManager = giveMeMyFeaturesManagerSomehow();
// feature will now be enabled
const xrHitTest1 = featuresManager.enableFeature(WebXRFeatureName.HIT_TEST /* Same as "xr-hit-test" */ , 1);
```

## Writing a new feature

If you want to add your own feature here are a few guidelines:

### IWebXRFeature

The feature should implement the `IWebXRFeature` interface, which looks like this:

``` javascript
interface IWebXRFeature extends IDisposable {
    /**
     * Is this feature attached
     */
    attached: boolean;
    /**
     * Should auto-attach be disabled?
     */
    disableAutoAttach: boolean;
    /**
     * Attach the feature to the session
     * Will usually be called by the features manager
     *
     * @param force should attachment be forced (even when already attached)
     * @returns true if successful.
     */
    attach(force ? : boolean): boolean;
    /**
     * Detach the feature from the session
     * Will usually be called by the features manager
     *
     * @returns true if successful.
     */
    detach(): boolean;
}
```

To ease the process, you can, instead, extend the `WebXRAbstractFeature` , which has a few extra help-functions and implements most functions needed for a working feature.

After creating the feature, you will need to register it with the features manager, so it can be enabled.

To register it, use the static `AddWebXRFeature` function:

``` javascript
const nameOfFeature = "awesome-name";
const version = 1;
const isTheFeatureStable = true
WebXRFeaturesManager.AddWebXRFeature(nameOfFeature, (xrSessionManager, options) => {
    return () => new MyNewFeature(xrSessionManager, options);
}, version, isTheFeatureStable);
```

This way you can enable the feature using its name whenever you wish to use it.


One of the major differences between WebVR and WebXR was the support for different types of controllers. While WebVR supported the non-standard extended gamepad API and a few selected controllers, WebXR already supports a lot of different types of inputs, including touch screens, motion controllers and hands.

## Some terms and classes to clear things up

An XR controller comprises a lot of components that we at babylon sometimes name differently. It is also important to know the terms themselves to be able to use what you actually need. I would recommend reading the [XR Input section](https://www.w3.org/TR/webxr/#input) of the WebXR proposal draft.

An XR Session controls the input source of the current session. Every new input source connected to this session will be registered in the **inputSources** array of the native XR Session and will also trigger the `inputsourceschange` event with the new input source.

An Input source has one of three target Ray modes - `tracked-pointer` for gamepad-like controllers, `screen` for touch-screen oriented inputs, and `gaze` for gaze-based inputs (input sources like google cardboard that has no proper way for user input).

The [WebXRInput](/typedoc/classes/babylon.webxrinput) class is responsible of coordinating the addition and removal of input sources. It creates **WebXR Input Sources** classes and disposes them automatically for you.

Babylon's [WebXR Input Source](/typedoc/classes/babylon.webxrinputsource) class is the container for all user-input related objects. It is created automatically for you by the WebXR Input class for every controller.it is in charge of attaching the motion controller, which, in turn, is in charge of attaching the components and load the model.

An input source has two important reference spaces - one it the **`targetRay`** which represents the pointer's position and direction. Think - the edge of your finger.and the **`gripSpace`** which is the base of a handheld device connected to this input source. Think - the base of your hand. The `gripSpace` is optional and is only available when a motion controller is connected. And, althou sometimes the same, the grip and target ray space can have different transformation altogether.

A controller has an attached **motion controller** if the input source is a gamepad-like device (the oculus touch or the windows motion controllers are a good example for that). In turn, each controller has different **components** (buttons, triggers, thumbpads, touchpads) which have their state updated on each frame.

Note that input sources like of type `screen` are constantly created and removed when touch starts and end. This is called a transient input in the documentation.

## WebXRInput

The WebXR Input, initialized usually by the WebXR Experience Helper has little to no public members and is, in general, a standalone class that you won't interact with. However, it does have two observables that can be helpful for your experience:

### onControllerAddedObservable

This observable will be triggered when a new input source was detected and its corresponding WebXRInputSource class was created.

### onControllerRemovedObservable

Will be triggered when a controller left the experience, right before it is disposed.

## WebXRInputSource

The input source, created by the WebXR input, is your central container for a single input source (or controller). It has a few important members that will allow you to controller your input source.

## Public members

As mentioned before the Input source has two reference spaces - `grip` and `target` , which we call `pointer` . Both of those spaces are represented by a mesh, positioned in the orientation and position that is provided by the XRFrame (and the XR session). Which means that if you want to query the current transformation of the user's hand or the direction the user is pointing at.

To do that you can use the `getWorldPointerRayToRef` function:

``` javascript
const resultRay = new BABYLON.Ray();

// get the pointer direction
xrInputSource.getWorldPointerRayToRef(resultRay);
// get the grip direction, if available. If not, the pointer:
xrInputSource.getWorldPointerRayToRef(resultRay, true);
```

Usually, you would need to pointer direction ray.

### Input source observables

#### onMotionControllerInitObservable

This will be triggered when a motion controller, if available was initialized and its profile loaded.

#### onMeshLoadedObservable

This is a helper observable and is the same as `xrController.motionController.onModelLoadedObservable` . But since the motion controller is created async, using the motionController observable will only be available after `onMotionControllerInitObservable` was triggered:

``` javascript
// async, async, async
xrInput.onControllerAddedObservable.add((inputSource) => {
    inputSource.onMotionControllerInitObservable.add((motionController) => {
        motionController.onModelLoadedObservable.add((model) => {

        });
    });
});

// a little cleaner
xrInput.onControllerAddedObservable.add((inputSource) => {
    inputSource.onModelLoadedObservable.add((model) => {});
});
```

#### onDisposeObservable

Will be triggered right at the end of the `dispose()` function of the input source.

## Motion controllers

In most cases when starting a VR session, the user will have handheld devices, called here motion controllers. A motion controller will be automatically loaded, if available. A motion controller has a profile, containing its different components and their positions in the buttons and axes array, but babylon takes care of this for you so you don't have to know this to interact with the motion controller. You can see the different profiles in the [WebXR Input Profiles repository](https://github.com/immersive-web/webxr-input-profiles)

### Controller components

Each motion controller has different components, that are described in its profile. Each component has one of the types:

* Button
* Trigger
* Squeeze
* Thumbstick
* Touchpad

It also has a **unique** component id, which correlates to the actual component. For example, the **A button** on the oculus touch has the **type** `button` , and the **id** `a-button` .

#### Get the components available

To get a list of the components available, use the `getComponentIds` function. This will return an array of strings containing the IDs of the different components in this motion controller:

``` javascript
const ids = motionController.getComponentIds();
// ids = ["a-button", "b-button", "xr-standard-trigger", .....]
```

You can also get all of the available components using the `components` public member of the Motion Controller class. It is a map of all `WebXRControllerComponent` elements in this motion controller.

#### Get components

To get a component you need to either know its ID or type. When more than one of that type exists, the id would be better.
The IDs can be found in the profile.

To get a component according to its ID:

``` javascript
const triggerComponent = motionController.getComponent("xr-standard-trigger");
if (triggerComponent) {
    // found, do something with it.
}
```

To get a component of a specific type:

``` javascript
const squeezeComponent = motionController.getComponentOfType("squeeze");

// get the first registered button component
const buttonComponent = motionController.getComponentOfType("button");
```

to get all components of a specific type:

``` javascript
// get all button components
const buttonComponents = motionController.getAllComponentsOfType("button");
if (buttonComponents.length) {
    // some were found
}
```

#### The main component

Each controller has a main component, defined by the vendor. In most cases it is the trigger component type that is the main component. To get the main component (as defined in the profile):

``` javascript
const mainComponent = motionController.getMainComponent();
// mainComponent always exists!
```

#### Events and changes of a controller component

A component is updated on each frame with values provided by the gamepad object of the session's input source. Each button has 2 states - `touched` and `pressed` , and a value from 0 to 1 (0 being not pressed at all, 1 being fully pressed). Some components can only have the values 0 and 1 (like the button component).

Some types of components also have axes values (like a thumbstick or touchpad). The axes have values from -1 to 1.
1 in the X-axis means right, and 1 in the Y-Axis means down (towards the user).

To know what the components supports:

``` javascript
if (component.isButton()) {
    // we have a value
}
if (component.isAxes()) {
    // we have axes data
}
```

To get the component values at the current frame:

``` javascript
let value = component.value;
if (value > 0.8) {
    // do something nice with this value
}
if (component.pressed) {
    // the component is pressed, meaning value === 1
}

if (component.touched) {
    // fingers are on the component, might be half-pressed or moved
}
```

To access the axes data:

``` javascript
let axes = component.axes;
if (axes.x > 0.8) {
    // do something nice with the x-axis value
}
```

The component can also return the changes compared to the last frame. Changes are only populated when they exist, otherwise the changes map will be empty:

``` javascript
// maybe nothing happened between this and last frame
if (!component.hasChanges) {
    return;
}
let changes = component.changes;
if (changes.pressed) {
    // pressed state changed
    const isPressedNow = changes.pressed.current;
    const wasPressedInLastFrame = changes.pressed.previous;
}
if (changes.value) {
    // value changed! let's get the delta
    const delta - changes.value.current - changes.value.previous;
}
```

The components have two observables that can be used to fetch changes (and avoid checking value changes on each frame):

``` javascript
component.onButtonStateChangedObservable.add((component) => {
    // something changed, check the changes object
});

component.onAxisValueChangedObservable.add((values) => {
    console.log(values.x, values.y);
})
```

### How to get a model

#### The input-profile online repository

As part of the (successful!) attempt at forcing standards to WebXR, the guys at the [WebXR Input Profiles](https://github.com/immersive-web/webxr-input-profiles) github repository created an online repository that holds models and definition of visual reference definitions for most (if not all) motion controllers available today.

Babylon.js natively supports this repository and currently uses it as the default model delivery method for XR controllers.

There is little to no action required on your end - this is automated when not changing the configuration.

#### Babylon local controller definitions

Before the input-profile repository was published, Babylon had support for different types of controllers - Occulus Touch (1 and 2), Vive, Windows Motion Controllers and more. Since we still wanted to offer local support for those devices, we have decided to not only relay on the online profile repository, but to also deliver babylon-based controller classes for those that are already developed.

Babylon offers local definitions for the following:

* Windows Motion Controllers
* Oculus touch 1 and 2
* Vive
* Generic-Button controller

To use them, import them to your project, while not forgetting to prioritize them or disable the online repository:

``` javascript
// import the ones you want to use
import {
    WebXRMicrosoftMixedRealityController
} from '@babylonjs/core/XR/motionController/webXRMicrosoftMixedRealityController';

// prioritize the local classes (but use online if controller not found)
WebXRMotionControllerManager.PrioritizeOnlineRepository = false;
// or disable the online repository
WebXRMotionControllerManager.UseOnlineRepository = false;

// now, if loading a microsoft motion controller it will use the local class
```


Babylon's [WebXRSessionManager](/typedoc/classes/babylon.webxrsessionmanager) class is your direct contact to the browser's native XR session. Each XR experience has a corresponding session that holds the entire XR functionality. A session is initialized with a session mode (the default is `vr-immersive` ) and a reference space mode (default is `local-floor` ) that decides how the scene calculates the user's location and what functionality is available.

Usually, the Session Manager will be initialized by the [experience helper](/divingDeeper/webXR/webXRExperienceHelpers), but if you don't use the experience helper, you can create a session manger yourself. The session manager, along with the XR camera, are the only requirement on babylon's side to implement an XR experience.

## Basic usage and initialization

To construct a new session manager, initialize it with a babylon scene:

``` javascript
const sessionManager = new WebXRSessionManager(scene);
```

The session manager is now ready and can be initialized to be used with XR.

Before activating the session, you can check if XR is available and the session mode is supported by the browser.

You can do this using the static function `IsSessionSupportedAsync` or the `isSessionSupportedAsync` function of the session manager itself:

``` javascript
// Static:
const supported = await WebXRSessionManager.IsSessionSupportedAsync('immersive-vr');
if (supported) {
    // xr available, session supported
}

// or:

const supported = await sessionManager.isSessionSupportedAsync('immersive-vr');
if (supported) {
    // xr available, session supported
}
```

After making sure XR is available and the session is supported, you can initialize the session and prepare it for rendering:

``` javascript
sessionManager.initializeSessionAsync('immersive-vr' /*, xrSessionInit */ );
```

This function will initialize the native session. Without calling this function, no session is available and the XR experience will not work.

Right after you will need to initialize the reference space of this session, which will define the coordinate system the xr experience will use:

``` javascript
const referenceSpace = sessionManager.setReferenceSpaceAsync( /*referenceSpaceType = 'local-floor'*/ );
```

The only thing that is left right now is to prepare the render target and the [XR WebGL Layer](https://developer.mozilla.org/en-US/docs/Web/API/XRWebGLLayer):

``` javascript
const renderTarget = sessionManager.getWebXRRenderTarget( /*outputCanvasOptions: WebXRManagedOutputCanvasOptions*/ );
const xrWebGLLayer = renderTarget.initializeXRLayerAsync(this.sessionManager.session);
```

The session manager is now ready to render the scene using the XR session.

## Start rendering

To start rendering the scene use the `runXRRenderLoop` :

``` javascript
sessionManager.runXRRenderLoop();
```

The scene will now render to the XR Device instead of the browser canvas.

To stop rendering, end the session:

``` javascript
await sessionManager.exitXRAsync();
```

## Reference Space management

### Managing yourself

WebXR coordinate system is based on a reference space object, that defines the user's current transformation in the scene. This object calculates the current HUD and controllers transformation, and is also required for all AR features.

Babylon manages the reference space changes for you when you use the teleportation so you don't have to deal with it yourself. If, however, you wish to access and change the reference space on your own, you have full access to three reference space objects that will help you:

1. `xrSession.referenceSpace` is the current reference space, the one being used to render the scene.
2. `xrSession.baseReferenceSpace` is the initial reference space generated using the `ReferenceSpaceMode` you chose (like `local-floor` ).
3. `xrSession.viewerReferenceSpace` is the initial reference space in the `viewer` reference space mode, compensated with the `defaultHeightCompensation` value.

Using the `getOffsetReferenceSpace` function on the Reference Space object you can change the reference space yourself. Don't forget to update the new reference space in the session manager, otherwise it will not be used in the current scene:

``` javascript
// move the player 2 units (meters) up:

// height change - move the reference space negative 2 units (up two units):
const heightChange = new XRRigidTransform({
    x: 0,
    y: -2,
    z: 0
});
// get a new reference space object using the current reference space
const newReferenceSpace = xrSession.referenceSpace.getOffsetReferenceSpace(heightChange);
// update the session manager to start using the new space:
xrSession.referenceSpace = newReferenceSpace;
```

Read more about [`getOffsetReferenceSpace`](https://www.w3.org/TR/webxr/#dom-xrreferencespace-getoffsetreferencespace).

### Using a new reference space mode

To get a reference space object using a different `XRReferenceSpaceType` , use the `xrSession.setReferenceSpaceTypeAsync` with the requested reference space type. This will reset the viewer and base reference space as well. This function accepts a new reference mode and is promise based:

``` javascript
// Session was created using the `local` reference space mode, let's move to `local-floor` :
const newReferenceSpace = await xrSession.setReferenceSpaceTypeAsync('local-floor');

// The session will take care of updating all reference space objects (base, viewer, and the current one).
```

## Observables available

### onXRFrameObservable

Observers registered here will be triggered on each XR frame rendered. Can be compared to the `beforeRender` of the scene, but executed only when the scene is rendered in XR.

### onXRSessionInit

Will be triggered when the session was initialized, before a frame was rendered and before any transformation was applied.
In XR terms, this is called right after `requestSession` was called and returned with a successful result (a new XRSession).

### onXRSessionEnded

Will be triggered after the XRSession has ended and Babylon finished with clean-ups. It is triggered one frame before the regular scene render function is triggered.

### onXRReferenceSpaceChanged

 Will be triggered every time a new reference space was applied to the current scene. This is a good way of finding our if the user transported to a new location.

## Further functionalities

### Manually start rendering the XR session

When creating the experience yourself and not using the [WebXR Experience helper](/divingDeeper/webXR/webXRExperienceHelpers) you will need to tell the session manager to start rendering. To do that, call the `runXRRenderLoop` function.

The `runXRRenderLoop` will update the render function with the required XR rendering mechanism and run the engine's render loop.

Note that the FPS rate will probably change, as most if not all XR devices render in more than 60 FPS.



## Concepts

Tag? You may already have heard or read this word before. Let's see some generic concepts.

### Tags are used:

- as an index term assigned to a piece of information
- to pass parameters to subroutines
- as components of the HTML markup language
- as labels for specific revisions of a project
- as unique identifiers in URI
- as links to other Facebook pages
...

(from [Wikipedia](http://en.wikipedia.org/wiki/Tag))

### Tags on forums / Categories

If you spend some time on forums (let's pick one randomly: [forum](https://forum.babylonjs.com) ;)), you may have noticed that tags are attached to topics (and/or posts sometimes).
The author can write words (tags) to shortly describe his/her topic without having to write a gramatically correct sentence. It's kind of a list of words that you could say during a brainstorming after reading the post.

Thus, if you need information about, let's say, meshes, you can search for topics having "mesh" as a word in those topics, BUT you could also search for "mesh" as a tag of the topic. Indeed, maybe the word is never used in the topic (maybe it's only used, or not, in the title) but the author can choose to add it as a tag in the aim to categorize his/her topic.
Tags can be used to categorize/group things.

### CSS classes

OK...? What's the link with tags? Why are we about to talk about CSS classes?

Because CSS classes are great and Tags in Babylon.js can be considered similar, in principle, to CSS classes. So let's talk about them.

CSS stands for Cascading Style Sheets. It's used to define how to display HTML elements.

CSS classes are added to HTML elements (by writing them directly in the HTML code or by adding them via javascript) as a value of the ```class``` attribute of the corresponding HTML elements.

HTML elements can have several CSS classes in their ```class``` attribute and the same CSS class can be used on different HTML elements. CSS classes, just like tags on forums, can then be used to categorize HTML elements. Thus, a same style (background, font, color...) can easily be applied to a group of HTML elements identified by a CSS class (or a list of CSS classes).

_Style for all HTML elements of the page having the "center" class on them (to find elements with a specific class, write a period character, followed by the name of the class)_

```css
.center
{
    text-align: center;
    color: red;
}
```

Thanks to javascript, you can even retrieve all these elements and then do further javascript operations on them (jQuery plugins largely use CSS classes).

```javascript
var elements = document.getElementsByClassName(".center");
```

The above directive would gather a collection of all HTML elements that use the .center class.

Here we are! **Tags in babylon.js can be used to categorize/group elements, and helper functions are provided to retrieve/gather tagged elements.**

## Integration to babylon.js

Tags were integrated into babylon.js on April 7, 2014. [Pull request](https://github.com/BabylonJS/Babylon.js/pull/170#event-109351015)

There was a [discussion](https://www.html5gamedevs.com/topic/4961-user-data-in-mesh-object/?p=30458) about adding this feature on the forum. The goal was to be able to retrieve meshes.

### Pure javascript

The concept was expanded to allow the adding of tags on any javascript object (not necessarily only the objects created by babylon.js). The ```Tag``` class that has been added to babylon.js contains all the necessary code for this generic concept ([Typescript code](https://github.com/BabylonJS/Babylon.js/blob/master/src/Misc/tags.ts)) and internally uses the ```AndOrNotEvaluator``` class ([Typescript code](https://github.com/BabylonJS/Babylon.js/blob/master/Babylon/Tools/babylon.andOrNotEvaluator.ts)).

The use of tags for a javascript object can be enabled/disabled like this (javascript code):

```javascript
var myJSObj = {};
// enable tags for myJSObj
BABYLON.Tags.EnableFor(myJSObj);

// disable tags for myJSObj
BABYLON.Tags.DisableFor(myJSObj);
```

```EnableFor``` adds functions to the javascript object in the aim to:
*  test if it has tags ```hasTags```
*  add tags to it ```addTags```
*  remove tags from it ```removesTags```
*  test if it matches a tags query ```matchesTagsQuery``` (see below)

Those functions are proxies of static methods of ```Tags``` (```HasTags```, ```AddTagsTo```, ```RemoveTagsFrom``` and ```MatchesQuery```).

```Tags``` also contains ```GetTags``` which retrieves the array of tags of the javascript object.

Remark: Tags.AddTagsTo enables tags for the object if needed

```javascript
var myJSObj1 = {};
// enable tags for myJSObj1
BABYLON.Tags.EnableFor(myJSObj);// => addTags is available on myJSObj1
// add tags to myJSObj1
myJSObj1.addTags("tag1 tag2"); // same as BABYLON.Tags.AddTagsTo(myJSObj1, "tag1 tag2"),

var myJSObj2 = {};
// add tags to myJSObj2 without having to enable tags for it first
BABYLON.Tags.AddTagsTo(myJSObj2, "tag1 tag2"); // addTags couldn't be used on myJSObj2 since tags were not previously enabled for myJSObj2
```

Tags query:

```Tags.MatchesQuery``` (and ```matchesTagsQuery``` if tags are enabled for the javascript object) accepts a list of correct tags (see "Rules to respect") containing parenthesis, and boolean evaluators such as ```(tag1 && (tag2 || tag4 || !tag5)) || !(!tag1) && !!!tag5```. The tags query is evaluated thanks to ```AndOrNotEvaluator```.

Full example:

```javascript
var myJSObj1 = {};
BABYLON.Tags.AddTagsTo(myJSObj1, "tag1 tag2");

var myJSObj2 = {};
BABYLON.Tags.AddTagsTo(myJSObj2, "tag3 tag4 tag5");

var myJSObj3 = {};
BABYLON.Tags.EnableFor(myJSObj3);

var myJSObj4 = {};

myJSObj4.hasTags(); // TypeError: undefined is not a function
BABYLON.Tags.HasTags(myJSObj4); // false

myJSObj3.hasTags(); // false
BABYLON.Tags.HasTags(myJSObj3); // false

myJSObj2.hasTags(); // true
myJSObj1.hasTags(); // true

myJSObj1.matchesTagsQuery("tag1"); // true
myJSObj1.matchesTagsQuery("tag2"); // true
myJSObj1.matchesTagsQuery("tag1 || tag2"); // true
myJSObj1.matchesTagsQuery("tag1 && tag2"); // true
myJSObj1.matchesTagsQuery("tag3"); // false
myJSObj1.matchesTagsQuery("!tag3"); // true
myJSObj1.matchesTagsQuery("tag1 && tag3"); // false
myJSObj1.matchesTagsQuery("tag1 || tag3"); // true
myJSObj1.matchesTagsQuery("tag1 && !tag3"); // true

myJSObj1.removeTags("tag1");

myJSObj1.matchesTagsQuery("tag1 && !tag3"); // false

myJSObj2.removeTags("tag4 tag3 tag5");

myJSObj2.hasTags(); // false

BABYLON.Tags.DisableFor(myJSObj2);

myJSObj2.hasTags(); // TypeError: undefined is not a function

myJSObj3.matchesTagsQuery(""); // false
myJSObj3.matchesTagsQuery(); // true

myJSObj4.matchesTagsQuery(""); // TypeError: undefined is not a function
myJSObj4.matchesTagsQuery(); // TypeError: undefined is not a function

BABYLON.Tags.MatchesQuery(myJSObj4, ""); // false
BABYLON.Tags.MatchesQuery(myJSObj4, undefined); // true
BABYLON.Tags.MatchesQuery(myJSObj4); // true
```

### Rules to respect

* the tags "true" and "false" are reserved and cannot be used as tags.
* a tag cannot start with "||", "&&", or '!'
* a tag cannot contain whitespaces

### Use in babylon.js

Since it's possible to use tags on any javascript object and since meshes are javascript objects, it's possible to add tags on them and to retrieve them according to a tags query.

```javascript
var meshes = myScene.getMeshesByTags("tag1 && (tag2 || tag4 || !tag5)) || !(!tag1) && !!!tag5");
```

All tags added to meshes, cameras, lights... are saved to the scene files (see [.babylon file format](/advanced_topics/.babylonFileFormat) and reloaded from them.

## What to do with them?

It's up to you!

You can use them to retrieve all the meshes that should be lighted by the light "light1":

```javascript
var meshesToLightByLight1 = myScene.getMeshesByTags("mustBeLightedByLight1");
```

or make some green ghosts appear when you want:

```javascript
var ghosts = myScene.getMeshesByTags("ghost && green");

for(var index=0; index < ghosts.length; index++) {
    ghosts[index].isVisible = true;
}
```

WebXR

Coming next

WebXR

Learn about creating immersive web experineces with WebXR in Babylon.js.

WebXR Selected Features

Learn about key WebXR features in Babylon.js.

WebXR Experience Helpers

Learn about WebXR experience helpers in Babylon.js.

WebXR Session Manager

Learn all about the WebXR session manager in Babylon.js.

The WebXR Camera

Learn all about the WebXR camera in Babylon.js.

WebXR Features Manager

Learn all about the powerful WebXR features manager in Babylon.js.

WebXR Demos and Examples

Check out a series of WebXR demos and examples in Babylon.js.

WebXR Controllers Support

Learn about the robust library of WebXR controllers and input supported in Babylon.js.

WebXR Augmented Reality Features

Learn about WebXR augmented reality features in Babylon.js.