
An AssetContainer can be used to manage a list of assets (like nodes, cameras, lights, meshes, etc..). These 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#1016" 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#439" 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 executed 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.RegisterSceneLoaderPlugin` function.

### Plugins

A file importer should implement the `ISceneLoaderPluginAsync` interface.

<Alert severity="warning" title="Warning" description="Avoid using ISceneLoaderPlugin as it is deprecated and has been replaced by ISceneLoaderPluginAsync" />

An abbreviated example of a file importer (scene loader plugin) might look something like this:

```typescript
import { ISceneLoaderPluginAsync } from "@babylonjs/core/Loading/sceneLoader";

class MyCustomImporter implements ISceneLoaderPluginAsync {
  public readonly name = "myCustomImporter";

  public readonly extensions = ".myCustomExtension";

  public async importMeshAsync(...) {
    // Load specified meshes into the Scene
  }

  public async loadAsync(...) {
    // Load all data into the Scene
  }

  public async loadAssetContainerAsync(...) {
    // Load all data into an AssetContainer
  }
}
```

A plugin instance can be passed to `BABYLON.RegisterSceneLoaderPlugin`, but plugin factories are more flexible and full featured, so we recommend using them to create your custom importers.

### Plugin Factories

When you register a plugin, you can register a plugin factory rather than a plugin instance. The factory must have a `createPlugin` function that returns an instance of the plugin. The factory is invoked each time a load function is called. The `pluginOptions` property of the loader options are also passed to the factory function. This makes it possible for your file importer to be configurable through options.

A plugin factory can return the plugin instance either synchronously or asynchronously. We recommend you dynamically import your plugin to avoid loading it until it is needed. For example:

```typescript
import { RegisterSceneLoaderPlugin } from "@babylonjs/core/Loading/sceneLoader";

RegisterSceneLoaderPlugin({
  name: "myCustomImporter",
  extensions: ".myCustomExtension",
  createPlugin: async () => {
    const { MyCustomImporter } = await import("./MyCustomImporter");
    return new MyCustomImporter();
  },
});
```

To expose options for your custom file importer, you should first augment the `SceneLoaderPluginOptions` interface to add options for your importer. For example, if the name of your importer is `myCustomImporter`, you would add the following to your code:

```typescript
type MyCustomImporterOptions = { option1?: string, option2?: number };

declare module "@babylonjs/core" {
  export interface SceneLoaderPluginOptions {
    myCustomImporter: MyCustomImporterOptions;
  }
}
```

Then, when you register your file importer, you can access the options like this:

```typescript
import { RegisterSceneLoaderPlugin } from "@babylonjs/core/Loading/sceneLoader";

RegisterSceneLoaderPlugin({
  name: "myCustomImporter",
  extensions: ".myCustomExtension",
  createPlugin: async (options) => {
    const { MyCustomImporter } = await import("./MyCustomImporter");
    return new MyCustomImporter(options["myCustomImporter"]);
  },
});
```

Note that in this example, you will need to modify the `MyCustomImporter` class to accept options (`MyCustomImporterOptions`) in its constructor.

Finally, these options can be passed into one of the scene loader functions like this:

```typescript
await LoadAssetContainerAsync("path/to/model", scene, {
  pluginOptions: {
    myCustomImporter: {
      option1: "hello world",
      option2: 42,
    },
  },
});
```



# Gaussian Splatting File Import
Babylon.js supports multiple Gaussian splatting file formats:
- .PLY
- .Splat
- .compressed.PLY
- Niantic .SPZ

To use it you just have to reference it after Babylon.js:

```html
<script src="Babylon.js"></script>
<script src="babylon.splatFileLoader.js"></script>
```

If you want to import splat files statically (not recommended), you can do so via:

```javascript
import "@babylonjs/loaders/SPLAT/splatFileLoader";
```

You can read more about [NPM support](/setup/frameworkPackages/npmSupport)



## Setup

