
## Body Tracking

Some XR devices can track the full pose of the user's body — not just their hands and head — and expose that data via the [WebXR Body Tracking specification](https://immersive-web.github.io/body-tracking/). Babylon.js provides a `WebXRBodyTracking` feature that consumes this data and, optionally, uses it to drive a rigged humanoid mesh so users can see their own avatar move with them in real time.

Up to **83 body joints** are tracked each frame, covering the full skeleton from the hips and spine up through the head, arms, and hands, and down through the legs and feet.

<Playground id="#0FOISU#2" title="WebXR Body Tracking" description="Full-body avatar driven by WebXR body tracking data" />

### Device and browser support

Body tracking is currently available on:

- **Meta Quest** devices (Quest 2, Quest Pro, Quest 3, Quest 3S) using the Meta Quest Browser.

Check the [WebXR Body Tracking specification](https://immersive-web.github.io/body-tracking/) for the latest platform support information. The feature degrades gracefully — if the runtime does not provide body data, the feature stays inactive and fires no errors.

### Getting started

Enable the feature on the features manager after creating the default XR experience:

```javascript
const xr = await scene.createDefaultXRExperienceAsync();

const bodyTracking = xr.baseExperience.featuresManager.enableFeature(
  BABYLON.WebXRFeatureName.BODY_TRACKING,
  "latest",
  {
    // optional: attach a rigged body mesh immediately
    bodyMesh: myRiggedMesh,
  }
);
```

At this point the feature creates 83 `TransformNode` objects (one per joint) and updates them every frame with the poses reported by the XR runtime. If you provided a `bodyMesh` with a skeleton, the skeleton bones are automatically linked to those transform nodes, so the mesh animates with the user.

### The 83 tracked body joints

The joints correspond to the names defined by the [WebXR Body Tracking spec](https://immersive-web.github.io/body-tracking/#xrbody-interface). They are exposed as the `WebXRBodyJoint` string enum:

| Group | Joints |
|---|---|
| **Torso / Spine** | `hips`, `spine-lower`, `spine-middle`, `spine-upper`, `chest`, `neck`, `head` |
| **Left Arm** | `left-shoulder`, `left-scapula`, `left-arm-upper`, `left-arm-lower`, `left-hand-wrist-twist` |
| **Right Arm** | `right-shoulder`, `right-scapula`, `right-arm-upper`, `right-arm-lower`, `right-hand-wrist-twist` |
| **Left Hand** | `left-hand-palm`, `left-hand-wrist`, plus all 5 fingers (metacarpal → tip) |
| **Right Hand** | `right-hand-palm`, `right-hand-wrist`, plus all 5 fingers (metacarpal → tip) |
| **Left Leg** | `left-upper-leg`, `left-lower-leg`, `left-foot-ankle-twist`, `left-foot-ankle`, `left-foot-subtalar`, `left-foot-transverse`, `left-foot-ball` |
| **Right Leg** | `right-upper-leg`, `right-lower-leg`, `right-foot-ankle-twist`, `right-foot-ankle`, `right-foot-subtalar`, `right-foot-transverse`, `right-foot-ball` |

You can iterate over the complete ordered list with `WebXRBodyTracking.AllBodyJoints`.

### Observables

The feature exposes three observables for reacting to body tracking events:

```javascript
// Fired once when the runtime first delivers valid body data.
bodyTracking.onBodyTrackingStartedObservable.add((trackedBody) => {
  console.log("Body tracking started!");
});

// Fired every frame while body tracking is active.
bodyTracking.onBodyTrackingFrameUpdateObservable.add((trackedBody) => {
  // All joint TransformNodes are already up-to-date at this point.
  const hipsTransform = trackedBody.getJointTransform(BABYLON.WebXRBodyJoint.HIPS);
  console.log("Hips position:", hipsTransform.position);
});

// Fired when the runtime stops delivering body data.
bodyTracking.onBodyTrackingEndedObservable.add(() => {
  console.log("Body tracking lost.");
});
```

Use `bodyTracking.isTracking` to poll the current tracking state without subscribing to an observable.

### Accessing joint data

The `WebXRTrackedBody` object (received from the observables above, or via `bodyTracking.trackedBody`) provides helpers for reading individual joints or whole body parts:

```javascript
// Get the TransformNode for a single joint.
const headTransform = trackedBody.getJointTransform(BABYLON.WebXRBodyJoint.HEAD);

// Get all TransformNodes for one body part.
const leftArmTransforms = trackedBody.getBodyPartTransforms(BABYLON.BodyPart.LEFT_ARM);

// Or iterate the raw array (index matches WebXRBodyTracking.AllBodyJoints order).
const allTransforms = trackedBody.jointTransforms;
```

The available `BodyPart` values are: `TORSO`, `LEFT_ARM`, `RIGHT_ARM`, `LEFT_HAND`, `RIGHT_HAND`, `LEFT_LEG`, `RIGHT_LEG`.

### Attaching a rigged body mesh

Any humanoid mesh with a skeleton can be driven by body tracking. You tell the feature how to map the 83 XR joint names to your skeleton's bone names using a **rig mapping** object.

#### Mixamo models

For meshes exported from [Mixamo](https://www.mixamo.com/) (the most common source for humanoid characters), use the built-in `isMixamoModel` shortcut:

```javascript
const bodyTracking = xr.baseExperience.featuresManager.enableFeature(
  BABYLON.WebXRFeatureName.BODY_TRACKING,
  "latest",
  {
    bodyMesh: myMixamoMesh,
    isMixamoModel: true,
  }
);
```

Setting `isMixamoModel: true` automatically:
- Applies the built-in `MixamoRigMapping` (which covers hips, spine, head, shoulders, arms, legs, and feet).
- Enables `useBoneOrientationOffsets` for cleaner retargeting of the torso and wrist joints.
- Detects and handles the `mixamorig:` bone-name prefix automatically, so the same setting works for both prefixed and un-prefixed Mixamo exports.

#### Custom rig mapping

For other skeletons, supply a `rigMapping` object whose keys are `WebXRBodyJoint` names and whose values are the corresponding bone names in your skeleton:

```javascript
const bodyTracking = xr.baseExperience.featuresManager.enableFeature(
  BABYLON.WebXRFeatureName.BODY_TRACKING,
  "latest",
  {
    bodyMesh: myMesh,
    rigMapping: {
      "hips": "Bip01_Pelvis",
      "spine-lower": "Bip01_Spine",
      "spine-upper": "Bip01_Spine2",
      "neck": "Bip01_Neck",
      "head": "Bip01_Head",
      "left-shoulder": "Bip01_L_Clavicle",
      "left-arm-upper": "Bip01_L_UpperArm",
      "left-arm-lower": "Bip01_L_Forearm",
      "left-hand-wrist": "Bip01_L_Hand",
      "right-shoulder": "Bip01_R_Clavicle",
      "right-arm-upper": "Bip01_R_UpperArm",
      "right-arm-lower": "Bip01_R_Forearm",
      "right-hand-wrist": "Bip01_R_Hand",
      "left-upper-leg": "Bip01_L_Thigh",
      "left-lower-leg": "Bip01_L_Calf",
      "left-foot-ankle": "Bip01_L_Foot",
      "right-upper-leg": "Bip01_R_Thigh",
      "right-lower-leg": "Bip01_R_Calf",
      "right-foot-ankle": "Bip01_R_Foot",
      // … add more joints as needed
    },
  }
);
```

You do not need to map every joint — only the bones you want to animate.

#### Attaching a mesh after the feature is enabled

You can attach (or replace) a body mesh at any time with the `setBodyMesh` method:

```javascript
// Load a mesh later and attach it to the running feature.
const result = await BABYLON.SceneLoader.ImportMeshAsync("", "/models/", "avatar.glb", scene);
const avatarMesh = result.meshes[0];

bodyTracking.setBodyMesh(avatarMesh, {
  "hips": "Hips",
  // … rest of mapping …
});
```

The `onBodyMeshSetObservable` fires whenever a mesh is attached this way.

### Configuration options

All options are passed in the third argument to `enableFeature`:

| Option | Type | Default | Description |
|---|---|---|---|
| `bodyMesh` | `AbstractMesh` | — | A rigged body mesh to drive with tracked joint poses. |
| `rigMapping` | `XRBodyMeshRigMapping` | — | Maps each `WebXRBodyJoint` name to a bone name in the mesh skeleton. |
| `isMixamoModel` | `boolean` | `false` | Apply the built-in Mixamo mapping and sensible defaults automatically. |
| `jointScaleFactor` | `number` | `1.0` | Uniformly scales local joint offsets to fit avatars of different proportions. Values > 1 stretch the skeleton; values < 1 compress it. Does not affect the root (hips) position. |
| `preserveBindPoseBonePositions` | `boolean` | `false` | When `true`, mapped bones keep their bind-pose local translations and only rotations are retargeted. Useful for driving avatar rigs that have different proportions from the user without distorting segment lengths. |
| `useBoneOrientationOffsets` | `boolean` | `false` | Applies a per-bone orientation correction using each bone's bind-space child axis direction, compensating for rigs whose local axes don't match the XR joint convention. Automatically enabled when `isMixamoModel` is `true`. |
| `aimChildOverrides` | `Partial<Record<WebXRBodyJoint, WebXRBodyJoint>>` | — | Per-joint override of the "aim child" joint used when `useBoneOrientationOffsets` is enabled. Redirect noisy short segments (e.g. the very short hips→spine-lower segment) to a farther, more stable joint. |
| `jointLocalRotationOffset` | `Quaternion` | — | A rotation applied in each tracked joint's local frame before retargeting, for runtimes that emit joint data with non-standard axis conventions. |

#### Example: fitting an oversized avatar

```javascript
xr.baseExperience.featuresManager.enableFeature(
  BABYLON.WebXRFeatureName.BODY_TRACKING,
  "latest",
  {
    bodyMesh: giantAvatarMesh,
    isMixamoModel: true,
    preserveBindPoseBonePositions: true, // keep the avatar's own bone lengths
    jointScaleFactor: 1.5,              // stretch root offsets to match a taller user
  }
);
```

#### Example: adjusting the scale at runtime

The `jointScaleFactor` can also be changed at any time after the feature is enabled:

```javascript
// Make the skeleton larger dynamically
bodyTracking.trackedBody.jointScaleFactor = 1.2;
```

### Coordinate system

WebXR delivers body pose data in a **right-handed** coordinate system. Babylon.js defaults to **left-handed**. The `WebXRBodyTracking` feature handles this conversion automatically:

- Joint matrices are converted in-place (Z-axis negation) before being written to the `TransformNode`s.
- For meshes authored in a right-handed tool (glTF, Blender exports), bone data is un-flipped so the skeleton interprets poses correctly.
- If you have set `scene.useRightHandedSystem = true`, no conversion is applied.

You do not need to do anything special — this is handled transparently.

### Further reading

- [WebXR Body Tracking Specification](https://immersive-web.github.io/body-tracking/)
- [WebXR Hand Tracking](/features/featuresDeepDive/webXR/WebXRSelectedFeatures/WebXRHandTracking)
- [WebXR Features Manager](/features/featuresDeepDive/webXR/webXRFeaturesManager)
- [Source code: WebXRBodyTracking.ts](https://github.com/BabylonJS/Babylon.js/blob/master/packages/dev/core/src/XR/features/WebXRBodyTracking.ts)



## Hand tracking

Some devices and browsers support tracking hand joints directly, with no need for external controllers. These include Oculus Quest 1 and 2 using the native Oculus browser.

Twenty-five points on each hand are tracked and delivered on each frame. Babylon's hand-tracking feature uses this information to constantly update the WebXRHand object and the transforms of its 25 children.

Please note that when referring to "hands" on this page, we are referring to the actual handedness of the user, not to a left-handed versus right-handed system. WebXR is right-handed by nature.

### Getting started

To get started, you will first need a supported device.

Starting with version 6.40.0, hand support is enabled by default, if supported, when using the default experience helper. To configure it, pass the details when initializing the experience helper:

```javascript
const xrHelper = scene.createDefaultXRExperienceAsync({
  handSupportOptions: {
    // options you want to change
  },
});
```

To enable hand support in older versions (or to change the configuration), enable the WebXR feature:

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
  // other options
});
```

This will enable basic hand support: 25 hidden spheres will be created for each hand, and each hand will have the default hand mesh loaded and enabled:

![BabylonJS WebXR Hand tracking mesh](/img/how_to/xr/xrHandTrackingMesh.webp)

### Configuration Options

The current options for the plugin can always be found at the [WebXR hand tracking feature source code](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/XR/features/WebXRHandTracking.ts#L31). Most of them will be explained later.

### Hand meshes

Babylon's default hand meshes are enabled by default. You can disable them entirely, or provide different ones.

To disable them, use the `disableDefaultHandMesh` flag when creating the feature:

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
  jointMeshes: {
    disableDefaultHandMesh: true,
  },
});
```

This will disable mesh loading and show the 25 points (25 spheres per hand by default):

![BabylonJS WebXR Hand tracking spheres](/img/how_to/xr/handTrackingSpheres.webp)

If you want to provide different hand meshes (for example, if you want your users to wear gloves), it is recommended that you start with the current RHS (right-handed system) hand meshes from the [hand meshes](https://github.com/BabylonJS/Assets/tree/master/meshes/HandMeshes) assets directory and modify them. Otherwise, you will need to create your own skeleton/bones and weight the skin correctly.

Once you are done creating them, you will need two important objects per hand. The first is the actual mesh for each hand. The other is the mapping between the native XR tracked joints and the bones in your model. It is a structured array of bone names as strings, sorted according to the XR joint mapping. The default one is this:

```javascript
this._rigMapping = [
  "wrist_",
  "thumb_metacarpal_",
  "thumb_proxPhalanx_",
  "thumb_distPhalanx_",
  "thumb_tip_",
  "index_metacarpal_",
  "index_proxPhalanx_",
  "index_intPhalanx_",
  "index_distPhalanx_",
  "index_tip_",
  "middle_metacarpal_",
  "middle_proxPhalanx_",
  "middle_intPhalanx_",
  "middle_distPhalanx_",
  "middle_tip_",
  "ring_metacarpal_",
  "ring_proxPhalanx_",
  "ring_intPhalanx_",
  "ring_distPhalanx_",
  "ring_tip_",
  "little_metacarpal_",
  "little_proxPhalanx_",
  "little_intPhalanx_",
  "little_distPhalanx_",
  "little_tip_",
].map((joint) => `${joint}${handedness === "right" ? "R" : "L"}`);
```

Once you have both objects per hand, you can provide them when enabling the feature:

```javascript
const rightHandMesh = getRightHandMesh(); // get it any way you want
const leftHandMesh = getLeftHandMesh(); // get it any way you want
const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
  jointMeshes: {
    disableDefaultHandMesh: true,
    handMeshes: {
      right: rightHandMesh,
      left: leftHandMesh,
    },
    rigMapping: {
      right: [
        //... mapping for the right hand mesh
      ],
      left: [
        //... mapping for the left hand mesh
      ],
    },
  },
});
```

### 25 tracked points per hand

As mentioned before, WebXR allows us to track 25 points per hand. Those points are listed here: [XR Skeleton Joints](https://immersive-web.github.io/webxr-hand-input/#skeleton-joints-section).

It looks roughly like this:

![BabylonJS WebXR Hand tracking spheres](/img/how_to/xr/handTrackingSpheres.webp).

Each of those 25 points has an InstancedMesh created when the hand-tracking feature is enabled. Those meshes can be used for physics, gesture recognition, collision detection, and more. The default mesh is a sphere. To provide a different mesh, use the `sourceMesh` option:

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
  jointMeshes: {
    sourceMesh: BoxBuilder.CreateBox("jointParent", { size: 1 }),
  },
});
```

Babylon will take this `sourceMesh` and use it to create 25 instances per hand. This mesh will then be set invisible, unless you want it to remain visible:

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
  jointMeshes: {
    sourceMesh: BoxBuilder.CreateBox("jointParent", { size: 1 }),
    keepOriginalVisible: true, // will keep the original instance visible
  },
});
```

Those instances will be visible if no hand mesh is enabled. If you want them to be invisible, set the `invisible` flag:

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
  jointMeshes: {
    disableDefaultHandMesh: true,
    invisible: true,
  },
});
```

If you want to modify those meshes individually (for example, to provide a different material per joint), you can use the `onHandJointMeshGenerated` callback:

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
  jointMeshes: {
    disableDefaultHandMesh: true,
    onHandJointMeshGenerated: (instance) => {
      // do whatever you want with the instance
      return instance; // you can return a whole new mesh or the instance itself. If the instance is not returned, babylon will dispose the unused instance for you.
    },
  },
});
```

### Pointer support

The underlying system will provide a native pointer ray for each hand. Babylon's `WebXR Pointer system` will automatically detect it and allow users to interact with the scene using pointer down/move/up events. Each hand will be provided with a pointer ID to differentiate its pointer events. You can use this information to find the hand object from the pointer selection and the hand-tracking feature:

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

const xrHandFeature = featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
});

