
An AssetContainer can be used to manage a list of assets (like nodes, cameras, lights, meshes, etc..). This assets are still linked to a scene but are not taken in account. Consider asset containers like pool of entities.

## Creating an AssetContainer

It can be created manually
```javascript
var container = new BABYLON.AssetContainer(scene);
```
Or by loading from a file. See [loading from files](/divingDeeper/importers/loadingFileTypes)

## Adding or removing assets to the scene

The container can then be used to add or remove contents of the container from the scene.
```javascript
// Add all objects in the asset container to the scene
container.addAllToScene()

// Remove all objects in the container from the scene
container.removeAllFromScene()
```

<Playground id="#5NFRVE#1" title="Asset Container Adding and Removing Assets" description="Simple Example of adding and removing asset container assets into your scene." image="/img/playgroundsAndNMEs/divingDeeperAssetContainer1.jpg"/>

This can be used to add/remove all objects in a scene without the need to exit WebVR. <Playground id="#JA1ND3#48" title="Asset Container Adding and Removing Assets in WebVR" description="Simple Example of adding and removing asset container assets into your WebVR scene." image="/img/playgroundsAndNMEs/divingDeeperAssetContainer2.jpg"/>

When creating assets manually the moveAllFromScene method can be used to move all assets currently in a scene into an AssetContainer and remove them from the scene for later use. 
```javascript
var keepAssets = new BABYLON.KeepAssets();
keepAssets.cameras.push(camera);
container.moveAllFromScene(keepAssets);
```
<Playground id="#5NFRVE#3" title="Moving Assets Into an Asset Container" description="Simple Example of moving assets in a scene into an asset container." image=""/> 

## Duplicating the models
Asset containers can also be used as "templates" to duplicate models without reloading them.

To do so, you only need to call:
```
let entries = container.instantiateModelsToScene();
```

The return entries object will contain:
- rootNodes: A list of all the root nodes created by the duplication process
- skeletons: A list of all the skeletons created by the duplication process
- animationGroups: A list of all the animation groups created by the duplication process

<Playground id="#S7E00P" title="Instantiating Asset Container Assets" description="Simple Example of using asset containers as templates to dupliate assets in a scene." image="/img/playgroundsAndNMEs/divingDeeperAssetContainer3.jpg"/>

You can also set two parameters to the call to `instantiateModelsToScene`:
- nameFunction: This will let you decide what will be the name of the cloned entities (instead of "Clone of...")
- cloneMaterials: By default materials are not cloned but shared. With this parameter you can force the system to also clone the materials

```
var entries = container.instantiateModelsToScene(name => "p" + name, true);
```


## How To Load Files with Assets Manager

In order to help developers load multiple assets, Babylon.js (starting with version 1.14) introduced the AssetsManager class.

This class can be used to import meshes into a scene or load text and binary files.

**Note:** Since meshes you import can have a _rotationQuaternion_ set applying a _rotation_ to one will have unforeseen consequences as detailed in this [warning](/divingDeeper/mesh/transforms/center_origin/rotation_conventions).

## Using AssetsManager

### Initializing and creating tasks

To use it, you just have to instantiate it with a current scene:

```javascript
var assetsManager = new BABYLON.AssetsManager(scene);
```

Then you can add tasks to the manager:

```javascript
var meshTask = assetsManager.addMeshTask("skull task", "", "scenes/", "skull.babylon");
```

Each task provides an ```onSuccess``` and an ```onError``` callback:

```javascript
meshTask.onSuccess = function (task) {
    task.loadedMeshes[0].position = BABYLON.Vector3.Zero();
}
```

```javascript
meshTask.onError = function (task, message, exception) {
    console.log(message, exception);
}
```

You can do the same thing but with text and binary files:

```javascript
var textTask = assetsManager.addTextFileTask("text task", "msg.txt");
textTask.onSuccess = function(task) {
    console.log(task.text);
}

var binaryTask = assetsManager.addBinaryFileTask("binary task", "grass.jpg");
binaryTask.onSuccess = function (task) {
    // Do something with task.data
}
```

Images are also supported through imageTask:

```javascript
var imageTask = assetsManager.addImageTask("image task", "img.jpg");
imageTask.onSuccess = function(task) {
    console.log(task.image.width);
}
```

Textures can also be loaded, through textureTask:

```javascript
var textureTask = assetsManager.addTextureTask("image task", "img.jpg");
textureTask.onSuccess = function(task) {
    material.diffuseTexture = task.texture;
}
```

### Task state and error handling

Each task has a state object that represents the current execution state of the task. The state is represented by an enum, `BABYLON.AssetTaskState` and has 4 states:
* INIT - before the task started executing
* RUNNING - when the task started executing but hasn't finished yet.
* DONE - when the task successfully finished execution
* ERROR - when the task failed.

