
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
const container = new BABYLON.AssetContainer(scene);
```

Or by loading from a file. See [loading from files](/features/featuresDeepDive/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
const 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."/>

## 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:

```javascript
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 duplicate 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

```javascript
const entries = container.instantiateModelsToScene(name => "p" + name, true);
```

You can dispose a specific set of instantiated models again with:
```javascript
entries.dispose();
```



## 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](/features/featuresDeepDive/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
const assetsManager = new BABYLON.AssetsManager(scene);
```

Then you can add tasks to the manager:

```javascript
const 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
const textTask = assetsManager.addTextFileTask("text task", "msg.txt");
textTask.onSuccess = function (task) {
  console.log(task.text);
};

const binaryTask = assetsManager.addBinaryFileTask("binary task", "grass.jpg");
binaryTask.onSuccess = function (task) {
  // Do something with task.data
};
```

Images are also supported through imageTask:

```javascript
const imageTask = assetsManager.addImageTask("image task", "img.jpg");
imageTask.onSuccess = function (task) {
  console.log(task.image.width);
};
```

Textures can also be loaded, through textureTask:

```javascript
const textureTask = assetsManager.addTextureTask("image task", "img.jpg");
textureTask.onSuccess = function (task) {
  material.diffuseTexture = task.texture;
};
```


And make sure to call load() to initialize the tasks:

```javascript
textureTask.load();