// ... at a later point

scene.onPointerObservable.add((evt) => {
  const pointerId = evt.event.pointerId;
  const xrController = xrHelper.pointerSelection.getXRControllerByPointerId(pointerId);
  const webxrHandObject = xrHandFeature.getHandByControllerId(xrController.uniqueId);
});
```

Note that each system might have different gestures for "select". On Quest, it is executed by holding the index finger and the thumb together. Other systems might use a different gesture.

### Near interactions

Hands are perfect for near-field interactions. They are enabled by default when using the default WebXR experience helper. Otherwise, you will need to enable the WebXRNearInteraction feature.

To enable a mesh or a GUI element for near interaction, simply mark it as near-pickable (or near-grabbable):

```javascript
sphere.isNearPickable = true;
```

Now hands (and controllers) can emit pointer events directly on the mesh. This is wonderful for 2D GUI interactions.

<Playground id="#9K3MRA#1513" title="XR Near interactions" description="2D GUI with near interaction enabled" image=""/>

### Using the hand and skeleton joint data

Each hand has its own WebXRHand object associated with it. The WebXR hand object references the following information:

- the `trackedMeshes` object, holding all 25 joint meshes, sorted according to XR joint tracking
- the `handMesh` object (if enabled)
- the `xrController` associated with this hand

There are a few ways to get the hand object:

- Use the controller id as described before
- Use the handedness:

```javascript
const xrHandFeature = featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
});

