
## Cameras, Mesh Collisions, and Gravity

Did you ever play an FPS (First-Person Shooter) game? In this tutorial, we are going to simulate the same camera movements: the camera is on the floor, in collision with the ground, and potentially in collision with any objects in the scene.

## How can I do this ?

To replicate this movement, we have to do 3 simple steps:

### 1. Define and apply gravity

The first thing to do is to define our gravity vector, defining the G-force.

Babylon.js [Scenes](/typedoc/classes/babylon.scene) have a [gravity](/typedoc/classes/babylon.scene#gravity) property that can be applied to any camera you've previously defined in your code. This will move the camera along the direction and speed specified (a [Vector3](/typedoc/classes/babylon.vector3) object) unless the camera's ellipsoid (see #2 below) is colliding with another mesh in that direction (such as your ground mesh) with [checkCollisions](/typedoc/classes/babylon.mesh#checkcollisions) set to `true`.

```javascript
scene.gravity = new BABYLON.Vector3(0, -0.15, 0);
```

To apply the scene's gravity to your camera, set the [applyGravity](/typedoc/classes/babylon.freecamera#applygravity) property to `true`:

```javascript
camera.applyGravity = true;
```

In the real world, gravity is a _force_ (ok, sort of) that is exerted downward -- _i.e._, in a negative direction along the Y-axis. On Earth, this force is roughly 9.81m/s². Falling bodies _accelerate_ as they fall, so it takes 1 second to fully reach this velocity, then the velocity reaches 19.62m/s after 2 seconds, 29.43m/s after 3 seconds, etc. In an atmosphere, wind drag eventually matches this force and velocity ceases to increase ("terminal velocity").

Babylon.js follows a much simpler gravitational model, however -- `scene.gravity` represents a _constant velocity_, not a force of acceleration, and it is measured in _units/frame_ rather than _meters/second_. As each frame is rendered, the cameras you apply this gravity to will _move_ by the vector's value along each axis (usually `x` and `z` are set to 0, but you can have "gravity" in any direction!), until a collision is detected.

While Babylon.js units have no direct physical equivalent, with the default camera field of view, an approximation of 1 unit = 1 meter is a fairly standard assumption. So, if you want to approximate nominal Earth gravity, you'll need to make some assumptions about the number of frames being rendered per second, and compute a suitable vector:

```javascript
const assumedFramesPerSecond = 60;
const earthGravity = -9.81;
scene.gravity = new BABYLON.Vector3(0, earthGravity / assumedFramesPerSecond, 0);
```

Since this is computed once per frame, the camera isn't actually "moving," it is making tiny "hops" along the direction of the gravity vector. This may be important if you are relying on collision detection to determine if the camera (or, rather, a mesh attached to it for that purpose) has "entered" or "exited" some other mesh (for example, a plane under your "ground" layer to sense a falling character and reset the game play). Depending on your chosen gravity, the starting elevation, and the position and height of the "trigger" mesh, the camera may jump _right through_ the trigger mesh without ever "intersecting" it. Be sure to check the math to ensure that at least one multiple of `scene.gravity` added to the starting elevation will intersect your trigger mesh.

If you need a more accurate representation of gravitational (or other) forces, you can use the physics engines [integrated with Babylon](/features/featuresDeepDive/physics/usingPhysicsEngine), or [add your own](/features/featuresDeepDive/physics/addPhysicsEngine).

#### A Warning
Adding both physics impostors and setting collision enabled to the same object might lead to unexpected behavior.

### 2. Define an ellipsoid

The next important step is to define the ellipsoid around our camera. This ellipsoid represents our player’s dimensions: a collision event will be raised when a mesh comes in contact with this ellipsoid, preventing our camera from getting too close to this mesh:

![Ellipsoid](/img/babylon101/ellipsoid.png)

The [ellipsoid](/typedoc/classes/babylon.freecamera#ellipsoid) property on Babylon.js cameras is default to size (0.5, 1, 0.5). Changing these values will make you taller, bigger, smaller, thinner, depending on the adjusted axis. In the example below, we will make our camera's ellipsoid a bit wider and deeper than the default one:

```javascript
//Set the ellipsoid around the camera (e.g. your player's size)
camera.ellipsoid = new BABYLON.Vector3(1, 1, 1);
```

Please note that the ellipsoid for the camera is offset to always have the viewpoint on top of the ellipsoid. You can control this behavior by updating the [ellipsoidOffset](/typedoc/classes/babylon.freecamera#ellipsoidoffset) property.

The computation will be the following:

`finalPosition = position - vec3(0, ellipsoid.y, 0) + ellipsoidOffset`

### 3. Apply collision

Our final step is to declare that we are interested in sensing collisions in our scene:

```javascript
// Enable Collisions
scene.collisionsEnabled = true;
camera.checkCollisions = true;
```

And to declare which meshes could be in collision with our camera:

```javascript
ground.checkCollisions = true;
box.checkCollisions = true;
```

That’s it! Easy!

You can play with the scene used in this tutorial: <Playground id="#4HUQQ#1713" title="Basic Camera Collision Example" description="A simple example of adding an ellipsoid collision buffer around a camera."/>

Now, your camera is going to fall on the y-axis until it collides with the ground. And, your camera will collide with the box when you move it too close to it.

### 4. Object vs. object collision

You can do the same thing with a mesh by playing with the [ellipsoid](/typedoc/classes/babylon.mesh#ellipsoid) property and the [moveWithCollisions(velocity)](/typedoc/classes/babylon.mesh#movewithcollisions) function. This function will attempt to move the mesh according to a given velocity when it finds no collisions between the current mesh and any meshes with [checkCollisions](/typedoc/classes/babylon.mesh#checkcollisions) activated.

You can also use a mesh's [ellipsoidOffset](/typedoc/classes/babylon.mesh#ellipsoidoffset) to move the ellipsoid on the mesh (by default, the ellipsoid is centered on the mesh).

```javascript
var speedCharacter = 8;
var gravity = 0.15;
var character = Your mesh;

character.ellipsoid = new BABYLON.Vector3(0.5, 1.0, 0.5);
character.ellipsoidOffset = new BABYLON.Vector3(0, 1.0, 0);

var forwards = new BABYLON.Vector3(parseFloat(Math.sin(character.rotation.y)) / speedCharacter, gravity, parseFloat(Math.cos(character.rotation.y)) / speedCharacter);
forwards.negate();
character.moveWithCollisions(forwards);
// or
var backwards = new BABYLON.Vector3(parseFloat(Math.sin(character.rotation.y)) / speedCharacter, -gravity, parseFloat(Math.cos(character.rotation.y)) / speedCharacter);
character.moveWithCollisions(backwards);
```

<Playground id="#1M79PT#1" title="Basic Mesh Collision Example" description="A simple example of adding an ellipsoid collision buffer around a mesh."/>

## ArcRotateCamera

The `ArcRotateCamera` can also check collisions, but instead of sliding along obstacles, this camera won't move when a collision happens.

To activate collisions, just set `camera.checkCollisions` to `true`. You can also define the collision radius:

```javascript
camera.collisionRadius = new BABYLON.Vector3(0.5, 0.5, 0.5);
```

## Other types of collisions

Great, now you can develop a real FPS game! But maybe you would like to know when a mesh is in collision with another mesh? If that interests you, you can head on over here: [Mesh Collisions](/features/featuresDeepDive/mesh/interactions/mesh_intersect).



## Cameras

Of the many cameras available in Babylon.js, the two most used are probably the [Universal Camera](/typedoc/classes/babylon.universalcamera), used for "first-person" movement, [ArcRotateCamera](/typedoc/classes/babylon.arcrotatecamera), an orbital camera, and [WebXRCamera](/typedoc/classes/babylon.webxrcamera), used for modern virtual reality experiences.

To allow user input, a camera must be attached to the canvas using:

```javascript
camera.attachControl(canvas, true);
```

The second parameter is optional and defaults to `false`, which prevents default actions on a canvas event. Set to `true` to allow canvas default actions.

### Notes

1. A [Gamepad](/features/featuresDeepDive/input/gamepads) may be used as a controller.
2. For touch control, either [PEP](https://github.com/jquery/PEP) or [hand.js](https://github.com/Deltakosh/handjs) is needed.

## Universal Camera

This was introduced with version 2.3 of Babylon.js and is controlled by the keyboard, mouse, touch, or [gamepad](/features/featuresDeepDive/input/gamepads) depending on the input device used, with no need for the controller to be specified. This extends and replaces the [Free Camera](/typedoc/classes/babylon.freecamera), the [Touch Camera](/typedoc/classes/babylon.touchcamera) and the [Gamepad Camera](/typedoc/classes/babylon.gamepadcamera), which are all still available.

The Universal Camera is now the default camera used by Babylon.js, and it’s your best choice if you’d like to have an FPS-like control in your scene. All demos on [babylonjs.com](https://www.babylonjs.com/) utilize the Universal Camera. Plug an Xbox controller into your PC and you'll be able to use it to navigate most of the demos.

The default actions are:

1. Keyboard - The left and right arrow keys move the camera left and right, and the up and down arrow keys move it forwards and backward;

2. Mouse - Rotates the camera about the axes with the camera as origin;

3. Touch - Swipe left and right to move the camera left and right, and swipe up and down to move it forward and backward;

4. [gamepad](/features/featuresDeepDive/input/gamepads) - corresponds to device.

Optional actions are:

1. MouseWheel - The scroll wheel on a mouse or scroll actions on a touchpad. <Playground id="#DWPQ9R#1" title="Adding Scroll Wheel to Universal Camera" description="A simple example of adding scroll wheel functionality to the universal camera." image="/img/playgroundsAndNMEs/divingDeeperCamerasIntro1.jpg"/>

### Note

Using keys in the Playground requires you to click inside the rendering area to give it the focus.

### Constructing a Universal Camera

```javascript
// Parameters : name, position, scene
var camera = new BABYLON.UniversalCamera("UniversalCamera", new BABYLON.Vector3(0, 0, -10), scene);

// Targets the camera to a particular position. In this case the scene origin
camera.setTarget(BABYLON.Vector3.Zero());

// Attach the camera to the canvas
camera.attachControl(canvas, true);
```

<Playground id="#DWPQ9R#1" title="Universal Camera Example" description="A simple example of how to construct a universal camera." image="/img/playgroundsAndNMEs/divingDeeperCamerasIntro2.jpg" isMain={true} category="Cameras"/>

## Arc Rotate Camera

This camera always points towards a given target position and can be rotated around that target with the target as the center of rotation. It can be controlled with cursors and mouse, or with touch events.

Think of this camera as one orbiting its target position, or more imaginatively as a satellite orbiting the earth. Its position relative to the target ("Earth") can be set by three parameters:

- [alpha](/typedoc/classes/babylon.arcrotatecamera#alpha) (the longitudinal rotation, in radians),
- [beta](/typedoc/classes/babylon.arcrotatecamera#beta) (the latitudinal rotation, in radians), and
- [radius](/typedoc/classes/babylon.arcrotatecamera#radius) (the distance from the target).

Here is an illustration:

![arc rotate camera](/img/how_to/camalphabeta.jpg)

Setting `beta` to 0 or PI can, for technical reasons, cause problems, so in this situation, `beta` is offset by 0.1 radians (about 0.6 degrees).

`beta` increases in a clockwise direction, while `alpha` increases counter-clockwise.

The position of the camera can also be set from a vector, which will override any current value for `alpha`, `beta` and `radius`. This can be much easier than calculating the required angles.

Whether using the keyboard, mouse, or touch swipes, left/right directions change `alpha`, and up/down directions change `beta`.

The following optional `ArcRotateCamera` properties can also be handy:

- **zoomToMouseLocation** - if set to `true` will cause mouse wheel to zoom in or out centered on
  current mouse location instead of a fixed camera.target location.  This makes it easy  to explore
  all corners of a large scene.  Setting this means that the mouse wheel input controller will be
  changing the camera.target position during mouse wheel zooming.  When this is `true` the zoom
  operation using the mouse wheel is doing both zooming and a small amount of panning at the same
  time.

- **wheelDeltaPercentage** - if set to non-zero value will cause the zooming amount to be set to a
  percentage of the camera radius.  This means the zoom slows down as you get closer to the target
  object which is nice because it means you can be more precise about camera placement while you
  explore your object up close.

### Constructing an Arc Rotate Camera

```javascript
// Parameters: name, alpha, beta, radius, target position, scene
var camera = new BABYLON.ArcRotateCamera("Camera", 0, 0, 10, new BABYLON.Vector3(0, 0, 0), scene);

// Positions the camera overwriting alpha, beta, radius
camera.setPosition(new BABYLON.Vector3(0, 0, 20));

// This attaches the camera to the canvas
camera.attachControl(canvas, true);
```

<Playground id="#SRZRWV#839" title="arcRotate Camera Example" description="A simple example of how to construct an arcRotate camera." image="/img/playgroundsAndNMEs/divingDeeperCamerasIntro2.jpg" isMain={true} category="Cameras"/>

By default, panning with an `ArcRotateCamera` is also possible by using <kbd>Ctrl</kbd> + <kbd>left mouse button</kbd>. You can use <kbd>right mouse button</kbd> instead by setting `useCtrlForPanning` to `false` in the `attachControl` call :

```javascript
camera.attachControl(canvas, noPreventDefault, useCtrlForPanning);
```

If required, you can also totally deactivate panning by setting :

```javascript
camera.panningSensibility = 0;
```

Here's a demo demonstrating some of these things, along with other features of the ArcRotateCamera:

<Playground id="#3B5W22#29" title="ArcRotateCamera Offset Demo" description="A demonstration of setting targetScreenOffset" image="/img/playgroundsAndNMEs/divingDeeperCamerasIntro6.jpg" isMain={true} category="Cameras"/>

## FollowCamera

The [FollowCamera](/typedoc/classes/babylon.followcamera) does what it says on the tin. Give it a mesh as a target, and from whatever position it is currently at it will move to a goal position from which to view the target. When the target moves, so will the Follow Camera.

The initial position of the Follow Camera is set when it is created then the goal position is set with three parameters:

1. [radius](/typedoc/classes/babylon.followcamera#radius): the distance from the target

2. [heightOffset](/typedoc/classes/babylon.followcamera#heightOffset): the height above the target;

3. [rotationOffset](/typedoc/classes/babylon.followcamera#rotationOffset): the goal angle in degrees around the target in the x y plane.

The speed with which the camera moves to a goal position is set through its acceleration ([cameraAcceleration](/typedoc/classes/babylon.followcamera#cameraacceleration)) up to a maximum speed ([maxCameraSpeed](/typedoc/classes/babylon.followcamera#maxcameraspeed)).

### Constructing a Follow Camera

```javascript
// Parameters: name, position, scene
var camera = new BABYLON.FollowCamera("FollowCam", new BABYLON.Vector3(0, 10, -10), scene);

// The goal distance of camera from target
camera.radius = 30;

// The goal height of camera above local origin (centre) of target
camera.heightOffset = 10;

// The goal rotation of camera around local origin (centre) of target in x y plane
camera.rotationOffset = 0;

// Acceleration of camera in moving from current to goal position
camera.cameraAcceleration = 0.005;

// The speed at which acceleration is halted
camera.maxCameraSpeed = 10;

// This attaches the camera to the canvas
camera.attachControl(canvas, true);

// NOTE:: SET CAMERA TARGET AFTER THE TARGET'S CREATION AND NOTE CHANGE FROM BABYLONJS V 2.5
// targetMesh created here.
camera.target = targetMesh; // version 2.4 and earlier
camera.lockedTarget = targetMesh; //version 2.5 onwards
```

<Playground id="#SRZRWV#6" title="Follow Camera Example" description="A simple example of how to construct a follow camera." image="/img/playgroundsAndNMEs/divingDeeperCamerasIntro3.jpg" isMain={true} category="Cameras"/>

## AnaglyphCameras

The [AnaglyphUniversalCamera](/typedoc/classes/babylon.anaglyphuniversalcamera) and [AnaglyphArcRotateCamera](/typedoc/classes/babylon.anaglypharcrotatecamera) extend the use of the Universal and Arc Rotate Cameras for use with red and cyan 3D glasses. They use post-processing filtering techniques.

### Constructing an Anaglyph Universal Camera

```javascript
// Parameters : name, position, eyeSpace, scene
var camera = new BABYLON.AnaglyphUniversalCamera("af_cam", new BABYLON.Vector3(0, 1, -15), 0.033, scene);
```

### Constructing an Anaglyph ArcRotateCamera

```javascript
// Parameters : name, alpha, beta, radius, target, eyeSpace, scene
var camera = new BABYLON.AnaglyphArcRotateCamera("aar_cam", -Math.PI / 2, Math.PI / 4, 20, BABYLON.Vector3.Zero(), 0.033, scene);
```

The `eyeSpace` parameter sets the amount of shift between the left-eye view and the right-eye view. Once you are wearing your 3D glasses, you might want to experiment with this float value.

You can learn all about anaglyphs by visiting a [Wikipedia page that explains it thoroughly](https://en.wikipedia.org/wiki/Anaglyph_3D).

## Device Orientation Camera

The [DeviceOrientationCamera](/typedoc/classes/babylon.deviceorientationcamera) is specifically designed to react to device orientation events such as a modern mobile device being tilted forward, back, left, or right.

### Constructing a Device Orientation Camera

```javascript
// Parameters : name, position, scene
var camera = new BABYLON.DeviceOrientationCamera("DevOr_camera", new BABYLON.Vector3(0, 0, 0), scene);

// Targets the camera to a particular position
camera.setTarget(new BABYLON.Vector3(0, 0, -10));

// Sets the sensitivity of the camera to movement and rotation
camera.angularSensibility = 10;
camera.moveSensibility = 10;

// Attach the camera to the canvas
camera.attachControl(canvas, true);
```

<Playground id="#SRZRWV#3" title="Device Orientation Camera Example" description="A simple example of how to construct a Device Orientation camera." image="/img/playgroundsAndNMEs/divingDeeperCamerasIntro4.jpg" isMain={true} category="Cameras"/>

## Virtual Joysticks Camera

The [VirtualJoysticksCamera](/typedoc/classes/babylon.virtualjoystickscamera) is specifically designed to react to Virtual Joystick events. Virtual Joysticks are on-screen 2D graphics that are used to control the camera or other scene items.

**Note:** This camera requires the third-party file [hand.js](https://archive.codeplex.com/?p=handjs).

### Video

<Youtube id="53Piiy71lB0"/>

![Screenshot of the Virtual Joysticks Camera in action on Espilit](https://david.blob.core.windows.net/babylonjs/VJCBabylon.jpg)

### Complete sample

Here is a complete sample that loads the Espilit demo and switches the default camera to a virtual joysticks camera:

```javascript
document.addEventListener("DOMContentLoaded", startGame, false);
function startGame() {
  if (BABYLON.Engine.isSupported()) {
    var canvas = document.getElementById("renderCanvas");
    var engine = new BABYLON.Engine(canvas, true);

    BABYLON.SceneLoader.Load("Espilit/", "Espilit.babylon", engine, function (newScene) {

      var VJC = new BABYLON.VirtualJoysticksCamera("VJC", newScene.activeCamera.position, newScene);
      VJC.rotation = newScene.activeCamera.rotation;
      VJC.checkCollisions = newScene.activeCamera.checkCollisions;
      VJC.applyGravity = newScene.activeCamera.applyGravity;

      // Wait for textures and shaders to be ready
      newScene.executeWhenReady(function () {
        newScene.activeCamera = VJC;
        // Attach camera to canvas inputs
        newScene.activeCamera.attachControl(canvas);
        // Once the scene is loaded, just register a render loop to render it
        engine.runRenderLoop(function () {
          newScene.render();
        }),
      }),
    }, function (progress) {
    // To do: give progress feedback to user.
    }),
  }
}
```

If you switch back to another camera, don’t forget to call `dispose()` first. The `VirtualJoysticks` are creating a 2D canvas on top of the 3D WebGL canvas to draw the joysticks with cyan and yellow circles. If you forget to call `dispose()`, the 2D canvas will remain and will continue to handle touch events.

## VR Device Orientation Cameras

The [VRDeviceOrientationFreeCamera](/typedoc/classes/babylon.vrdeviceorientationfreecamera), [VRDeviceOrientationArcRotateCamera](/typedoc/classes/babylon.vrdeviceorientationarcrotatecamera), and [VRDeviceOrientationGamepadCamera](/typedoc/classes/babylon.vrdeviceorientationgamepadcamera) are a newer set of cameras that extend the cameras above to handle device orientation from a VR device.

Example (requires a VR device):

<Playground id="#SRZRWV#4" title="VR Device Orientation Camera Example" description="A simple example of how to construct a VR Device Orientation camera." image="/img/playgroundsAndNMEs/divingDeeperCamerasIntro5.jpg"/>

## Constructing a VR Device Orientation Free Camera

```javascript
// Parameters: name, position, scene, compensateDistortion, vrCameraMetrics
var camera = new BABYLON.VRDeviceOrientationFreeCamera("Camera", new BABYLON.Vector3(-6.7, 1.2, -1.3), scene);
```

### Constructing a VR Device Orientation Arc Rotate Camera

```javascript
// Parameters: name, alpha, beta, radius, target, scene, compensateDistortion, vrCameraMetrics
var camera = new BABYLON.VRDeviceOrientationArcRotateCamera("Camera", Math.PI / 2, Math.PI / 4, 25, new BABYLON.Vector3(0, 0, 0), scene);
```

### Constructing a VR Device Orientation Gamepad Camera

```javascript
// Parameters: name, position, scene, compensateDistortion, vrCameraMetrics
var camera = new BABYLON.VRDeviceOrientationGamepadCamera("Camera", new BABYLON.Vector3(-10, 5, 14));
```

## WebVR Free Camera

**NOTE:** WebVR is deprecated! Please use WebXR instead

[WebVRFreeCamera](/typedoc/classes/babylon.webvrfreecamera) is the legacy virtual reality camera, now intended for use with older VR device browsers that don't support the WebXR standard.

```javascript
// Parameters : name, position, scene, webVROptions
var camera = new BABYLON.WebVRFreeCamera("WVR", new BABYLON.Vector3(0, 1, -15), scene);
```

This camera deserves its own page: [Using the WebVR Camera](/features/featuresDeepDive/cameras/webVRCamera).

## FlyCamera

[FlyCamera](/typedoc/classes/babylon.flycamera) imitates free movement in 3D space, think "a ghost in space." It comes with an option to gradually correct Roll, and also an option to mimic banked-turns.

Its defaults are:

1. Keyboard - The <kbd>A</kbd> and <kbd>D</kbd> keys move the camera left and right. The <kbd>W</kbd> and <kbd>S</kbd> keys move it forward and backward. The <kbd>E</kbd> and <kbd>Q</kbd> keys move it up and down.

2. Mouse - Rotates the camera about the Pitch and Yaw (X, Y) axes with the camera as the origin. Holding the <kbd>right mouse button</kbd> rotates the camera about the Roll (Z) axis with the camera as the origin.

### Constructing a Fly Camera

```javascript
// Parameters: name, position, scene
var camera = new BABYLON.FlyCamera("FlyCamera", new BABYLON.Vector3(0, 5, -10), scene);

// Airplane like rotation, with faster roll correction and banked-turns.
// Default is 100. A higher number means slower correction.
camera.rollCorrect = 10;
// Default is false.
camera.bankedTurn = true;
// Defaults to 90° in radians in how far banking will roll the camera.
camera.bankedTurnLimit = Math.PI / 2;
// How much of the Yawing (turning) will affect the Rolling (banked-turn.)
// Less than 1 will reduce the Rolling, and more than 1 will increase it.
camera.bankedTurnMultiplier = 1;

// This attaches the camera to the canvas
camera.attachControl(canvas, true);
```

## Clipping Planes and Infinite Perspective

Cameras in Babylon.js have [clipping planes](/features/featuresDeepDive/scene/clipPlanes) that specify a visual range in the scene that will be rendered. Anything outside of that range will not be rendered. For example, setting the camera's far clipping plane to 100 like this:

```javascript
camera.maxZ = 100;
```

will not render anything past 100 units from the camera. The same is true of the near clipping plane as well. For example, setting the near clipping plane to 10 like this:

```javascript
camera.minZ = 10;
```

will not rendering anything closer than 10 units from the camera.

In some cases, you may not want to clip the rendering of your scene. You may want your scene to effectively render out to infinity. This can be done by setting the far clipping plane to 0 like this:

```javascript
camera.maxZ = 0;
```

Just a friendly warning, setting the far clipping plane to infinity can reduce depth precision, so use this carefully!

## Customizing inputs

The cameras rely upon user inputs to move the camera. If you are happy with the camera presets Babylon.js is giving you, just stick with it.

If you want to change user inputs based upon user preferences, customize one of the existing presets, or use custom input mechanisms. Those cameras have an input manager that is designed for those advanced scenarios. Read [customizing camera inputs](/features/featuresDeepDive/cameras/customizingCameraInputs) to learn more about tweaking inputs on your cameras.

## Correcting perspective projection

If you are doing applications like architectural rendering, you may encounter the need to compensate for perspective tilting of vertical lines.
Let's consider this case : you are rendering a tall building from a human eye point of view. Naturally, vertical lines will converge towards a vanishing point, like on [this playground](https://playground.babylonjs.com/#L20FJ4#15) : ![Screenshot of the tilted vertical lines](/img/how_to/tilted-vertical.jpg).

While this is realistic, it may be visually inappealing. If the angle between those lines stays quite low, it may be interesting to consider correcting the perspective correction, using `camera.applyVerticalCorrection()`. This method will automatically compute the vertical correction to apply regarding the current camera pitch angle : ![Screenshot of the corrected vertical lines](/img/how_to/corrected-vertical.jpg).

And if you want further control other the camera projection plane tilting, you can mess with the `camera.projectionPlaneTilt` property.
See [this forum post](https://forum.babylonjs.com/t/add-vertical-shift-to-3ds-max-exporter-babylon-cameras/17480/16) for more information.




## How to Customize Camera Inputs

Every Babylon.js camera will automatically handle inputs for you, once you call the camera's [attachControl](/typedoc/classes/babylon.freecamera#attachcontrol) method. You can revoke the control by using the [detachControl](/typedoc/classes/babylon.freecamera#detachcontrol) method. Most Babylon.js experts use a two-step process to activate and attach a camera:

```javascript
//First, set the scene's activeCamera... to be YOUR camera.
scene.activeCamera = myCamera;
// Then attach the activeCamera to the canvas.
//Parameters: canvas, noPreventDefault
scene.activeCamera.attachControl(canvas, true);
```

A simpler version might look like this:

```javascript
myCamera.attachControl(canvas);
```

By default `noPreventDefault` is set to `false`, meaning that `preventDefault()` is automatically called on all canvas mouse clicks and touch events.

Babylon.js v2.4 introduced a different way to manage camera inputs to provide an approach oriented toward composability of inputs. You can now use an input manager and each input can be seen as a plugin that is specific to this camera family and to a given input type (mouse, keyboard, gamepad, device orientation, etc.).

Using input managers, you can add, remove, enable, or disable any input available for the camera. You can also easily implement custom input mechanisms or override the existing ones.

The input manager is available through the camera's [inputs](/typedoc/classes/babylon.freecamera#inputs) property. For example:

```javascript
var camera = new BABYLON.FreeCamera("sceneCamera", new BABYLON.Vector3(0, 1, -15), scene);
var inputManager = camera.inputs;
```

## Configure your inputs

Most inputs provide settings to customize the sensibility and adapt it to your own scene.

Each input provides a short name available on the manager. The goal is to provide a friendly syntax when playing with your inputs.

```javascript
var camera = new BABYLON.FreeCamera("sceneCamera", new BABYLON.Vector3(0, 1, -15), scene);
camera.inputs.add(new BABYLON.FreeCameraGamepadInput());
camera.inputs.attached.gamepad.gamepadAngularSensibility = 250;
```

## Adding an existing input

The input managers of `ArcRotateCamera` and `FreeCamera` expose short-hand functions for adding built-in inputs.

```javascript
var camera = new BABYLON.FreeCamera("sceneCamera", new BABYLON.Vector3(0, 1, -15), scene);
camera.inputs.addGamepad();
```

If you wish, you can also add an instance of your own input (we will cover how to implement your own input at the end of this article).

```javascript
var camera = new BABYLON.FreeCamera("sceneCamera", new BABYLON.Vector3(0, 1, -15), scene);
camera.inputs.add(new BABYLON.FreeCameraGamepadInput());
```

## Enable or disable inputs

When you call `attachControl` on the camera, you are activating all inputs attached to the input manager. In the same way, you could turn off all inputs by calling `detachControl` on the camera.

If you want to disable an input temporarily, you can call `detachControl` directly on the input... like this:

```javascript
var camera = new BABYLON.FreeCamera("sceneCamera", new BABYLON.Vector3(0, 1, -15), scene);
camera.inputs.attached.mouse.detachControl();
camera.inputs.addGamepad();
```

You can then call `attachInput` when you want to turn it on again.

```javascript
camera.inputs.attachInput(camera.inputs.attached.mouse);
```

## Removing inputs

Sometimes you want a very specific input mechanism. The best approach in such cases is probably to clear all inputs and add only those you may want in your scene.

```javascript
var camera = new BABYLON.FreeCamera("sceneCamera", new BABYLON.Vector3(0, 1, -15), scene);
camera.inputs.clear();
camera.inputs.addMouse();
```

You can also remove a single input from your input manager. You can remove them by instance, or by Type name

```javascript
var camera = new BABYLON.FreeCamera("sceneCamera", new BABYLON.Vector3(0, 1, -15), scene);
// remove by instance
camera.inputs.remove(camera.inputs.attached.mouse);
// remove by type
camera.inputs.removeByType("FreeCameraKeyboardMoveInput");
```

## Implementing Your Own Input

Your input method is created as a function object. You must then write code for several methods, with required names, that are called by the input function object. The method names and purpose are:

```javascript
// This function must return the class name of the camera, it could be used for serializing your scene
getClassName();

// This function must return the simple name that will be injected in the input manager as short hand
// for example "mouse" will turn into camera.inputs.attached.mouse
getSimpleName();

//T his function must activate your input event.  Even if your input does not need a DOM element
// element and noPreventDefault must be present and used as parameter names.
// Return void.
attachControl(element, noPreventDefault);

// Detach control must deactivate your input and release all pointers, closures or event listeners
// element must be present as a parameter name.
// Return void.
detachControl(element);

// This optional function will get called for each rendered frame, if you want to synchronize your
// input to rendering, no need to use requestAnimationFrame. It's a good place for applying
// calculations if you have to.
// Return void.
checkInputs();
```

## HammerJS Input

If the builtin touch controls for the ArcRotateCamera are not enough for you, you can implement your own camera input using the well-known touch gestures library HammerJS. https://hammerjs.github.io/

We have an example of how to use HammerJS to simulate something similar to Google Earth controls. We use BabylonJS's ArcRotateCamera for this purpose. The camera is locked on the Y axis and horizontal pan moves the camera along the X axis and the vertical pan moves it along the Z axis. The `alpha` angle of the camera is taken into account when panning. By pinching you can change the `radius` of the camera so you can zoom in and out. You can change the `alpha` angle of the camera by a two finger rotate gesture so basically you can rotate around the cameras target.

Example app:
https://demos.babylonjs.xyz/hammerjs-example/#/

GitHub repo:
https://github.com/RolandCsibrei/babylonjs-hammerjs-arc-rotate-camera

The example contains `utils\ArcRotateCameraHammerJsInput.ts` which implements `ICameraInput<ArcRotateCamera>`. There are multiple parameters for the input and are pretty self explanatory. Please refer to the source code of the input and set the sensitivity and treshold values which fits your needs. First you need to install HammerJS, please refer to https://hammerjs.github.io/getting-started/ and import it

```javascript
import "hammerjs";
```

To use the new input you add it to your `camera.inputs` after you have create the camera. To avoid one input fighting the other remove the `ArcRotateCameraPointersInput` from `camera.inputs`. After you've created your Input you can set it's parameters. The default ones (please refer to https://github.com/RolandCsibrei/babylonjs-hammerjs-arc-rotate-camera/blob/680cf12155924a818faac5ff9d7f0a0271bb632b/src/utils/ArcRotateCameraHammerJsInput.ts#L21) are good for a general touch screen monitor so you may have to set them according to your needs.

```javascript

    // remove mouse input
    camera.inputs.removeByType('ArcRotateCameraPointersInput')

    // add hammer js input
    const hammerJsInput = new ArcRotateCameraHammerJsInput()
    // now you can set the parameters you like
    // let's double the zoomSensitivity (default is 1)
    hammerJsInput.zoomSensitivity = 2
    // add the input to the camera
    camera.inputs.add(hammerJsInput)
```

Feel free to use this Input class as a starter for your own HammerJS based input.

## With Javascript

This changes the normal key mappings for moving the camera left, right, forward, and back, and rotating at its current position.

First, remove the default keyboard input.

```javascript
camera.inputs.removeByType("FreeCameraKeyboardMoveInput");
```

Now create the new input method `FreeCameraKeyboardRotateInput`:

```javascript
var FreeCameraKeyboardRotateInput = function () {
  this._keys = [];
  this.keysLeft = [37];
  this.keysRight = [39];
  this.sensibility = 0.01;
};
```

Add get name methods:

```javascript
FreeCameraKeyboardRotateInput.prototype.getClassName = function () {
  return "FreeCameraKeyboardRotateInput";
};
FreeCameraKeyboardRotateInput.prototype.getSimpleName = function () {
  return "keyboardRotate";
};
```

and attach and detach methods:

```javascript
FreeCameraKeyboardRotateInput.prototype.attachControl = function (noPreventDefault) {
  var _this = this;
  var engine = this.camera.getEngine();
  var element = engine.getInputElement();
  if (!this._onKeyDown) {
    element.tabIndex = 1;
    this._onKeyDown = function (evt) {
      if (_this.keysLeft.indexOf(evt.keyCode) !== -1 || _this.keysRight.indexOf(evt.keyCode) !== -1) {
        var index = _this._keys.indexOf(evt.keyCode);
        if (index === -1) {
          _this._keys.push(evt.keyCode);
        }
        if (!noPreventDefault) {
          evt.preventDefault();
        }
      }
    };
    this._onKeyUp = function (evt) {
      if (_this.keysLeft.indexOf(evt.keyCode) !== -1 || _this.keysRight.indexOf(evt.keyCode) !== -1) {
        var index = _this._keys.indexOf(evt.keyCode);
        if (index >= 0) {
          _this._keys.splice(index, 1);
        }
        if (!noPreventDefault) {
          evt.preventDefault();
        }
      }
    };

    element.addEventListener("keydown", this._onKeyDown, false);
    element.addEventListener("keyup", this._onKeyUp, false);
    BABYLON.Tools.RegisterTopRootEvents(canvas, [{ name: "blur", handler: this._onLostFocus }]);
  }
};

FreeCameraKeyboardRotateInput.prototype.detachControl = function () {
  var engine = this.camera.getEngine();
  var element = engine.getInputElement();
  if (this._onKeyDown) {
    element.removeEventListener("keydown", this._onKeyDown);
    element.removeEventListener("keyup", this._onKeyUp);
    BABYLON.Tools.UnregisterTopRootEvents(canvas, [{ name: "blur", handler: this._onLostFocus }]);
    this._keys = [];
    this._onKeyDown = null;
    this._onKeyUp = null;
  }
};
```

Optionally, add checking inputs:

```javascript
FreeCameraKeyboardRotateInput.prototype.checkInputs = function () {
  if (this._onKeyDown) {
    var camera = this.camera;
    // Keyboard
    for (var index = 0; index < this._keys.length; index++) {
      var keyCode = this._keys[index];
      if (this.keysLeft.indexOf(keyCode) !== -1) {
        camera.cameraRotation.y += this.sensibility;
      } else if (this.keysRight.indexOf(keyCode) !== -1) {
        camera.cameraRotation.y -= this.sensibility;
      }
    }
  }
};
```

Finally, add this new input method to the camera inputs:

```javascript
camera.inputs.add(new FreeCameraKeyboardRotateInput());
```

<Playground id="#KHQBRL" title="Rotate Free Camera Example" description="A simple example of customizing inputs to create a Rotate Free Camera."/>

### With Typescript

Using TypeScript, you could implement the interface `ICameraInput`:

```typescript
interface ICameraInput<TCamera extends BABYLON.Camera> {
  // the input manager will fill the parent camera
  camera: TCamera;

  //this function must return the class name of the camera, it could be used for serializing your scene
  getClassName(): string;

  //this function must return the simple name that will be injected in the input manager as short hand
  //for example "mouse" will turn into camera.inputs.attached.mouse
  getSimpleName(): string;

  //this function must activate your input, event if your input does not need a DOM element
  attachControl: (element: HTMLElement, noPreventDefault?: boolean) => void;

  //detach control must deactivate your input and release all pointers, closures or event listeners
  detachControl: (element: HTMLElement) => void;

  //this optional function will get called for each rendered frame, if you want to synchronize your input to rendering,
  //no need to use requestAnimationFrame. It's a good place for applying calculations if you have to
  checkInputs?: () => void;
}
```

## How to Make a Walk and Look Around Camera

The following example customizes the keyboard and mouse inputs to a universal camera. With this change, using the arrow keys you can walk forwards and backward in the scene and rotate to look left and right. Using the mouse you can look around and above and below.

In the example there are two viewports, the upper one gives a first-person view as you move and look around. The lower one gives a representation of the camera and the collision volume surrounding it.

Remember to click on the scene before using the arrow keys.

<Playground id="#CTCSWQ#945" title="Walk and Look Camera Example" description="A simple example of customizing camera inputs to create a walk and look camera." image="/img/playgroundsAndNMEs/divingDeeperCustomCameraInput1.jpg"/>



# How to use Layer Masks and Multi-Camera Textures

## Different meshes for multiple cameras using layer masks

A `layerMask` is a number assigned to each mesh and camera. It is used at the bit level to indicate whether lights and cameras should shine-upon or show the mesh. The default value, 0x0FFFFFFF, will cause the mesh to be illuminated and shown by any stock light and camera.

The feature is used primarily when multiple cameras are active at the same time. If you wish to have a mesh that is always visible on the screen and pickable, e.g. a button, you might add a second camera and light to the scene to exclusively show and light it.

You'll need the 2nd camera to ONLY see the button. The button should also only be visible once.

Notice that the default `layerMask` starts with the first 4 bits being 0, or off. If the 2nd camera and button were to both have a `layerMask` with one of the 4 values below, then the 2nd camera would only see the button:

- 0x10000000
- 0x20000000
- 0x40000000
- 0x80000000

It should also be noted that a mesh with a `layerMask` of 0, can never be seen by anyone. This might be good for hiding things.

To setup for multi-cameras:

```javascript
if (scene.activeCameras.length === 0){
    scene.activeCameras.push(scene.activeCamera);
}
var secondCamera = new Babylon.Camera(...);
secondCamera.layerMask = 0x10000000;
scene.activeCameras.push(secondCamera);

var Button = new BABYLON.Mesh(...);
Button.layerMask = 0x10000000;
```

## Lights

Unless the material of the meshes for the 2nd camera is purely emissive, this still leaves any light for the button illuminating all the other meshes, and other lights in the scene illuminating the button. To keep scene lights from illuminating the button, loop through the existing lights, and set the excludeWithLayerMask value:

```javascript
for (var i = scene.lights.length - 1; i >= 0; i--) {
  scene.lights[i].excludeWithLayerMask = 0x10000000;
}
```

Then make the "button" light:

```javascript
var light = new BABYLON.Light(...);
light.includeOnlyWithLayerMask = 0x10000000;
```

Finally, if there may be more lights generated later, you can register a call-back when a light is added:

```javascript
scene.onNewLightAdded = onNewLight;
```

This could be:

```javascript
onNewLight = function (newLight, positionInArray, scene) {
  newLight.excludeWithLayerMask = 0x10000000;
};
```

## Gun Sight Crosshair Example

Here is a simple example of using a 2nd orthographic camera that shows a gun sight. To keep it simple, emissive material was used to avoid lighting it. Just copy and paste it into any scene, then call it. The `layerMask` chosen also allows Babylon's Dialog extension to inter-operate. Perhaps these could be combined to do a heads-up tank sight with a rangefinder.

A commercial-quality implementation would probably not use `CreateBox()`, since it creates depth faces that cannot be seen straight-on anyway. It should also take into account a window size change unless it is a tablet app.

```javascript
function addGunSight(scene) {
  if (scene.activeCameras.length === 0) {
    scene.activeCameras.push(scene.activeCamera);
  }
  var secondCamera = new BABYLON.FreeCamera("GunSightCamera", new BABYLON.Vector3(0, 0, -50), scene);
  secondCamera.mode = BABYLON.Camera.ORTHOGRAPHIC_CAMERA;
  secondCamera.layerMask = 0x20000000;
  scene.activeCameras.push(secondCamera);

  meshes = [];
  var h = 250;
  var w = 250;

  var y = BABYLON.Mesh.CreateBox("y", h * 0.2, scene);
  y.scaling = new BABYLON.Vector3(0.05, 1, 1);
  y.position = new BABYLON.Vector3(0, 0, 0);
  meshes.push(y);

  var x = BABYLON.Mesh.CreateBox("x", h * 0.2, scene);
  x.scaling = new BABYLON.Vector3(1, 0.05, 1);
  x.position = new BABYLON.Vector3(0, 0, 0);
  meshes.push(x);

  var lineTop = BABYLON.Mesh.CreateBox("lineTop", w * 0.8, scene);
  lineTop.scaling = new BABYLON.Vector3(1, 0.005, 1);
  lineTop.position = new BABYLON.Vector3(0, h * 0.5, 0);
  meshes.push(lineTop);

  var lineBottom = BABYLON.Mesh.CreateBox("lineBottom", w * 0.8, scene);
  lineBottom.scaling = new BABYLON.Vector3(1, 0.005, 1);
  lineBottom.position = new BABYLON.Vector3(0, h * -0.5, 0);
  meshes.push(lineBottom);

  var lineLeft = BABYLON.Mesh.CreateBox("lineLeft", h, scene);
  lineLeft.scaling = new BABYLON.Vector3(0.01, 1, 1);
  lineLeft.position = new BABYLON.Vector3(w * -0.4, 0, 0);
  meshes.push(lineLeft);

  var lineRight = BABYLON.Mesh.CreateBox("lineRight", h, scene);
  lineRight.scaling = new BABYLON.Vector3(0.01, 1, 1);
  lineRight.position = new BABYLON.Vector3(w * 0.4, 0, 0);
  meshes.push(lineRight);

  var gunSight = BABYLON.Mesh.MergeMeshes(meshes);
  gunSight.name = "gunSight";
  gunSight.layerMask = 0x20000000;
  gunSight.freezeWorldMatrix();

  var mat = new BABYLON.StandardMaterial("emissive mat", scene);
  mat.checkReadyOnlyOnce = true;
  mat.emissiveColor = new BABYLON.Color3(0, 1, 0);

  gunSight.material = mat;
}
```

See it in action here: <Playground id="#JU1DZP" title="Gun Sight Crosshair Example" description="A simple example of creating a gun sight crosshair using layer masks and two cameras." image="/img/playgroundsAndNMEs/divingDeeperLayerMasks1.jpg" isMain={true} category="Cameras"/>

Using the information here and combining it with the viewport information from the previous [section](/features/featuresDeepDive/cameras/multiViewsPart2), we can create a more complex example that includes the option to omit meshes from specific cameras.

<Playground id="#L92PHY#217" title="Picture in Picture Visual Camera" description="Using layer masks and viewports, show a visual representation of camera movement." image="/img/playgroundsAndNMEs/pipcamera.png" isMain={true} category="Cameras"/>



# How to use Multiview

## Introduction

The [WebGL Multiview extension](https://www.khronos.org/registry/webgl/extensions/OVR_multiview2/) allows rendering multiple views (eg. each eye for VR scenarios) in a single render pass. This can make rendering around 1.5 to 2.0 times faster.

Multiview is not currently supported in all browsers. If it is supported, the multiview capability should be present.

```javascript
scene.getEngine().getCaps().multiview;
```

**Note:** Multiview rendering renders to a texture array instead of a standard texture. This may cause unexpected issues when applying postprocessing with custom shaders, effects, or postprocessing (_e.g._, the highlight layer will have no effect).

## Using with VRExperienceHelper

Multiview can be enabled by setting the `useMultiview` option to `true`.

```javascript
scene.createDefaultVRExperience({ useMultiview: true });
```

<Playground id="#SRV2A0" title="VR Experience Multiview Example" description="A simple example of using multiviews for a VR experience." image="/img/playgroundsAndNMEs/divingDeeperMultiviews1.jpg"/>

## Using with VRDeviceOrientationFreeCamera to display on the screen

Enable through the option in the [VRCameraMetrics](/typedoc/classes/babylon.vrcamerametrics) object:

```javascript
// Enable multiview
var multiviewMetrics = BABYLON.VRCameraMetrics.GetDefault();
multiviewMetrics.multiviewEnabled = true;
// Create camera
var multiviewCamera = new BABYLON.VRDeviceOrientationFreeCamera("", new BABYLON.Vector3(-10, 5, 0), scene, undefined, multiviewMetrics);
```

<Playground id="#EZDZZV" title="VRDeviceOrientationFreeCamera Multiview Example" description="A simple example of using multiviews to create a VRDeviceOrientationFreeCamera." image="/img/playgroundsAndNMEs/divingDeeperMultiviews2.jpg"/>



## How to use Multi-Views

Babylon.js can render multiple views of the same scene.

## Active cameras

A scene has an [activeCamera](/typedoc/classes/babylon.scene#activecamera) property to define the point of view. But you can define many active cameras using code like this:

```javascript
scene.activeCameras.push(camera);
scene.activeCameras.push(camera2);
```

## Viewports

If you want to use many cameras, you will need to specify a viewport for each camera:

```javascript
camera.viewport = new BABYLON.Viewport(0.5, 0, 0.5, 1.0);
camera2.viewport = new BABYLON.Viewport(0, 0, 0.5, 1.0);
```

A viewport is defined by the following constructor:

```javascript
BABYLON.Viewport = function (x, y, width, height);
```

where x, y, are the lower lefthand corner of the viewport followed by its width and height. Values for x, y, width, and height are numbers between 0 and 1 representing the fraction of the screen width and height, respectively.

<Playground id="#4JXV32" title="Viewport Example" description="A simple example of constructing a viewport." image="/img/playgroundsAndNMEs/divingDeeperMultiviews3.jpg"/>



## WebVR vs WebXR

While the WebVR camera will continue to be supported, **it is strongly recommended that new projects use the [WebXR camera](/features/featuresDeepDive/webXR/webXRCamera)**. For more information, check out our [introduction to WebXR](/features/featuresDeepDive/webXR/introToWebXR).

## Introduction

Since v2.5, Babylon.js supports WebVR using the `WebVRFreeCamera` camera.

As of Babylon v3.0, we fully support the WebVR 1.1 specifications (https://w3c.github.io/webvr/), which is supported by the latest version of Microsoft Edge, Chrome, and Firefox.

The WebVR camera is Babylon's simple interface to interaction with Windows Mixed Reality, HTC Vive, Oculus Rift, Google Daydream, and Samsung GearVR.

Babylon.js also supports the VR devices' controllers - The Windows Mixed Reality controllers, HTC Vive's controllers, the Oculus Touch, GearVR controller, and Daydream controller - using the gamepad extension. Further details below.

To quickly get started creating a WebVR scene, the [WebVR Experience Helper](/features/featuresDeepDive/cameras/webVRHelper) class can be used to automatically setup the WebVR camera and enable other features such as teleportation out of the box.

## Browser support

### WebVR

WebVR 1.1 is enabled in specific versions of Microsoft Edge, Chrome, and Firefox. To get constant status updates, please visit WebVR Rocks at https://webvr.rocks/ . We support any browser that implements WebVR 1.1.

### WebVR controllers

The WebVR controllers are offered in browsers that support the WebVR gamepad extensions - https://w3c.github.io/gamepad/extensions.html .

## The WebVRFreeCamera class

### Getting started

The `WebVRFreeCamera` is initialized the same as a standard free camera:

```javascript
var camera = new BABYLON.WebVRFreeCamera("camera1", new BABYLON.Vector3(0, 0, 0), scene);
```

This will initialize a new WebVR camera and will enable WebVR in the engine.

Just like any other camera, to get the camera working correctly with user input and interactions, we will need to attach the camera (and the VR device) to the canvas and the scene. To do that we use the same method we know from the free camera:

```javascript
camera.attachControl(canvas, true);
```

Most browsers only support attaching the VR device to the scene during user interaction (a mouse click, for example). To get that working correctly, a simple solution would be:

```javascript
scene.onPointerDown = function () {
  scene.onPointerDown = undefined;
  camera.attachControl(canvas, true);
};
```

What it does is attach control once the user clicks on the canvas, and disables the `onPointerDown` callback.

This can be done with an HTML or a Canvas2D button as well, and using vanilla JavaScript event listeners. Any intentional user interaction is allowed. A mouse-move event will not trigger it. A simple example would be:

```javascript
// after creating a button with vrButton as ID:
let button = document.getElementById("vrButton");

function attachWebVR() {
  camera.attachControl(canvas, true);
  window.removeEventListener("click", attachWebVR, false);
}

button.addEventListener("click", attachWebVR, false);
```

Don't forget to remove the event listener, otherwise any click on the button will trigger the attach function. It won't attach again, but it will result in unnecessary function calls.

You should now be able to see your scene in the WebVR device. If not, go to troubleshooting!

### Extra WebVR transformation (Pose data)

The WebVR camera is an extended `FreeCamera`. Apart from all of the abilities a standard `FreeCamera` has, the WebVR camera has 2 major extensions - an extra position and an extra rotation, which are the pose data broadcasted by the VR device connected to the browser. This means the camera has actually two transformations - one is controlled by you, and the other by the device. They are accumulated - position is being added and rotation multiplied - in order to combine the developer's input and the VR device's pose data.

To understand that think of your head and your body. Without moving your body, your head can move in all directions, and rotate in all directions. The WebVR device is your head. Your body is the regular position and `rotationQuaternion` we all know and love. If you rotate your body, the head rotates with it. But if you move the head, the body stays in the same position.

This is exactly how you should see the WebVR extra transformation - your head position is set by the VR device (and cannot be interfered with). Your body (or position in the world) is fully controlled by you.

This allows you to use the same code you use for a game based on the FreeCamera with the WebVR camera. the only difference is that the user will have the ability to rotate the camera locally using the VR device and not the mouse.

This also allows the WebVR to be controlled by the same input devices that control the FreeCamera - keyboard, mouse (with rotation exception), Xbox controller and so on.

### Resetting the device's rotation

The device's "front" position is set by the device itself (it is set during the device's setup and has not a lot to do with WebVR directly). The developer, however, has the ability to change the "front" rotation with a simple function call:

`camera.resetToCurrentRotation()`.

This will set the current Y-axis (and Y-axis direction only!!) to be the current front rotation of the user.

### Low level fun

- If you want to use the `vrDevice` directly, it is exposed using `camera._vrDevice`, a public hidden member in the camera.
- If you want to use the raw pose data (righthanded data!), it is exposed at `camera.rawPose`. The `rawPose` has the following interface (a dream for physics lovers!):

```javascript
export interface DevicePose {
    readonly position?: Float32Array;
    readonly linearVelocity?: Float32Array;
    readonly linearAcceleration?: Float32Array;

    readonly orientation?: Float32Array;
    readonly angularVelocity?: Float32Array;
    readonly angularAcceleration?: Float32Array;
}
```

Note: Raw pose values are not modified based on the `webVRCamera`'s rotation or position. To reference modified position and rotation in Babylon space, use the `devicePosition` and `deviceRotationQuaternion` fields.

```javascript
webVRCamera.devicePosition;
webVRCamera.deviceRotationQuaternion;
webVRCamera.leftController.devicePosition;
webVRCamera.leftController.deviceRotationQuaternion;
```

## The Gamepad Extensions support (WebVR controllers)

Each VR device currently available (Windows Mixed Reality, Oculus Rift, Vive, Daydream, and GearVR) has controllers that complement its usage. Windows Mixed Reality controllers, Vive controllers, Oculus Touch controllers, Daydream Controller, and GearVR Controller are supported by using the gamepad extensions.

### Init controllers

During the WebVRFreeCamera initialization, it will attempt to attach the controllers and detect them if found. If found, the controllers will be located at `camera.controllers` which is an array that will either have a length of 2 or 0 (GearVR and Daydream support only 1 controller). If the controllers are attached and were not detected, you could also try to manually call `camera.initControllers()` at a future time.

To fire a callback when the controllers are found you can use the optional `camera.onControllersAttached` callback:

```javascript
onControllersAttached = function (controllers) {
  console.log(controllers.length === 2); // outputs true;
};
```

Initializing the controllers using the camera will also attach them to the camera. This will allow moving the controllers with the WebVR camera as the user moves them.

### Using the controllers

There are a few high-level implementations that are automatically assigned to a WebVR controller:

`WindowsMotionController` for the Windows Mixed Reality controllers.

`OculusTouchController` for the Oculus Touch.

`ViveController` for the Vive controllers.

`GearVRController` for the Samsung Gear VR controller.

`DaydreamController` for the Google Daydream controller.

each extends the `WebVRController` class, which extends the `PoseEnabledController`.

To make a long story short, each controller has the same set of functions, the only difference being the button mappings. The device type can be retrieved using `controller.controllerType`, which has the following values:

```typescript
enum PoseEnabledControllerType {
  VIVE,
  OCULUS,
  WINDOWS,
  GEAR_VR,
  DAYDREAM,
  GENERIC,
}
```

This enum will be extended as needed.

### Controller button mapping

A controller button has the following set of data:

```typescript
interface ExtendedGamepadButton extends GamepadButton {
  readonly pressed: boolean;
  readonly touched: boolean;
  readonly value: number;
}
```

These values will be sent to the observers of any specific button when either one of them was changed.

The controllers also have Axes-data, which can be compared to the stick value of an Xbox controller. They consist of a 2D vector (with x and y values). Stick values (SHOULD BE) are between -1, -1 and 1, 1, with 0,0 being the default value.

- Not all buttons of each controller support all 3 values, but all 3 will always be provided. For example, the Vive's trigger doesn't support "touched", which will always be false, but will send the value data when pressed (a percentage of the press from 0 to 1).
- Having a value does not automatically mean that "pressed" is set to true. The oculus controllers, for example, will only set the trigger's "pressed" to true when the value exceeds 0.15 (15% pressed).
- The controllers have a "hand" assigned to them, which is a string, either "left" or "right". This can be found at controller.hand .

#### Abstract mapping

The following observables exist on all types of WebVR controllers, in case you wish to develop an abstract solution to all VR devices and not focus on a specific device:

1. `onTriggerStateChangedObservable` is the main trigger observable
2. `onMainButtonStateChangedObservable` the main button observable
3. `onSecondaryButtonStateChangedObservable` - you get the point...
4. `onPadStateChangedObservable` - stick-button observable (NOT the Stick Values)
5. `onPadValuesChangedObservable` - stick values changed observable

To use any of them, simple register a new function with the desired observable.
For example, to monitor the trigger and observe pad value changes:

```javascript
controller.onPadValuesChangedObservable.add(function (stateObject) {
  console.log(stateObject); // {x: 0.1, y: -0.3}
});
controller.onTriggerStateChangedObservable.add(function (stateObject) {
  let value = stateObject.value;
  console.log(value);
});
```

#### Windows Mixed Reality Controller mapping

The Windows Mixed Reality controller supports:

1. Thumbstick axis - axis values. Mapped to `onPadValuesChangedObservable`.
2. Thumbstick press - pressed. Mapped to `onPadStateChangedObservable`.
3. Touchpad axis - axis values. Mapped to `onTouchpadValuesChangedObservable` and `onTrackpadValuesChangedObservable` (aliases).
4. Touchpad press - pressed and touch. Mapped to `onTouchpadButtonStateChangedObservable` and `onTrackpadChangedObservable` (aliases).
5. Trigger - pressed and value. Mapped to `onTriggerStateChangedObservable`
6. Grip button - pressed. Mapped to `onMainButtonStateChangedObservable` and `onGripButtonStateChangedObservable` (aliases)
7. Menu button - pressed. Mapped to `onSecondaryButtonStateChangedObservable` and `onMenuButtonStateChangedObservable` (aliases).

#### Vive Controller mapping

The Vive supports:

1. Touchpad - pressed, touch and axis values. Mapped to `onPadStateChangedObservable`
2. Trigger - pressed and value. Mapped to `onTriggerStateChangedObservable`
3. Left AND right buttons together (!) - touched, pressed. Mapped to `onMainButtonStateChangedObservable`, `onRightButtonStateChangedObservable` and `onLeftButtonStateChangedObservable` (aliases to the same observable object!);
4. Menu button - touched, pressed. Mapped to `onSecondaryButtonStateChangedObservable` and `onMenuButtonStateChangedObservable` (aliases).

#### Oculus Touch mapping

The Oculus Touch supports 6 buttons:

1. Thumbstick - touch, press, value = pressed (0,1). Mapped to `onPadStateChangedObservable`.
2. Index trigger - touch (?), press (only when value > 0.1). Mapped to `onTriggerStateChangedObservable`.
3. Secondary trigger (same). Mapped to `onSecondaryTriggerStateChangedObservable`.
4. A (right) X (left) - touch, pressed = value. Mapped to `onMainButtonStateChangedObservable`, `onAButtonStateChangedObservable` on the right hand and `onXButtonStateChangedObservable` on the left hand.
5. B / Y - touch, pressed = value. Mapped to `onSecondaryButtonStateChangedObservable`, `onBButtonStateChangedObservable` on the right hand and `onYButtonStateChangedObservable` on the left hand.
6. thumb rest. Mapped to `onThumbRestChangedObservable` .

#### Gear VR Controller mapping

The Gear VR controller supports:

1. Trackpad - pressed, touch, and axis values. Mapped to `onPadValuesChangedObservable` and `onTrackpadChangedObservable`
2. Trigger - pressed and values. Mapped to `onTriggerStateChangedObservable`

#### Google Daydream Controller mapping\*

The Google Daydream controller supports:

1. Touchpad - pressed, touch and axis values. Mapped to `onPadValuesChangedObservable` and `onTriggerStateChangedObservable`

note: The Daydream controller home and app buttons are not mapped in WebVR.

### Attaching to a mesh

Instead of forcing you to use the controller meshes (which will prevent you from implementing a single app for many types of devices), we have decided to allow you to attach the controller to a mesh. This will make the controller the mesh's "parent" (but not using the parenting system! As a controller is not a node). The controller's actions (rotation and position changes) will reflect directly to the mesh.

To attach the controller to a mesh:

```javascript
controller.attachToMesh(mesh);
```

Note that this will create a new quaternion to the mesh .

The default controller mesh can be hidden with the following code.

```javascript
scene.createDefaultVRExperience({ controllerMeshes: true });
```

### Low level

### Controllers without WebVR camera

The controllers can also be initialized without using a WebVR camera, which means - you can use them to control your regular WebGL game or 3D application.

To do that, simply initialize the Gamepads Class:

```javascript
new BABYLON.Gamepads((gp) => {
  if (gp.type === BABYLON.Gamepad.POSE_ENABLED) {
    // Do something with the controller!
  }
});
```

Note that the position will be relative to the initial VR Device that is related to those controllers.

### Pose data

Just like the WebVR camera, the controllers export their (right-handed!) raw pose data. The data is updated each frame at `controller.rawPose`.

## Notes

- The WebVR camera supports both left-handed systems and right-handed systems.
- To further read about WebVR try https://mozvr.com/ .

## Examples

<Playground id="G46RP6#2" title="VR Helmet Example" description="A simple example of how to leverage the WebVRFreeCamera."/>
<Playground id="#5MV04" title="Basic VR Scene" description="A simple example of a basic VR scene."/>

Enjoy!

## Troubleshooting

- My WebVR camera is not working!!

  Seems like a very common problem - a WebVRFreeCamera class is initialized, but you can't see a thing in the device.

  1. Check the console - Are you seeing any errors? COuld it be that WebVR is not supported on your browser?
  2. In your console, type `navigator.getVRDevices().then((vrs) => {console.log(vrs.length)})`. If you got 0 or an error, the device is not properly connected.
  3. If you are using Oculus Rift, did you enable "unknown sources" in the Oculus Rift settings?
  4. Try following the instructions in https://mozvr.com/ . Does the camera work there?

- The camera's rotation is changing, but I can't see anything in my display

  This error occurs when you didn't attach a control to the VR device.

  1. Make sure that `attachControl` is called inside a user-interaction callback. Chrome will not allow broadcasting to the VR device without user consent.

- My (Vive) controllers are not detected!! HELP!!!!

  Ah, I know this problem.

  1. Try pressing the left and right buttons of the Vive controller, or the pad button of the Oculus Touch. This should turn them on and make them visible.
  2. Make sure you called `camera.initControllers()` !
  3. open your console, search for errors.
  4. type `navigator.getGamepads()` in your console. Is the list empty? are there controllers in the list? what controllers?
  5. make sure the gamepad extensions is enabled in your browser! Check https://mozvr.com/ for installation instructions.

- Gear VR or Daydream controller models are not showing

  These are 3 DoF devices (no position). The model's positions aren't yet determined, but you have the rays from controller orientation and functional trigger buttons.



# How to use the WebVR experience helper

## WebVR vs WebXR

While the WebVR experience helper will continue to work, **it is strongly recommended that new projects use the [WebXR experience helper](/features/featuresDeepDive/webXR/webXRExperienceHelpers)**. For more information, check out our [introduction to WebXR](/features/featuresDeepDive/webXR/introToWebXR).

## Introduction

The WebVR Experience Helper provides a quick way to add WebVR support to a Babylon scene.

Features include:

1. WebVR camera and non-WebVR camera initialization
1. Enter WebVR button
1. Teleportation and rotation in the world
1. Gaze tracking with mesh selection from HMD and controllers

## Setup

A VRExperienceHelper can be created directly from the scene.

```javascript
var scene = new BABYLON.Scene(engine);
var vrHelper = scene.createDefaultVRExperience();
```

This will initialize a WebVR camera and a non-WebVR camera in the scene. It will also create an enterVR button at the bottom right of the screen which will start rendering to the HMD on click.

### Options

- createDeviceOrientationCamera(default: true): If the non-WebVR camera should be created. To use an existing camera, create it and then initialize the helper with this set to false in the constructor.
- createFallbackVRDeviceOrientationFreeCamera(default: true): When no HMD is connected, this flag specifies if the VR camera should fallback to a VRDeviceOrientationFreeCamera which will render each eye on the screen. This can be set to false to only enable entering VR if an HMD is connected.

## Detect if fallback orientation camera is supported

If a webVR capable device is not detected Babylon will fallback to using a vrDeviceOrientationCamera however device orientation will only be available if the device has an orientation sensor available. In the latest version of Safari, the orientation sensor is disabled by default and it does not prompt users to enable it in settings so currently this must be done by the app. See https://www.applemust.com/how-and-why-to-use-motion-orientation-settings-in-ios/

```javascript
vrHelper.onAfterEnteringVRObservable.add(() => {
  if (scene.activeCamera === vrHelper.vrDeviceOrientationCamera) {
    BABYLON.FreeCameraDeviceOrientationInput.WaitForOrientationChangeAsync(1000)
      .then(() => {
        // Successfully received sensor input
      })
      .catch(() => {
        alert("Device orientation camera is being used but no sensor is found, prompt user to enable in safari settings");
      });
  }
});
```

See it in action here: <Playground id="#TAFSN0#230" title="Fallback Orientation Camera Example" description="A simple example of detecting if a fallback orienation camera is supported." image="/img/playgroundsAndNMEs/divingDeeperWebVRExperienceHelper1.jpg"/>

## Teleportation and Rotation

To enable teleportation in the scene, create a mesh that the user should be able to teleport to and then enable teleportation with that mesh's name.

```javascript
var ground = BABYLON.Mesh.CreateGround("ground", 6, 6, 2, scene);
vrHelper.enableTeleportation({ floorMeshName: "ground" });
```

To teleport, hold up on the joystick to display where the user will be teleported to and then release to teleport.
To rotate, move the joystick to the left or to the right.

When WebVR controllers are connected, the teleportation will be based on where the controller is pointing.

When WebVR controllers are not connected, the user will teleport to where the user is looking and teleportation can be triggered with an Xbox controller.

## Teleportation events

Teleportation has two observables you can subscribe to:

onBeforeCameraTeleport: Observable raised when teleportation is requested, receiving target Vector3 position as parameter:

```javascript
vrHelper.onBeforeCameraTeleport.add((targetPosition) => {
  //Raised before camera is teleported
});
```

onAfterCameraTeleport: Observable raised when teleportation animation finishes, receiving target Vector3 position as parameter:

```javascript
vrHelper.onAfterCameraTeleport.add((targetPosition) => {
  //Raised after teleportation animation finishes
});
```

To enable teleportation in the scene, create a mesh that the user should be able to teleport to and then enable teleportation with that mesh's name.

```javascript
var ground = BABYLON.Mesh.CreateGround("ground", 6, 6, 2, scene);
vrHelper.enableTeleportation({ floorMeshName: "ground" });
```

## Enabling / disabling teleportation

Teleportation can be enabled or disabled on demand by using the property teleportationEnabled:

```javascript
// Enable teleportation
vrHelper.teleportationEnabled = true;

//Disable teleportation (teleportation mesh will not be displayed)
vrHelper.teleportationEnabled = false;
```

To customize the teleportation target mesh the following property can be set to the mesh you'd like to use:

```javascript
vrHelper.teleportationTarget = BABYLON.Mesh.CreateSphere("sphere1", 4, 0.1, scene);
```

## Accessing cameras

The VR and non-VR camera can be accessed from the helper to handle any application specific logic.

```javascript
// Initial camera before the user enters VR
vrHelper.deviceOrientationCamera;
// WebVR camera used after the user enters VR
vrHelper.webVRCamera;
// One of the 2 cameras above depending on which one is in use
vrHelper.currentVRCamera;
```

## Accessing controllers

The controllers can be accessed from the helper to handle any application specific logic.

```javascript
vrHelper.onControllerMeshLoaded.add((webVRController) => {
  var controllerMesh = webVRController.mesh;
  webVRController.onTriggerStateChangedObservable.add(() => {
    // Trigger pressed event
  });
});
```

Please note that the microsoft controllers are using the GLB file format and require the [GLTF Loader](/features/featuresDeepDive/importers/glTF).

## Accessing vr device position and rotation

Position and rotation in Babylon space can be accessed through the webVRCamera's devicePosition and deviceRotationQuaternion

```javascript
// Left and right hand position/rotation
if (vrHelper.webVRCamera.leftController) {
  leftHand.position = vrHelper.webVRCamera.leftController.devicePosition.clone();
  leftHand.rotationQuaternion = vrHelper.webVRCamera.leftController.deviceRotationQuaternion.clone();
}
if (vrHelper.webVRCamera.rightController) {
  rightHand.position = vrHelper.webVRCamera.rightController.devicePosition.clone();
  rightHand.rotationQuaternion = vrHelper.webVRCamera.rightController.deviceRotationQuaternion.clone();
}

// Head position/rotation
head.position = vrHelper.webVRCamera.devicePosition.clone();
head.rotationQuaternion = vrHelper.webVRCamera.deviceRotationQuaternion.clone();
```

See an Example here: <Playground id="#VIGXA3#7" title="Accessing VR Device position and rotation Example" description="A simple example of accessing a vr device's position and rotation."/>

## Gaze and interaction

Gaze and interactions can be enabled through the enableInteractions method. See Example: <Playground id="#JA1ND3#40" title="Gaze and Interactions Example" description="A simple example of handling VR Gaze and Interaction." image="/img/playgroundsAndNMEs/divingDeeperWebVRExperienceHelper2.jpg"/>

```javascript
vrHelper.enableInteractions();
```

This will start casting a ray from either the user's camera or controllers. Where this ray intersects a mesh in the scene, a small gaze mesh will be placed to indicate to the user what is currently selected.

Please note the gaze controllers will simulate pointer events so `scene.onPointerObservable` will be raised when gaze is enabled.

To filter which meshes the gaze can intersect with, the raySelectionPredicate can be used:

```javascript
vrHelper.raySelectionPredicate = (mesh) => {
  if (mesh.name.indexOf("Flags") !== -1) {
    return true;
  }
  return false;
};
```

This will cause the user's gaze to pass through any mesh which results in the raySelectionPredicate returning false.

As the user moves between meshes with their gaze, the onNewMeshSelected event will occur.
Note: This only works after interactions have been enabled.

```javascript
vrHelper.onNewMeshSelected.add((mesh) => {
  // Mesh has been selected
});
```

This will return the single closest mesh that was selected.

Prior to onNewMeshSelected an event called onNewMeshPicked is raised when a mesh is selected based on meshSelectionPredicate successful evaluation. This observable notifies a PickingInfo object to subscribers.

```javascript
vrHelper.onNewMeshPicked.add((pickingInfo) => {
  //Callback receiving ray cast picking info
});
```

As the user unselects a mesh with their gaze or controller, the onSelectedMeshUnselected event will occur.

```javascript
vrHelper.onSelectedMeshUnselected.add((mesh) => {
  // Mesh has been unselected
});
```

You can add your own filtering logic with meshSelectionPredicate.
Note: This will be applied after the raySelectionPredicate.

```javascript
vrHelper.meshSelectionPredicate = (mesh) => {
  if (mesh.name.indexOf("Flags01") !== -1) {
    return true;
  }
  return false;
};
```

The logic order for raySelectionPredicate, meshSelectionPredicate, onNewMeshPicked, onNewMeshSelected are as followed:

1. Ray is casted from the controller
2. When the ray hits an object the raySelectionPredicate will be called and if true the ray will collide there and be stopped otherwise the ray will pass through the object
3. Teleportation target location is updated to where the ray collided if the collision is also a floor mesh
4. If the collision object was not collided with on the last frame meshSelectionPredicate is checked, if it returns true the onNewMeshPicked event is fired and then onNewMeshSelected is fired

The gaze tracker can be customized by setting the gazeTrackerMesh. <Playground id="#ZHYP5K" title="GazeTrackerMesh Example" description="A simple example showing how to use the gazeTrackerMesh." image="/img/playgroundsAndNMEs/vrglasses.png"/>

```javascript
vrHelper.gazeTrackerMesh = BABYLON.Mesh.CreateSphere("sphere1", 4, 0.1, scene);
```

On specific devices like iOS (where fullscreen is not supported), you may want to set `vrHelper.enableGazeEvenWhenNoPointerLock = true` to let the gaze controller run even when not under fullscreen and pointer lock.

## Grab

By combining By combining WebVR controller method and add/removeChild method, you can grab objects by pressing trigger button.

```javascript
webVRController.onTriggerStateChangedObservable.add((stateObject) => {
  if (webVRController.hand == "left") {
    if (selectedMesh != null) {
      //grab
      if (stateObject.value > 0.01) {
        webVRController.mesh.addChild(selectedMesh);
        //ungrab
      } else {
        webVRController.mesh.removeChild(selectedMesh);
      }
    }
  }
});
```

Selected mesh is detected by onNewMeshSelected method.

```javascript
VRHelper.onNewMeshSelected.add(function (mesh) {
  selectedMesh = mesh;
});

VRHelper.onSelectedMeshUnselected.add(function () {
  selectedMesh = null;
});
```

See the example.

- <Playground id="#B4C2AH" title="Grabbing Objects Example" description="A simple example of how to grab objects using the WebVRController." image="/img/playgroundsAndNMEs/divingDeeperWebVRExperienceHelper3.jpg"/>

## Multiview

To improve rendering performance by up to 2x, try using [Multiview](/features/featuresDeepDive/cameras/multiViewsPart1) which will render both eyes in a single render pass

## Examples

Scenes:

- <Playground id="#JA1ND3#6" title="Sponza" description="Sponza scene." image="/img/playgroundsAndNMEs/divingDeeperWebVRExperienceHelper4.jpg"/>
- <Playground id="#JA1ND3#15" title="Mansion" description="Mansion scene." image="/img/playgroundsAndNMEs/divingDeeperWebVRExperienceHelper5.jpg"/>
- <Playground id="#JA1ND3#18" title="Hill Valley" description="Hill Valley scene." image="/img/playgroundsAndNMEs/divingDeeperWebVRExperienceHelper6.jpg"/>

Games:

- <Playground id="#32DWVS#4" title="Minecraft JMJ" description="Minecraft JMJ Game." image="/img/playgroundsAndNMEs/divingDeeperWebVRExperienceHelper7.jpg"/>
- <Playground id="#FAXLY2" title="Fruit Ninja" description="Fruit Ninja Game." image="/img/playgroundsAndNMEs/divingDeeperWebVRExperienceHelper8.jpg"/>



## Cameras

There are a wide range of cameras to use with Babylon.js, Probably the two most used are the universal and arcRotate cameras and increasingly virtual reality ones.

* _Universal Camera_ - the one to choose for first person shooter type games, and works with all the keyboard, mouse, touch and gamepads. With this camera you can check for collisions and apply gravity.
* _Arc Rotate Camera_ - which acts like a satellite in orbit around a target and always points towards the target position.
* _Follow Camera_ - this takes a mesh as a target and follows it as it moves. Both a free camera version _followCamera_ and an arc rotate version _arcFollowCamera_ are available.
* _Anaglyph Camera_ - extending the use of the Universal and Arc Rotate Cameras for use with red and cyan 3D glasses. 
* _Device Orientation Cameras_ - this is a designed to react to a device being tilted forward or back and left or right. 
* _Virtual Joysticks Camera_ - on-screen 2D graphics that are used to control the camera or other scene items. 

* _Virtual Reality Camera_ a range of cameras for VR devices

Methods are available to change how a camera reacts to inputs and to use multiple cameras.


## Introduction
Mesh behaviors are [Behaviors](/features/featuresDeepDive/behaviors) that can be attached to a mesh.

## PointerDragBehavior
This is used to drag a mesh around a plane or axis using a mouse or VR controller.
```
var pointerDragBehavior = new BABYLON.PointerDragBehavior({dragAxis: new BABYLON.Vector3(0,1,0)});
```
It can be initialized in 3 different modes:
 - `dragAxis`: Dragging will occur along the provided axis
 - `dragPlaneNormal`: Dragging will occur along the plane defined by the normal
 - _None_: Dragging will occur along the plane facing the camera

By default, the dragging plane/axis will be modified by the object's orientation. To keep the specified axis/plane fixed to the world, set `useObjectOrientationForDragging` to false.
```
pointerDragBehavior.useObjectOrientationForDragging = false;
```
By default, the drag plane will update on every frame. To disable this, set `updateDragPlane` to false.
```
pointerDragBehavior.updateDragPlane = false;
```
To listen to drag events, the following can be used.
```
pointerDragBehavior.onDragStartObservable.add((event)=>{
    console.log("dragStart");
    console.log(event);
})
pointerDragBehavior.onDragObservable.add((event)=>{
    console.log("drag");
    console.log(event);
})
pointerDragBehavior.onDragEndObservable.add((event)=>{
    console.log("dragEnd");
    console.log(event);
})
```
To use the drag behavior without moving the attached mesh, set `moveAttached` to false. The drag events above can then be used for custom drag interactions.
```
pointerDragBehavior.moveAttached = false;
```
To disable all dragging behavior, set `enabled` to false.
```
pointerDragBehavior.enabled = false;
```
To inspect the current state of the dragged mesh, `currentDraggingPointerID`, `dragging` and `lastDragPosition` can be inspected.
```
// The id of the pointer that is currently interacting with the behavior (-1 when no pointer is active)
pointerDragBehavior.currentDraggingPointerID;
// The last position where the pointer hit the drag plane in world space
pointerDragBehavior.lastDragPosition;
// If the behavior is currently in a dragging state
pointerDragBehavior.dragging;
```

* Playground Example: <Playground id="#YEZPVT" title="Drag Along an Axis" description="A simple example of the pointerDragBehavior." image="/img/playgroundsAndNMEs/divingDeeperMeshBehaviors1.jpg" isMain={true} category="Behaviors"/>

## SixDofDragBehavior
This is used to drag a mesh around in 3D space based on the pointer's origin (eg. camera or VR controller position).
```
var sixDofDragBehavior = new BABYLON.SixDofDragBehavior();
```
By default, pointer jitter is smoothed by slowly moving the mesh to where the pointer is pointing. To remove or modify this behavior, the following field can be modified.
```
// The distance towards the target drag position to move each frame. This can be useful to avoid jitter. Set this to 1 for no delay. (Default: 0.2)
sixDofDragBehavior.dragDeltaRatio = 0.2;
```
By default, dragging objects away/towards you will be magnified to make moving objects large distances easier. To avoid/modify this, the following can be used.
```
// The distance towards the target drag position to move each frame. This can be useful to avoid jitter. Set this to 1 for no delay. (Default: 0.2)
sixDofDragBehavior.zDragFactor = 0.2;
```
**Note** - To avoid large performance hits when using with models that have complex geometries, the object should be wrapped in a bounding box mesh. See [BoundingBoxGizmo.MakeNotPickableAndWrapInBoundingBox](/features/featuresDeepDive/mesh/gizmo)
* Playground Example: <Playground id="#5G9MC5" title="Six Directions Example" description="A simple example of SixDofDragBehavior." image="/img/playgroundsAndNMEs/divingDeeperMeshBehaviors2.jpg" isMain={true} category="Behaviors"/>

## MultiPointerScaleBehavior
This is used to scale a mesh based on 2 pointers (eg. fingers or VR controllers).
```
var multiPointerScaleBehavior = new BABYLON.MultiPointerScaleBehavior();
```
**Note** - To avoid large performance hits when using with models that have complex geometries, the object should be wrapped in a bounding box mesh. See [BoundingBoxGizmo.MakeNotPickableAndWrapInBoundingBox](/features/featuresDeepDive/mesh/gizmo)
* Playground Example: <Playground id="#5G9MC5" title="MultiPointerScaleBehavior Example" description="A simple example of MultiPointerScaleBehavior." image="/img/playgroundsAndNMEs/divingDeeperMeshBehaviors2.jpg" />

## AttachToBoxBehavior (AppBar)
This is used to attach a mesh or UI on top of a mesh's bounding box.
```
var behavior = new BABYLON.AttachToBoxBehavior(appBar);
boundingBox.addBehavior(behavior);
```

To adjust the positioning of the attached mesh, use the following.
```
behavior.distanceAwayFromFace = 0.15;
behavior.distanceAwayFromBottomOfFace = 0.15;
```

This can be used to attach an app bar to a mesh.

![](/img/how_to/gui/appBar.PNG)

* Playground Example: <Playground id="#X6MQ1L" title="AttachToBoxBehavior Example" description="A simple example of AttachToBoxBehavior." image="/img/playgroundsAndNMEs/divingDeeperMeshBehaviors2.jpg" isMain={true} category="Behaviors"/>

## FollowBehavior
This is used to make a mesh follow the camera.

```
var followBehavior = new BABYLON.FollowBehavior();
followBehavior.attach(mesh);
```

The position/rotation of the mesh will be updated in 3 cases:
+ Either the mesh goes outside the bounds of the field of view. Use `maxViewVerticalDegrees` and `maxViewHorizontalDegrees` to tweak these bounds.
+ Either the mesh goes too close or too far from the camera. Use `defaultDistance`, `minimumDistance` and `maximumDistance` to tweak these distances.
+ Either the mesh is facing away from the camera. Use `orientToCameraDeadzoneDegrees` to delimit the maximum angle that the mesh can be facing away.

In XR experiences, it can be useful not to consider the user's complete head rotation. Use the property `ignoreCameraPitchAndRoll` to only consider the yaw (rotation around the Y axis) of the head. In this mode, you can use `pitchOffset`, to slightly put the mesh under or over the horizontal plane.

Like `SixDofDragBehavior`, every transformation of the mesh is interpolated to avoid jitter. Use `lerpTime` to adjust the length of the interpolation (the higher the slower).

## SurfaceMagnetismBehavior
This is used to make a mesh stick to another mesh, and be oriented along its normal. It can, for instance, be used in XR experiences to make UI controls stick to walls.

The property `meshes` is the list of meshes that we should consider as intersectors.

```
var surfaceMagnetismBehavior = new BABYLON.SurfaceMagnetismBehavior();
surfaceMagnetismBehavior.attach(mesh);
surfaceMagnetismBehavior.meshes = meshes;
```

By default, it will intersect `meshes` everytime the pointer moves, and the position will be updated accordingly (with interpolation, like with `FollowBehavior`). Use the flag `enabled` to control whether this behavior should get into play.

## HandConstraintBehavior
This is used to make a mesh follow the hand of the user. It should always be linked to a [WebXRDefaultExperience](/features/featuresDeepDive/webXR/webXRExperienceHelpers#the-webxr-default-experience) to retieve the position of the hand.
The XR experience should also enable the [HandTracking](/features/featuresDeepDive/webXR/WebXRSelectedFeatures#hand-tracking) feature like this :

```
xr.baseExperience.featuresManager.enableFeature(BABYLON.WebXRFeatureName.HAND_TRACKING, "latest", {
    xrInput: xr.input
});
```

And then you can instanciate the behavior, attach it to a mesh, and link it to the XR experience:

```
var handConstraintBehavior = new BABYLON.HandConstraintBehavior();
handConstraintBehavior.attach(mesh);
handConstraintBehavior.linkToXRExperience(xr);
```

You can change the hand it should follow with the property `handedness`.


Cameras

Cameras

Coming next

Camera Introduction

Introduction to the different camera types in Babylon.js.

Camera Collisions

Dive into understanding camera collisions, mesh collisions, and gravity.

Customizing Camera Inputs

Learn how to customize input controls for Babylon.js cameras.

MultiViews Part 1

Learn how to leverage multi-views in Babylon.js.

MultiViews Part 2

Continue learning how to leverage multi-views in Babylon.js.

Layer Masks and Multi-Cam Textures

Learn how to assign different objects to different layer masks.

WebVR Camera (Deprecated)

Learn how to create a VR scene with the WebVR Camera.

WebVR Experience Helper

Set up a VR scene with one line of code.