If a task has the error state (`BABYLON.AssetTaskState.ERROR`) a new object will be added to the task: `task.errorObject` . The error object have 2 variables defined, both optional:
* message - a string explaining the error shortly (such as "request returned 404")
* exception - in case an exception was thrown during execution, the exception object will contain the stack trace information

This way the error is accessible also when using the assets manager observers:

```javascript
assetsManager.onTaskErrorObservable.add(function(task) {
    console.log('task failed', task.errorObject.message, task.errorObject.exception);
});
```


### Manager callbacks and observables

The manager itself provides four callbacks:
* onFinish
* onProgress
* onTaskSuccess
* onTaskError

```javascript
assetsManager.onProgress = function(remainingCount, totalCount, lastFinishedTask) {
	engine.loadingUIText = 'We are loading the scene. ' + remainingCount + ' out of ' + totalCount + ' items still need to be loaded.';
};

assetsManager.onFinish = function(tasks) {
    engine.runRenderLoop(function() {
        scene.render();
    });
};
```

The manager also allows you to use observers in order to handle onFinish, onProgress, onTaskSuccess and onTaskError:
* onTaskSuccessObservable - registered observers will be executed when a single task finished successfully.
* onTaskErrorObservable - registered observers will be executed when a single task failed.
* onProgressObservable - registered observers will be executed when a single task finished successfully or failed.
* onTasksDoneObservable - registered observers will be execute when all tasks' executions are done (success or failed!)

```javascript
assetsManager.onTaskSuccessObservable.add(function(task) {
    console.log('task successful', task)
});
```

```javascript
assetsManager.onTasksDoneObservable.add(function(tasks) {
    var errors = tasks.filter(function(task) {return task.taskState === BABYLON.AssetTaskState.ERROR});
    var successes = tasks.filter(function(task) {return task.taskState !== BABYLON.AssetTaskState.ERROR});
});
```

### Executing the tasks

To launch all the tasks, you have to call:

```javascript
assetsManager.load();
```

* You can see a live demo [here](https://www.babylonjs.com/scenes/assets)
* Playground demo: <Playground id="#ZJYNY#0" title="Asset Manager Example" description="Simple Example of using the asset manager in your scene." image="/img/playgroundsAndNMEs/divingDeeperAssetManager1.jpg"/>

## Available tasks

There are 7 types of tasks that can be executed using the assets manager.

Each task is extending the AbstractAssetTask class (and implementing IAssetTask interface) with the following properties:

```javascript
onSuccess: (task: IAssetTask) => void;
onError: (task: IAssetTask, message?: string, exception?: any) => void;

isCompleted: boolean = false;
name: string;
taskState: AssetTaskState;
errorObject: { message?: string; exception?: any; };
```

Note that the properties required to initialize a task are always corresponding to the object type it creates. Foe example, the constructor signature of the CubeTextureAssetTask takes the same variables as the class BABYLON.CubeTexture . The order of the variables might vary.

### MeshAssetTask

The mesh asset task is used to load a model externally (a .babylon, .obj, .gltf and so on).

Constructor signature:

```javascript
constructor(name: string, meshesNames: any, rootUrl: string, sceneFilename: string)
```

Extra properties:

```javascript
public loadedMeshes: Array<AbstractMesh>;
public loadedParticleSystems: Array<ParticleSystem>;
public loadedSkeletons: Array<Skeleton>;
```

### TextFileAssetTask

Is used to async-load a (text) file.

Constructor signature:

```javascript
constructor(name: string, url: string)
```

Extra properties:

```javascript
public url: string;
public text: string;
```

### BinaryFileAssetTask

This task is used to load a binary file. The main difference between this and the TextFileAssetTask is that the data will be stored in an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)

Constructor signature:

```javascript
constructor(name: string, url: string)
```

Extra properties:

```javascript
public url: string;
public data: ArrayBuffer;
```

### ImageAssetTask

This function will load an image (.png, .jpg, .gif). It will create an [HTMLImageElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement) object

Constructor signature:

```javascript
constructor(name: string, url: string)
```

Extra properties:

```javascript
public url: string;
public image: HTMLImageElement;
```

### TextureAssetTask

This will create a new BABYLON.Texture from a provided single url.

Constructor signature:

```javascript
constructor(name: string, url: string, noMipmap?: boolean, invertY?: boolean, samplingMode: number = BABYLON.Texture.TRILINEAR_SAMPLINGMODE)
```

Extra properties:

```javascript
public texture: Texture;
```

### CubeTextureAssetTask