// after the controllers were initialized
const rightHand = xrHandFeature.getHandByHandedness("right");
```

- The recommended way is to use the `onHandAddedObservable`:

```javascript
const xrHandFeature = featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
});

xrHandFeature.onHandAddedObservable.add((newHand) => {
  // celebrate, we have a new hand!
  scene.onBeforeRenderObservable.add(() => {
    // get the real world wrist position on each frame
    console.log(newHand.trackedMeshes[0].position);
  });
});
```

### Hands physics

To enable physics on each of the 25 tracked points use the `enablePhysics` flag:

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
  jointMeshes: {
    enablePhysics: true,
  },
});
```

To configure the physics properties (which default to a sphere with the default friction and restitution), use the physics props option:

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
  xrInput: xrHelper.input,
  jointMeshes: {
    enablePhysics: true,
    physicsProps: {
      friction: 0.5,
      restitution: 0.3,
    },
  },
});
```

Notice that you can't define the mass. That is because the tracked joints will always have mass `0` to prevent them from constantly "falling down" toward the center of gravity.

<Playground id="#X7Y4H8#73" title="Hand tracking with physics" description="A simple example of a hands-enabled physics playground" image="/img/how_to/xr/handTrackingSpheres.webp"/>


### Microgestures

The Oculus Quest Browser includes support for hand tracking microgestures through a Meta OpenXR [extension](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XR_META_hand_tracking_microgestures), compatible with Quest 2, Quest Pro, Quest 3, and Quest 3S.

This extension introduces five boolean input states per hand (`menu` - only left hand, `swipe-left`, `swipe-right`, `swipe-forward`, `swipe-backward`, `tap-thumb`), enabling fine-grained interaction detection. The image below shows how to perform each microgesture:

<img src="/img/how_to/xr/hand-tracking-microgestures.webp" title="Hand tracking microgestures" alt="Hand tracking microgestures" width="500" height="900" />
<br/><br/>

If you're using ES6 modules with tree-shaking, make sure to import the controller to ensure its initialization.

 ```ts
