
## How to use clip planes

You can clip the rendering of a scene by using one of the supported clip planes:

- `scene.clipPlane`
- `scene.clipPlane2`
- `scene.clipPlane3`
- `scene.clipPlane4`
- `scene.clipPlane5`
- `scene.clipPlane6`

Each clip plane is a BABYLON.Plane that you can define like this:

```
scene.clipPlane4 = new BABYLON.Plane(0, 1, 0, 0);
```

The first three parameters of the Plane constructor define the normal of the plane, and the last one defines the distance from (0,0,0).

You can find an interactive demo about clip planes here: <Playground id="#Y6W087" title="Clipping Planes Example 1" description="Simple example showing how to use clipping planes."/>

A maximum of 6 different clip planes can be used simultaneously for a specific rendering.

If you want to apply per mesh clip planes, you can rely on the following observables:

- `mesh.onBeforeRenderObservable`
- `mesh.onAfterRenderObservable`

Example:

```
sphere.onBeforeRenderObservable.add(function() {
    scene.clipPlane = new BABYLON.Plane(1, 0, 0, 0);
});

sphere.onAfterRenderObservable.add(function() {
    scene.clipPlane = null;
});    
```

Demo: <Playground id="#EHLHNX" title="Clipping Planes Example 2" description="Using clipping planes per mesh (scene level)."/>

Since version 5.33.0, the best way to use clip planes in this case is through the properties `material.clipPlane` / `clipPlane2` / ... / `clipPlane6`. This way, you don't need to add observers to `onBeforeRenderObservable` / `onAfterRenderObservable`.

Demo: <Playground id="#EHLHNX#104" title="Clipping Planes Example 3" description="Using clipping planes per mesh (material level)."  image="/img/playgroundsAndNMEs/pg-EHLHNX.webp" />



## How To Create a Custom Loading Screen

Starting with Babylon.js 2.3, the loading screen (the screen used when loading assets or a scene) can be changed by the developer.

To create a new loading screen, you will have to create a simple class, implementing the following interface:

```javascript
interface ILoadingScreen {
  //What happens when loading starts
  displayLoadingUI: () => void;
  //What happens when loading stops
  hideLoadingUI: () => void;
  //default loader support. Optional!
  loadingUIBackgroundColor: string;
  loadingUIText: string;
}
```

In plain JavaScript, your loader code will look like this:

```javascript
function CustomLoadingScreen(/* variables needed, for example:*/ text) {
  //init the loader
  this.loadingUIText = text;
}
CustomLoadingScreen.prototype.displayLoadingUI = function () {
  alert(this.loadingUIText);
};
CustomLoadingScreen.prototype.hideLoadingUI = function () {
  alert("Loaded!");
};
```

In TypeScript, the same code looks like this:

```javascript
class CustomLoadingScreen implements ILoadingScreen {
  //optional, but needed due to interface definitions
  public loadingUIBackgroundColor: string
  constructor(public loadingUIText: string) {}
  public displayLoadingUI() {
    alert(this.loadingUIText);
  }

  public hideLoadingUI() {
    alert("Loaded!");
  }
}
```

The usage is the same in both languages:

```javascript
var loadingScreen = new CustomLoadingScreen("I'm loading!!");
// replace the default loading screen
engine.loadingScreen = loadingScreen;
// show the loading screen
engine.displayLoadingUI();

/*
 * create your scene over here
 */

// hide the loading screen when you want to
engine.hideLoadingUI();
```

## Example

Here is a playground using a custom loading screen:

<Playground id="#5Y2GIC#847" title="Custom Loading Screen Example" description="Simple example showing how to create and use a custom loading screen."/>

You might also be interested in a standalone HTML example:

```html
<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

    <title>Babylon.js custom loading screen example</title>
    <script src="https://code.jquery.com/pep/0.4.2/pep.min.js"></script>
    <script src="https://preview.babylonjs.com/babylon.js"></script>
    <script src="https://preview.babylonjs.com/loaders/babylonjs.loaders.js"></script>

    <style>
      html,
      body {
        overflow: hidden;
        width: 100%;
        height: 100%;
        margin: 0;
        padding: 0;
      }

      #renderCanvas {
        width: 100%;
        height: 100%;
        touch-action: none;
      }

      #loadingScreen {
        position: absolute;
        width: 100%;
        height: 100%;
        color: white;
        font-size: 50px;
        text-align: center;
        background-color: #bb464bcc;
        z-index: 9999;
      }
    </style>
  </head>

  <body>
    <div id="loadingScreen">default div text</div>
    <canvas id="renderCanvas"></canvas>
    <script>
      var canvas = document.getElementById("renderCanvas");
      var engine = new BABYLON.Engine(canvas, true);

      var loadingScreenDiv = window.document.getElementById("loadingScreen");

      function customLoadingScreen() {
        console.log("customLoadingScreen creation");
      }
      customLoadingScreen.prototype.displayLoadingUI = function () {
        console.log("customLoadingScreen loading");
        loadingScreenDiv.innerHTML = "loading";
      };
      customLoadingScreen.prototype.hideLoadingUI = function () {
        console.log("customLoadingScreen loaded");
        loadingScreenDiv.style.display = "none";
      };
      var loadingScreen = new customLoadingScreen();
      engine.loadingScreen = loadingScreen;

      engine.displayLoadingUI();

      var delayCreateScene = function () {
        var scene = new BABYLON.Scene(engine);
        scene.createDefaultCamera(true, true, true);
        BABYLON.ImportMeshAsync("https://models.babylonjs.com/CornellBox/cornellBox.glb", scene).then(function () {
          scene.createDefaultCamera(true, true, true);
          scene.createDefaultEnvironment();
          scene.activeCamera.alpha = Math.PI / 2;

          engine.hideLoadingUI();
        });
        return scene;
      };
      var scene = delayCreateScene();

      engine.runRenderLoop(function () {
        if (scene) {
          scene.render();
        }
      });
      window.addEventListener("resize", function () {
        engine.resize();
      });
    </script>
  </body>
</html>
```

## Getting File Loading Rate

When loading files, you can access the [SceneLoaderProgressEvent](/typedoc/classes/babylon.sceneloader) sent to the `onProgress` callback.

Example using `BABYLON.ImportMeshAsync`:

```javascript
BABYLON.ImportMeshAsync("https://models.babylonjs.com/CornellBox/cornellBox.glb", scene, {
  onProgress: function (evt) {
    // onProgress
    var loadedPercent = 0;
    if (evt.lengthComputable) {
      loadedPercent = ((evt.loaded * 100) / evt.total).toFixed();
    } else {
      var dlCount = evt.loaded / (1024 * 1024);
      loadedPercent = Math.floor(dlCount * 100.0) / 100.0;
    }
    // assuming "loadingScreenPercent" is an existing html element
    document.getElementById("loadingScreenPercent").innerHTML = loadedPercent;
  },
}).then(function () {
  // onSuccess
  scene.createDefaultCamera(true, true, true);
  scene.activeCamera.alpha = Math.PI / 2;
  engine.hideLoadingUI();
});
```

## File Loading Rate of Multiple Assets

This example expands on the use of [SceneLoaderProgressEvent](/typedoc/classes/babylon.sceneloader) from the previous section to track the loading of multiple assets using different loading methods.

<Playground id="#BCU1XR#7895" title="Loading Rate of Multiple Assets" description="Example showing how to get a loading rate for multiple assets."/>



Starting with Babylon.js v4.2, you have the opportunity to apply delta changes to a scene.
This means you can "record" all changes made to a scene and later reapply them.

This is particularly useful when you load a scene from a .babylon or a .gltf file and want to apply changes to it without re-exporting the scene from your DCC tool.

## Recording the changes

To record changes done to a scene, you simply have to create a new `SceneRecorder` and call its `track()` function:

```javascript
var recorder = new BABYLON.SceneRecorder();

recorder.track(scene);
```

This will mark the origin of the changes, e.g. the original state of your scene. All changes made after that call (well, almost all—please check the limitations chapter below) will be tracked and available in the delta file.

## Applying the changes

Once you're done with the changes you want to record, you can get the delta file with this call:

```javascript
var delta = recorder.getDelta();
```

The returned value is a JSON object that you can download or reuse later.

To download it, you can leverage the Tools class:

```javascript
BABYLON.Tools.Download(JSON.stringify(delta), "delta.json");
```

If you want to apply it to your scene, you can call this static function:

```javascript
BABYLON.SceneRecorder.ApplyDelta(delta, scene);
```

## Example

Let's have a look at an example to see it in action:

```javascript
var scene = new BABYLON.Scene(engine);
var camera = new BABYLON.FreeCamera("camera1", new BABYLON.Vector3(0, 5, -10), scene);
camera.setTarget(BABYLON.Vector3.Zero());
camera.attachControl(canvas, true);

var light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0, 1, 0), scene);
light.intensity = 0.7;

var sphere = BABYLON.MeshBuilder.CreateSphere("sphere", { diameter: 2, segments: 32 }, scene);
sphere.position.y = 1;

var ground = BABYLON.MeshBuilder.CreateGround("ground", { width: 6, height: 6 }, scene);

// Instantiate the recorder
var recorder = new BABYLON.SceneRecorder();

recorder.track(scene);

// Let's make some changes
sphere.position.y = 0;
scene.clearColor.r = 1;

light.intensity = 0;

var light2 = new BABYLON.HemisphericLight("light2", new BABYLON.Vector3(0, 1, 0), scene);

ground.dispose();

// Now we can get the delta file
let delta = recorder.getDelta();

// Just to see the changes, we are updating the value so we can see what the delta is doing
ground = BABYLON.MeshBuilder.CreateGround("ground", { width: 6, height: 6 }, scene);
light2.dispose();
sphere.position.y = 2;
scene.clearColor.r = 0;
light.intensity = 1.0;

// Apply the delta
BABYLON.SceneRecorder.ApplyDelta(delta, scene);
```

You can play with this code on this Playground: <Playground id="#MPD4TQ#1" title="Delta System Example" description="Simple example showing how to save deltas and apply them to your scene."/>

## Using the Inspector

You can also use the Inspector to record your delta. To do so, jump to the Tools tab and select the [Start recording] button in the Replay section:

![Replay section](/img/how_to/scene/inspector-record.webp)

When you are done with your recording, go to the same place and hit the [Generate delta file]:

![Replay section](/img/how_to/scene/inspector-generate.webp)

This will download the file locally.

## Limitations

The recorder has some limitations:

- It will only record simple values (arrays, colors, vectors, booleans, numbers)
- It will not record large state changes like:
  - Updating the material property of a mesh
  - Updating the skeleton property of a mesh
  - Updating mesh's geometry



## How To Fast Build a World

There are a number of helpers that, once you have put models into a scene, add cameras, lights, and an environment that automatically adjust to the models, allowing you to view them quickly. You can then make adjustments as needed.