The same as the TextureAssetTask but for a cube texture

Constructor signature:

```javascript
constructor(name: string, url: string, extensions?: string[], noMipmap?: boolean, files?: string[])
```

Extra properties:

```javascript
public texture: CubeTexture;
```

### HDRCubeTextureAssetTask

Same as the CubeTextureAssetTask, but for HDR cube textures

```javascript
constructor(name: string, url: string, size?: number, noMipmap = false, generateHarmonics = true, useInGammaSpace = false, usePMREMGenerator = false)
```

Extra properties:

```javascript
public texture: HDRCubeTexture;
```

### EquiRectangularCubeTextureAssetTask

Same as the CubeTextureAssetTask, but for Equirectangular cube textures

```javascript
constructor(name: string, url: string, size: number, noMipmap = false, useInGammaSpace = true)
```

Extra properties:

```javascript
public texture: EquiRectangularCubeTexture;
```

## Using a loading screen

By default, the AssetsManager will display a loading screen while loading assets:

<img src="/img/features/scene/loader.jpg" title="Babylon.js Loading Spinner"/>

If you want to disable the loading screen, you have to set ```useDefaultLoadingScreen``` to false:

```javascript
assetsManager.useDefaultLoadingScreen = false;
```

The loading screen will also be displayed while loading a scene using SceneLoader if ```ShowLoadingScreen``` is set to true (by default).

```javascript
BABYLON.SceneLoader.ShowLoadingScreen = false;
```

In the same way, you can also display or hide the loading screen manually using these functions:

```javascript
engine.displayLoadingUI();
engine.hideLoadingUI();
```

Loading text is controlled using ```loadingUIText``` :

```javascript
engine.loadingUIText = "text";
```

Background color is controlled using ```loadingUIBackgroundColor``` :

```javascript
engine.loadingUIBackgroundColor = "red";
```


## How to Create Your Own File Importer
By default, babylon.js comes with an importer for .babylon files.

You can also create your own importer by providing a specific object to the ```BABYLON.SceneLoader.RegisterPlugin``` function.

This object must have three properties:

* A list of supported file extensions (```extensions```)
* An ```importMesh``` function to import specific meshes
* A ```load``` function to import complete scene
* A ```loadAssets``` function to import all babylon elements from the file but do not add them to the scene

Here is a sample importer object:
```javascript
    BABYLON.SceneLoader.RegisterPlugin({
        extensions: ".babylon",
        importMesh: function (meshesNames, scene, data, rootUrl, meshes, particleSystems, skeletons) {
            return true;
        },
        load: function (scene, data, rootUrl) {
            return true;
        },
        loadAssets(scene, data, rootUrl){
            var container = new AssetContainer(scene);
            return container;
        }
    });
```

* ```meshesNames``` is the names of meshes to import
* ```scene``` is the scene to load data into
* ```data``` is the string representation of the file to load
* ```rootUrl``` defines the root URL of your assets
* ```meshes``` is the list of imported meshes
* ```particleSystems``` is the list of imported particle systems
* ```skeletons``` is the list of imported skeletons



## Setup