import "@babylonjs/core/XR/motionController/webXROculusHandController";
 ```

Finally, you can subscribe to events just like with any other input controller. For example, to subscribe to the `swipe-left` microgesture event:

 ```ts
xr.input.onControllerAddedObservable.add((xrController) => {
        xrController.onMotionControllerInitObservable.add((motionController) => {
            const swipeLeftComponent = motionController.getComponent('swipe-left');
            swipeLeftComponent?.onButtonStateChangedObservable.add(() => {
                if (swipeLeftComponent.pressed) {
                    // do something here...
                }
            });
        })
    });
 ```

In the playground below, you can find subscriptions for all available events.

<Playground id="#F41V6N#2427" title="Hand tracking microgestures" description="A simple example of a hand tracking microgestures" />


# WebXR Layers

WebXR Layers lets the XR compositor present content separately from the application's projection layer. A composition layer can produce sharper text and video, avoid an extra projection-rendering pass for media, and place content on a quad, cylinder, equirectangular surface, or cube around the viewer.

The feature depends on the browser and XR runtime implementing the relevant parts of the [WebXR Layers specification](https://www.w3.org/TR/webxrlayers-1/). Support is runtime-dependent, so applications must check capabilities and handle a `null` result when creating an optional layer.

## Supported layer types

Babylon.js supports the projection layer used to render the XR scene and the following additional layer types:

| Shape           | Graphics factory        | Media factory                | Typical use                                      |
| --------------- | ----------------------- | ---------------------------- | ------------------------------------------------ |
| Quad            | `createQuadLayer()`     | `createMediaQuadLayer()`     | Flat panels, video screens, and HUD-like content |
| Cylinder        | `createCylinderLayer()` | `createMediaCylinderLayer()` | Curved interfaces and panoramic video            |
| Equirectangular | `createEquirectLayer()` | `createMediaEquirectLayer()` | Partial or full 360-degree content               |
| Cube            | `createCubeLayer()`     | Not available                | Cubemap content surrounding the viewer           |

Graphics layers use `XRWebGLBinding` with a WebGL engine or `XRGPUBinding` with a WebGPU engine. Media layers use `XRMediaBinding` and receive video content directly from an `HTMLVideoElement`.

New layers are automatically appended to the session's layer list after the projection layer, in creation order.

## Enable WebXR Layers

Enable the feature before entering XR. It creates the session's initial projection layer when the feature attaches:

```javascript
const xr = await scene.createDefaultXRExperienceAsync();
const featuresManager = xr.baseExperience.featuresManager;

const layers = featuresManager.enableFeature(BABYLON.WebXRFeatureName.LAYERS, "stable");

await xr.baseExperience.enterXRAsync("immersive-vr", "local-floor");
```

When using ES modules with tree shaking, import the feature so that it is registered:

```javascript
import "@babylonjs/core/XR/features/WebXRLayers.js";
```

Additional composition and media layers can only be created during an active XR session. Calling a creation factory before the session starts throws an error. The projection layer must also be initialized first; enabling the feature before `enterXRAsync` handles this automatically.

## Check runtime support

Use `isLayerTypeSupported()` to check whether the active rendering backend exposes a graphics or media factory:

```javascript
const supportsGraphicsCylinder = layers.isLayerTypeSupported("XRCylinderLayer");
const supportsMediaCylinder = layers.isLayerTypeSupported("XRCylinderLayer", "media");
```

The supported type names are:

- `"XRProjectionLayer"`
- `"XRQuadLayer"`
- `"XRCylinderLayer"`
- `"XREquirectLayer"`
- `"XRCubeLayer"`

The optional source is `"graphics"` by default and can be set to `"media"`. Projection and cube layers do not have media variants.

`isLayerTypeSupported()` only checks whether the corresponding native factory exists. It does not validate creation options, guarantee that the active device can create the layer, or check `XRGPUBinding.getSubImage` on WebGPU. Always handle a `null` result, and allow exceptions from invalid native initialization dictionaries to surface.

## Create a media layer

Media layers are the most direct way to present video through the XR compositor. The application owns the video element and remains responsible for loading, playing, pausing, and disposing it:

```javascript
const video = document.createElement("video");
video.src = "/videos/demo.mp4";
video.loop = true;
video.muted = true;
video.playsInline = true;

// Start playback from a user gesture when required by the browser.
await video.play();

const screenNode = new BABYLON.TransformNode("media screen", scene);
screenNode.position.set(0, 1.5, 2);

const mediaLayer = layers.createMediaQuadLayer(video, {
  transformNode: screenNode,
  layerInit: {
    width: 2,
    height: 1.125,
  },
});

if (!mediaLayer) {
  console.warn("Native WebXR media quad layers are unavailable.");
}
```

`createMediaQuadLayer()`, `createMediaCylinderLayer()`, and `createMediaEquirectLayer()` pass the video directly to `XRMediaBinding`. Babylon does not create a render target for a native media layer and does not call `video.play()`.

Common media initialization values include `space`, `layout`, and `invertStereo`, plus the shape-specific values listed below.

<Playground id="#D35HOL#0" title="WebXR media quad layer" description="Compare a Babylon VideoTexture plane with a native WebXR media quad layer." image=""/>

## Create graphics-backed layers

The graphics factories create and manage compositor-owned layers for advanced workflows:

<Alert severity="warning" title="Advanced layer-management API">
Babylon internally wraps graphics-layer subimages as render targets, but a stable generic public API for scheduling arbitrary Babylon rendering into those targets is not yet defined. Do not rely on internal render-target provider classes or observables. Use a specialized path such as `addFullscreenAdvancedDynamicTexture()`, the media factories, or the cube layer's raw subimage API when it fits the content.
</Alert>

```javascript
const panelNode = new BABYLON.TransformNode("curved panel", scene);
panelNode.position.set(0, 1.4, 2);

const cylinderLayer = layers.createCylinderLayer({
  transformNode: panelNode,
  layerInit: {
    radius: 3,
    centralAngle: Math.PI,
    aspectRatio: 2,
    viewPixelWidth: 2048,
    viewPixelHeight: 1024,
    layout: "mono",
  },
});