For beginners to Babylon.js, the [Fastest Build](/features/featuresDeepDive/scene/fastBuildWorld#fastest-build) and [Import and Fastest Build](/features/featuresDeepDive/scene/fastBuildWorld#import-and-fastest-build) sections will quickly give you a viewable world and are a good way to look at models. As such, they are level 1 material. It is worth considering working through Babylon101 and parts of the level 1 material to make the other information and details on this page easier to understand.

## Helpers

The following is a list of the methods of the `scene` object that help in fast building a world, with a link to their API description:

- [createDefaultCameraOrLight](/typedoc/classes/babylon.scene#createdefaultcameraorlight);
- [createDefaultCamera](/typedoc/classes/babylon.scene#createdefaultcamera);
- [createDefaultLight](/typedoc/classes/babylon.scene#createdefaultlight);
- [createDefaultEnvironment](/typedoc/classes/babylon.scene#createdefaultenvironment);
- [createDefaultSkybox](/typedoc/classes/babylon.scene#createdefaultskybox);

## Fastest Build

To build a world very quickly, just use `createDefaultCameraOrLight` along with `createDefaultEnvironment`, as in this example:

```javascript
scene.createDefaultCameraOrLight(true, true, true);
scene.createDefaultEnvironment();
```

<Playground id="#MJNICE" title="The Quickest Way To Build A World" description="Simple example of creating a world with createDefaultEnviornment." isMain={true} category="Environment"/>

You can see how the camera automatically adjusts by adding a second box and repositioning it:

<Playground id="#MJNICE#3" title="Fast Build With Camera Adjust" description="Simple example of building a world quickly and adjusting the camera."/>

More information about these methods, including details about parameters, can be found in the individual sections below.

## Create Default Camera or Light

As shown in the _Fastest Build_ section, the `createDefaultCameraOrLight` helper creates both a camera and a light in one line. The three parameters it takes are the same as for the `createDefaultCamera` method. The second parameter also applies to the light and replaces any existing camera or light when `true`. Accessing the camera or light works the same way as with the individual methods.

## Create Default Camera

`createDefaultCamera` takes three boolean parameters, all set to _false_ by default. They are:

- createArcRotateCamera: creates a free camera by default and an arc rotate camera when _true_;
- replace: when _true_ the created camera will replace the existing active one;
- attachCameraControls: when _true_ attaches control to the canvas.

This code will create an arc rotate camera, replace any existing camera, and attach the camera controls to the canvas:

```javascript
scene.createDefaultCamera(true, true, true);
```

<Playground id="#MJNICE#4" title="Camera Helper Example (no light)" description="Simple example of the camera helper with no light."/>
<Playground id="#MJNICE#5" title="Camera Helper Example" description="Simple example of the camera helper."/>

For a free camera:

```javascript
scene.createDefaultCamera(false, true, true);
```

<Playground id="#MJNICE#6" title="Camera Helper Example (Free Camera)" description="Simple example of the camera helper with a free camera."/>

The camera will adjust depending on the size and position of each mesh in the world.

<Playground id="#MJNICE#7" title="Camera Helper Adjusting" description="Simple example of the camera helper and adjusting to a large box."/>

### Accessing the Camera

Since creating the camera this way makes the helper-created camera the active camera, the simplest way to access it is:

```javascript
scene.createDefaultCamera(true, true, true);

var helperCamera = scene.activeCamera;
```

<Playground id="#MJNICE#11" title="Camera Helper With Active Camera Changes" description="Simple example of the camera helper and making changes to the active camera."/>

An alternative way to access the helper-created camera immediately after creating it is to use the fact that it will be the last one in the `scene.cameras` array:

```javascript
scene.createDefaultCamera(true, true, true);

var helperCamera = scene.cameras[scene.cameras.length - 1];

//OR

var helperCamera = scene.cameras.pop();
scene.cameras.push(helperCamera);
```

<Playground id="#MJNICE#8" title="Camera Helper With Radius and Angle Changes" description="Simple example of the camera helper and making changes to the camera radius and angles."/>

## Create Default Light

`createDefaultLight` takes just one boolean parameter, set to _false_ by default:

- replace: when _true_ the created light will replace all the existing ones; when _false_ and there are no existing lights a hemispherical light is created; when _false_ and lights already exist, no change is made to the scene.

When this method is used before any other lights are created, it is usually sufficient to use:

```javascript
scene.createDefaultLight();
```

### Accessing the Light

Provided you access the helper-created light immediately after creating it, it will be the last one in the `scene.lights` array.

You can obtain it using

```javascript
scene.createDefaultLight();

var helperLight = scene.lights[scene.lights.length - 1];

//OR

var helperLight = scene.lights.pop();
scene.lights.push(helperLight);
```

<Playground id="#MJNICE#9" title="Light Helper With Direction and Color Change" description="Simple example of the light helper and changing the light's color and direction."/>

## Create Default Environment

The simple code

```javascript
scene.createDefaultEnvironment();
```

adds a skybox and ground to the scene, sets a wide range of environmental parameters, and returns an [environmental helper](/typedoc/classes/babylon.environmenthelper).

You will also find below a helper for [just a skybox](/features/featuresDeepDive/scene/fastBuildWorld#create-default-skybox).

When you look at the following playground:

<Playground id="#MJNICE" title="Playground Fast Build" description="Simple example of creating the default enviornment in the playground."/>

it is not obvious that a skybox and ground have been added. The defaults have been set to be very subtle and to help give the objects a grounded feel.

Moving the camera further out shows that the skybox is constructed.

<Playground id="#MJNICE#1" title="Skybox Example" description="Simple example showing how to create a skybox."/>

You can also see the skybox and ground by using the options parameter and setting different values for the skybox texture and the ground color.

<Playground id="#MJNICE#10" title="Skybox and Ground Changes" description="Simple example of creating a skybox and ground and changing their properties."/>

### Options Parameters

As you can see in the above playground, the `createDefaultEnvironment` method takes an options parameter. The full range of environmental helper option properties is available in the [API](/typedoc/interfaces/babylon.ienvironmenthelperoptions).

So, for example

to prevent the creation of the skybox:

```javascript
var helper = scene.createDefaultEnvironment({
  createSkybox: false,
});
```

to enable ground reflection:

```javascript
var helper = scene.createDefaultEnvironment({
  enableGroundMirror: true,
});
```

when you see z-fighting with the ground, modify the `groundYBias` to a larger number:

```javascript
var helper = scene.createDefaultEnvironment({
  groundYBias: 0.01,
});
```

### Applicable Methods

Since the `createDefaultEnvironment` method returns an `environmentalHelper` object, all the properties and methods of this object (as described in the [API](/typedoc/classes/babylon.environmenthelper)) are available.

So, for example, if the environment color is not your preferred choice, you can modify it after creation:

```javascript
var helper = scene.createDefaultEnvironment();
helper.setMainColor(BABYLON.Color3.Teal());
```

<Playground id="#MJNICE#12" title="Changing The Main Color" description="Simple example of changing the scene's main color."/>

Or, if you wish to dispose of the ground after creating the environment, use:

```javascript
var helper = scene.createDefaultEnvironment();
helper.ground.dispose();
```

Or you can change the option parameters:

```javascript
var helper = scene.createDefaultEnvironment();
var options = {
  skyboxTexture: new BABYLON.CubeTexture("/textures/skybox", scene),
};
helper.updateOptions(options);
```

<Playground id="#MJNICE#13" title="Changing Scene Options" description="Simple example showcasing how to change options of the scene."/>

### Environmental Helper

NOTE: The environment helper relies exclusively on the [BackgroundMaterial](/features/featuresDeepDive/environment/backgroundMaterial) to be as efficient as possible.

## Create Default Skybox

The `createDefaultSkybox` method can be used when you do not want to create a full environment. The [parameters](/typedoc/classes/babylon.scene#createdefaultskybox) used determine how the skybox is created.

for example

```javascript
var texture = new BABYLON.CubeTexture("/assets/textures/SpecularHDR.dds", scene);
scene.createDefaultSkybox(texture, true, 100);
```

In this case the first two parameters used give the texture for the skybox and specify that [a PBRMaterial](/features/featuresDeepDive/materials/using/introToPBR) is to be used (second parameter, _true_) as opposed to a standard material (second parameter, _false_ - default value).

The third parameter defines the scale of your skybox (this value depends on the scale of your scene), the default value is _1000_.

<Playground id="#MJNICE#14" title="Skybox Scale Example" description="Simple example showing how to scale a skybox in the playground."/>

## Import and Fastest Build

To import models and build a world very quickly, just use `createDefaultCameraOrLight` along with `createDefaultEnvironment`, as in this example:

<Playground id="#MJNICE#15" title="Importing Models and Quickly Building A World" description="Simple example showcasing how to import models and quickly build a world."/>

The camera adjusts its position automatically to make the world viewable depending on the scale and position of the models. More information on importing models with the scene helpers follows below.

## Importing Models for Your World

Since the `createDefault...` helpers take into account any models in the scene, they can only be applied after the model is loaded, so they are placed in the callback function. For example:

```javascript
BABYLON.AppendSceneAsync("https://www.babylonjs.com/assets/DamagedHelmet/glTF/", "DamagedHelmet.gltf", scene).then(function ({ meshes }) {
  scene.createDefaultCameraOrLight(true, true, true);
  scene.createDefaultEnvironment();
});
```

There is then a problem. When creating a scene, Babylon.js checks for a camera. When importing models, the existence of a camera will be checked before the model has finished loading, so the scene will fail.

The solution is to replace the `createScene` function with the `delayCreateScene` function. Whether in a playground or in your own project this is a direct replacement.

**NOTE:** Other [scene loader](/features/featuresDeepDive/importers/loadingFileTypes) methods are available.

### Using Scene Helpers with Import

All the helper methods described earlier on this page behave in exactly the same way when importing models. Just remember to call them within the scene loader callback.

### Import Playground Examples

<Playground id="#10D6YT#33" title="Simple Import and Main Color Change" description="Simple example of importing a scene and changing the main color."/>
<Playground id="#10D6YT#35" title="Importing Blur, Reflections, and Shadow" description="Simple example showing how to import blur, reflections, and shadows."/>


# New: FloatingOriginMode
Since this page was written, we have introduced floatingOriginMode to the scene (and useLargeWorldRendering to the engine). See [Large World Rendering / Floating Origin](/features/featuresDeepDive/scene/large_world).


## How floating-origin works

In traditional 3D rendering, objects pass through three stages before they are displayed on screen:

- World matrix: places, scales and rotates the object on the world;
- View matrix: will translate and rotate relative to camera;
- Projection matrix: will project vertices to screen.


This is well known and works perfectly.

The only problem is that our GPUs are still limited to 32-bit floating point, so when we have large coordinates—objects and/or cameras very far from the world's origin, for example at (10000000, 0, 10000000)—we will notice jittering because the large numbers inside matrices cause 32-bit floating-point imprecision on the GPU.

![Pic01](/img/how_to/floating_origin/pic01.webp)

But there is a trick that helps mitigate that problem: floating origin, first described by Chris Thorne [^1].

The idea of floating origin is very simple: keep the camera fixed at the world's origin
(0, 0, 0) and move the objects instead.

This does not mean that the camera cannot move, though. It "moves," but not directly. Here is
where the trick lies: instead of changing the real camera position, we use a separate, double-precision [^*]
Vector3 that stores the camera position. The real camera position is always kept at the origin (0, 0, 0).

We do the same for the objects: all of them get a separate, double-precision Vector3 to store their coordinates. We don't set their real positions directly; instead, we set their separate coordinates.

Then, in a loop that runs every frame just before rendering, we subtract the camera's double-precision position from each object's double-precision position, and that difference is copied to the object's real position.

The result is that the camera is always kept at the origin, and the objects float around it, removing
huge coordinates from the objects that are close to the camera. In other words, imprecision only happens very far
from the camera, and because those objects are already far away, we cannot see the jittering.

![Pic02](/img/how_to/floating_origin/pic02.webp)

Let's use an example:

In a solar system, we have an asteroid located at (10000000, 0, 10000000).
Our camera is close to the asteroid, at (10000000, 0, 10000500).

Normally, that would certainly cause jittering, because both objects are very far from the world's origin. But with
our trick, the jittering does not happen—remember, we subtract the camera's double-precision position from the object's double-precision position
and then set the object's real position to that offset, keeping the camera always at (0, 0, 0):

Object Position: (10000000, 0, 10000000)  
Camera Position: (10000000, 0, 10000500)  
Offset: (0, 0, -500)

The offset is small enough to be absolutely precise even with only 32-bit floating point. The GPU is very happy with that,
and we don't see any jittering.

We just need to set the object at (0, 0, -500) and it will have the same visual effect as if we used its real coordinates,
but with no jittering.

## Floating-origin examples

You can find a working playground example with OriginCamera and Entity classes here:  

<Playground id="#LHI514#66" title="Floating-Origin" description="A simple example of huge scene far from world's origin using floating-origin trick." image="/img/playgroundsAndNMEs/divingDeeperFloatingOrigin.webp"/>


If you decide to use floating origin, all your objects will have to use the same trick, or your game won't work properly. You will need to create one instance of OriginCamera
and at least one instance of Entity.

OriginCamera is a special camera that has a separate position control stored as doublepos (and its target as doubletgt). 
You must stop using position and target from the camera, and use their double-precision counterparts, doublepos and doubletgt.

All objects in the scene must then be parented to an Entity instance. Entity also has a doublepos property, which is a double-precision coordinate. 
You must use its doublepos to set an object's position instead of using position directly.

So, let's say that we want a sphere with double precision:

```javascript
// Create the OriginCamera
let camera = new OriginCamera("camera", new BABYLON.Vector3(10000000, 0, 10000500), scene);
camera.doubletgt = new BABYLON.Vector3(10000000, 0, 10000000);
camera.touchAngularSensibility = 10000;
camera.inertia = 0;
camera.speed = 1;
camera.keysUp.push(87);    		// W
camera.keysDown.push(83)   		// D
camera.keysLeft.push(65);  		// A
camera.keysRight.push(68); 		// S
camera.keysUpward.push(69);		// E
camera.keysDownward.push(81);     // Q
camera.minZ = 0.5;
camera.maxZ = 50000000;
camera.fov = 1;
camera.attachControl(canvas, true);

// Create an Entity for the sphere
let entSphere = new Entity("entSphere", scene);
camera.add(entSphere);

// Create the sphere and parent it to its Entity
let sphere = BABYLON.CreateSphere("sphere", {diameter:256});
sphere.parent = entSphere;

// Position the Entity
entSphere.doublepos = new BABYLON.Vector3(10000000, 0, 10000000);
```  

The OriginCamera extends UniversalCamera, so you can use the same features as that camera.

Finally, even in huge scenes, you will commonly have objects spread across separate regions, so you
most likely would not need one Entity instance for each object. If you plan carefully, you
can have one Entity instance for each region of your scene, as long as a region does not extend for more
than, say, 10,000 units, to avoid imprecision again. Then, you can add many objects that are
always in that region to a single Entity. By doing that, you can even move those objects by using
their positions directly, as you normally would. Even then, no visible imprecision will remain.

Article and code written by Vander R. N. Dias

[^1]: Chris Thorne, 2005. Using a Floating Origin to Improve Fidelity and Performance of Large Distributed Virtual Worlds
[^*]: The original article by Chris Thorne uses single-precision floats.



## How to Interact with A Scene

There are three main ways for a user to interact with a scene: the keyboard, the [GUI](/features/featuresDeepDive/gui), and directly through a mouse, touch, or gamepad. The use of keyboard and pointer interactions is described on this page.

## Keyboard Interactions

This is a code template to control reactions to different keys. Both the `ASCII` code for the key and the key itself are available to you.

```javascript
scene.onKeyboardObservable.add((kbInfo) => {
  switch (kbInfo.type) {
    case BABYLON.KeyboardEventTypes.KEYDOWN:
      console.log("KEY DOWN: ", kbInfo.event.key);
      break;
    case BABYLON.KeyboardEventTypes.KEYUP:
      console.log("KEY UP: ", kbInfo.event.code);
      break;
  }
});
```

## Pointer Interactions

This is a code template for reacting to pointer events:

```javascript
scene.onPointerObservable.add((pointerInfo) => {
  switch (pointerInfo.type) {
    case BABYLON.PointerEventTypes.POINTERDOWN:
      console.log("POINTER DOWN");
      break;
    case BABYLON.PointerEventTypes.POINTERUP:
      console.log("POINTER UP");
      break;
    case BABYLON.PointerEventTypes.POINTERMOVE:
      console.log("POINTER MOVE");
      break;
    case BABYLON.PointerEventTypes.POINTERWHEEL:
      console.log("POINTER WHEEL");
      break;
    case BABYLON.PointerEventTypes.POINTERPICK:
      console.log("POINTER PICK");
      break;
    case BABYLON.PointerEventTypes.POINTERTAP:
      console.log("POINTER TAP");
      break;
    case BABYLON.PointerEventTypes.POINTERDOUBLETAP:
      console.log("POINTER DOUBLE-TAP");
      break;
  }
});
```

[PEP](https://github.com/jquery/PEP) is an option for supporting **touch** events in older browsers (ones that don't natively support [pointer events](https://caniuse.com/pointer)). To use PEP, all that is necessary is to:

1. Install PEP

```javascript
<script src="https://code.jquery.com/pep/0.4.3/pep.js"></script>
```

2. Stop the default touch-action within the rendering canvas

```javascript
<canvas id="renderCanvas" touch-action="none"></canvas>
```

## Playground Examples

<Playground id="#0XYMA9#107" title="Scene Observables Template" description="Simple scene observables template." image="/img/playgroundsAndNMEs/divingDeeperInteractions1.webp" isMain={true} category="Interactions"/>
<Playground id="#7CBW04" title="Simple Drag Example" description="Simple example of a drag behavior." image="/img/playgroundsAndNMEs/divingDeeperInteractions2.webp" isMain={true} category="Interactions"/>
<Playground id="#XZ0TH6" title="Simple Keyboard Input Example" description="Simple example of keyboard input." image="/img/playgroundsAndNMEs/divingDeeperInteractions3.webp" isMain={true} category="Interactions"/>
<Playground id="#2SA7J8#7" title="Click+Drag to Multi Select" description="Simple example of how to multi-select objects in a scene using rectangular selection." isMain={true} category="Interactions"/>

Remember to click in the scene (to set focus) before using the keyboard.



# Large World Rendering / Floating Origin

## The Problem

When working with very large world coordinates, 32-bit floating point numbers lose precision. A float32 value can represent roughly 7 significant decimal digits, which means that at a world position of 1,000,000 units from the origin, the smallest representable step is about 0.06 units. This loss of precision causes visible **jittering** — meshes wobble, shadows flicker, and animations stutter — even though the objects themselves are not moving.

This is a well-known problem in flight simulators, space games, open-world titles, and any application where the camera can be very far from the world origin.

## The Solution: Floating Origin and HighPrecisionMatrices

Babylon.js provides a **floating origin** system that eliminates precision issues by keeping the active camera conceptually at the world origin and offsetting all geometry and shader uniforms by the camera's position. This means that no matter how far you travel from the original world origin, the values sent to the GPU are always small and precise.

The system has two complementary parts:

1. **`useLargeWorldRendering`** — an engine option that sets both `useHighPrecisionMatrices` on the engine and enables `floatingOriginMode` on all scenes.
    - `useHighPrecisionMatrices` forces **high precision (64-bit) matrix computations** on the CPU, so intermediate math remains accurate.
    - `floatingOriginMode` **offsets all matrix uniforms** (`world`, `view`, `viewProjection`, `worldViewProjection`, etc.) so the camera is treated as being at the world origin, and **offsets position-related values** (`eye position`, `clip planes`, etc.) by the camera's actual position. This is all performed at the last stage before passing the values to the shader.
2. **`useFloatingOrigin`** — a scene option that enables `floatingOriginMode` when not all scenes are large worlds. If only some scenes use `useFloatingOrigin`, you must also instantiate the engine with `useHighPrecisionMatrices` to get full large-world rendering capabilities.



From the perspective of your application code, nothing changes — meshes are still positioned at their world coordinates, the camera moves normally, and all existing APIs work as before. The offsetting happens at the rendering layer and is not detectable by the user.

## Examples

<Playground id="#5U0N0Q" title="Large World Rendering Demo" description="Side-by-side comparison of rendering with and without floating origin enabled. Move the camera to see jitter" image="/img/playgroundsAndNMEs/floatingOriginMain.webp" />
## Quick Start

The simplest way to enable floating origin is at the engine level:

```javascript
const engine = new BABYLON.Engine(canvas, true, {
    useLargeWorldRendering: true,
});

// All scenes created from this engine will automatically use floating origin
const scene = new BABYLON.Scene(engine);
```

Setting `useLargeWorldRendering: true` does two things:

1. Enables `useHighPrecisionMatrix` — all `Matrix` computations use 64-bit doubles internally.
2. Enables `floatingOriginMode` on every scene created by this engine.

### Per-Scene Control

If you only want floating origin on specific scenes (for example, your main world scene but not a UI scene), you can enable it per-scene instead. In this case, you must also enable high precision matrices on the engine:

```javascript
const engine = new BABYLON.Engine(canvas, true, {
    useHighPrecisionMatrix: true,
});

// Only this scene will use floating origin
const worldScene = new BABYLON.Scene(engine, { useFloatingOrigin: true });

// This scene will NOT use floating origin
const uiScene = new BABYLON.Scene(engine);
```

## API Reference

### Engine Options (`AbstractEngineOptions`)

| Option                   | Type      | Default | Description                                                                                                                              |
| ------------------------ | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `useLargeWorldRendering` | `boolean` | `false` | Enables both high precision matrices and floating origin mode on all scenes.                                                             |
| `useHighPrecisionMatrix` | `boolean` | `false` | Forces 64-bit matrix computations. Required for proper large world rendering. Automatically set when `useLargeWorldRendering` is `true`. |

### Scene Properties

| Property                     | Type                 | Description                                                                                                                             |
| ---------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `scene.floatingOriginMode`   | `boolean` (readonly) | `true` if floating origin is active on this scene.                                                                                      |
| `scene.floatingOriginOffset` | `Vector3` (readonly) | The current offset applied to all rendering. Equal to the active camera's eye position when enabled, or `Vector3.Zero()` when disabled. |

### Scene Options (`ISceneOptions`)

| Option              | Type      | Default | Description                                      |
| ------------------- | --------- | ------- | ------------------------------------------------ |
| `useFloatingOrigin` | `boolean` | `false` | Enables floating origin for this specific scene. |

## How It Works

### Matrix Interception

When floating origin mode is active, Babylon.js monkey-patches `Effect.setMatrix` and `UniformBuffer._updateMatrixForUniform` to intercept every matrix being sent to shaders. Based on the uniform name, the system applies the appropriate offset:

- **`world`** — The world matrix translation is shifted by subtracting the camera position.
- **`view`** — The view matrix translation is zeroed out (since the camera is conceptually at the origin).
- **`worldView`** — Decomposed into world and view, each offset separately, then recomposed.
- **`viewProjection`** — The view is offset and remultiplied with the projection matrix.
- **`worldViewProjection`** — Fully decomposed, offset, and recomposed.

This also works with **Node Material** custom blocks, where uniform names are prefixed with `u_` (e.g., `u_World`, `u_ViewProjection`).

### Additional Offsets

Beyond matrices, the system also offsets:

- **Eye position** (`vEyePosition`) — Shifted so lighting and reflections compute correctly relative to the offset geometry.
- **Clip planes** — Adjusted using the formula `d' = d + normal · offset` so clipping works at the correct world-space boundaries.

### What Is Handled Automatically

The following Babylon.js subsystems are floating-origin-aware and require no additional work:

- Standard and PBR materials
- Node Materials
- Shadow generators (including cascaded shadow maps)
- Particles (GPU and CPU)
- Sprites
- Lights (point, spot, area, clustered)
- Bounding box and edge renderers
- Background and sky materials
- Water material
- Atmosphere addon
- Utility layers (gizmos, overlays, etc.)

### **A note about Custom shaders.** 
If you have custom shaders that use position-based uniforms, ensure they use standard uniform names (`world`, `view`, `viewProjection`, `worldViewProjection`) so the floating origin system can intercept and offset them automatically. For Node Materials, block uniforms prefixed with `u_` are handled automatically.

## Physics: Havok Multi-Region Support

### The Physics Precision Problem

The floating origin system keeps rendering precise by offsetting values before they reach the GPU. However, the **Havok physics engine** also uses 32-bit floats internally. If physics bodies are positioned at large world coordinates, the same precision loss occurs in the physics simulation — bodies jitter, collisions become unreliable, and constraints break down.

### Multi-Region Worlds

To solve this, the Havok plugin implements a **multi-region** architecture. Instead of simulating all bodies in a single physics world, bodies are distributed across multiple Havok world instances, each with its own **fixed floating origin**. Bodies within a region are simulated using coordinates relative to that region's origin, keeping all values small and precise.

This happens automatically when `floatingOriginMode` is enabled on the scene. You don't need to manually manage regions — the plugin handles creation, assignment, and cleanup.

### How It Works

1. **Region creation**: When a physics body is created, the plugin checks if an existing world region contains its world position (within the configured radius). If not, a new region is created centered at that position.

2. **Body simulation**: Each body stores its transform relative to its region's floating origin. From the body's perspective, it is always near the origin of its local physics world.

3. **Region migration**: During each physics step, bodies that have moved outside their current region's boundary (with a 20% hysteresis margin to prevent oscillation) are automatically migrated to the correct region. Linear and angular velocity are preserved across the transition.

4. **Velocity-based look-ahead**: When a body leaves its region, the plugin projects its position forward by one second of travel to find the best target region. This prevents creating unnecessary intermediate regions for fast-moving bodies heading toward existing regions.

5. **Garbage collection**: Empty non-default regions are automatically cleaned up when all their bodies have migrated elsewhere.

6. **Per-region gravity**: Each world region can have its own gravity vector, enabling scenarios like planetary bodies with different gravitational fields.

### Configuration

The Havok plugin accepts an optional `floatingOriginWorldRadius` parameter:

```javascript
const havokInstance = await HavokPhysics();
const havokPlugin = new BABYLON.HavokPlugin(true, havokInstance, {
    floatingOriginWorldRadius: 100000, // default: 100,000 units
});

scene.enablePhysics(new BABYLON.Vector3(0, -9.81, 0), havokPlugin);
```

| Parameter                   | Type     | Default  | Description                                                                                                                                                                                   |
| --------------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `floatingOriginWorldRadius` | `number` | `100000` | The radius of each physics world region. Bodies within this distance of a region's origin are simulated in that region. Bodies outside all existing regions trigger creation of a new region. |

Choose a radius that balances precision with the number of regions:

- **Larger radius** = fewer regions, but bodies farther from region origins may still lose some precision.
- **Smaller radius** = more regions and better precision, but more overhead from region management and body migration.

For most applications, the default of 100,000 units provides a good balance.

### Per-Region Gravity

You can set gravity for a specific world region by passing a world position to `setGravity`:

```javascript
// Set gravity for the region containing this position
havokPlugin.setGravity(new BABYLON.Vector3(0, -1.62, 0), new BABYLON.Vector3(500000, 0, 0));

// Get gravity for a specific region
const gravity = havokPlugin.getGravity(new BABYLON.Vector3(500000, 0, 0));
```

When called without a position, `setGravity` and `getGravity` operate on all regions or return the default gravity.








## Physics Examples

<Playground id="#9NRVWK" title="Havok+FloatingOrigin Stacked Boxes" description="Side-by-side view of havok physics far from world origin, with floatingorigin mode enabled/disabled" image="/img/playgroundsAndNMEs/havokFloatingOriginStacked.webp"/>

<Playground id="#24ZAQP" title="Havok+FloatingOrigin BoomBox" description="Side by side of havok physics with floating origin enabled / disabled" image="/img/playgroundsAndNMEs/havokBoombox.webp" />

<Playground id="#7N17MT#26" title="Havok Multi-Region with Dynamic Re-Regioning" description="Demonstrates multi-region physics with dynamic re-regioning. Use 'Launch Ball' to test physics drift collision across regions, and 'Move Box' to test teleporting bodies between regions." image="/img/playgroundsAndNMEs/havokFloatingOrigin.webp" />


# In-Depth layerMask

`layerMask` is a property you can find on many objects and may be a bit difficult to grasp at first. This page should give you a good understanding of how it works across Babylon.js objects.

## layerMask meaning

`layerMask` is a value that can be assigned to different objects (like meshes, cameras, layers, particle systems, etc.) and is used to determine the visibility of one object from another (for example, whether a mesh is visible from a camera or whether a layer should be displayed after a given camera is processed).

The only two things to understand with `layerMask` are that:
* it can be any number from 0 to 0xFFFFFFFF (or 4294967295, but it’s easier to write 0xFFFFFFFF)
* when computing a visibility flag, two values of `layerMask` are **AND**ed and if the result is different from 0 the flag is true

So, for example, if `camera.layerMask = 35` and `mesh.layerMask = 2`, `35 & 2 == 2 != 0`, so the mesh is visible from this camera. We often show these numbers in hexadecimal because doing the **AND** as a mental calculation is easier that way: `35=0x23` and `2=0x02` and `35 & 2 == 0x23 & 0x02`, and from this latter representation it’s easier to see that the result is 2 (well, at least when you are a bit comfortable with hexadecimal!).

## Usage in Babylon.js

In Babylon, by default all `layerMask` properties are `0x0FFFFFFF` (for Camera, Mesh, Layer, …). So, when it comes to determining visibility, `0x0FFFFFFF & 0x0FFFFFFF != 0` and everything is always visible (at least from the standpoint of the `layerMask` test).

As you can see, there are 4 bits not set by default in the `layerMask` (the leading `0` before the first `F`). This makes `layerMask` easier to use, as a common use case is to hide some meshes from a camera. To achieve that, you need to set a `layerMask` on the meshes so that the **AND** operation with the `layerMask` of the camera (`0x0FFFFFFF` by default) is 0: you can use `0x10000000`, `0x20000000`, `0x40000000` or `0x80000000`. Now you can see why showing these numbers in hexadecimal helps: it’s a lot easier to see that `0x10000000 & 0x0FFFFFFF = 0` than `268435456 & 268435455`!

If the default value for `layerMask` was `0xFFFFFFFF`, you would also need to update the `layerMask` of your camera to have your meshes invisible from it because `0xFFFFFFFF` is an all-one 32 bit value. So the `0x0FFFFFFF` value is simply a default value that can help make your life a little easier, but in all generality you can put any value in the `layerMask` property of cameras, meshes, layers, etc (as in the `35 & 2` example above) and simply understand how it is used to compute visibility.

### Layers and Skeleton Animations
If the active camera in a scene is using a layerMask to hide meshes that are animated with skeletons, then other cameras that do show the meshes will not show the animation because the skeletons are not being updated. A solution is to prepare the skeleton before each frame is rendered.

```typescript
let scene: BABYLON.Scene
let avatar: BABYLON.TransformNode;

scene.onBeforeRenderObservable.add(onBeforeRender);

function onBeforeRender(scene:BABYLON.Scene, eventState: BABYLON.EventState){
    const meshes = avatar.getChildMeshes(false);

    meshes.forEach(prepareSkeleton);
}

function prepareSkeleton(mesh:BABYLON.AbstractMesh){
    const skeleton = mesh.skeleton;

    if (!skeleton) return;

    skeleton.prepare();
}
```



Starting with Babylon.js v4.1, it is now possible to use one engine on several canvases.

To do so, you need to create "views". A view is defined by a canvas (the target) and an optional camera (the definition of the view).

**Please note that when a view is registered, the canvas used to initialize the Engine becomes a "working" canvas and is no longer supposed to be displayed directly.**

## Creating a view

To create a view, you need to register the combination of a canvas and a camera to the engine:

```javascript
let view = engine.registerView(document.getElementById("renderCanvas1"), camera1);
```

Please note that you can also call the same code with no camera:

```javascript
let view = engine.registerView(document.getElementById("renderCanvas1"));
```

If the camera is undefined, the render loop will be executed for the view without changing anything in the active scenes.

## Removing a view

To remove a previously registered view, you can run the following code:

```javascript
engine.unRegisterView(document.getElementById("renderCanvas1"));
```

## Cameras

If a view is defined with a camera, the system will use it as the active camera to render the scene.

A view cannot be rendered if it has a defined camera and the underlying scene is using multiple active cameras (e.g. `scene.activeCameras.length > 0`).

## Multi scenes

You can use views to render multiple cameras from the same scene or from different scenes. As you control the render loop, it is up to you to test the `engine.activeView` to determine which view is currently rendered.

So your render loop could look like:

```javascript
let myRenderLoop = () => {
  if (engine.activeView.camera === undefined) {
    mainScene.render();
  } else if (engine.activeView.target === view1) {
    scene1.render();
  }
};
```

## Events

By default, scenes will capture events from the main rendering canvas (the one used to create the Engine). You can change that behavior by setting the `engine.inputElement` to the DOM element you want to use for events.

This must be done before creating a scene, or if you do it afterward, you have to run the following code:

```javascript
scene.detachControl();
engine.inputElement = myNewElement;
scene.attachControl();
```

## Performance

To ensure optimal performance, **multiple canvases on the same page should have the same size**, otherwise it forces a resize of the master canvas for each view, which is detrimental to performance.

From Babylon.js v5, views can also be disabled, for instance to improve performance when one or more canvases are offscreen.

```javascript
view.enabled = false;
```

## Demo

You can see a live demo here: https://www.babylonjs.com/Demos/Views/

The initialization code for this page can be found here: https://github.com/BabylonJS/Website/blob/master/build/Demos/Views/index.html



## How to Use Multiple Scenes

To use multiple scenes, create them with

```javascript
var scene0 = new BABYLON.Scene(engine);
var scene1 = new BABYLON.Scene(engine);
```

Then put the relevant camera, lights, and meshes inside each scene and call them in `runRenderLoop`.

```javascript
engine.runRenderLoop(function () {
  scene0.render();
  scene1.render();
});
```

However, this simple code has a potential problem. Remember that each `scene.render` call will try to clear what has been rendered before, and to avoid one scene erasing what another has rendered, you need to set `scene.autoClear = false` on all the scenes rendered on "top" of others:

```javascript
var scene0 = new BABYLON.Scene(engine);
var scene1 = new BABYLON.Scene(engine);
scene1.autoClear = false; 
```

```javascript
engine.runRenderLoop(function () {
  scene0.render();
  scene1.render(); // Since scene1's autoClear is false, it will not "erase" what scene0 has rendered.
});
```

### Multiple scenes on the Playground

However, there is a difference between writing multiple scenes within your own projects and trying them out in the Playground.

In your own project, it is easy enough to set up create scene functions for each scene and call them in the engine render loop. For example:

```javascript
var createScene0 = function () {
  var scene0 = new BABYLON.Scene(engine);

  //Add camera, light and meshes for scene0

  return scene0;
};

var createScene1 = function () {
  var scene1 = new BABYLON.Scene(engine);

  //Add camera, light and meshes for scene1

  return scene1;
};

//Any other code
var scene0 = createScene0();
var scene1 = createScene1();

engine.runRenderLoop(function () {
  scene0.render();
  scene1.render();
});
```

The Playground has its own engine render loop, which needs to be stopped before running your own version:

```javascript
var createScene = function () {
  var scene = new BABYLON.Scene(engine);

  //Add camera, light and meshes for scene

  ////////OTHER SCENE////////////////////
  var scene1 = new BABYLON.Scene(engine);

  //Add camera, light and meshes for scene

  ////////CONTROL ENGINE LOOP///////////
  setTimeout(function () {
    engine.stopRenderLoop();

    engine.runRenderLoop(function () {
      scene.render();
      scene1.render();
    });
  }, 500);

  return scene;
};
```

An example of switching the currently active scene on the Playground is as follows:
<Playground id="#P3E9YP" title="Switching Scenes" description="Simple example showing how to switch scenes." isMain={true} category="Scene"/>



An offscreen canvas is a canvas that can be rendered offscreen and on a different thread than the main UI thread.

It could be really interesting to do so if your main thread is already heavily used for other tasks.

You can see a page demonstrating this use case here: https://www.babylonjs.com/Demos/Offscreen/

<Youtube id="zYrZNROQzKQ"/>

# Setting up the engine

Starting with Babylon.js v4.1, you can create an engine inside a worker by initializing it with an offscreen canvas.

First, you need to create an offscreen canvas out of your regular canvas:

```javascript
var canvas = document.getElementById("renderCanvas");
canvas.width = canvas.clientWidth;
canvas.height = canvas.clientHeight;
var offscreen = canvas.transferControlToOffscreen();
```

Then you need to spin off a new worker and send it the offscreen canvas.

```javascript
var worker = new Worker("worker.js");
worker.postMessage({ canvas: offscreen }, [offscreen]);
```

The worker code will then listen for your message, get the offscreen canvas, and start Babylon.js as usual:

```javascript
onmessage = function (evt) {
  canvas = evt.data.canvas;
  var engine = new BABYLON.Engine(canvas, true);

  // Your scene setup here
};
```

Then you can use your engine as usual.

# Caveats

The main caveat of using Babylon.js with an offscreen canvas in a worker thread is that you will need to do special work to communicate with the engine from the main thread. You will have to use the same messaging API we used before to communicate between threads.

Furthermore, Babylon.js will not be able to handle inputs for you, so APIs like `camera.attachControls()` will not work and you will have to message inputs to workers.

Here is an example of communication you will have to set up to support canvas resizing.

On main thread:

```javascript
window.addEventListener("resize", () => {
  worker.postMessage({ width: canvas.clientWidth, height: canvas.clientHeight });
});
```

On worker thread:

```javascript
var engine;
onmessage = function (evt) {
  if (evt.data.width) {
    canvas.width = evt.data.width;
    canvas.height = evt.data.height;
  }
};
```

# Compatibility

Note that this feature is new and not yet compatible with every device or browser.
You can check current support of offscreen canvas here: https://caniuse.com/#feat=offscreencanvas

If you want to test the compatibility, you can add this condition before using offscreen canvas:

```javascript
if ("OffscreenCanvas" in window && "transferControlToOffscreen" in canvas) {
  // Ok to use offscreen canvas
}
```

# Resources

- https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas
- https://developers.google.com/web/updates/2018/08/offscreen-canvas



# How To Optimize Using Cached Resources

By default, all texture contents are cached by the engine, so if you load the same texture twice, it will be instantaneous (and the resource will be shared to save memory).

Starting with the **1.4 release** of Babylon.JS, you can indicate that you want to **cache the resources associated with your scene/game** inside the local **IndexedDB** of the browser. It can enhance the user experience because the JSON and texture files can be loaded directly from the database rather than from the web.

## Usage

To enable offline support, the first thing you need to do is create a _**.manifest**_ file associated with your scene. It should be named _NameOfYourScene.babylon.manifest_.

**Starting with Babylon.js v4.0 you also have to turn the feature on with:**

```javascript
engine.enableOfflineSupport = true;
BABYLON.Database.IDBStorageEnabled = true;
```

**Note:** by default, the Babylon engine is configured to use online resources. So if you don’t provide any .manifest file, it will assume that you want the resources to be loaded directly from the web all the time.
If you still want to cache the downloaded resources and do not provide a manifest, you can add the following flag to the engine:

```javascript
engine.disableManifestCheck = true;
```

It is better to use a manifest file, because it allows you to control the point at which the offline database is updated. Inside this **.manifest** file, insert the following piece of JSON:

```javascript
{
  "version" : 1,
  "enableSceneOffline" : true,
  "enableTexturesOffline" : true
}
```

When you’re loading a scene using the Babylon engine, one of the first things it will try is loading this manifest file and checking this JSON description. If not found (404), it will directly load the resources from the web. If found, it will load the values. You can then change those values anytime, they will be verified every time the engine loads your scene.

You have 3 parameters to fill:

1. The first one is _**version**_ and must be an integer. It’s simply the current version of your assets. If you change it, the Babylon engine will detect that change during the next reload of your scene. This will force a complete reload and update of all the assets in the browser’s database. This can be useful if you want to be sure that the client browser is using up-to-date textures or a recently updated scene description from your web server.

2. The second parameter _**enableSceneOffline**_ is a boolean. If set to true, you will be asking to load the JSON associated with your scene (the file with the .babylon extension) and store it into the local database of the user. Next time the user loads the game, the scene description will be directly loaded from the DB rather than from the hosting web server.

3. The third parameter _**enableTexturesOffline**_ is also a boolean. This time, you will be asking the Babylon engine to load all textures (PNG or JPG files) and store them into the local database of the user. Thus, the textures will be directly streamed from the database rather than the web server.

**Note:** images are loaded using XHR2 in the blob format. IE11, Firefox and Chrome 37+ support the storing of blob data into the IndexedDB. [More details](http://caniuse.com/#search=indexeddb)

## Exceptions

If you do not want to enable offline mode, you can set `engine.enableOfflineSupport = false`. This will completely turn off the feature.
If you want more fine-grained control, you can use the `scene.disableOfflineSupportExceptionRules` array:

```javascript
scene.disableOfflineSupportExceptionRules.push(/dude\.babylon/gi);
```

## Samples

Most of the samples on our [website mainpage](https://www.babylonjs.com) are configured to use offline for their scene and textures. For instance, you can try the [Espilit scene](https://www.babylonjs.com/Demos/GlowingEspilit/). The scene is described in _espilit.babylon_ and the associated manifest file is _espilit.babylon.manifest_.

One of the scenes is configured to cache only the texture. It’s the “[The Car](https://www.babylonjs.com/Demos/TheCar/)” scene. This is because the JSON file, _TheCar.babylon_, is more than 93 MB. IE11 and Chrome can’t store a file that large in their DB, so the decision was made to avoid trying to cache it.



## How To Optimize Your Scene with Octrees
Octrees are a really powerful data structure that can quickly select entities based on space coordinates.
More on wikipedia: http://en.wikipedia.org/wiki/Octree

Babylon.js supports octrees through a class named ```BABYLON.Octree```. Dedicated functions are available to help you create these octrees when required:

## Optimizing Meshes Selection for Rendering
If your scene has a lot of meshes, it can be useful to create an octree to speed up visible mesh selection (e.g. finding meshes the camera can see). To do so, just call this function:

```javascript
var octree = scene.createOrUpdateSelectionOctree(capacity, maxDepth)
```

You can call the function each time you want to update your octree. This function accepts two parameters:

* capacity: defines the maximum number of meshes you want on your octree's leaves. The default value is 64.
* maxDepth: defines the maximum depth (sub-levels) for your octree. Default value is 2, which means 8 * 8 * 8 = 512 blocks :) (This parameter takes precedence over capacity.)

**Warning: Octrees can be counterproductive if there are not enough meshes in your scene.**

# Managing Dynamic Meshes
The main problem with octrees is that your meshes must be static. Indeed, an octree is not dynamic, which means that it cannot take into account a mesh's movement.
If you want to have dynamic meshes while keeping your octree, you can just register a mesh as dynamic like this:

```javascript
octree.dynamicContent.push(mesh)
```

In this case, the octree will always select the dynamic mesh.

## Optimizing Collisions and Picking
Computing collisions or clicking on complex meshes (more than 10k vertices, for instance) can be really slow. You can speed things up by subdividing your mesh into submeshes using ```mesh.subdivide(x)``` where x is the number of submeshes you want.

Then you can optimize the selection of submeshes for collisions or picking by creating an octree on the mesh for its submeshes:

```javascript
mesh.createOrUpdateSubmeshesOctree(capacity, maxDepth)
```

You can even specify the usage of your octree independently:

* ```mesh.useOctreeForCollisions```
* ```mesh.useOctreeForPicking```
* ```mesh.useOctreeForRenderingSelection``` : An octree for submeshes can even be used during mesh selection based on the camera field of view. Once a mesh is selected by the camera, the camera has to select which submeshes are visible. In this case, having an octree can be really helpful.

## GroundMesh
For the specific case of ground meshes, Babylon.js provides a class called ```BABYLON.GroundMesh``` that you can create using ```BABYLON.MeshBuilder.CreateGround``` and ```BABYLON.MeshBuilder.CreateGroundFromHeightMap```.

By calling ```groundMesh.optimize(chunkSize)``` where chunkSize defines the number of submeshes you want, the mesh will be optimized for rendering, picking, and collisions by creating an internal octree (be sure to select an appropriate chunkSize).

## Using Octrees Manually
You can also use octrees from your code to get a list of meshes or submeshes.

Here are the helpful functions you can find on an octree:

* ```select(frustumPlanes: Plane[], allowDuplicate: boolean)```
* ```intersects(sphereCenter: Vector3, sphereRadius: number, allowDuplicate: boolean)```
* ```intersectsRay(ray: Ray)```

These functions return a [SmartArray](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Misc/smartArray.ts) where duplicates are present or not according to the ```allowDuplicate``` parameter.

## Demos
* <Playground id="#3YFJ5R#0" title="Octree Demo" description=""/>



## How To Optimize Your Scene

This tutorial will help you find links and information on how to improve your scene's rendering performance.

## Use TransformNode instead of AbstractMesh or empty meshes

If you need node containers or transform nodes, do not use meshes but TransformNode instead. Use meshes only when associated with content to render.

The meshes need to go through an evaluation process where the camera checks if they are in the frustum. This is an expensive process so reducing the number of candidates by using TransformNode when possible is a good practice.

## Reducing Shaders Overhead
Babylon.js uses an advanced, automatic shader engine. This system will keep shaders up to date regarding material options. If you are using a static material (ie. an immutable material), you can let Babylon.js know by using the following code:

```
material.freeze();
```

Once frozen, the shader will remain unchanged even if you change a material's properties. You will have to unfreeze it to update the inner shader:

```
material.unfreeze();
```

## Reducing World Matrices Computation
Every mesh has a world matrix to specify its position / rotation / scaling. This matrix is evaluated on every frame. You can improve performance by freezing this matrix. Any subsequent changes to position / rotation / scaling will then be ignored:

```
mesh.freezeWorldMatrix();
```

You can unfreeze a mesh with:

```
mesh.unfreezeWorldMatrix();
```

## Freezing the active meshes
If you are CPU-bound, you can decide to keep the list of active meshes unchanged and free the CPU time spent determining active meshes:

```
scene.freezeActiveMeshes();
```

You can unfreeze the active meshes with:

```
scene.unfreezeActiveMeshes();
```

Note that you can force a mesh to be in the active meshes before freezing the list with `mesh.alwaysSelectAsActiveMesh = true`.

Freezing the active meshes list may cause some things in the scene to stop updating. One example is [RenderTargetTexture](/features/featuresDeepDive/postProcesses/renderTargetTextureMultiPass), if it's used by mesh materials. In that case, the RTT needs to be explicitly added to the list of the active camera's custom render targets, which will guarantee that it ends up in the render list of the scene:

```javascript
camera.customRenderTargets.push(renderTargetTexture);
```

## Not updating the bounding info
In conjunction with `mesh.alwaysSelectAsActiveMesh` you can also decide to turn off bounding info synchronization. This way the world matrix computation will be faster as the bounding info will not be updated (this could be a problem if you want to use picking or collisions):

```
mesh.doNotSyncBoundingInfo = true;
```

## Not picking the scene on pointer move
On every pointer move, the scene browses the list of meshes to see if a mesh under the pointer may need to have an associated action / event raised.
To avoid this process, you can set `scene.skipPointerMovePicking = true`.

Please note that by doing so, you will have no event over any mesh when the pointer moves (and `scene.meshUnderPointer` will not be updated even if `scene.constantlyUpdateMeshUnderPointer === true`).

## Reducing draw calls
Whenever possible, please use [instances](/features/featuresDeepDive/mesh/copies/instances) as they are drawn with a single draw call.

If sharing the same material is a problem, you can use clones, which share the same geometry, with `mesh.clone("newName")`.

One remark regarding instances: If one of the instances has a world matrix with a different determinant (e.g. one instance has a negative scale while others don't), Babylon.js will be forced to remove back-face culling from their material.

## Reducing calls to gl.clear()
By default, Babylon.js automatically clears the color, depth, and stencil buffers before rendering the scene. It also clears the depth and stencil buffers after switching to a new camera and before rendering a new RenderingGroup. On systems with poor fill rates, these can add up quickly and have a significant impact on performance.

If your scene is set up in such a way that the viewport is always 100% filled with opaque geometry (if you're always inside a skybox, for instance), you can disable the default scene clearing behavior with:

```
scene.autoClear = false; // Color buffer
scene.autoClearDepthAndStencil = false; // Depth and stencil, obviously
```

If you know that the geometry in a particular RenderingGroup will always be positioned in front of geometry from other groups, you can disable buffer clearing for that group with the following:

```
scene.setRenderingAutoClearDepthStencil(renderingGroupIdx, autoClear, depth, stencil);
```
```autoClear```: ```true``` to enable auto clearing. If ```false```, overrides ```depth``` and ```stencil```

```depth```: Defaults to ```true``` to enable clearing of the depth buffer

```stencil```: Defaults to ```true``` to enable clearing of the stencil buffer

Go ahead and be aggressive with these settings. You'll know if it's not appropriate for your application if you see any smearing!

## Using depth pre-pass
When dealing with complex scenes, it could be useful to use a depth pre-pass. This technique will render designated meshes only in the depth buffer to leverage early depth test rejection. This could be used, for instance, when a scene contains meshes with advanced shaders.
To enable a depth pre-pass for a mesh, just call `mesh.material.needDepthPrePass = true`.

## Using unindexed meshes
By default Babylon.js uses indexed meshes where vertices can be reused by faces. When vertex reuse is low and when vertex structure is fairly simple (like just a position and a normal) then you may want to unfold your vertices and stop using indices:

```
mesh.convertToUnIndexedMesh();
```
For example this works very well for a cube where it is more efficient to send 32 positions instead of 24 positions and 32 indices.

## Turning AdaptToDeviceRatio Off/On
By default, Babylon.js no longer adapts to device ratio. It now focuses on performance rather than quality after many community requests.

The drawback is that this can look low-res. You can turn it on with the fourth parameter of the Engine constructor:

```
var engine = new BABYLON.Engine(canvas, antialiasing, null, true);
```

## Blocking the dirty mechanism

By default, the scene will keep all materials up to date when you change a property that could potentially impact them (alpha, texture update, etc.). To do so, the scene needs to go through all materials and flag them as dirty. This could be a potential bottleneck if you have a lot of materials.

To prevent this automatic update, you can execute:

```
scene.blockMaterialDirtyMechanism = true;
```

Do not forget to restore it to false when you are done with your batch changes.

## Using Animation Ratio
Babylon.js processes speed depending on the current frame rate.

On low-end devices, animations or camera movement may differ from what you see on high-end devices. To compensate, you can use:

```
scene.getAnimationRatio();
```

The return value is higher on low frame rates.

## Handling WebGL context lost
Starting with version 3.1, Babylon.js can handle the [WebGL context lost event](https://www.khronos.org/registry/webgl/specs/latest/1.0/#5.14.13). This event is raised by the browser when the GPU needs to be taken away from your code. This can happen, for instance, when using WebVR in a hybrid scenario (with multiple GPUs). In this case, Babylon.js has to recreate ALL low-level resources (including textures, shaders, programs, buffers, etc.). The process is entirely transparent and handled under the hood by Babylon.js.

As a developer, you should not be concerned with this mechanism. However, to support this scenario, Babylon.js may need additional memory to keep track of resource creation. If you do not need to support the WebGL context lost event, you can turn off the tracking by instantiating your engine with the doNotHandleContextLost option set to true.

If you created resources that need to be rebuilt (like vertex buffers or index buffers), you can use the `engine.onContextLostObservable` and `engine.onContextRestoredObservable` observables to keep track of the context lost and context restored events.

## Scene with large number of meshes
If you have a large number of meshes in a scene and need to reduce the time spent adding or removing those meshes, there are several `Scene` constructor options that can help:
 - Setting the option `useGeometryUniqueIdsMap` to `true` will speed-up the addition and removal of `Geometry` in the scene.
 - Setting the option `useMaterialMeshMap` to `true` will speed up disposing of `Material` by reducing the time spent looking for bound meshes.
 - Setting the option `useClonedMeshMap` to `true` will speed up disposing of `Mesh` by reducing the time spent looking for associated cloned meshes.

For each of these options that is turned on, Babylon.js will need an additional amount of memory.

Also, if you are disposing of a large number of meshes in a row, you can save unnecessary computation by setting the scene property `blockfreeActiveMeshesAndRenderingGroups` to true just before disposing the meshes, and setting it back to `false` just after, like this:
````javascript

scene.blockfreeActiveMeshesAndRenderingGroups = true;
/*
 * Dispose all the meshes in a row here
 */
scene.blockfreeActiveMeshesAndRenderingGroups = false;

````
## Changing Mesh Culling Strategy
Culling is the process of selecting whether a mesh must be passed to the GPU to be rendered or not. It's done on the CPU side.
If a mesh intersects the camera frustum in some way then it's passed to the GPU.
Depending on its accuracy (checking mesh bounding boxes or bounding spheres only, trying to include or exclude the mesh from the frustum quickly), this process can be time-consuming.
On the other hand, reducing this process's accuracy to make it faster can lead to some false positives: some meshes are passed to the GPU, are computed there, and still won't be visible in the viewport.
By default, Babylon.js applies the "Bounding Sphere Only" exclusion test to check if a mesh is in the camera frustum.
You can change this behavior for any mesh in your scene at any time (and change it back later, if needed) through the `mesh.cullingStrategy` property.
```javascript
/**
* Possible values :
         * - BABYLON.AbstractMesh.CULLINGSTRATEGY_STANDARD
         * - BABYLON.AbstractMesh.CULLINGSTRATEGY_BOUNDINGSPHERE_ONLY
         * - BABYLON.AbstractMesh.CULLINGSTRATEGY_OPTIMISTIC_INCLUSION
         * - BABYLON.AbstractMesh.CULLINGSTRATEGY_OPTIMISTIC_INCLUSION_THEN_BSPHERE_ONLY
*/

mesh.cullingStrategy = oneOfThePossibleValues;
```
* Standard : the most accurate and standard one. This is an exclusion test. The test order is:
  *  Is the bounding sphere outside the frustum ?
  *  If not, are the bounding box vertices outside the frustum ?
  *  If not, then the cullable object is in the frustum.
* Bounding Sphere Only : faster but less accurate. This is an exclusion test. It's faster than the standard strategy because the bounding box is not tested. It's also less accurate than the standard because some invisible objects can still be selected. The test order is:
  *  Is the bounding sphere outside the frustum ?
  *  If not, then the cullable object is in the frustum.
* Optimistic Inclusion : This is an inclusion test first, then the standard exclusion test. This can be faster when a cullable object is expected to be almost always in the camera frustum. This could also be a little slower than the standard test when the tested object's center is not in the frustum but one of its bounding box vertices is still inside. Anyway, it's as accurate as the standard strategy. The test order is:
  *  Is the cullable object bounding sphere center in the frustum ?
  *  If not, apply the default culling strategy.
* Optimistic Inclusion Then Bounding Sphere Only : This is an inclusion test first, then the bounding-sphere-only exclusion test. This can be the fastest test when a cullable object is expected to be almost always in the camera frustum. This could also be a little slower than the BoundingSphereOnly strategy when the tested object's center is not in the frustum but its bounding sphere still intersects it. It's less accurate than the standard strategy and as accurate as the BoundingSphereOnly strategy. The test order is:
  *  Is the cullable object bounding sphere center in the frustum ?
  *  If not, apply the Bounding Sphere Only strategy. No Bounding Box is tested here.

Optimistic Inclusion modes provide a small gain. They keep the same accuracy as the base mode to which they are applied (standard or bSphereOnly).
BoundingSphereOnly modes, because they reduce accuracy significantly, provide a good performance gain. These should not be used with high-poly meshes, because sending false positives to the GPU has a real rendering cost. These can be very interesting for numerous low-poly meshes instead. **Really useful if you are CPU-bound.**

## Performance Priority Modes

Starting with Babylon.js 5.22, you can now change how the scene prioritizes performance, backward compatibility, and ease of use.

### Backward compatibility mode (default)
By default, `scene.performancePriority` is set to `BABYLON.ScenePerformancePriority.BackwardCompatible`. In this mode, there is simply no change. The scene will keep prioritizing ease of use and backward compatibility.

### Intermediate mode
If you switch the `performancePriority` to `BABYLON.ScenePerformancePriority.Intermediate`, the scene will automatically:
* Freeze materials when they are ready. If you need to change something on a material, you will have to call `material.markDirty(true)` after making your changes
* New meshes will have their `alwaysSelectAsActiveMesh` property set to true. The system will then skip frustum clipping for the mesh and always set it to active (saving complex CPU operations). Keep in mind that you should turn it off if your scene is GPU-bound
* New meshes will have their `isPickable ` property set to false. Picking and action managers will not work anymore. You can always turn that property back on if you need picking for a specific mesh
* `scene.skipPointerMovePicking ` will be turned on (meaning that there will be no OnPointerMove events)
* `scene.autoClear` will be turned off

### Aggressive mode
If you switch the `performancePriority` to `BABYLON.ScenePerformancePriority.Aggressive`, the scene will automatically:
* Enable all features of the `Intermediate` mode
* The scene will skip all the frustum clipping phase entirely (`scene.skipFrustumClipping` will be set to true)
* New meshes will have their `doNotSyncBoundingInfo` set to true
* The manager will not reset between frames (`scene.renderingManager.maintainStateBetweenFrames` is set to true). This means that if a mesh becomes invisible or transparent, it will not be visible until this boolean is set to false again



**Please note that the `Intermediate` and `Aggressive` modes are not backward compatible, which means that we will probably add more performance-first features to these modes in the future.**

Here is an example: <Playground id="#6HWS9M" title="Performance Mode Example" description="Simple example of using Performance Mode." isMain={true} category="Scene"/>

## Instrumentation
Instrumentation is a key tool when you want to optimize a scene. It will help you figure out where the bottlenecks are so you can optimize what needs to be optimized.

### EngineInstrumentation
The EngineInstrumentation class allows you to get the following counters:
* *gpuFrameTimeCounter*: Time (in nanoseconds) spent by the GPU to render a single frame. Must be turned on with `instrumentation.captureGPUFrameTime = true`.
* *shaderCompilationTimeCounter*: Time (in milliseconds) spent by the CPU to compile all shaders. Must be turned on with `instrumentation.captureShaderCompilationTime = true`.

Here is an example of how to use engine instrumentation:
<Playground id="#HH8T00#1" title="Engine Instrumentation Example" description="Simple example of using engine instrumentation."/>

Please note that each counter is a *PerfCounter* object, which can provide multiple properties like average, total, min, max, count, etc.

The GPU timer requires a special extension (EXT_DISJOINT_TIMER_QUERY - also sometimes reported with the \_webgl2 prefix in WebGL2 context) in order to work. This extension had been disabled due to Spectre and Meltdown on all major browsers, but some have added it back, like Chrome and Edge. You can check if your browser supports this extension on the [Khronos SDK test page](https://www.khronos.org/registry/webgl/sdk/tests/conformance/extensions/ext-disjoint-timer-query.html) or on [WebGL report](https://webglreport.com/?v=2).

* Note: On Chrome mobile, this extension can be enabled at `chrome://flags#enable-webgl-developer-extensions`, followed by a browser restart.

### SceneInstrumentation
The SceneInstrumentation class allows you to get the following counters (per scene):
* *activeMeshesEvaluationTimeCounter*: Time (in milliseconds) spent to evaluate active meshes (based on active camera frustum). Must be turned on with `instrumentation.captureActiveMeshesEvaluationTime = true`.
* *renderTargetsRenderTimeCounter*: Time (in milliseconds) spent to render all render target textures. Must be turned on with `instrumentation.captureRenderTargetsRenderTime = true`.
* *drawCallsCounter*: Number of draw calls (actual calls to engine.draw) per frame. A good guideline is to keep this number as small as possible.
* *frameTimeCounter*: Time (in milliseconds) spent to process an entire frame (including animations, physics, render targets, special fx, etc.). Must be turned on with `instrumentation.captureFrameTime = true`.
* *renderTimeCounter*: Time (in milliseconds) spent to render a frame. Must be turned on with `instrumentation.captureRenderTime = true`.
* *interFrameTimeCounter*: Time (in milliseconds) spent between two frames. Must be turned on with `instrumentation.captureInterFrameTime = true`.
* *particlesRenderTimeCounter*: Time (in milliseconds) spent rendering particles (including animations). Must be turned on with `instrumentation.captureParticlesRenderTime = true`.
* *spritesRenderTimeCounter*: Time (in milliseconds) spent rendering sprites. Must be turned on with `instrumentation.captureSpritesRenderTime = true`.
* *physicsTimeCounter*: Time (in milliseconds) spent simulating physics. Must be turned on with `instrumentation.capturePhysicsTime = true`.
* *cameraRenderTimeCounter*: Time (in milliseconds) spent to render a camera. Must be turned on with `instrumentation.captureCameraRenderTime = true`.

Those counters are all reset to 0 at the beginning of each frame. Therefore, it is easier to access them in the `onAfterRender` callback or observable.

## Inspector

Starting with Babylon.js v4.0 you can use the Inspector to [analyze your scene](/toolsAndResources/inspectorv2) or turn on/off features or [debugging tools](/toolsAndResources/inspectorv2).

## VR/XR scenarios

When using Babylon.js with WebVR or WebXR, enabling [Multiview](/features/featuresDeepDive/cameras/multiViewsPart1) is a quick way to almost double the rendering speed.



# How To Reduce Memory Footprint

Babylon.js offers multiple options to reduce the memory usage of a scene:

## Turning off IndexedDB

By default, all assets are saved in the local IndexedDB to reduce network calls when loading the same files multiple times.
This feature uses memory so you can turn it off at engine level with:

```
 engine.enableOfflineSupport = false;
```

## Turning off support for context lost / context restore

Babylon.js will automatically recreate everything in a transparent way if the [WebGL context is lost](/features/featuresDeepDive/scene/optimize_your_scene#handling-webgl-context-lost).
While handy, this feature consumes a lot of memory, so you may want to turn it off when creating the engine with:

```
var engine = new BABYLON.Engine(canvas, true, {doNotHandleContextLost: true});
```

You can also turn it off after engine creation (but before creating any resources) with:

```
engine.doNotHandleContextLost = true;
```

## Removing cached vertex data

All vertex buffers keep a copy of their data in CPU memory to support collisions, picking, geometry editing, or physics.
If you don't need to use these features, you can call this function to free associated memory:

```
scene.clearCachedVertexData();
```

## Removing cached texture buffers

In order to be able to serialize or rebuild them, all textures keep an internal buffer of the original source (this could be a string if you used a URL, but it could also be a buffer if you used a blob).
If you don't need to use these features, you can call this function to free associated memory:

```
scene.cleanCachedTextureBuffer();
```


You can find a demo here: <Playground id="#AS54U8#1" title="Reducing Memory Footprint Example" description="Simple example showing how to reduce the memory footprint of a scene."/>



## Render a scene and take a screenshot on a remote server

Capturing images of a Babylon scene (e.g. a GLTF model) from the server side can be useful for scenarios such as:
- Remote rendering of a scene to display on a device that does not support a browser
- Server-side testing
- Creating a catalog of 3D model images

To get started, follow the steps below:

## Set up a Babylon scene you would like to render

Create a local server hosting the scene or use a Playground, e.g. <Playground id="#PN1NNI#1" title="Initial Setup" description="Simple example showing how to set up youur scene."/>

## Using Puppeteer
[Puppeteer](https://github.com/GoogleChrome/puppeteer) is an npm package that can be used to run and interact with a headless version of Chrome. This way, the same code written with Babylon to run in the browser should run the same way with Puppeteer.

Create a browser instance and load a webpage.
```
const browser = await puppeteer.launch({});
const page = await browser.newPage();
await page.goto("https://playground.babylonjs.com/frame.html#PN1NNI#1"); 
```

Inject JS into the webpage.
```
page.evaluate("BABYLON.Engine.LastCreatedScene.activeCamera.alpha = 1.4;");
```

Take a screenshot of the webpage.
```
await page.screenshot({path: './public/example.png'});
```
## Configuring to use the GPU
Typical server virtual machines do not provide access to a GPU, and when they do, setting up the proper drivers so Puppeteer can access it can be difficult. One method that has worked is using an [Azure NV virtual machine running Windows and installing grid drivers](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/n-series-driver-setup#nvidia-grid-drivers).

Once the VM is set up, Puppeteer must be configured to run in non-headless mode so that it uses the GPU renderer.
```
// Don't disable the gpu
var args = puppeteer.defaultArgs().filter(arg => arg !== '--disable-gpu');
// Run in non-headless mode
args = args.filter(arg => arg !== '--headless');
// Use desktop graphics
args.push("--use-gl=desktop")
// Lanch pupeteer with custom arguments
const browser = await puppeteer.launch({
    headless: false,
    ignoreDefaultArgs: true,
    args
});
```
After this initial setup, follow the same steps described above.

## Example
An example project can be found [here](https://github.com/TrevorDev/babylonServer).


# How to

The `CreateScreenshot` functions can be used to render a screenshot of your scene, allowing you to download it or even use it as a texture in the scene itself. The available methods are the following:

## CreateScreenshot

```javascript
scene.onReadyObservable.add(() => {
  BABYLON.Tools.CreateScreenshot(engine, camera, size, successCallback, mimeType, forceDownload, quality, useFill);
});
```

Observe that the screenshot creation is inside the scene's `onReadyObservable`, so it can wait for the meshes to be drawn. Otherwise, they won't appear in the screenshot.

<Playground id="#750168" title="Simple Screenshot Example" description="A simple example of how to use the CreateScreenshot method" />

The size parameter can be one of the following:

- A `{width: number, height: number}` with the width and height of the canvas and the created screenshot.
- A `{precision: number}` value that is a multiplier of the current resolution of the canvas.
- A single number indicating both width and height.

The optional `useFill` parameter, when set to true, allows the render canvas to fill the screenshot. Otherwise, the render canvas will be "letterboxed" if its aspect ratio does not match the aspect ratio of the screenshot size.

The success callback is a function that contains the screenshot as a string of base64-encoded characters. This string can be assigned to the src attribute of an `<img>` to display it, or it can be used to create a new Texture in the scene.

<Playground id="#750168#1" title="Use screenshot as texture" description="Example of how to use the CreateScreenshot callback to assign the screenshot data as a texture in the scene" />

More information about the other arguments of the function can be found in its [documentation page](/typedoc/classes/BABYLON.Tools#CreateScreenshot).

This function also has a `CreateScreenshotAsync` version that can be awaited using the [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await) keyword.

_NOTE: If creating a screenshot with a camera that is NOT the scene's active camera, use `CreateScreenshotUsingRenderTarget` instead._

## CreateScreenshotUsingRenderTarget

As the name suggests, this function renders the scene to a [RenderTargetTexture](/features/featuresDeepDive/postProcesses/renderTargetTextureMultiPass) for the screenshot. It has a few more [configuration options](/typedoc/classes/BABYLON.Tools#CreateScreenshotUsingRenderTarget):

```javascript
BABYLON.Tools.CreateScreenshotUsingRenderTarget(engine, camera, size, successCallback, mimeType, samples, antialiasing, fileName, renderSprites, enableStencilBuffer, useLayerMask, quality, customizeTexture);
```

The `customizeTexture` callback can be used to modify the texture before taking the screenshot. This can be used, for example, to modify its `renderList` property, changing which objects will appear in the screenshot. You can also turn post-processes [on or off](/features/featuresDeepDive/postProcesses/usePostProcesses).

<Playground id="#2mvlub#22" title="CreateScreenshotUsingRenderTarget" description="Example of how to modify the renderList and useCameraPostProcesses of a screenshot texture."/>

It also has a `CreateScreenshotUsingRenderTargetAsync` version.



## Record a Scene to a Video

First, you may ask why it is better than an external video capture tool.

As the HTML5 standard continues to evolve, modern browsers can now directly record a stream generated from a canvas. This ensures that no framerate drop occurs during recording, and it all happens automatically in the browser.

## How to record with the Inspector
A new action has been added to the Tools tab of the inspector. You can find a Start Recording Video button in compatible browsers.

![InspectorTools](/img/how_to/scene/inspectorVideoRecorder.webp)

This records 7 seconds of video by default. You can press the button again at any time during the recording session to stop it earlier.

## How to record by code

### Check support
Because browser support is still limited, recording the canvas should always be preceded by a capability check. You can use this code to ensure that the required APIs are available in your browser:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
}
```

### Simple Record
In order to record your currently displayed scene, you can simply use this code:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording();
}
```

You can see a <Playground id="#47H64G" title="Simple Video Recording Example" description="Simple example of recording a video of the current scene."/>

This will by default record 7 seconds of video to a file name "babylonjs.webm".

### Changing default File Name
You can pass the file name to the startRecording API:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording("test.webm");
}
```

You can see a live version here: <Playground id="#47H64G#1" title="Changing The Default Recorded Video Name" description="Simple example showing how to record a video of the current scene and change the default file name."/>

This will by default record 7 seconds of video to a file name "test.webm".

### Changing default Record Time
You can pass the default time in seconds to the startRecording API:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording("test.webm", 2);
}
```

You can see a live demo here: <Playground id="#47H64G#2" title="Chaning Default Record Time" description="Simple example showing how to change the default record time of recorded videos."/>

This will by default record 2 seconds of video to a file name "test.webm".

### Stop video before the Record Time
Once a recording is in progress, you can stop it earlier by using the `stopRecording` API:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording();
    setTimeout(() => {
        recorder.stopRecording()
    }, 500);
}
```

You can see a live version here: <Playground id="#47H64G#3" title="Stopping Video Before Record Time" description="Simple example showing how to stop recording before the allotted time has completed."/>

This will record 500 milliseconds of video to a file name "babylonjs.webm".

### When does recording end
To detect the end of the recording (either by reaching the record time or being manually stopped), you can use the promise returned by the `startRecording` API:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording().then(() => {
        alert("done");
    });
}
```

You can see a live version here: <Playground id="#47H64G#4" title="Detect Recording End" description="Simple example showing how to detect when a recording has ended."/>

This will record 7 seconds of video to a file name "babylonjs.webm" and display the "done" message.

### How not to download the file automatically
Passing `null` as the fileName will prevent the download from happening automatically and, as in the previous section, you can rely on the promise returned by `startRecording` to deal with the video data on your own:

```javascript
if (BABYLON.VideoRecorder.IsSupported(engine)) {
    var recorder = new BABYLON.VideoRecorder(engine);
    recorder.startRecording(null, 1).then((videoBlob) => {
        // Do Something with the videoBlob.
    });
}
```

You can see a live version here: <Playground id="#47H64G#5" title="Not Downloading The Recorded Video" description="Simple example showing how you can stop an automatic download of the recorded video."/>

This will record 1 second of video to a blob.

## Limitations
Video recording is based on both the MediaRecorder and Canvas.captureStream() APIs, which are still not broadly supported. Recording support is therefore limited by the browser's ability to record a canvas.

The second limitation is that the file format you can record to is currently limited to webm. You cannot directly record to .mp4 or .mov with this method so far.

Let's hope that wider browser and file format support will be added soon.



## How To Use **SceneOptimizer**

Rendering a scene in a browser is great because you can reach many different users and hardware configurations. However, the main caveat is that you may encounter very low-end devices.

The `SceneOptimizer` tool is designed to help you reach a specific framerate by gracefully degrading rendering quality at runtime.

## Basic usage

To start using the `SceneOptimizer`, you can create a new `BABYLON.SceneOptimizer` instance.
The `SceneOptimizer` constructor requires the current scene and a `BABYLON.SceneOptimizerOptions` object (we will come back to it later).

```javascript
var options = new BABYLON.SceneOptimizerOptions();
options.addOptimization(new BABYLON.HardwareScalingOptimization(0, 1));

// Optimizer
var optimizer = new BABYLON.SceneOptimizer(scene, options);
```

When creating the `SceneOptimizer`, you can provide the following parameters:
- A `BABYLON.Scene` which will define the scene to work on
- A `BABYLON.SceneOptimizerOptions` which will define the options to use with the `SceneOptimizer`
- A `boolean` which will define if priorities must be generated and not read from `SceneOptimization` property (true by default)
- A `boolean` which will define if the optimizer will run in improvement mode (see below) (false by default)

The `SceneOptimizer` object allows you to set several properties:
- `optimizations`: This property contains the list of current optimizations
- `targetFrameRate`: This property defines the target frame rate to reach (60 by default)
- `trackerDuration`: This property defines the interval between two checks (2000ms by default)
- `currentFrameRate`: This property (read-only) gets the current frame rate checked by the `SceneOptimizer`
- `currentPriorityLevel`: This property (read-only) gets the current priority level (0 at start)
- `onSuccessObservable`: This property defines an observable called when the optimizer reaches the target frame rate
- `onNewOptimizationAppliedObservable`: This property defines an observable called when the optimizer enables an optimization
- `onFailureObservable`: This property defines an observable called when the optimizer is not able to reach the target frame rate

It also provides several functions:
- `start()`: used to start the overall optimization process
- `stop()`: used to stop the current process
- `reset()`: used to restore the current priority level to 0
- `dispose()`: used to release all resources

## Helper

You can also use a static helper that will create everything you need in one line: `BABYLON.SceneOptimizer.OptimizeAsync()`. You can call this function when you want to optimize your scene. The simplest call is the following:

```javascript
BABYLON.SceneOptimizer.OptimizeAsync(scene),
```

You have to provide at least a scene. That previous line of code is actually equivalent to this:

```javascript
BABYLON.SceneOptimizer.OptimizeAsync(scene, BABYLON.SceneOptimizerOptions.ModerateDegradationAllowed(),
function() {
   // On success
}, function() {
   // FPS target not reached
});
```

As you can see, you can provide success/fail callbacks and a set of options.
Please note that the `BABYLON.SceneOptimizer.OptimizeAsync()` function returns a `SceneOptimizer` object which is created with `autoGeneratePriorities` set to false.

## Options

A set of options contains a list of optimizations to apply in a specific order. As soon as the target FPS is reached, the `SceneOptimizer` stops. There are different layers (or passes) that are applied one after another. The `SceneOptimizer` pauses between each layer to ensure a stable FPS and to measure it. Create a `BABYLON.SceneOptimizerOptions` like this:

```javascript
// With a target framerate of 50fps and a check|rate of 500ms
let optimizerOptions = new BABYLON.SceneOptimizerOptions(50, 500);
```

Here are the properties available on a `BABYLON.SceneOptimizerOptions` instance:

* `targetFrameRate`: a number defining the FPS you want to achieve (60 by default)
* `optimizations`: an array of `BABYLON.SceneOptimization` objects.
* `trackerDuration`: time in milliseconds between passes (2000 by default)

By default, there are 3 sets available:

```javascript
BABYLON.SceneOptimizerOptions.LowDegradationAllowed()
BABYLON.SceneOptimizerOptions.ModerateDegradationAllowed()
BABYLON.SceneOptimizerOptions.HighDegradationAllowed()
```

All these sets return a `BABYLON.SceneOptimizerOptions` object configured with progressive degradations.

Based on these optimizations, the basic sets are configured like this:

* **BABYLON.SceneOptimizerOptions.LowDegradationAllowed()**:

  

   * Level 0: `MergeMeshesOptimization`, `ShadowsOptimization` and `LensFlaresOptimization`
   * Level 1: `PostProcessesOptimization` and `ParticlesOptimization`
   * Level 2: `TextureOptimization(2, 1024)`

* **BABYLON.SceneOptimizerOptions.ModerateDegradationAllowed()**:

  

   * Level 0: `MergeMeshesOptimization`, `ShadowsOptimization` and `LensFlaresOptimization`
   * Level 1: `PostProcessesOptimization` and `ParticlesOptimization`
   * Level 2: `TextureOptimization`(2, 512)
   * Level 3: `RenderTargetsOptimization`
   * Level 4: `HardwareScalingOptimization`(4, 2)

* **BABYLON.SceneOptimizerOptions.HighDegradationAllowed()**:

  

   * Level 0: `MergeMeshesOptimization`, `ShadowsOptimization` and `LensFlaresOptimization`
   * Level 1: `PostProcessesOptimization` and `ParticlesOptimization`
   * Level 2: `TextureOptimization(2, 256)`
   * Level 3: `RenderTargetsOptimization`
   * Level 4: `HardwareScalingOptimization(4, 4)`

## The Built-in Optimizations.

The `priority` of an optimization is used by the `SceneOptimizer` to form a queue of optimizations. When performing optimizations, the `SceneOptimizer` starts with optimizations with lower `priority`, then continues to optimizations with higher `priorities`:



* `BABYLON.MergeMeshesOptimization(priority)`: This optimization will merge meshes with the same material.
* `BABYLON.TextureOptimization(priority, maximumSize)`: This optimization tries to reduce the size of render textures.
* `BABYLON.HardwareScalingOptimization(priority, maximumScale)`: This optimization increments or decrements the value of hardware scaling. This is a really aggressive optimization that could really help if you are GPU-bound.
* `BABYLON.ShadowsOptimization(priority)`: This optimization disables shadows (It will turn them on if the optimizer is in improvement mode (see below)).
* `BABYLON.PostProcessesOptimization(priority)`: This optimization disables post-processes (It will turn them on if the optimizer is in improvement mode (see below)).
* `BABYLON.LensFlaresOptimization(priority)`: This optimization disables lens flares (It will turn them on if the optimizer is in improvement mode (see below)).
* `BABYLON.ParticlesOptimization(priority)`: This optimization disables particles (It will turn them on if the optimizer is in improvement mode (see below)).
* `BABYLON.RenderTargetsOptimization(priority)`: This optimization disables render targets (It will turn them on if the optimizer is in improvement mode (see below)).
* `BABYLON.CustomOptimization(priority)`: This optimization will call two callbacks when required: 
 * `onApply(scene, optimizer)`: A custom callback used to apply custom optimizations. It must return true if all optimizations were applied
 * `onGetDescription()`: This callback must return a string describing the action of the optimization

### Custom Optimizations.

You can create your own optimizations by extending the class `BABYLON.CustomOptimization`. The new class must provide two functions, `onApply` and `onGetDescription`. Every instance takes a `priority` as its only argument, and it must be a number. For example:

```javascript
class MyCustomOptimization extends BABYLON.CustomOptimization{
    constructor(priority){
        super(priority)
    }

    onApply(){
        // Some optimizing code
    }
    onGetDescription(){
        // A desription of your optimization
        return "I make framerate go prrrr!";
    }
};

options.addOptimization(new MyCustomOptimization(2));
```

A much simpler shorthand is available, using the `addCustomOptimization` method, on a `BABYLON.SceneOptimizerOptions()` instance:

```javascript
// Using shorthand syntax, fn(onApply, onGetDescrition, priority)
options.addCustomOptimization(function () {
	// Some optimizing code
}, function () {
    return "Making optimizations...";
}, 0.6);
```

## Advanced Usage

You can create your own set of options with the following code (please note that if `autoGeneratePriorities` is true, you don't need to define the priority value):

```javascript
var result = new BABYLON.SceneOptimizerOptions(60, 2000);

var priority = 0;
result.optimizations.push(new BABYLON.ShadowsOptimization(priority));
result.optimizations.push(new BABYLON.LensFlaresOptimization(priority));

// Next priority
priority++;
result.optimizations.push(new BABYLON.PostProcessesOptimization(priority));
result.optimizations.push(new BABYLON.ParticlesOptimization(priority));

// Next priority
priority++;
result.optimizations.push(new BABYLON.TextureOptimization(priority, 256));

// Next priority
priority++;
result.optimizations.push(new BABYLON.RenderTargetsOptimization(priority));

// Next priority
priority++;
result.optimizations.push(new BABYLON.HardwareScalingOptimization(priority, 4));

return result;
```

## Improvement Mode

When created in improvement mode (4th parameter of the constructor), the `SceneOptimizer` object will run all optimizations while the current FPS is above the target frame rate. So, for instance, if the target FPS is 60, the optimizer will execute all optimizations in its list while the FPS remains at 60. It is a good tool for providing rendering improvements to a given scene.
Please note that when in improvement mode, the optimizations will adapt their behavior automatically (for instance, the `ShadowsOptimization` will turn shadows on instead of off).

## Demos

<Playground id="#3Q8PCL" title="Scene Optimizer Example" description="Simple example of how to use the scene optimizer."/>

<Playground id="#WZNAU4#4" title="CustomOptimization Example" description="A Playground Example Of The CustomOptimization in action"/>



# The Scene

The scene is somewhat like the stage on which all the meshes, cameras, and lights are placed so they can be viewed. Of course, a good scene includes more than meshes, cameras, and lights; for example, it may also include a user interface. There are also special effects that can make the environment more realistic. If you want to overlap two or more scenes, that is possible as well. 

If you want to build a scene with a minimum of code, fast build is for you. 

What else might you expect of your scene? You might expect to be able to

* have the scene react to clicks and touches;
* have your own design displayed when your scene is loading;
* optimise your scene to maintain a good speed;
* output images of particular views of your scene.


## How to use RenderTargetTexture and run multiple passes

Sometimes it is useful to render a scene multiple times and compose the generated passes into the final image. There are multiple uses for this: you can generate a texture in real time to make, for example, a car rearview mirror, or you can perform complex effects with multiple independent renders that are combined together. 

The PostProcess API doesn't let you render a scene twice. That's where RenderTargetTexture (RTT) comes into play. Several [games use multiple passes for their graphics](http://www.adriancourreges.com/blog/2016/09/09/doom-2016-graphics-study/).

## Creating a RenderTargetTexture

You need to create a RenderTargetTexture and attach it to the scene. It's pretty straightforward:

```    
var renderTarget = new BABYLON.RenderTargetTexture(
    'render to texture', // name 
    512, // texture size
    scene // the scene
);
scene.customRenderTargets.push(renderTarget); // add RTT to the scene
```

You also need to pick which objects will be rendered to that texture. This enables you to select only a few objects for a particular effect, or use simpler meshes for faster rendering.

```
let sphere = BABYLON.MeshBuilder.CreateSphere("sphere", {diameter: 2, segments: 32}, scene); // create your mesh
renderTarget.renderList.push(sphere); // add it to the RTT
```

## Using the RTT in your scene as a regular texture

You can use the rendered image as the texture of an object in your main render. Just set it as the texture of a material:

```
var mat = new BABYLON.StandardMaterial("RTT mat", scene);
mat.diffuseTexture = renderTarget;
```

In this example, we only add half of the spheres to the RTT, showing how you can selectively choose which objects are rendered there.

Playground example: <Playground id="#69DRZ1" title="Render Target Texture" description="Simple example of using the render target texture."/>

In this example we add two meshes, pool and ground, to the RTT and distort the UVs of the texture applied to the water plane using a node material to simulate refraction of the mesh behind the water plane.

Playground example: <Playground id="#7ILX7T" title="Water Refraction with RTT" description="Render Target Texture used to simulate water refraction." image="/img/playgroundsAndNMEs/NMEwaterRefractionRTT.webp" />

## Making multiple passes and composing them

Another possibility, as mentioned, is to make multiple render passes from the main camera and compose them. Let's do that by adding a simple effect to all meshes and composing it with the original material. One interesting effect to simulate with this technique is water caustics. We can render the scene with a material that simulates caustics using a wave generator and mix it with the base texture.

Since v5.0 it's very easy to use a different material than the regular material (`mesh.material`) when a mesh is rendered into a render target texture: simply use `RenderTargetTexture.setMaterialForRendering(meshOrMeshes, material)`.

```javascript
const causticMaterial = new BABYLON.ShaderMaterial(
    'caustic shader material', // human name
    scene,
    'caustic', // shader path
    {
        attributes: ['position', 'normal', 'uv'],
        uniforms: ['world', 'worldView', 'worldViewProjection', 'view', 'projection', 'time', 'direction']
    }
);

// the render texture. We'll render the scene with caustic shader to this texture.
const renderTarget = new BABYLON.RenderTargetTexture('caustic texture', 512, scene);
scene.customRenderTargets.push(renderTarget);

renderTarget.setMaterialForRendering(ground, causticMaterial);
```

For the final pass, we'll create a shader to merge the base render (which will be provided in the [GLSL](https://www.khronos.org/opengl/wiki/OpenGL_Shading_Language) as `textureSampler`) and the caustic texture, which we declare here as `causticTexture`. 

```javascript
// create the final pass composer
var finalPass = new BABYLON.PostProcess(
    'Final compose shader', 
    'final', // shader name
    null, // attributes
    [ 'causticTexture' ], // textures
    1.0,  // options
    camera,
    BABYLON.Texture.BILINEAR_SAMPLINGMODE, // sampling
    engine // engine
);
finalPass.onApply = (effect) => {
    effect.setTexture('causticTexture', renderTarget); // pass the renderTarget as our second texture
};
```

Playground example: <Playground id="#TG2B18#60" title="Multiple Passes Example" description="Simple example showing how to run multiple passes with the render target texture." isMain={true} category="Post-processing"/>. On the left you'll see the base render, in the middle the caustic render, and on the right both combined together.

## Performance and tips

Remember that you'll be rendering your scene multiple times, one for each pass. This can significantly slow things down if you are not careful. There are a number of strategies to improve performance:

- reduce the RTT size.
- render as few objects as you can on the RTT.
- use a simple shader on the RTT pass.
- prefer simpler meshes.
- use instances. If you have a large amount of copies of the same object, instances are a good optimization. You only change the material of the base mesh.

Replacing materials is an expensive operation in Babylon, as it requires a resync from the CPU. If your meshes use materials such as `ShaderMaterial` or `PBRMaterial`, this might significantly impact the frame rate. The example above is simple to follow and helps explain the concept, but there is a way to achieve much better performance by freezing materials. Here's how to do it.

Note that since v5.0, you don't need to add complicated code in the `RTT.onBeforeRender` / `RTT.onAfterRender` observers to save or replace the effects manually. You just have to freeze the materials that you know won't change, and you're good to go!

First, create objects that will be in the RTT with clones of the RTT shader material.

```javascript
// helper function to create clones of the caustic material
// we need that because we'll have different transforms on the shaders
let rttMaterials = [];
const getCausticMaterial = () => {
    let c = rttMaterial.clone();
    c.freeze(); // freeze because we'll only update uniforms
    rttMaterials.push(c);
    return c;
};

// some material for the ground.
var grass0 = new BABYLON.StandardMaterial("grass0", scene);
grass0.diffuseTexture = new BABYLON.Texture("textures/grass.png", scene);
grass0.freeze();

// Our built-in 'ground' shape.
var ground = BABYLON.MeshBuilder.CreateGround("ground", {width: 6, height: 6}, scene);
ground.material = grass0;
// add caustics
renderTarget.setMaterialForRendering(ground, getCausticMaterial());
renderTarget.renderList.push(ground);
```

Apply any uniforms on all material clones:

```javascript
scene.onBeforeRenderObservable.add(() => {
    // ... 
    rttMaterials.forEach((c) => c.setFloat('time', timeDiff));
});
```

The example has the complete code, including animated objects and instances. You could freeze some meshes with `scene.freezeActiveMeshes()` to improve the performance even further.

Playground example: <Playground id="#S1W87B#42" title="Performance Example" description="Example of managing performance when running multiple passes."/>


### Notes about your shader

Note that since you replace the material with a shader from scratch for mesh instances, you need to handle effects such as animation or instance transformations, and this will affect your vertex shader (and possibly your fragment shader as well). There are [several includes in Babylon](https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/core/src/Shaders/ShadersInclude) that help with that. Here's a sample vertex shader with support for bone animations and instances:

```glsl
precision highp float;

attribute vec3 position;
attribute vec2 uv;

uniform mat4 view;
uniform mat4 projection;
uniform mat4 worldViewProjection;

varying vec2 vUV;

#include<bonesDeclaration>
#include<instancesDeclaration>

void main() {
    vec3 positionUpdated = position;

    #include<instancesVertex>
    #include<bonesVertex>

    vec4 worldPos = finalWorld * vec4(positionUpdated, 1.0);

    vUV = uv;

    gl_Position = projection * view * worldPos;
}
```

### Debugging multiple passes

Your final composer might become a complicated shader, and each pass might be complicated in itself. You certainly will need to debug shaders along the way. One way to easily debug individual passes is to show only that pass to the screen, commenting the rest of the code.

```
varying vec2 vUV;
uniform sampler2D somePassTexture;

void main() {
    // comment other code
    vec4 debugColor = texture2D(someTexture, vUV);
    gl_FragColor = debugColor;
}
```

Testing passes separately and then adding them one at a time to the composer will make it easier to debug any issues. You can also use the technique from the playgrounds above, splitting the screen into columns, each with a different pass.

Finally you can also check RT textures with the [Babylon inspector](/toolsAndResources/inspectorv2).


Scene

Coming next

In-Depth layerMask

Learn how the layerMask property works across the library

Scene

Learn how to quickly build a world in a "scene" within Babylon.js.

Interacting With Scenes

Begin learning about how to develop interactions for your Babylon.js scenes.

Using Multiple Scenes

Learn about using multiple scenes at the same time in Babylon.js.

Using Multiple Canvases

Learn about using multiple canvases at the same time in Babylon.js.

Applying Delta Changes To A Scene

Learn about using the delta system in Babylon.js to save and reload changes made to your scenes.

Creating Custom Loading Screens

Learn how to create custom loading screens in Babylon.js.

Optimizing Your Scene

Learn how to optimize your scene in Babylon.js.

The Scene Optimizer

Learn all about the scene optimizer in Babylon.js.

Optimizing With Octrees

Learn how to optimize your scene using octrees in Babylon.js.

Optimizing Using Cached Resources

Learn how to optimize your scene using cached resources in Babylon.js.

Floating Origin (Huge Scenes Support)

Learn how to manage huge scenes using the floating-origin trick.

Large World Rendering / Floating Origin

Learn how to use Babylon.js's floating origin system to render large worlds without floating point precision issues.

Reducing Memory Footprint

Learn how to reduce the memory footprint of scenes in Babylon.js.

Offscreen Canvas

Learn all about the offscreen canvas in Babylon.js.

Render Scenes To .png Files

Learn how to render scenes to .png files.

Render Scenes To Video.

Learn how to render scenes to video files.

Using Clipping Planes

Learn all about clipping planes in Babylon.js.

Rendering Scenes On A Remote Server

Learn how to render scenes on a remote server and take screenshots.