The glTF loader files are located [here](https://github.com/BabylonJS/Babylon.js/tree/master/dist/preview%20release/loaders).

## Full Version

This loader supports both glTF 1.0 and 2.0 and will use the correct loader based on the glTF version string.

```html
<script src="babylon.js"></script>
<script src="babylon.glTFFileLoader.js"></script>
```

## Version 2 Only

This loader supports only glTF 2.0 and will fail to load glTF 1.0.

```html
<script src="babylon.js"></script>
<script src="babylon.glTF2FileLoader.js"></script>
```

## Version 1 Only

This loader supports only glTF 1.0 and will fail to load glTF 2.0.

```html
<script src="babylon.js"></script>
<script src="babylon.glTF1FileLoader.js"></script>
```

## Loading the Scene

Use one of the static function on the `SceneLoader` to load a glTF asset.
See [Load from any file type](/divingDeeper/importers/loadingFileTypes).

See an example here: <Playground id="#WGZLGJ" title="Load a glTF Asset" description="Simple example showing how load a .glTF asset into your scene." image="/img/playgroundsAndNMEs/divingDeeperglTF1.jpg"/>

## API (Version 2)

## Properties and Methods

See the available [properties and methods](/api/classes/babylon.gltffileloader) from the API documentation.

## Extensions

See the available [extensions](/api/modules/babylon.gltf2.loader.extensions) from the API documentation.

## API (Version 1)

## Properties

### IncrementalLoading

Set this property to false to disable incremental loading which delays the loader from calling the success callback until after loading the meshes and shaders. Textures always loads asynchronously. For example, the success callback can compute the bounding information of the loaded meshes when incremental loading is disabled. Defaults to true.

```javascript
BABYLON.GLTFFileLoader.IncrementalLoading = false;
```

### HomogeneousCoordinates

Set this property to true in order to work with homogeneous coordinates, available with some converters and exporters. Defaults to false.

```javascript
BABYLON.GLTFFileLoader.HomogeneousCoordinates = true;
```

## Extensions

[KHR_binary_glTF](https://github.com/KhronosGroup/glTF/tree/master/extensions/1.0/Khronos/KHR_binary_glTF)  
[KHR_materials_common](https://github.com/KhronosGroup/glTF/tree/master/extensions/1.0/Khronos/KHR_materials_common)  



## How To Use the Incremental Loading System

In order to support incremental loading (introduced by v1.5.0), you just have to go to [this page](https://github.com/BabylonJS/Exporters/tree/master/Tools/MakeIncremental) in order to get a tool to convert your .babylon file to a .incremental.babylon file alongside associated resources (_.babylonmeshdata_ and _.babylongeometrydata_ files).

These files can be used just like a standard _.babylon_ scene except that they will allow **Babylon.js** to load meshes and textures on the fly. This means that the meshes and the textures will not be loaded at startup but only when they become active (when the active camera can see them).

You have to put the _.babylonmeshdata_ and _.babylongeometrydata_ files in the same folder as the _.incremental.babylon_ file.

You can find a demo of an incremental scene here: <Playground id="#JA1ND3#84" title="Incremental Loading Example" description="Simple Example of incremental loading assets." image="/img/playgroundsAndNMEs/divingDeeperIncrementalLoading1.jpg"/>

## Node.js based incremental file converter
This script can be used to generate incremental files from babylon scenes. It can be ran directly from node or it can be integrated into build scripts. More information about how to install and configure the script can be found [here](https://www.npmjs.com/package/babylonjs-make-incremental).



## How to Use Scene Loader

### Basic Usage

To load a file of a given type, Babylon must first have a reference to the plugin for that file type.

Currently plugins can be found for:
 - [.glTF also use for binary version .glb](/divingDeeper/importers/glTF)
 - [.obj](/divingDeeper/importers/oBJ)
 - [.stl](/divingDeeper/importers/stl)

To quickly add support for all loaders the following script can be added to your page:

#### Production links

```javascript
<script src="https://cdn.babylonjs.com/babylon.js"></script>
<script src="https://cdn.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>
```

#### Preview links (useful to test for changes to loaders)

```javascript
<script src="https://preview.babylonjs.com/babylon.js"></script>
<script src="https://preview.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>
```
For NPM usage see: https://www.npmjs.com/package/babylonjs-loaders

Once the plugin is referenced, the SceneLoader class can be used which provides a few loading methods.

## SceneLoader.Append

Loads all babylon assets from the file and appends them to the scene

```javascript
BABYLON.SceneLoader.Append("./", "duck.gltf", scene, function (scene) {
    // do something with the scene
});
```

See an example here: <Playground id="#WGZLGJ" title="Append An Object" description="Simple example showing how append an object to your scene." image="/img/playgroundsAndNMEs/divingDeeperFileImport1.jpg"/>

Loads all babylon assets from a string and appends them to the scene

```javascript
BABYLON.SceneLoader.Append("", "data:" + gltfString, scene, function (scene) {
    // do something with the scene
});
```

See an example here: <Playground id="#88CB6A#1" title="Append Assets From A String" description="Simple example showing how append objects from a string." image="/img/playgroundsAndNMEs/divingDeeperFileImport2.jpg"/>

You can also load a .glb binary file from a data string as long as the binary data is base64 encoded:

```javascript
var base64_model_content = "data:base64,BASE 64 ENCODED DATA...";
BABYLON.SceneLoader.Append("", base64_model_content, scene, function (scene) { 
    // do something with the scene
});
```

Note that two mime types are allowed in the string data:
```javascript
var base64_model_content = "data:application/octet-stream;base64,-BASE 64 ENCODED DATA-";
var base64_model_content = "data:model/gltf-binary;base64,-BASE 64 ENCODED DATA-";
```

See an example here: <Playground id="#7F6S08#15" title="Load .glb From Binary Data" description="Simple example showing how to load an object from a data string that is base64 encoded." image="/img/playgroundsAndNMEs/divingDeeperFileImport3.jpg"/>

## SceneLoader.Load

Loads all babylon assets from the file and creates a new scene

```javascript
BABYLON.SceneLoader.Load("/assets/", "batman.obj", engine, function (scene) { 
   // do something with the scene
});
```

## SceneLoader.ImportMesh

Loads the meshes from the file and appends them to the scene

```javascript
// The first parameter can be set to null to load all meshes and skeletons
BABYLON.SceneLoader.ImportMesh(["myMesh1", "myMesh2"], "./", "duck.gltf", scene, function (meshes, particleSystems, skeletons) {
    // do something with the meshes and skeletons
    // particleSystems are always null for glTF assets
});
```

See an example here: <Playground id="#JUKXQD" title="Import Mesh" description="Simple example showing how to import an object into your scene." image="/img/playgroundsAndNMEs/divingDeeperFileImport4.jpg"/>

## SceneLoader.LoadAssetContainer

Loads all babylon assets from the file and does not append them to the scene

```javascript
BABYLON.SceneLoader.LoadAssetContainer("./", "duck.gltf", scene, function (container) {
    var meshes = container.meshes;
    var materials = container.materials;
    //...

    // Adds all elements to the scene
    container.addAllToScene();
});
```

See an example here: <Playground id="#JA1ND3#48" title="Asset Container Load Example" description="Simple example showing how to load assets into asset containers." image="/img/playgroundsAndNMEs/divingDeeperFileImport5.jpg"/>

## SceneLoader.ImportAnimations

Loads the animations from the file and merges them to the scene
You can customize the import process using options and callbacks
```javascript
BABYLON.SceneLoader.ImportAnimations("./", "Elf_run.gltf", scene);
```
See an example here: <Playground id="#UGD0Q0#62" title="Importing Animations" description="Simple example showing how to import animations into your scene." image="/img/playgroundsAndNMEs/divingDeeperFileImport6.jpg"/>

## SceneLoader.AppendAsync

There are also `Async` versions of these functions that return promises:

```javascript
BABYLON.SceneLoader.AppendAsync("./", "duck.gltf", scene).then(function (scene) {
    // do something with the scene
});
```

See [How to Use Promises](/divingDeeper/events/promises) to learn more about using promises.

## Advanced Usage

Use the `onPluginActivatedObservable` to set properties and call methods specific to a particular loader.

```javascript
BABYLON.SceneLoader.OnPluginActivatedObservable.add(function (loader) {
    if (loader.name === "gltf") {
        // do something with the loader
        // loader.<option1> = <...>
        // loader.<option2> = <...>
    }
});
```

Alternatively, the static synchronous SceneLoader functions return the plugin.

```javascript
var loader = BABYLON.SceneLoader.Load("./", "duck.gltf", engine, function (scene) {
    // do something with the scene
});

// do something with the loader
// loader.<option1> = <...>
// loader.<option2> = <...>
```

## Loading multiple assets

For assistance when load multiple assets the AssetsManager class can be used.
See [Load Files with Assets Manager](/divingDeeper/importers/assetManager)


## OBJ File Import

To use it, you just have to reference the loader file:

```
<script src="babylon.js"></script>
<script src="babylon.objFileLoader.js"></script>
```
You can find it [here](https://github.com/BabylonJS/Babylon.js/tree/master/dist/preview%20release/loaders)


If you are using ES6 imports via NPM, you need to reference with side-effects:
```
import 'babylonjs-loaders'
```

You can read more about [NPM support](/divingDeeper/developWithBjs/npmSupport)

### Load
See [how to load from any file type](/divingDeeper/importers/loadingFileTypes)
Babylon.js will know how to load the obj file and its mtl file automatically: 

## Good things to know
* Your model doesn't have to be triangulated, as this loader will do it automatically.
* A Babylon.Mesh will be created for each object/group
* The obj model should be exported with -Z axis forward, and Y axis upward to be compatible with Babylon.js

![Axis](/img/how_to/import-obj/axys.jpg)

* By default, due to optimization in the code for loading time, UVs problems can appear, like this :

![Batman UVs problem](/img/how_to/import-obj/uv-issue.jpg)

If you meet this problem, set the variable:
```
BABYLON.OBJFileLoader.OPTIMIZE_WITH_UV = true;
```
Then, you'll have a better texture, but with a longer loading.

![Batman UVs ok](/img/how_to/import-obj/uv-fixed.jpg)

Depending on the modeling program you export your OBJ files from, textures may appear distorted or inverted. As a workaround, you can modify your imported model's UV coordinate scale via setting the variable:
```
BABYLON.OBJFileLoader.UV_SCALE = new BABYLON.Vector2(xValue, yValue)
```

Although not part of Wavefront OBJ file format, some OBJ files include vertex colors. If you are loading such a file and want vertices with colors, set the variable:
```
BABYLON.OBJFileLoader.IMPORT_VERTEX_COLORS = true;
```

If you have an OBJ file without normals or wish to have them calculated for you, set the variable:
```
BABYLON.OBJFileLoader.COMPUTE_NORMALS = true;
```

To have your imported model inverted on the y-axis, set the variable:
```
BABYLON.OBJFileLoader.INVERT_Y = true;
```

To invert your imported textures on the y-axis, set the variable:
```
BABYLON.OBJFileLoader.INVERT_TEXTURE_Y = true;
```

By default if a MTL file cannot be loaded (missing/error) it will silently fail.  The model will still be loaded, but if you want to enforce a stricter loading of materials you can use onSuccess() and onError() callbacks accordingly.  Set the variable:
```
BABYLON.OBJFileLoader.MATERIAL_LOADING_FAILS_SILENTLY = false;
```

If a MTL is defined in your OBJ and you wish to have it ignored, set the variable:
```
BABYLON.OBJFileLoader.SKIP_MATERIALS = true;
```

## Supported
* Object/group
* Geometric vertex
    * colors
* Faces
    * triangles
    * quads
    * polygons
* Colors
    * diffuseColor
    * ambientColor
    * specularColor
    * specularPower
    * alpha
* Textures
    * ambientTexture
    * diffuseTexture
    * specularTexture
    * bumpTexture
    * opacityTexture
* Multimaterial
	* For each material defined in the same mesh, it creates a new BABYLON.Mesh.
	* The name of the created BABYLON.Mesh follows this syntax: meshName_mmX 
	* X is the nth BABYLON.Mesh created with this method

## Not supported currently
* Smoothing groups (s parameter in OBJ file)
* Illumination (illum parameter in MTL file)
* The differents options for loading textures in MTL file.
* A good description about MTL files and their options can be found here: http://paulbourke.net/dataformats/mtl/



## Introduction

Downloading large assets is often slow even with a decent internet connection. Progressively loading discrete levels of detail (LODs) is one technique to combat this. The idea is to store multiple LODs in the asset and progressively load them from low to high quality. This method improves the time to first render since the lowest quality LOD is often dramatically smaller than the highest quality LOD.

<Playground id="#ARN6TJ#5" title="Progressive Loading With LODs" description="Simple Example of progressively loading assets with levels of detail." image="/img/playgroundsAndNMEs/divingDeeperProgressivelyLoading1.jpg"/>

This demo playground loads a glTF binary (a.k.a. GLB) asset which is a single file store on the server. It uses HTTP range requests to partially download parts of the GLB. The glTF loader minimizes the amount of HTTP requests sent to the server for optimal efficiency. It also shows progress of each stage of the download. Console logging is enabled to show what the glTF loader is doing.

## About MSFT_lod

[MSFT_lod](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/MSFT_lod) is a Microsoft glTF extension for discrete LODs. It has support for both node and material LODs. Babylon.js currently only supports progressively loading these LODs for the purpose of reducing the time to first render. LODs that switch based on rendering distance or screen coverage is not currently supported.

There are not many tools that can create assets with MSFT_lod at the moment. The asset in the demo above is exported from [Adobe Dimension](https://www.adobe.com/products/dimension.html) for sharing on the web. [BabylonPolymorph](https://github.com/BabylonJS/BabylonPolymorph) will eventually be able to do this, but this project is still very early. There is also [glTF-Toolkit](https://github.com/Microsoft/glTF-Toolkit) for Windows Mixed Reality which unfortunately is not well suited for Babylon.js, but perhaps it can be modified to work better.

## Using HTTP Range Requests

A glTF asset can be either loose files or packed together into a glTF binary (GLB). Serving files as GLB on a server is typically not a good idea except when using [HTTP range requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests). Using range requests will enable the loader to partially download a range of the asset instead of all at once. The glTF loader in Babylon.js supports range requests. It can be enabled like this:

```javascript
BABYLON.SceneLoader.OnPluginActivatedObservable.addOnce(function (loader) {
    if (loader.name === "gltf") {
        loader.useRangeRequests = true;
    }
});
```

## Caveats
- The HTTP server hosting the asset must support range requests.
- The LODs in the GLB should be authored with a contiguous range per LOD for maximum efficiency.

## Showing Progress

When loading large assets either using loose files or with range requests, it is useful to show the download progress. Progress is supported through the progress callback of `BABYLON.SceneLoader` methods which is a small subset of the HTTP request [progress event](https://developer.mozilla.org/en-US/docs/Web/API/ProgressEvent). Here is an example from the demo above:

```javascript
BABYLON.SceneLoader.AppendAsync(url, undefined, scene, function (event) {
    // Compute the percentage for each stage unless the length is not computable.
    // The lengthComputable is often false when serving content that is gzipped.
    const percentage = event.lengthComputable ? " " + Math.floor(event.loaded / event.total * 100) + "%" : "";

    // Check if an LOD is loading yet.
    if (lodNext === null) {
        // Ignore GLB header progress.
        if (event.total === 20) return;

        // Show that the glTF is downloading.
        bottomLine.text = "Loading glTF..." + percentage;
    }
    else {
        // Show that the LOD is downloading.
        bottomLine.text = "Loading '" + lodNames[lodNext] + "' LOD..." + percentage;
    }
}, ".glb")
```

## Key Notes
- Gzipped content hosted on server often results in `lengthComputable` equaling `false` which in turn causes the `total` to be zero. When this happens, the only choices are to not show the progress or show the number of bytes downloaded instead.
- When using HTTP range requests with a GLB, the first thing that is downloaded is the GLB header which downloads very quickly and is almost always 20 bytes loaded and 20 bytes total when the progress event fires. Ignore it by checking when `total` is exactly 20.

## Debugging LODs

It is useful to stop at a specific LOD to inspect the results. This can be achieved by setting the `maxLODsToLoad` property on the MSFT_lod loader extension:

```javascript
BABYLON.SceneLoader.OnPluginActivatedObservable.addOnce(function (loader) {
    if (loader.name === "gltf") {
        loader.onExtensionLoadedObservable.add(function (extension) {
            if (extension.name === "MSFT_lod") {
                // Stop at the first LOD.
                extension.maxLODsToLoad = 1;
            }
        }
    }
}
```

## Enabling Logging

Enabling logging is often useful to understand and debug the loading of a glTF asset. This is especially true for MSFT_lod assets. Logging can be enabled like this:

```javascript
BABYLON.SceneLoader.OnPluginActivatedObservable.addOnce(function (loader) {
    if (loader.name === "gltf") {
        loader.loggingEnabled = true;
    }
});
```

Here is an example console log from the demo above:
```
BJS - [16:31:29]: Binary version: 2
BJS - [16:31:29]: JSON length: 59200
BJS - [16:31:29]: Loading 0
BJS - [16:31:29]: Asset version: 2.0
BJS - [16:31:29]: Asset generator: Adobe Dimension - 9ce31d2be91132df879a9b9136f9df4ef7b7fa2c
BJS - [16:31:29]: LOADING
BJS - [16:31:29]: /scenes/0 scene
BJS - [16:31:29]:   /nodes/0 render_camera_n3d
BJS - [16:31:29]:     /cameras/0 render_camera
BJS - [16:31:29]:   /nodes/1 ground_plane_n3d
BJS - [16:31:29]:   /nodes/2 sportsCar_4K
BJS - [16:31:29]:     /nodes/3 car_lores.obj
BJS - [16:31:29]:       /nodes/4 g car_lores_gt_lores_lowdetails group1
BJS - [16:31:29]:         /nodes/5 car_lores_gt_lores_lowdetails group1
BJS - [16:31:29]:           /meshes/0 car_lores_gt_lores_lowdetails group1
BJS - [16:31:29]:             /meshes/0/primitives/0
BJS - [16:31:29]:               deferred
BJS - [16:31:30]:               /materials/12/extensions/MSFT_lod
BJS - [16:31:30]:                 /materials/0 details_lod2
BJS - [16:31:30]:                   /materials/0/normalTexture
BJS - [16:31:30]:                     /textures/2 tmp_image_pie_10f1_2c55_943e
BJS - [16:31:30]:                       /images/2 normal
BJS - [16:31:30]:                         deferred
BJS - [16:31:30]:                   /materials/0/occlusionTexture
BJS - [16:31:30]:                     /textures/1 ambient_roughness_metallic
BJS - [16:31:30]:                       /images/1 ambient_roughness_metallic
BJS - [16:31:30]:                         deferred
...
BJS - [16:31:32]: Loading buffer range [0-4864522]
BJS - [16:31:37]: READY
BJS - [16:31:37]: Loading buffer range [4864523-8856965]
BJS - [16:31:39]: Loaded material LOD 1
BJS - [16:31:39]: Loading buffer range [8856966-67953580]
BJS - [16:32:00]: Loaded material LOD 2
BJS - [16:32:00]: COMPLETE
```

Note the `deferred` message when loading primitives and images. The loader is deferring the download until it has determined what ranges of the GLB is necessary for the LODs. Once the ranges are determined, the loader loads the range for the first LOD before the state changes to `READY` which indicates the asset is ready for viewing. Then it loads the remaining LODs in sequence until all the LODs are loaded before the state changes to `COMPELTE` which indicates the asset is completely loaded.


# STL File Import

You can find the STL loader [here](https://github.com/BabylonJS/Babylon.js/tree/master/dist/preview%20release/loaders)

To use it you just have to reference it after Babylon.js:


```
<script src="Babylon.js"></script>
<script src="babylon.stlFileLoader.js"></script>
```

Then you can use one of the static functions on the `SceneLoader` to load.
See [how to load from any file type](/divingDeeper/importers/loadingFileTypes)



## Introduction
The [DeviceSourceManager](/api/classes/babylon.devicesourcemanager) is a class that will manage the connections for various user input devices and provide methods of querying those devices for their current state.  
This class supports several methods of input:
- **Keyboard** *(DeviceType: BABYLON.DeviceType.Keyboard, Inputs: number)*
- **Mouse** *(DeviceType: BABYLON.DeviceType.Mouse, Inputs: BABYLON.PointerInput)*
- **Touch** *(DeviceType: BABYLON.DeviceType.Pointer, Inputs: BABYLON.PointerInput)*
- **DualShock Gamepad** *(DeviceType: BABYLON.DeviceType.DualShock, Inputs: BABYLON.DualShockInput)*
- **Xbox Gamepad, One or 360** *(DeviceType: BABYLON.DeviceType.Xbox, Inputs: BABYLON.XboxInput)*
- **Switch Gamepad, L+R JoyCon Grip or Pro Controller** *(DeviceType: BABYLON.DeviceType.Switch, Inputs: BABYLON.SwitchInput)*
- **Generic/Other Gamepad** *(DeviceType: BABYLON.DeviceType.Generic, Inputs: number)*

Here's an example of the DeviceSourceManager in use
<Playground id="#C7PM2B#18" title="DeviceSourceManager Example" description="Simple example showing how to use the DeviceSourceManager in your scene." image="/img/playgroundsAndNMEs/pg-C7PM2B-17.png"/>

To use the DeviceSourceManager, first create an instance of it.  You will need to provide an engine object.
```javascript
var deviceSourceManager = new BABYLON.DeviceSourceManager(scene.getEngine());
```

Within your scene's render/game loop, you can query the DeviceSourceManager for the current state of a specific input.  First, you will need to get the DeviceSource object.  With this object, you can then query for a specific input's status.

```javascript
// If the device has been registered in the DeviceSourceManager
if (deviceSourceManager.getDeviceSource(BABYLON.DeviceType.Xbox)) {
    // And the A button was pressed
    if (deviceSourceManager.getDeviceSource(BABYLON.DeviceType.Xbox).getInput(BABYLON.XboxInput.A) == 1) {
        // Do something
    }
}
```

It should also be noted that you can use optional chaining to make checks fit into a single line
```javascript
if (deviceSourceManager.getDeviceSource(BABYLON.DeviceType.Xbox)?.getInput(BABYLON.XboxInput.A) == 1) {
    // Do something
}
```

## Events and Observables
You can use the following Observables to work with identifiers for a given device
```javascript

// When a device is registered in the DeviceSourceManager
onDeviceConnectedObservable.add((device) => {
    // You can get the device type by using device.deviceType
    // You can also get the device slot by using device.deviceSlot (default is 0 for keyboard and 1 for mouse)
    // "device" is of Type DeviceSource do you can also access the getInput function or add an observable for onInputChangedObservable
});

// When a device is unregistered in the DeviceSourceManager
onDeviceDisconnectedObservable.add((device) => {
    // You can get the device type by using device.deviceType
    // You can also get the device slot by using device.deviceSlot (default is 0 for keyboard and 1 for mouse)
    // "device" is of Type DeviceSource
});
```

For Keyboards and Pointers, you can use an event based system to get the current input and previous input when an input is activated
```javascript
deviceSourceManager.getDeviceSource(BABYLON.DeviceType.Keyboard).onInputChangedObservable.add((device) => {
    // device.inputIndex is the activated input
    // device.currentState is the current value
    // device.previousState is the previous value (before activation)
});
```


Importing Assets

Coming next

Loading Any File Type

Learn how to import any file type in Babylon.js.

.glTF File Loader Plugin

Learn about the .glTF File Loader Plugin available in Babylon.js.

.stl File Loader Plugin

Learn about the .stl File Loader Plugin available in Babylon.js.

.obj File Loader Plugin

Learn about the .obj File Loader Plugin available in Babylon.js.

Incremental Loading System

Learn about the incremental loading system in Babylon.js.

Create Your Own File Importer

Learn how to create your own file importer for Babylon.js.

Asset Manager

Learn the wonderful world of the Babylon.js asset manager.

Asset Containers

Learn all about using asset containers in Babylon.js.

Progressively Load .glTF Files

Learn about progressively loading .glTF files in Babylon.js.