if (!cylinderLayer) {
  console.warn("Native WebXR cylinder layers are unavailable.");
}
```

The example creates, configures, and places the native layer; it does not populate the layer's graphics content. The factories currently provide native layer initialization, placement, ordering, removal, disposal, capability detection, and fallback management.

For a ready-made Babylon content path, `addFullscreenAdvancedDynamicTexture()` renders an existing fullscreen ADT through a quad layer. Cube layers are deliberately low-level and expose `getSubImage(frame, eye?)` so the application can populate all six cubemap faces.

Graphics initialization uses `layerInit` for WebGL-compatible values and `gpuLayerInit` for WebGPU-specific overrides:

```javascript
const quadLayer = layers.createQuadLayer({
  layerInit: {
    width: 1.6,
    height: 0.9,
    layout: "mono",
    isStatic: true,
  },
  gpuLayerInit: {
    colorFormat: "rgba8unorm",
  },
});
```

On WebGPU, Babylon copies the shared values from `layerInit` and then applies `gpuLayerInit`, so WebGPU-specific values take precedence. WebGL-only fields are not copied.

When omitted, Babylon supplies:

- The current XR reference space.
- The projection layer's pixel dimensions.
- `layout: "mono"`.
- WebGL `textureType: "texture"` and `clearOnAccess: true`.
- Square cube faces using the smaller projection-layer dimension.

Cube `viewPixelWidth` and `viewPixelHeight` values must be equal. When `isStatic` is enabled, Babylon only acquires compositor subimages while the native layer's `needsRedraw` flag is set.

## Layer initialization values

Each shape accepts its matching WebXR initialization dictionary:

| Layer           | Shape-specific values                                                                       |
| --------------- | ------------------------------------------------------------------------------------------- |
| Quad            | `transform`, `width`, `height`                                                              |
| Cylinder        | `transform`, `radius`, `centralAngle`, `aspectRatio`                                        |
| Equirectangular | `transform`, `radius`, `centralHorizontalAngle`, `upperVerticalAngle`, `lowerVerticalAngle` |
| Cube            | `orientation`; square `viewPixelWidth` and `viewPixelHeight`                                |

Graphics dictionaries also support values such as pixel dimensions, `space`, `layout`, `isStatic`, texture formats, and mip levels. Media dictionaries support `space`, `layout`, and `invertStereo`.

Use values from the WebXR Layers specification. Invalid values are passed to the native factory and can cause it to throw; an invalid dictionary does not activate the mesh fallback.

## Position and rotate layers

Pass a `TransformNode` to position a layer with Babylon scene coordinates:

```javascript
const layerNode = new BABYLON.TransformNode("layer transform", scene);
layerNode.position.set(0, 1.6, 1.5);
layerNode.rotationQuaternion = BABYLON.Quaternion.RotationYawPitchRoll(Math.PI, 0, 0);

const layer = layers.createMediaQuadLayer(video, {
  transformNode: layerNode,
  layerInit: { width: 1.8, height: 1 },
});
```

Babylon synchronizes the node's world position and rotation to the native layer every XR frame. It converts position using the session's `worldScalingFactor` and handles left-handed scene conversion. Node scaling does not change the physical dimensions of a native layer; use the layer initialization values to size it.

Cube layers synchronize rotation only because the WebXR Layers API does not support cube-layer translation.

When no `transformNode` is supplied, Babylon creates one from `layerInit.transform` or the cube orientation. Babylon owns and disposes that generated node. A node supplied by the application remains application-owned.

If `space` is omitted, the layer uses the session reference space and follows reference-space changes such as recentering. When the application supplies an explicit `space`, Babylon leaves it unchanged.

## Handle creation results

A successful factory returns a wrapper around either a native composition layer or an optional mesh fallback:

- Native spatial wrappers expose `layer`, `layerType`, `transformNode`, and `usesSessionReferenceSpace`.
- Native media wrappers additionally expose `isMediaLayer`.
- Native cube wrappers expose `getSubImage(frame, eye?)`.
- Mesh fallback wrappers have `layer === null`, `isNative === false`, and expose `mesh`, `texture`, and `transformNode`.

Factories return `null` when the required runtime API is unavailable and no requested fallback can be created.

For native cube layers, WebGL applications must populate all six cubemap faces. WebGPU applications must populate six consecutive texture-array layers beginning at the returned subimage's base array layer.

## Opt in to mesh fallbacks

A composition-layer fallback is an ordinary Babylon mesh rendered through the projection layer. It does not provide the quality or performance characteristics of a native compositor layer, but it can preserve visible content on runtimes that do not expose the requested factory.

Fallback rendering is excluded from projection-only, tree-shaken bundles. Import it explicitly:

```javascript
import "@babylonjs/core/XR/features/WebXRLayersFallback.js";
```

Pure registrations can opt in without the side-effect entry point:

```javascript
import { RegisterWebXRLayersFallback } from "@babylonjs/core/XR/features/WebXRLayersFallback.pure.js";

RegisterWebXRLayersFallback();
```

Request the fallback with `fallbackMode: "mesh"`:

```javascript
const result = layers.createCylinderLayer({
  fallbackMode: "mesh",
  fallbackTexture: panelTexture,
  transformNode: panelNode,
  layerInit: {
    radius: 2,
    centralAngle: Math.PI,
    aspectRatio: 2,
  },
});