You can find the loader [here](https://cdn.babylonjs.com/loaders/babylon.glTFFileLoader.js)

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

## 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 _cdn.babylonjs.com_. In case you want to deliver these files locally (e.g. for GDPR compliance), you can set the [DracoDecoder.DefaultConfiguration](https://doc.babylonjs.com/typedoc/classes/BABYLON.DracoDecoder) object to use local files:

```typescript
DracoDecoder.DefaultConfiguration = {
  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://cdn.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>
```

## NPM

When using the Babylon npm packages in your own build, it is preferable to register the glTF file importer via the top level dynamic loader registration function `registerBuiltInLoaders`. See [Loading Any File Type](/features/featuresDeepDive/importers/loadingFileTypes#npm) for more information.

If you want to import the glTF file importer statically (not recommended), you can do so via:

```javascript
import "@babylonjs/loaders/glTF/2.0";
```

You can read more about [NPM support](/setup/frameworkPackages/npmSupport)

## Loading the Scene

Use one of scene loader functions to load a glTF asset.
See [Load from any file type](/features/featuresDeepDive/importers/loadingFileTypes).

See an example here: <Playground id="#WGZLGJ#11018" 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 built in [extensions](/typedoc/modules/babylon.gltf2.loader.extensions) from the API documentation.

You can also [create your own extensions](/features/featuresDeepDive/importers/glTF/createExtensions).

## 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;
```



## 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#1017" 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
await BABYLON.AppendSceneAsync("src/my-scene.incremental.babylon", scene);
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).


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.AppendSceneAsync("duck.gltf", scene).then(function () {
  // do something with the scene
});
```

See an example here: <Playground id="#WGZLGJ#11155" 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.AppendSceneAsync("data:" + gltfString, scene).then(function () {
  // do something with the scene
});
```

See an example here: <Playground id="#88CB6A#165" 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.AppendSceneAsync(base64_model_content, scene).then(function () {
  // 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#386" 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"/>

## LoadSceneAsync

Loads all babylon assets from the file and creates a new scene

```javascript
BABYLON.LoadSceneAsync("/assets/", "batman.obj", engine).then(function (scene) {
  // do something with the scene
});
```

## SceneLoader.ImportMesh

<Alert severity="info">Note: This function is deprecated. Use the `ImportMeshAsync` function instead.</Alert>

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"/>

### 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.ImportMeshAsync("./duck.gltf", scene, { meshNames: ["myMesh1", "myMesh2"] });
importPromise.then((result) => {
  //// Result has meshes, particleSystems, skeletons, animationGroups and transformNodes
});
```

See an example here: <Playground id="#TVHK90#646" 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.ImportMeshAsync("./duck.gltf", scene, { meshNames: ["myMesh1", "myMesh2"] });
// Result has meshes, particleSystems, skeletons, animationGroups and transformNodes
```

See an example here: <Playground id="#YAL1RN#307" 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"/>

## LoadAssetContainerAsync

Loads all babylon assets from the file and does not append them to the scene

```javascript
BABYLON.LoadAssetContainerAsync("./duck.gltf", scene).then(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#1053" 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"/>

## ImportAnimationsAsync

Loads the animations from the file and merges them to the scene
You can customize the import process using options and callbacks

```javascript
BABYLON.ImportAnimationsAsync("./Elf_run.gltf", scene);
```

See an example here: <Playground id="#UGD0Q0#315" title="Importing Animations" description="Simple example showing how to import animations into your scene." image="/img/playgroundsAndNMEs/divingDeeperFileImport6.jpg"/>

## AppendSceneAsync

There are also `Async` versions of these functions that return promises:

```javascript
BABYLON.AppendSceneAsync("./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> = <...>
  }
});
```

## 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:

```javascript
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" />



## 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#57" title="Load Asset From Memory" description="Simple example of loading an asset from memory."/>

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.

```javascript
const assetArrayBuffer = await BABYLON.Tools.LoadFileAsync("scenes/BoomBox.glb", true);
```

Next we convert that array buffer to a blob (in memory).

```javascript
const assetBlob = new Blob([assetArrayBuffer]);
```

Then we create a url to that blob.

```javascript
const assetUrl = URL.createObjectURL(assetBlob);
```

Then finally we load the asset into the scene from the url which points to the memory blob.

```javascript
await BABYLON.AppendSceneAsync(assetUrl, scene, {
    pluginExtension: ".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 `AppendSceneAsync` method (the options object) specifies the `pluginExtension` as `".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](/features/featuresDeepDive/importers/glTF) (also used for binary version .glb)
- [.obj](/features/featuresDeepDive/importers/oBJ)
- [.stl](/features/featuresDeepDive/importers/stl)
- [.ply, .compressed.ply, .splat, .spz](/features/featuresDeepDive/importers/gaussianSplatting)

You can also create your own [custom importer](/features/featuresDeepDive/importers/createImporters) for additional file types.

#### CDN

To quickly add support for all loaders the following script can be added to your page:

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

##### Production links

```html
<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)

```html
<script src="https://preview.babylonjs.com/babylon.js"></script>
<script src="https://preview.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>
```

Once the plugin is referenced, scene loader functions can be used to load model files.

#### NPM

When you have a built/bundled app, you can use [@babylonjs/loaders](https://www.npmjs.com/package/@babylonjs/loaders).

The preferred way to bring in the loaders is via:

```typescript
import { registerBuiltInLoaders } from "@babylonjs/loaders/dynamic";
...
registerBuiltInLoaders();
```

This will register all supported loaders, but internally uses dynamic imports to only download/load a specific importer (e.g. glTF, splat, etc.) when a model of that type is first loaded.

You can also register all loaders statically (e.g. they will all be included in your primary bundle). This is not recommended, but can be done via:

<Alert severity="warning" title="Warning" description="If possible, prefer registerBuiltInLoaders rather than statically importing loaders." />

```typescript
import "@babylonjs/loaders";
```

If you are using the UMD package, dynamic loading is not supported. Instead, you should use the static import approach. See [`babylonjs-loaders`](https://www.npmjs.com/package/babylonjs-loaders).

Importers must be registered with one of these approaches before the scene loader functions can be used.

## LoadAssetContainerAsync

Loads all babylon assets from the file and does not append them to the scene. Instead, they are returned in an `AssetContainer` object.

```typescript
const container = await BABYLON.LoadAssetContainerAsync("path/to/model", scene);
```

See an example here: <Playground id="#C3MP99#26" 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"/>

## AppendSceneAsync

Loads all babylon assets from the file and appends them to the scene.

```typescript
await BABYLON.AppendSceneAsync("path/to/model", scene);
```

See an example here: <Playground id="#WGZLGJ#11018" title="Append An Object" description="Simple example showing how append an object to your scene." image="/img/playgroundsAndNMEs/divingDeeperFileImport1.jpg" isMain={true} category="Import"/>

## LoadSceneAsync

Loads all babylon assets from the file and creates a new scene.

```typescript
const scene = await BABYLON.LoadSceneAsync("path/to/model", engine);
```

## ImportAnimationsAsync

Loads the animations from the file and merges them to the scene.
You can customize the import process using options and callbacks.

```typescript
await BABYLON.ImportAnimationsAsync("path/to/model", scene);
```

See an example here: <Playground id="#UGD0Q0#312" title="Importing Animations" description="Simple example showing how to import animations into your scene." image="/img/playgroundsAndNMEs/divingDeeperFileImport6.jpg"/>

## ImportMeshAsync

Loads the meshes from the file and appends them to the scene.

```typescript
await BABYLON.ImportMeshAsync("path/to/model", scene);
```

## String encoded model sources

For any of the scene loading functions, you can also pass a string containing the model source data itself.

Loads all babylon assets from a string and appends them to the scene.

```typescript
await BABYLON.AppendSceneAsync("data:" + gltfString, scene);
```

See an example here: <Playground id="#ANPU8N#10" 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:

```typescript
const base64_model_content = "data:;base64,BASE 64 ENCODED DATA...";
await BABYLON.AppendSceneAsync(base64_model_content, scene);
```

Note that two mime types are allowed in the string data:

```typescript
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="#68J9RS#1" 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"/>

When loading from a string that is not glTF data, you must specify the pluginExtension option to tell Babylon which loader to use. For example, to load an OBJ file from a string:

```typescript
const objDataURL = "data:;base64,ZyB0ZXRyYWhlZHJvbgoKdiAx...";
await BABYLON.AppendSceneAsync(objDataURL, scene, { pluginExtension: "obj" });
```

See example here: <Playground id="#58T0JY#46" 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" />

## Advanced usage

For any of the scene loading functions, you can pass in an options object that configures the load function and the loader.

For example, if you need to explicitly pass in the root url (rather than allowing us to try to infer it from the file path), you can do so like this:

```typescript
await BABYLON.AppendSceneAsync("model_file_name", scene, { rootUrl: "https://example.com/assets/" });
```

You can also pass in loader specific options. For example, with the glTF loader, you can pass in general glTF options and even options for individual glTF extensions. For example:

```typescript
const assetContainer = await BABYLON.LoadAssetContainerAsync("https://raw.githubusercontent.com/BabylonJS/Assets/master/meshes/LevelOfDetail.glb", scene, {
  pluginOptions: {
    gltf: {
      skipMaterials: false,
      extensionOptions: {
        MSFT_lod: {
          maxLODsToLoad: 1,
        },
      },
    },
  },
});
```

See an example here: <Playground id="#IAAJMR#4" title="Load With Detailed Options" description="Simple example showing how to pass glTF loader options and glTF extension options." image="/img/playgroundsAndNMEs/divingDeeperFileImport7.jpg"/>

## SceneLoader class (legacy)

The [`SceneLoader` class](/features/featuresDeepDive/importers/legacy) can also be used to load model files, but has effectively been replaced by module level scene loader functions as they result in better tree shaking (smaller bundles) and offer a simple solution for passing in loader options.



## 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)

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

When using the Babylon npm packages in your own build, it is preferable to register the OBJ file importer via the top level dynamic loader registration function `registerBuiltInLoaders`. See [Loading Any File Type](/features/featuresDeepDive/importers/loadingFileTypes#npm) for more information.

If you want to import the OBJ file importer statically (not recommended), you can do so via:

```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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
BABYLON.OBJFileLoader.OPTIMIZE_NORMALS = true;
```

To have your imported model inverted on the y-axis, set the variable:

```javascript
BABYLON.OBJFileLoader.INVERT_Y = true;
```

To invert your imported textures on the y-axis, set the variable:

```javascript
BABYLON.OBJFileLoader.INVERT_TEXTURE_Y = true;
```

By default if an 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:

```javascript
BABYLON.OBJFileLoader.MATERIAL_LOADING_FAILS_SILENTLY = false;
```

If an MTL is defined in your OBJ and you wish to have it ignored, set the variable:

```javascript
BABYLON.OBJFileLoader.SKIP_MATERIALS = true;
```

The OBJ-Loader's behavior has changed in this PR - [https://github.com/BabylonJS/Babylon.js/pull/14920](https://github.com/BabylonJS/Babylon.js/pull/14884) to support handedness correctly. If you have issues loading your OBJ after the change, but it had worked previously, you can set the following flag to fix it:

```javascript
OBJFileLoader.USE_LEGACY_BEHAVIOR = 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 different 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)

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

To use it you just have to reference it after Babylon.js:

```html
<script src="Babylon.js"></script>
<script src="babylon.stlFileLoader.js"></script>
```

When using the Babylon npm packages in your own build, it is preferable to register the STL file importer via the top level dynamic loader registration function `registerBuiltInLoaders`. See [Loading Any File Type](/features/featuresDeepDive/importers/loadingFileTypes#npm) for more information.

If you want to import the STL file importer statically (not recommended), you can do so via:

```javascript
import "@babylonjs/loaders/STL/stlFileLoader";
```

You can read more about [NPM support](/setup/frameworkPackages/npmSupport)

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, splat, 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
});
```