textureTask.onFinish = (tasks) => {
      // do render stuff
  _this.engine.runRenderLoop(() => {
    _this.scene.render();
  })
}
```


### 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) {
  const errors = tasks.filter(function (task) {
    return task.taskState === BABYLON.AssetTaskState.ERROR;
  });
  const 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 | File)
```

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) {
    const 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

You can find the loader here [here](https://cdn.babylonjs.com/loaders/babylon.glTFFileLoader.js)

## 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>
```

## Loading files locally

By default, the gltf loader will request additional files for [draco compression](https://google.github.io/draco/) from *preview.babylonjs.com*. In case you want to deliver these files locally (e.g. for GDPR compliance), you can set the [DracoCompression.Configuration](https://doc.babylonjs.com/typedoc/classes/BABYLON.DracoCompression) object to use local files:

```typescript
DracoCompression.Configuration = {
  decoder: {
    wasmUrl: "/babylon-draco-files/draco_wasm_wrapper_gltf.js",
    wasmBinaryUrl: "/babylon-draco-files/draco_decoder_gltf.wasm",
    fallbackUrl: "/babylon-draco-files/draco_decoder_gltf.js",
  },
};
```

Be sure to download the files first (from `https://preview.babylonjs.com/[FILENAME]`) and put them in a local path (`public/babylon-draco-files`, in this case).

## Warning

A \_root\_ node is added to hold all the **glTF** and **glb** models and model parts are stored as sub-meshes. This is so applications that save models using a right handed system will be loaded correctly into Babylon.js when you add to your create scene function

```javascript
scene.useRightHandedSystem = true;
```

This also means that _loadedMeshes[0]_ will point to the added \_root\_ node and _loadedMeshes[1]_ will point to your first loaded mesh.

## 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>
```

See [Skinning](/features/featuresDeepDive/importers/glTF/glTFSkinning) for details on how skinning is implemented in Babylon.js for glTF 2.0.

## 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](/features/featuresDeepDive/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" isMain={true} category="Import"/>

## API (Version 2)

## Properties and Methods

See the available [properties and methods](/typedoc/classes/babylon.gltffileloader) from the API documentation.

## Extensions

See the available [extensions](/typedoc/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"/>

## Detailed Step by step
For users less experienced with command line tools, here's a more detailed step by step of what you need to use the tool:

1. Get the Exporters project (by either using git or downloading the ZIP):
![Exporters project](/img/importers/incremental_loading/incr_step_1.png "Babylon.js Exporters project")

2. Download and install [.NET Core 3.1](https://dotnet.microsoft.com/en-us/download/dotnet/3.1)

3. Open a command prompt (cmd.exe should do the trick) and navigate to the MakeIncremental directory:
![MakeIncremental directory](/img/importers/incremental_loading/incr_step_3.png "Navigating to the MakeIncremental directory")

4. Type `dotnet build` on the command prompt:
![.NET build](/img/importers/incremental_loading/incr_step_4.png "Building the project")

5. Navigate to the directory where the build files were written, `\bin\Debug\netcoreapp3.1\`:
![Build directory](/img/importers/incremental_loading/incr_step_5.png "Navigating to the build directory")

6. Type the command `MakeIncremental.exe /i:my-scene.babylon`, where `my-scene.babylon` is the name of your scene (if your scene is named something else, just change what's after the `:` symbol):
![Run command](/img/importers/incremental_loading/incr_step_6.png "Running the MakeIncremental command")

7. The script is going to generate quite a few files, you will need all of them, except your original `my-scene.babylon`. Copy them to a directory your project has access to (on this example, it's `/src`):
![Generated files](/img/importers/incremental_loading/incr_step_7.png "Files generated by the MakeIncremental command")

8. And you're ready to load it into Babylon!
```javascript
BABYLON.SceneLoader.Append("src/", "my-scene.incremental.babylon", scene, function() {
    console.log("My incremental file was loaded! WOHOO!");
});
```

## 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).



## Loading Assets Directly From Memory

There may be times where you'll want to pre-load (store) assets in memory and load those assets from memory into your Babylon scene. This is achievable by using a blob url.

<Playground id="#FIWM5X#1" title="Load Asset From Memory" description="Simple example of loading an asset from memory." image="/img/playgroundsAndNMEs/divingDeeperNodeMaterialParticle1.jpg"/>

The way this works is that you load an asset into memory, convert it to a blob, create a url to that blob in memory, and then you have a url that you can use with any of the loading methods in Babylon.

Let's take a quick look at the 4 lines of code to achieve this.

First we load an object from a url directly into an arrayBuffer in memory.

```
const assetArrayBuffer = await BABYLON.Tools.LoadFileAsync("scenes/BoomBox.glb", true);
```

Next we convert that array buffer to a blob (in memory).

```
const assetBlob = new Blob([assetArrayBuffer]);
```

Then we create a url to that blob.

```
const assetUrl = URL.createObjectURL(assetBlob);
```

Then finally we load the asset into the scene from the url which points to the memory blob.

```
await BABYLON.SceneLoader.AppendAsync(assetUrl, undefined, scene, undefined, ".glb");
```

It's important to note that the Babylon scene loader will use the correct loader based on the file extension of the asset you're trying to load. In this case, since we're loading binary data saved to memory, the scene loader needs to be explicitly told which loader to use. This is why the final argument in the AppendAsync method is ".glb".


## 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](/features/featuresDeepDive/importers/glTF)
- [.obj](/features/featuresDeepDive/importers/oBJ)
- [.stl](/features/featuresDeepDive/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" isMain={true} category="Import"/>

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
const 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
const base64_model_content = "data:application/octet-stream;base64,-BASE 64 ENCODED DATA-";
const base64_model_content = "data:model/gltf-binary;base64,-BASE 64 ENCODED DATA-";
```

See an example here: <Playground id="#7F6S08#55" 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" isMain={true} category="Import"/>

### SceneLoader.ImportMeshAsync

[Asynchronous](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous) version of the ImportMesh function. The result can be obtained by calling on the returned [Promise](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Promises) or by using the [await](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await) keyword (note: to be able to use the await keyword in the `createScene` function, it has to be marked as async in its definition).

```javascript
// The first parameter can be set to null to load all meshes and skeletons
const importPromise = BABYLON.SceneLoader.ImportMeshAsync(["myMesh1", "myMesh2"], "./", "duck.gltf", scene);
importPromise.then((result) => {
  //// Result has meshes, particleSystems, skeletons, animationGroups and transformNodes
});
```

See an example here: <Playground id="#TVHK90" title="Import Mesh Async with Promises" description="Importing an object in your scene with async/await paradigm" image="/img/playgroundsAndNMEs/divingDeeperFileImport4.jpg" isMain={true} category="Import"/>

or

```javascript
// The first parameter can be set to null to load all meshes and skeletons
const result = await BABYLON.SceneLoader.ImportMeshAsync(["myMesh1", "myMesh2"], "./", "duck.gltf", scene);
// Result has meshes, particleSystems, skeletons, animationGroups and transformNodes
```

See an example here: <Playground id="#YAL1RN" title="Import Mesh Async with await" description="Importing an object in your scene with async/await paradigm" image="/img/playgroundsAndNMEs/divingDeeperFileImport4.jpg" isMain={true} category="Import"/>

## 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) {
  const meshes = container.meshes;
  const 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" isMain={true} category="Import"/>

## 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](/features/featuresDeepDive/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
const 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](/features/featuresDeepDive/importers/assetManager)

## Direct loading base64 encoded models

Babylon.JS supports directly loading models from base64 encoded [Data URLs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) without
needing to create an object URL or download the file. When loading from a base64 data url the plugin is not automatically detected (with the exception of some
glb formats). The `pluginExtension` parameter should be set when using base64 data urls in order to ensure the correct plugin is used to load the model.

The format for a minimum base64 encoded model file is:

```
data:;base64,<base64_encoded_file_contents>
```

The **;** before **base64** and the **,** following it are both required. See here for an example of loading an obj file in base64 encoding:
<Playground id="#58T0JY" title="Load base64 model" description="Example showing how to load a base64 encoded model using the data url syntax" image="/img/playgroundsAndNMEs/pg-58T0JY.png" />



## OBJ File Import

To use it, you just have to reference the loader file:

```html
<script src="babylon.js"></script>
<script src="babylon.objFileLoader.js"></script>
```

You can find it [here](https://cdn.babylonjs.com/loaders/babylon.objFileLoader.js)

If you are using UMD imports via NPM, you need to reference with side-effects:

```javascript
import 'babylonjs-loaders'
```

If you wish to benefit from the tree-shakeable ES6 package, you need to reference:

```javascript
import '@babylonjs/loaders/OBJ/objFileLoader';
```

You can read more about [NPM support](/setup/frameworkPackages/npmSupport)

### Load

See [how to load from any file type](/features/featuresDeepDive/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;
```

When using OPTIMIZE_WITH_UV = true you may experience some discontinuities in shading. Setting OPTIMIZE_NORMALS will help with this problem:

```
BABYLON.OBJFileLoader.OPTIMIZE_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/



# STL File Import

You can find the STL loader [here](https://cdn.babylonjs.com/loaders/babylon.stlFileLoader.js)

To use it you just have to reference it after Babylon.js:

```html
<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](/features/featuresDeepDive/importers/loadingFileTypes)

By default, the STL loader swaps the Y and Z axes. To disable this behavior,
set

```javascript
BABYLON.STLFileLoader.DO_NOT_ALTER_FILE_COORDINATES = true;
```



# Importing Assets

The built in file type is `.babylon` and Babylon.js can load these without a plugin. All other file types require a plugin as described in this section.

Possible file types are gLTF, obj, stl

To help you with imported assets there is a manager for them.

**Note:** Since meshes you import can have a _rotationQuaternion_ set before applying a rotation set the _rotationQuaternion_ to _null


## Introduction

The [DeviceSourceManager](/typedoc/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
const 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
});
```

Here's a demonstration of how these Observables work
<Playground id="#Y4YWCD#1" title="Basic DeviceSourceManager Demo" description="Simple demonstration of how the DeviceSourceManager observables work" image="/img/playgroundsAndNMEs/pg-Y4YWCD-1.png"/>

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((eventData) => {
  // eventData will contain the event data that you'd find in something like a PointerEvent or KeyboardEvent
  // eventData also has an additional value inputIndex
});
```


Importing Assets

Coming next

Loading Any File Type

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

Loading Assets From Memory

Learn how to load assets directly from memory.

Incremental Loading System

Learn about the incremental loading system 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.

Asset Manager

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

Asset Containers

Learn all about using asset containers in Babylon.js.

Create Your Own File Importer

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