if (result?.layer === null) {
  console.log("Using a projection-rendered mesh fallback.");
}
```

Graphics fallbacks require `fallbackTexture`. Cube fallbacks require a cube texture. Media fallbacks create an owned `VideoTexture` from the supplied video element, but playback remains application-owned. Caller-provided textures and transform nodes are not disposed by the wrapper.

Fallback geometry uses the requested shape dimensions. Omitted values default to:

| Shape           | Fallback defaults                                         |
| --------------- | --------------------------------------------------------- |
| Quad            | Width `1`, height `1`                                     |
| Cylinder        | Radius `2`, central angle `Math.PI / 4`, aspect ratio `2` |
| Equirectangular | Radius `1000`, full horizontal and vertical sphere        |
| Cube            | Inward-facing box with size `1000`                        |

Fallback dimensions are converted using `worldScalingFactor`. Cube fallbacks remain centered on the viewer and use the transform node's rotation only.

## Remove and dispose layers

Use `removeLayer()` with any result returned by a spatial or media factory:

```javascript
if (mediaLayer) {
  layers.removeLayer(mediaLayer);
}
```

It removes native layers from `XRRenderState.layers`, removes fallback meshes from Babylon's fallback list, and disposes wrapper-owned resources by default. Pass `false` to retain the wrapper and take responsibility for its cleanup:

```javascript
if (mediaLayer) {
  layers.removeLayer(mediaLayer, false);
  mediaLayer.dispose();
}
```

`removeXRSessionLayer()` is the lower-level equivalent for native session-layer wrappers. The active projection layer cannot be removed. Removing a wrapper that is not currently managed returns `false`.

Detaching or disposing the WebXR Layers feature disposes all wrappers and resources it owns. It does not dispose application-owned video elements, textures, or transform nodes.

## Backend and fallback support

| Source or backend      | Quad | Cylinder | Equirectangular | Cube |
| ---------------------- | ---- | -------- | --------------- | ---- |
| WebGL `XRWebGLBinding` | Yes  | Yes      | Yes             | Yes  |
| WebGPU `XRGPUBinding`  | Yes  | Yes      | Yes             | Yes  |
| `XRMediaBinding`       | Yes  | Yes      | Yes             | No   |
| Opt-in mesh fallback   | Yes  | Yes      | Yes             | Yes  |
| Babylon Native XR      | No   | No       | No              | No   |

Every "Yes" remains conditional on the active browser and XR runtime. WebGPU graphics layers require both the corresponding creation factory and `XRGPUBinding.getSubImage`. Babylon Native XR continues to use its native render target path and does not expose WebXR Layers.

### WebGPU-XR

WebXR Layers is optional for WebGL-backed XR but required for WebGPU-XR. Enable the feature before calling `enterXRAsync`; it creates the `XRGPUBinding` projection layer used to render the session.

<Alert severity="warning" title="Experimental WebGPU-XR support">
WebGPU-XR currently requires projection layers and does not support multiview. The WebGPU engine must be created with `{ xrCompatible: true }`. See [WebGPU in WebXR](/features/featuresDeepDive/webXR/webGPUXR) for complete setup and fallback guidance.
</Alert>

The graphics factories require the matching `XRGPUBinding.create*Layer` method and `XRGPUBinding.getSubImage`. Babylon logs a warning and returns `null` when either requirement is unavailable, unless an enabled mesh fallback is requested and can be created.

## Enable multiview

WebXR Layers can enable multiview rendering of the projection layer. Multiview renders both eyes with one render call instead of rendering two cameras separately and can improve scene rendering performance on supported runtimes.

To prefer multiview:

```javascript
featuresManager.enableFeature(BABYLON.WebXRFeatureName.LAYERS, "stable", {
  preferMultiviewOnInit: true,
});
```

If the browser supports multiview, Babylon enables it. Otherwise, the feature silently uses non-multiview rendering. On supported WebGL extensions, enabling multiview can also enable antialiasing in XR.

Multiview is not currently supported on the WebGPU-XR path. Setting `preferMultiviewOnInit` with a WebGPU engine still uses non-multiview rendering.

## Fullscreen 2D GUI support

`addFullscreenAdvancedDynamicTexture()` displays an Advanced Dynamic Texture through a quad layer. This allows the same GUI to appear in a desktop application and in XR:

```javascript
const guiLayer = layers.addFullscreenAdvancedDynamicTexture(advancedTexture, {
  distanceFromHeadset: 1.5,
});
```

The GUI behaves like a HUD and cannot be interacted with through this layer. The method is experimental and can return `null` when the runtime does not support the required quad-layer path.

<Playground id="#JA1ND3#941" title="WebXR 2D GUI example" description="WebXR fullscreen 2D GUI support with multiview." image=""/>



## Movement Module

The movement feature allows movement in the scene with controllers. It is separate from the teleportation module and is not designed to be used at the same time.

In order to enable this feature you must first ensure that teleportation is not switched on.

Teleportation can be disabled in the default XR experience:

```javascript
const xr = await scene.createDefaultXRExperienceAsync({
  disableTeleportation: true,
});
```

You can also disable teleportation manually before enabling the movement feature.

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;
featureManager.disableFeature(BABYLON.WebXRFeatureName.TELEPORTATION);
```

The movement feature enables the camera's position to be changed with the controllers.
Default configuration (can be changed in the options below):

1. Left controller - rotate counterclockwise or clockwise
2. Right controller - move forward/backward/left/right

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.MOVEMENT, "latest", {
  xrInput: xrHelper.input,
});
```

<Playground id="#AZML8U" title="Movement with controllers" description="A simple example of controller movement with collisions and gravity" image="/img/how_to/xr/xr-movement-playground.webp"/>

It is also possible to use the controller to set the movement direction. To do that, you need to disable the head-direction settings. You can optionally define which hand will control the rotation:

```javascript
const featureManager = xrHelper.baseExperience.featuresManager;

const movementFeature = featureManager.enableFeature(BABYLON.WebXRFeatureName.MOVEMENT, "latest", {
  xrInput: xr.input,
  // add options here
  movementOrientationFollowsViewerPose: false, // default true
  movementOrientationFollowsController: true, // enable controller direction
  orientationPreferredHandedness: "left", // the preferred hand for rotation. Defaults to right. If hand is not found it will use the first found controller.
});
```

<Playground id="#AZML8U#242" title="Movement with controllers, direction with controller" description="A simple example of controller movement with collisions and gravity using the controller as direction" image="/img/how_to/xr/xr-movement-playground.webp"/>

### Movement Configuration Options

The current options for the plugin can always be found in the [WebXR movement feature source code](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/XR/features/WebXRControllerMovement.ts#L20). Most of them are explained here.

One important option is `movementOrientationFollowsViewerPose`, which defaults to `true`. When configured to `false`, the forward direction will not adjust to the viewer pose, but only to the controller rotation. This can be useful for experiences where the viewer pose should not affect movement direction. For example, if you are moving forward and look left, you should not drift left but continue straight. You can try this in the playground above by changing the option.

The controllers themselves can be configured differently. For example, if you want to swap which hand controls rotation and which controls movement, override the `customRegistrationConfigurations` array. The feature handles movement and rotation state automatically and ignores them when rotation (`rotationEnabled`) or movement (`movementEnabled`) is not enabled. Speed is controlled by `rotationSpeed` and `movementSpeed`.

This swaps the handedness of the default configuration while maintaining the feature sensitivity thresholds:

```javascript
const swappedHandednessConfiguration = [
  {
    allowedComponentTypes: [BABYLON.WebXRControllerComponent.THUMBSTICK_TYPE, BABYLON.WebXRControllerComponent.TOUCHPAD_TYPE],
    forceHandedness: "right",
    axisChangedHandler: (axes, movementState, featureContext, xrInput) => {
      movementState.rotateX = Math.abs(axes.x) > featureContext.rotationThreshold ? axes.x : 0;
      movementState.rotateY = Math.abs(axes.y) > featureContext.rotationThreshold ? axes.y : 0;
    },
  },
  {
    allowedComponentTypes: [WebXRControllerComponent.THUMBSTICK_TYPE, WebXRControllerComponent.TOUCHPAD_TYPE],
    forceHandedness: "left",
    axisChangedHandler: (axes, movementState, featureContext, xrInput) => {
      movementState.moveX = Math.abs(axes.x) > featureContext.movementThreshold ? axes.x : 0;
      movementState.moveY = Math.abs(axes.y) > featureContext.movementThreshold ? axes.y : 0;
    },
  },
];

const featureManager = xrHelper.baseExperience.featuresManager;

featureManager.enableFeature(BABYLON.WebXRFeatureName.MOVEMENT, "latest", {
  xrInput: xrHelper.input,
  customRegistrationConfigurations: swappedHandednessConfiguration,
});
```

Other useful options are to change movement and rotation speed and to enable/disable movement (`movementEnabled`) and rotation (`rotationEnabled`), but these ones are also available on the feature itself to change at runtime. The threshold options determine the sensitivity when the input is accepted - the default is 0.25, which prevents accidental movements and jittering.

## Walking Locomotion

`WebXRWalkingLocomition` is an experimental Babylon.js capability which
enables users to traverse VR spaces by "walking in place."

```javascript
scene.createDefaultXRExperienceAsync({ disableTeleportation: true }).then((xr) => {
  const xrRoot = new BABYLON.TransformNode("xrRoot", scene);
  xr.baseExperience.camera.parent = xrRoot;
  xr.baseExperience.featuresManager.enableFeature(BABYLON.WebXRFeatureName.WALKING_LOCOMOTION, "latest", { locomotionTarget: xrRoot });
});
```

<Playground id="#HE33TR#11" title="Walking Locomotion Demo" description="Basic demo of walking locomotion"/>

While it is highly recommended to move the `WebXRCamera`'s parent
node in order to avoid conflating virtual positional data with XR
sensory readings, it is also possible to move the `WebXRCamera`
itself.

```javascript
scene.createDefaultXRExperienceAsync({ disableTeleportation: true }).then((xr) => {
  xr.baseExperience.featuresManager.enableFeature(BABYLON.WebXRFeatureName.WALKING_LOCOMOTION, "latest", { locomotionTarget: xr.baseExperience.camera.parent });
});
```

<Playground id="#HE33TR#10" title="WebXRCamera Walking Locomotion" description="Walking locomotion operating on the WebXRCamera directly"/>

To move, simply face in the direction you want to go and "walk in place,"
lifting and replacing each foot in turn much as you would if you were
actually walking forward. This is a control technique and is not expected
to work "magically"; it may take a small amount of practice to perform a
motion that the system recognizes as walking.

Under the hood, what the XR system is actually reacting to is the user's
head motion, specifically the characteristic back-and-forth "rocking"
motion traced by most people's heads when walking in place (or, for
example, on a treadmill). Because of this, walking-in-place motions which
keep the head stationary, or which cause the head to move erratically,
will not be recognized as "walking" by the `WebXRWalkingLocomotion`
feature. However, once a recognizable motion is performed, it should be
very easy and comfortable to replicate. Walking detection of a recognizable
motion should also be resilient to head orientation; because walking is
recognized from the movement of the head (at a guesstimated "nape of the
neck" position, which remains relatively stationary as the head rotates),
looking around while performing a recognizable "walking in place" motion
will not disrupt the locomotion feature.

### When to Use This Feature

`WebXRWalkingLocomotion` is a form of _continuous traversal_, similar to
walking around in real life and distinct from _discontinuous traversal_
alternatives such as teleportation. The most common example of continuous
traversal in VR, as in other forms of interactive 3D, is controller-based
and typically leverages a thumbstick to sort of "slide" the user around
the world in a continuous manner. Many users find this "sliding" effect
to be uncomfortable in VR, and for this reason teleportation is often
chosen as the default traversal alternative in VR applications.

However, there are times when teleportation and other discontinuous
traversal techniques are unsuitable, and in such circumstances
`WebXRWalkingLocomotion` can serve as an alternative to controller-based
continuous traversal. Early tests indicate that walking locomotion can
feel noticeably more comfortable than controller-based continuous
traversal, perhaps because the familiar "walking" motion reduces the
dissonance between the visual and vestibular stimuli presented to the
user.

It is also notable that `WebXRWalkingLocomotion`, because it assesses only
head motion, can be used entirely controller-free. This is particularly
powerful in combination with `WebXRHandTracking` because it allows for a
fully traversal-enabled VR experience where users can use their natural
hands without any controllers at all. This is not possible using other
traversal technologies without customizing the virtual space to support
point-to-point navigation and/or advanced hand gestures.



# 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 enables 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 though it doesn't support this 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 thumbstick teleportation. It is recommended to enable this only during development, unless this is the required behavior.

## Enabling teleportation

The teleportation module is turned on by default when using the [WebXR Default Experience Helper](/features/featuresDeepDive/webXR/webXRExperienceHelpers#the-basic-experience-helper). You can pass configuration options to the default experience helper itself:

```javascript
const xrHelper = await scene.createDefaultXRExperienceAsync({
  floorMeshes: [ground] /* Array of meshes to be used as landing points */,
  teleportationOptions: {
    // Options to pass to the teleportation module
  },
});
```

To disable teleportation (of course while being able to re-enable it at a later point), use the following flag:

```javascript
const xrHelper = await scene.createDefaultXRExperienceAsync({
  disableTeleportation: true,
});
```

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/tree/master/packages/dev/core/src/XR/features/WebXRControllerTeleportation.ts#L31).

Some teleportation parameters are needed during construction and are therefore configurable only through the constructor's `options` parameter. To reconfigure parameters that have no public getter/setter, re-enable the feature:

```javascript
const 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 `xrInput`, which is the controllers it will use to teleport the user.

## Setting floor meshes

Floor meshes are the most important part of teleportation, as the module needs to know where users are allowed to land and where they are not.

When using the [WebXR Default Experience Helper](/features/featuresDeepDive/webXR/webXRExperienceHelpers#the-basic-experience-helper) you can set the floorMeshes during initialization:

```javascript
const 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 is enabled, you can use the `addFloorMesh` function:

```javascript
teleportation.addFloorMesh(ground2);
```

And to remove one, 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."/>

## 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 are in sight, and it is the most convenient and straightforward way to move forward.

![Direct WebXR teleportation](/img/how_to/xr/xr-direct-teleportation.webp)

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

Direct teleportation is always enabled. Indirect teleportation is enabled by 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 farther, you can set the radius used to create the inspection ray when pointing the ray 90 degrees upward (default is 5):

```javascript
teleportation.parabolicCheckRadius = 10;
```

Note that the parabolic ray's radius is bigger the lower the controller's rotation angle is. 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 ray-casting mode. Rotating the finger after the ray is cast will rotate the direction in which the user lands. Releasing the finger when a landing zone is visible 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](/features/featuresDeepDive/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 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 meant 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.webp)

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

The example can be found here: <Playground id="#B8D5Z6#9" title="Custom Landing Zone" description="Simple example of a custom landing zone."/>

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

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

### Disable lighting on the ring

To make sure the ring is always visible no matter what 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.webp)

## Rotating while teleporting

It is possible to prevent the user from rotating after casting the initial ray. It is a flag directly on the teleportation object and is called `rotationEnabled`:

```javascript
teleportation.rotationEnabled = false;
```

## Backwards movement

Backward movement is enabled by default. When the user "pulls" the thumbstick or touchpad backward, they will move a predefined distance if that 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 backward movement, use this flag:

```javascript
teleportation.backwardsMovementEnabled = false; // Default is true
```

## Rotation in place

When moving the thumbstick left and right (X-axis movement on the thumbstick/touchpad), the user will rotate by a predefined amount. The 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 to 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](/features/featuresDeepDive/materials/advanced/transparent_rendering))
2. Utility layer (See [UtilityLayerRenderer](/features/featuresDeepDive/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.webp)

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 following:

- 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. The 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 target zone position within a 1.2-unit radius of one of the snap-to points will move the target zone location to the closest 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 movement and only let the user land on snap-to points, set `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.webp)

You can play around in this playground:

<Playground id="#DGS0NV#3" title="Snap-to Hotspot Example" description="Simple example of snap-to hotspots." image=""/>



# Babylon.js WebXR features

This page contains the documentation for all features that are not AR-exclusive. For AR-specific features, see the [BabylonJS WebXR AR Features](/features/featuresDeepDive/webXR/webXRARFeatures) page.



# WebGPU in WebXR

Babylon.js can render immersive WebXR sessions with a WebGPU engine through the browser's experimental `XRGPUBinding` implementation.

<Alert severity="warning" title="Experimental WebGPU-XR support">
WebGPU-XR browser and device support is experimental and may change. Test on every target browser and headset, and keep a WebGL entry path available when WebGPU-XR is not supported.
</Alert>

## Check the three levels of support

WebGPU, immersive WebXR, and WebGPU-XR are separate capabilities:

- `WebGPUEngine.IsSupportedAsync` checks whether Babylon can create a WebGPU engine.
- `WebXRSessionManager.IsSessionSupportedAsync("immersive-vr")` checks whether the browser reports support for that immersive WebXR session mode.
- `WebXRSessionManager.IsWebGPUXRSupported` checks whether the runtime exposes the `XRGPUBinding` projection-layer methods and the `XRGPUSubImage.getViewDescriptor` method required by Babylon.

`IsWebGPUXRSupported` is an experimental, static boolean getter. It requires the `XRGPUSubImage` interface and `XRGPUSubImage.prototype.getViewDescriptor` because Babylon uses that method to create texture views for each projection sub-image. This remains an advisory API-shape check, not a guarantee that the active device, GPU adapter, permissions, and session will work together. The actual session request can still reject.

## Select the engine before creating the scene

A WebGPU engine intended for XR must request an XR-compatible adapter when it is created:

```javascript
const engine = new BABYLON.WebGPUEngine(canvas, { xrCompatible: true });
await engine.initAsync();
```

WebGPU has no equivalent to making an existing context XR-compatible later. If your application supports WebGL fallback, select the rendering backend before creating the scene or any GPU resources:

```javascript
async function createEngineForImmersiveXR(canvas) {
  const webGPUSupported = await BABYLON.WebGPUEngine.IsSupportedAsync;
  const immersiveXRSupported = await BABYLON.WebXRSessionManager.IsSessionSupportedAsync("immersive-vr");
  // Includes XRGPUBinding projection APIs and XRGPUSubImage.getViewDescriptor.
  const webGPUXRSupported = BABYLON.WebXRSessionManager.IsWebGPUXRSupported;

  if (webGPUSupported && immersiveXRSupported && webGPUXRSupported) {
    const engine = new BABYLON.WebGPUEngine(canvas, { xrCompatible: true });
    try {
      await engine.initAsync();
      return engine;
    } catch (error) {
      engine.dispose();
      console.warn("Could not initialize an XR-compatible WebGPU engine; using WebGL instead.", error);
    }
  }

  return new BABYLON.Engine(canvas, true);
}

const engine = await createEngineForImmersiveXR(canvas);
const scene = new BABYLON.Scene(engine);
// Create the rest of the scene and its resources only after selecting the engine.
```

Babylon.js never swaps an existing WebGPU engine or scene to WebGL. If WebGPU session negotiation later fails, falling back requires reloading or fully rebuilding the engine, scene, and all GPU resources with a WebGL engine.

## Enable WebXR Layers before entering XR

WebGPU-XR uses an `XRProjectionLayer`, so the [WebXR Layers feature](/features/featuresDeepDive/webXR/WebXRSelectedFeatures/WebXRLayers) is required. Enable it before calling `enterXRAsync`:

```javascript
const xr = await scene.createDefaultXRExperienceAsync();

const featuresManager = xr.baseExperience.featuresManager;
featuresManager.enableFeature(BABYLON.WebXRFeatureName.LAYERS, "stable");

try {
  await xr.baseExperience.enterXRAsync("immersive-vr", "local-floor");
} catch (error) {
  // Show the error and offer to reload or rebuild the application with WebGL.
  console.error("Could not start the XR session:", error);
}
```

When using ES modules with tree shaking, import the Layers feature so it is registered:

```javascript
import "@babylonjs/core/XR/features/WebXRLayers.js";
```

Babylon rejects WebGPU XR entry with actionable guidance when the required `XRGPUBinding` projection path or `XRGPUSubImage.getViewDescriptor` support is missing, or when Layers was not enabled. If the browser rejects the WebGPU session request with `NotSupportedError`, Babylon preserves the original error as the cause and reports that the application must recreate the scene with WebGL to fall back.

## Current feature caveats

- **Projection layers and sub-image view descriptors are required.** The runtime must expose `XRGPUSubImage.prototype.getViewDescriptor`; the WebGL `XRWebGLLayer` rendering path is not available to a WebGPU engine.
- **Multiview is not available with WebGPU-XR yet.** `preferMultiviewOnInit` does not enable it on this path.
- **Raw Camera Access is unavailable.** The browser exposes camera images through `XRWebGLBinding`, not `XRGPUBinding`.
- **Space Warp is unavailable.** Its current implementation depends on WebGL-specific binding functionality.
- **Additional graphics layers are method-gated.** Quad, cylinder, equirectangular, and cube layers require the matching `XRGPUBinding.create*Layer` factory and `getSubImage`. Babylon warns and returns `null` when either requirement is missing, unless an enabled mesh fallback was requested.
- **Depth Sensing requires CPU-optimized depth.** Request CPU usage with `usagePreference: ["cpu"]`; GPU-optimized environment depth has no `XRGPUBinding` equivalent.

These limitations are specific to the experimental WebGPU-XR path. A feature may still be available in a WebGL-backed WebXR session.


WebXR Selected Features

Coming next

WebXR Hand Tracking Feature

Learn about WebXR hand tracking in Babylon.js.

WebXR Layers

Create and manage projection, quad, cylinder, equirectangular, cube, and media layers in Babylon.js WebXR experiences.

WebXR Teleportation feature

Learn about how to use teleportation in WebXR

WebXR Body Tracking Feature

Learn about the WebXR body tracking feature in Babylon.js, which drives a full-body rigged mesh from XR joint pose data.

WebXR Movement

Learn about how to move in a WebXR scene