
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 into account. Consider asset containers as pools 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.webp"/>

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.webp"/>

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 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 returned `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.webp"/>

You can also set two parameters to the call to `instantiateModelsToScene`:

- nameFunction: This lets you decide what the names of the cloned entities will be (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 can 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 the 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 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 its current execution state. The state is represented by an enum, `BABYLON.AssetTaskState`, and has four 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 has two optional variables:

- message - a string briefly explaining the error (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.webp"/>

## Available tasks

There are 7 types of tasks that can be executed using the assets manager.

Each task extends the AbstractAssetTask class (and implements the 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 always correspond to the object type it creates. For example, the constructor signature of the CubeTextureAssetTask takes the same variables as the `BABYLON.CubeTexture` class. 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

This task is used to asynchronously 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 is 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 task loads an image (.png, .jpg, .gif). It creates 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 creates a new `BABYLON.Texture` from a provided 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

This is 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

This is the 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

This is the 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.webp" 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
- .SOG/SOGS Self-Organizing Gaussian https://github.com/fraunhoferhhi/Self-Organizing-Gaussians

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).



## Overview

The .glTF File Loader Plugin works in conjunction with Babylon's scene loader functions to import [glTF](https://www.khronos.org/gltf/) files.

<Alert severity="info" description="glTF 1.0 is deprecated. This page is primarily focused on glTF 2.0." />

## Setup

The recommended way to use the .glTF file loader plugin is via the `@babylonjs/loaders` ES6 NPM package. Please read [Loading Any File Type](/features/featuresDeepDive/importers/loadingFileTypes#npm) for more information about installing and using the loader package in your own build.

<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."/>

But for testing purposes, the following compiled JS files are offered on the public CDN at https://preview.babylonjs.com/loaders/:

- `babylon.glTF2FileLoader.js` - Only glTF 2.0
- `babylon.glTF1FileLoader.js` - Only glTF 1.0
- `babylon.glTFFileLoader.js` - Both glTF 2.0 and 1.0
- `babylonjs.loaders.js` - The full Babylon loaders package
- `babylonjs.loaders.min.js` - The full Babylon loaders package, minified

### Usage

When using the `@babylonjs/loaders` package, it is preferable to register the glTF file importer via the top-level dynamic loader registration function `registerBuiltInLoaders`.

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 Codecs Locally

If your glTF files use any of the following features, you'll need to take a few extra steps for production use.

| Feature                               | glTF extension             | Babylon interface        |
| ------------------------------------- | -------------------------- | ------------------------ |
| Draco compression                     | KHR_mesh_draco_compression | DracoDecoder             |
| Meshopt compression                   | EXT_meshopt_compression    | MeshoptCompression       |
| .ktx2, or Basis Universal Compression | KHR_texture_basisu         | KhronosTextureContainer2 |

<br/>
Babylon performs extra work at load time to decompress the data that uses these extensions. By default, it will:
- Download the required decoder files from the Babylon CDN.
- Use web workers (if available) to execute the code.

This behavior can lead to issues like GDPR compliance concerns or CSP violations, so we recommend hosting these resources yourself.

How you do this depends on your setup. In general, there are two approaches.

#### Via URL Configuration

You can provide a different base URL (or a full URL) for all decoders, or for each decoder individually. This way, Babylon loads them from your server instead of the CDN. Read how to do this in the
[CDN Support docs](/setup/frameworkPackages/CDN#deploying-your-own-version-of-the-resources).

#### Via Resource Injection

Alternatively, you can inject the decoder modules directly (or workers preloaded with them) instead of relying on Babylon to fetch them.
Follow the steps in the [ESM/NPM Support docs](/setup/frameworkPackages/es6Support#ktx2-decoder-packages) to set this up with the KTX2 and Draco decoders. (_Note: Meshopt compression does not yet support injection._)

## Loading the Scene

Use one of the 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.webp" isMain={true} category="Import"/>

### Content Security Policy for Embedded Images

A GLB file can store image bytes inside the binary file. When Babylon.js uses `ImageBitmap` decoding, including with WebGPU, it passes these in-memory bytes directly to the browser decoder. It does not create or fetch a `blob:` URL. You do not need to add `blob:` to `connect-src` only to load images embedded in a GLB file.

This behavior applies when the loader already has an `ArrayBuffer`, an `ArrayBufferView`, or a `Blob`. A URL string, including an application-created `blob:` URL, still uses the normal URL loading path and must be allowed by your Content Security Policy. The initial GLB request and external buffers or images must also be allowed by the CSP directive that covers their loading path.

WebGL can decode in-memory images through an HTML image element. If your application also supports WebGL, keep `blob:` in `img-src` when that path is used.

## Extensions

See the built-in [extensions](/typedoc/modules/babylon.gltf2.loader.extensions) in the API documentation.

You can also [create your own extensions](/features/featuresDeepDive/importers/glTF/createExtensions).

## Options

Each of the scene loader functions accepts an options object, where you can customize the behavior of the glTF loader plugin. See the [full list of available glTF options](/typedoc/classes/BABYLON.GLTFLoaderOptions) from the API documentation.

### Disabling Extensions

To disable an extension on load, set its `enabled` option:

```typescript
LoadAssetContainerAsync("asset.glb", scene, {
  pluginOptions: {
    gltf: {
      extensionOptions: {
        KHR_texture_basisu: {
          enabled: false,
        },
        myCustomExtension: {
          enabled: false,
        },
      },
    },
  },
});
```

## Behavior

### The \_\_root\_\_ node

A `__root__` node is added to hold every **glTF** and **GLB** model. glTF uses a right-handed coordinate system. In Babylon.js's default left-handed scenes, the loader applies the coordinate conversion to this root; in a right-handed scene, no handedness conversion is needed.

```javascript
scene.useRightHandedSystem = true;
```

Set the scene mode before loading. Do not mirror the imported meshes a second time. `loadedMeshes[0]` points to the added `__root__` node and `loadedMeshes[1]` points to the first loaded mesh.

See [Coordinate Systems and Handedness](/features/featuresDeepDive/mesh/transforms/coordinateSystems) for axis conventions, loader behavior, and DCC interoperability guidance.

### Skinning

See [Skinning](/features/featuresDeepDive/importers/glTF/glTFSkinning) for details on how skinning is implemented in Babylon.js for glTF 2.0.

## Properties and Methods

See the available [properties and methods](/typedoc/modules/babylon.gltffileloader) from the API documentation.

## Version 1 Only

Though deprecated, Babylon maintains a dedicated glTF loader plugin for glTF 1.0.

### 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 load 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

To support incremental loading (introduced in v1.5.0), go to [this page](https://github.com/BabylonJS/Exporters/tree/master/Tools/MakeIncremental) to get a tool that converts your .babylon file to a .incremental.babylon file alongside its 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.webp"/>

## Detailed Step-by-Step

For users who are less experienced with command-line tools, here's a more detailed step-by-step guide to using the tool:

1. Get the Exporters project (by either using git or downloading the ZIP):
   ![Exporters project](/img/importers/incremental_loading/incr_step_1.webp "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.webp "Navigating to the MakeIncremental directory")

4. Type `dotnet build` at the command prompt:
   ![.NET build](/img/importers/incremental_loading/incr_step_4.webp "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.webp "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.webp "Running the MakeIncremental command")

7. The script will generate quite a few files. You will need all of them except your original `my-scene.babylon`. Copy them to a directory your project can access (in this example, it's `/src`):
   ![Generated files](/img/importers/incremental_loading/incr_step_7.webp "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 run 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. It 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.webp" 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.webp"/>

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.webp"/>

## 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.webp" 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 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 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.webp" 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.webp" 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.webp" isMain={true} category="Import"/>

## ImportAnimationsAsync

Loads the animations from the file and merges them into 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.webp"/>

## 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 loading 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 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.webp" />



## Loading Assets Directly From Memory

There may be times when you'll want to pre-load (store) assets in memory and load those assets into your Babylon scene from memory. 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."/>

This works by loading an asset into memory, converting it to a blob, creating a URL for that blob in memory, and then using that URL with any of Babylon's loading methods.

Let's take a quick look at the four lines of code needed 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 for that blob.

```javascript
const assetUrl = URL.createObjectURL(assetBlob);
```

Finally, we load the asset into the scene from the URL that points to the in-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.

Plugins are currently available for:

- [.gltf](/features/featuresDeepDive/importers/glTF) (also used for binary version .glb)
- [.usd, .usda, .usdc, .usdz](/features/featuresDeepDive/importers/usd)
- [.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.webp" 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.webp" 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 into 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.webp"/>

## 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.webp"/>

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.webp"/>

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.webp" />

## Advanced usage

For any of the scene loading functions, you can pass an options object that configures the load function and the loader.

For example, if you need to explicitly pass the root URL (rather than allowing Babylon 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.webp"/>

## SceneLoader class (legacy)

The [`SceneLoader` class](/features/featuresDeepDive/importers/legacy) can also be used to load model files, but it 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.webp)

- By default, because the code is optimized for loading time, UV problems can appear, like this:

![Batman UVs problem](/img/how_to/import-obj/uv-issue.webp)

If you meet this problem, set the variable:

```javascript
BABYLON.OBJFileLoader.OPTIMIZE_WITH_UV = true;
```

Then, you'll get a better texture, but with a longer loading time.

![Batman UVs ok](/img/how_to/import-obj/uv-fixed.webp)

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 the 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/



## What are Smart Assets?

The **Smart Asset Manager** (SAM) is a per-scene registry that maps stable string *keys* to asset *URLs*, and tracks every runtime object that each load produced. Once an asset is loaded through SAM, you can ask the registry for it by key, swap its URL, reload it from disk, or unload it — without having to chase down references in `scene.meshes`, `scene.textures`, and so on.

SAM is the foundation that the Inspector V2 [Override Manager](/toolsAndResources/inspectorv2/overrideManager) and the [`.babylonproj`](/toolsAndResources/inspectorv2/projectFile) project file format are built on, but it's a standalone API in `@babylonjs/core` and useful on its own for any code that needs a stable, named handle to an external asset.

Use Smart Assets when you want to:

- Treat external models and textures as **named addressable resources** instead of opaque URLs.
- Allow assets to be **swapped or hot-reloaded** at runtime without manually disposing the objects they created.
- Resolve assets by key when you do **not** control how they were loaded (e.g. they were brought in by a glTF) but you still want a per-asset handle.
- Persist a scene's asset list as a portable, declarative JSON manifest.

The SAM API is a set of module-level functions on `BABYLON`. There is no class to `new` — the per-scene manager is created lazily the first time you touch the API, and lives on `scene.metadata` under a private symbol.

## Quick start

This playground registers a glTF and a standalone texture under stable keys, then opens the Inspector V2 **Project Authoring** (Smart Assets) pane and runs a timed tour of the API — reload, add-and-bind a texture, unload, reload, swap a URL, and remove — so you can watch the **Assets** list update live. Open the developer console to follow each step.

<Playground id="#CNWWA5#0" title="Smart Assets - Basics" description="Register, load, bind, reload, swap, and remove assets while watching the Inspector Smart Assets pane." />

The pattern is intentionally minimal:

```javascript
// No GetSmartAssetManager() call is needed — the per-scene manager is created
// lazily the first time you load (or register) an asset.

// Register + load a glTF in one call. Returns the AssetContainer.
await BABYLON.LoadSmartAssetAsync(scene, "boombox", "https://playground.babylonjs.com/scenes/BoomBox/BoomBox.gltf");

// Register + load a standalone texture (routed to Texture / CubeTexture / HDRCubeTexture by extension).
const env = await BABYLON.LoadSmartAssetTextureAsync(scene, "envmap", "https://playground.babylonjs.com/textures/environment.env");
scene.environmentTexture = env;
```

## Core API

All SAM functions are top-level exports from `@babylonjs/core` (also reachable as `BABYLON.*` in the Playground).

### Scene-file assets

| Function | Purpose |
| --- | --- |
| `RegisterSmartAsset(scene, key, url, options?)` | Add an entry to the registry without loading it. Use this when you want to declare an asset up front and load it later. |
| `LoadSmartAssetAsync(scene, key, url?, options?)` | Register (if a URL is supplied) and load a scene-file asset (glTF, OBJ, .babylon...). Returns the `AssetContainer`. Repeating the call with the same URL is a cache hit. |
| `UnloadSmartAssetAsync(scene, key)` | Dispose the loaded objects for a key but keep the registry entry. |
| `ReloadSmartAssetAsync(scene, key)` | Unload and re-load the asset, optionally fetching fresh bytes via a `reloadSource` callback. |
| `RemoveSmartAssetAsync(scene, key)` | Unload **and** remove the key from the registry. |
| `LoadAllSmartAssetsAsync(scene)` | Concurrently load every registered key that hasn't been loaded yet. Used by [project file](/toolsAndResources/inspectorv2/projectFile) load. |

### Standalone textures

```javascript
const texture = await BABYLON.LoadSmartAssetTextureAsync(scene, "albedo", "https://playground.babylonjs.com/textures/bloc.jpg");
```

SAM routes texture URLs to the correct loader based on file extension: `.env` and `.dds` go through `CubeTexture`, `.hdr` through `HDRCubeTexture`, everything else through `Texture`. The set of recognized texture extensions is exposed by `BABYLON.GetSmartAssetTextureExtensions()`.

When a texture key doesn't already have a `displayName`, SAM sets it to the key. This is why textures loaded from `blob:` URLs (e.g. user-uploaded files) still show a human-readable name in the Scene Explorer and material slot pickers instead of an opaque URL.

### Querying the registry

| Function | Purpose |
| --- | --- |
| `GetSmartAssetManager(scene)` | Returns (and lazily creates) the manager for a scene. **Not required before loading** — `Load*`/`Register*` create the manager for you. Only call it when you need the manager instance directly (e.g. to set `onAssetNotFound` or subscribe to `onChangedObservable`). |
| `GetAllSmartAssets(scene)` | A read-only `Map<key, url>` of every registered entry. |
| `FindSmartAssetKeyForObject(scene, object)` | Reverse lookup: returns the key that owns a runtime `Node` / `Material` / `BaseTexture` / `AnimationGroup`, or `undefined` if the object was created locally. |
| `AddSmartAssetManagerCreatedObserver(callback)` | Notified once for each new manager (useful for inspector services). |

The manager itself exposes:

- `sam.scene` — the owning scene.
- `sam.onChangedObservable` — fires on every registration, load, unload, reload, or remove. Subscribe to keep UI in sync.
- `sam.onAssetNotFound` — see [the fallback section below](#recovering-from-missing-assets).

## Declarative asset maps

Instead of registering assets one at a time, you can describe the whole set as a small JSON document and load it in one shot:

```json
{
    "version": 1,
    "assets": {
        "boombox": { "url": "BoomBox/BoomBox.gltf" },
        "buggy":   { "url": "Buggy/glTF/Buggy.gltf" },
        "envmap":  { "url": "https://playground.babylonjs.com/textures/environment.env", "type": "texture" }
    }
}
```

`LoadSmartAssetMapAsync` accepts a URL (fetched as JSON), a `File` (typically user-dragged), or a pre-parsed object. Relative URLs are resolved against the optional `rootUrl` argument; absolute, `data:`, and `blob:` URLs are used as-is, so you can mix and match. Entries can declare a loader `type` (e.g. `"texture"`), an explicit `extension` (useful for blob URLs that have no recognizable filename), or arbitrary user-defined `metadata`.

`SerializeSmartAssetManagerMap(scene, baseUrl?)` rebuilds the same document from the live registry, so the format round-trips cleanly. Pass a `baseUrl` to relativize URLs that share its prefix.

Asset maps are also the asset layer of the [`.babylonproj`](/toolsAndResources/inspectorv2/projectFile) project file format; the project file just adds an overrides section and a companion `.babylon` for user-created objects on top of the same JSON.

## Binding textures to materials

SAM-tracked textures keep their identity across reloads, so the natural pattern for assigning a texture to a material slot is to look it up by key rather than by URL or by index into `scene.textures`:

```javascript
const findTexture = (key) =>
    scene.textures.find((t) => BABYLON.FindSmartAssetKeyForObject(scene, t) === key);

const mat = new BABYLON.PBRMaterial("paintMat", scene);
mat.albedoTexture = findTexture("albedo");
```

Re-registering the same key with a new URL atomically swaps the underlying texture; bindings made through the helper above pick up the new texture without any extra work.

<Playground id="#ETJUZH#0" title="Smart Assets - Textures and Material Binding" description="Load textures via SAM and bind them to PBR material slots." />

This is the exact pattern the `.babylonproj` loader uses to re-attach user-authored materials to SAM-tracked textures after a round trip — see [Project Files](/toolsAndResources/inspectorv2/projectFile#companion-babylon-and-texture-bindings).

## Recovering from missing assets

If a registered URL fails to load (404, dead `blob:` URL backed by a closed `FileSystemFileHandle`, moved local file, ...), SAM calls the optional `onAssetNotFound` callback. Return a replacement URL string or `File` object to retry, or `null` to give up.

```javascript
// GetSmartAssetManager() is not an init step — loading an asset already created
// the manager. You only fetch the handle here because attaching a callback needs
// the instance. (The manager is also created on demand if you call this first.)
const sam = BABYLON.GetSmartAssetManager(scene);

sam.onAssetNotFound = async (key, expectedUrl) => {
    console.warn(`"${key}" not found at ${expectedUrl}`);
    if (key === "hero") {
        // A real editor might prompt the user to pick a file here.
        return "https://playground.babylonjs.com/scenes/BoomBox/BoomBox.gltf";
    }
    return null;
};
```

The retry also **rewrites the registry**, so subsequent reloads use the resolved URL directly. This is what makes a `.babylonproj` resilient to being reopened on a machine where the user's local file paths have changed.

You don't have to build the file-picker UI yourself. Inspector V2 ships a ready-made missing-asset prompt — assign `inspectorAssetNotFoundHandler` (or call `installInspectorAssetNotFoundHandler(sam)`, both public `@babylonjs/inspector-v2` exports) and a failed load shows a *"Locate the file or click Skip"* dialog with a native file picker; the chosen file is returned to SAM as the replacement. This is exactly how the Inspector's [Project Authoring](/toolsAndResources/inspectorv2/projectFile) pane wires `onAssetNotFound`, and any app that opens Inspector V2 can reuse it:

```javascript no-code-variants
// Requires Inspector V2 to be open (it hosts the prompt).
sam.onAssetNotFound = BABYLON.INSPECTOR.inspectorAssetNotFoundHandler;
```

The playground below uses this built-in prompt: when the broken URL fails, click **Locate File…** and pick any `.glb`/`.gltf` (or Skip).

<Playground id="#L83X13#0" title="Smart Assets - onAssetNotFound Fallback" description="Recover from a broken asset URL using the Inspector's built-in file-picker prompt." />

## How SAM tracks runtime objects

When `LoadSmartAssetAsync` returns, every `Node`, `Material`, `BaseTexture`, `AnimationGroup`, `Light`, and `Camera` in the resulting `AssetContainer` is associated with the asset's key via an internal `WeakMap`. That's what makes `FindSmartAssetKeyForObject` cheap and lets `UnloadSmartAssetAsync` cleanly dispose only the objects a particular asset produced.

The manager itself is stored on `scene.metadata` under a private `Symbol`, so it's invisible to `Object.values` / `JSON.stringify` (and doesn't accidentally appear in the Inspector's metadata viewer or create a cycle when scenes are serialized).

When the scene is disposed, the manager unloads everything it owns and detaches itself automatically.

## Tree-shaking notes

SAM is fully tree-shakeable. The manager module has no top-level side effects: importing `GetSmartAssetManager` alone does **not** pull in texture loaders, scene-file loaders, the asset-map serializer, or anything else. Each function in the API table above lives in its own export, so an application that only needs `LoadSmartAssetTextureAsync` does not pay for the rest.

## Related

- [Override Manager](/toolsAndResources/inspectorv2/overrideManager) — persistent property diffs that work alongside SAM-tracked assets.
- [Project Files (.babylonproj)](/toolsAndResources/inspectorv2/projectFile) — the on-disk format that composes a SAM map, overrides, and a companion `.babylon` for user-created scene content.



# 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;
```



## Overview

The OpenUSD file loader imports `.usd`, `.usda`, `.usdc`, and `.usdz` stages. A WebAssembly build of [OpenUSD](https://openusd.org/) composes and extracts the stage in a Web Worker, then Babylon.js creates the scene objects from transferable binary buffers. No intermediate glTF or `.babylon` file is created.

The loader supports:

- OpenUSD composition, including sublayers, references, and payloads, when all dependencies are supplied to the loader
- Transform hierarchies, stage units, up-axis conversion, and visibility
- Polygon meshes, normals, UVs, display colors, geometric subsets, and analytic cube, sphere, cylinder, and cone primitives
- `UsdPreviewSurface` materials and `UsdUVTexture` textures
- Native instances and `UsdGeomPointInstancer` batches backed by Babylon.js thin instances
- `UsdSkel` skeletons, skinning, and animation
- Blend shapes, in-between shapes, and animated morph influences

## Setup

The recommended setup for an NPM application is the dynamic loader registration function. It loads the USD implementation only when a USD file is first requested.

```typescript
import { registerBuiltInLoaders } from "@babylonjs/loaders/dynamic";

registerBuiltInLoaders();
```

You can instead register the USD loader statically:

```typescript
import "@babylonjs/loaders/USD/usdFileLoader";
```

For a script-based experiment, load the complete loader bundle after Babylon.js:

<Alert severity="warning" title="Warning" description="The Babylon.js CDN should not be used in production environments. Serve Babylon.js, the loader bundle, and the OpenUSD runtime assets from your own CDN when deploying an application." />

```html
<script src="https://cdn.babylonjs.com/babylon.js"></script>
<script src="https://cdn.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>
```

The loader downloads its OpenUSD worker, WebAssembly module, JavaScript glue, and data bundle when it is first used. Browsers can cache those assets for subsequent imports.

## Loading a USD File

After registering the plugin, use any of the standard scene loader functions:

```typescript
await AppendSceneAsync("https://example.com/assets/model.usdz", scene);
```

Use `LoadAssetContainerAsync` when the imported objects should not be added to the scene immediately:

```typescript
const container = await LoadAssetContainerAsync("https://example.com/assets/model.usda", scene);
container.addAllToScene();
```

See a complete example here: <Playground id="#H0RPC8#0" title="Load an OpenUSD Stage" description="Load a public USDA stage with the Babylon.js OpenUSD file loader." isMain={true} category="Import" />

## Loading a Stage with Sublayers and References

OpenUSD stages often consist of a root layer plus other layers, payloads, and textures. The browser loader stages those files in a virtual filesystem before OpenUSD opens the root layer.

<Alert severity="info" title="Supply every dependency" description="Loading the root layer from a URL does not make its dependencies available automatically. Fetch each external layer, payload, and texture, then pass its bytes through pluginOptions.usd.files. A USDZ package that contains all of its dependencies normally needs only the package itself." />

Virtual paths must preserve the directory structure used by the authored asset paths. For example, assume the root layer is staged as `Package/Scenes/Main.usda`:

```text
Package/
|-- Scenes/
|   `-- Main.usda
|-- Layers/
|   `-- Geometry.usdc
`-- Looks/
    `-- Appearance.usda
```

If `Main.usda` contains:

```usda
#usda 1.0
(
    subLayers = [
        @../Layers/Geometry.usdc@,
        @../Looks/Appearance.usda@
    ]
)
```

load the root and supporting layers as follows:

```typescript
const assetRoot = "https://example.com/assets/Package";

const [geometryLayer, appearanceLayer] = await Promise.all([
    fetch(`${assetRoot}/Layers/Geometry.usdc`).then((response) => response.arrayBuffer()),
    fetch(`${assetRoot}/Looks/Appearance.usda`).then((response) => response.arrayBuffer()),
]);

await AppendSceneAsync(`${assetRoot}/Scenes/Main.usda`, scene, {
    pluginOptions: {
        usd: {
            rootFileName: "Package/Scenes/Main.usda",
            files: {
                "Package/Layers/Geometry.usdc": geometryLayer,
                "Package/Looks/Appearance.usda": appearanceLayer,
            },
        },
    },
});
```

The keys in `files` are virtual paths, not URLs. `rootFileName` gives the root layer its path in that same virtual filesystem, so OpenUSD can resolve each relative asset path exactly as authored.

See this composition working entirely from in-memory layers: <Playground id="#8VK7U1#0" title="Load Multiple OpenUSD Sublayers" description="Compose a root USDA layer with geometry and appearance sublayers supplied through the virtual file map." />

### Loading a Local Directory

For local assets, let the user select a directory and preserve each file's `webkitRelativePath`. If the directory contains multiple `.usd`, `.usda`, `.usdc`, or `.usdz` files, ask the user which one is the root layer.

```html
<input id="usdDirectory" type="file" webkitdirectory multiple />
```

```typescript
const input = document.getElementById("usdDirectory") as HTMLInputElement;
const selectedFiles = Array.from(input.files ?? []);
const rootFile = selectedFiles.find((file) => file.webkitRelativePath.endsWith("/Scenes/Main.usda"));

if (!rootFile) {
    throw new Error("The root USD layer was not selected.");
}

const entries = await Promise.all(
    selectedFiles
        .filter((file) => file !== rootFile)
        .map(async (file) => [file.webkitRelativePath, await file.arrayBuffer()] as const)
);

await AppendSceneAsync(rootFile, scene, {
    pluginOptions: {
        usd: {
            rootFileName: rootFile.webkitRelativePath,
            files: Object.fromEntries(entries),
        },
    },
});
```

### Absolute Asset Paths

`resolveByFileName` defaults to `true`. When an unresolved asset uses an absolute path authored on another computer, the loader can conservatively match one supplied virtual file with the same file name.

```typescript
pluginOptions: {
    usd: {
        rootFileName,
        files,
        resolveByFileName: true,
    },
}
```

This fallback only works when the file name is unambiguous. Preserve the authored directory layout whenever possible, especially when different directories contain files with the same name. Set `resolveByFileName` to `false` to require strict path resolution.

## Diagnostics

Use the loader callbacks to display progress, collect OpenUSD messages, and detect missing dependencies:

```typescript
await AppendSceneAsync(rootFile, scene, {
    pluginOptions: {
        usd: {
            rootFileName,
            files,
            onProgress: ({ phase, message }) => {
                console.log(phase, message);
            },
            onLog: (level, message) => {
                console.log(`[${level}] ${message}`);
            },
            onComplete: ({ timings, statistics, missingAssets }) => {
                console.table(timings);
                console.table(statistics);
                console.log("Missing assets:", missingAssets);
            },
        },
    },
});
```

`missingAssets` lists references that OpenUSD could not resolve from the root layer, a USDZ package, or the supplied virtual files.

## Hosting the OpenUSD Runtime

By default, the worker and OpenUSD runtime are downloaded from the Babylon.js CDN. To host them with your application, copy all four runtime files from the same protocol version and configure their URLs for each load:

```typescript
const importerRoot = "/runtime/babylonUsdImporter/";

await AppendSceneAsync("/assets/model.usdz", scene, {
    pluginOptions: {
        usd: {
            workerUrl: `${importerRoot}babylon-usd-importer.worker.js`,
            glueUrl: `${importerRoot}babylon-usd-importer.js`,
            wasmUrl: `${importerRoot}babylon-usd-importer.wasm`,
            dataUrl: `${importerRoot}babylon-usd-importer.data`,
        },
    },
});
```

Keep these four files together and use the protocol version associated with your `@babylonjs/loaders` version. Mixing runtime files or protocol versions is not supported.

## Current Limitations

- `UsdPreviewSurface` is supported; MaterialX and other surface shader networks currently use the default material.
- PNG, JPEG, BMP, and WebP textures are supported. Convert other texture formats before loading them in a browser.
- Animated point-instancer data is imported at its first authored frame as static thin instances.
- Nested point instancers are not currently supported.
- Mesh-name filtering is not currently supported; `ImportMeshAsync` imports the complete composed stage.



# Importing Assets

The built-in file type is `.babylon`, and Babylon.js can load it without a plugin. All other file types require a plugin, as described in this section.

Possible file types include glTF, OpenUSD, splat, OBJ, and STL.

To help you manage imported assets, Babylon.js provides an asset manager.

**Note:** Since imported meshes can already have a `rotationQuaternion` set, set `rotationQuaternion` to `null` before applying a rotation.


## Introduction

The [DeviceSourceManager](/typedoc/classes/babylon.devicesourcemanager) is a class that manages connections for various user input devices and provides methods for 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.webp"/>

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
  }
}
```

You can also use optional chaining to fit the checks 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 a given device's identifiers.

```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.webp"/>

For keyboards and pointers, you can use an event-based system to get the current 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 Assets From Memory

Learn how to load assets directly from memory.

.glTF File Loader Plugin

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

OpenUSD File Loader Plugin

Load composed OpenUSD stages from .usd, .usda, .usdc, and .usdz files 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.

Loading Any File Type

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

Incremental Loading System

Learn about the incremental loading system in Babylon.js.

Asset Containers

Learn all about using asset containers in Babylon.js.

Smart Assets

A scene-level registry that maps stable keys to asset URLs so models, textures, and materials can be reloaded, swapped, and persisted independently of the runtime objects they create.

Create Your Own File Importer

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

SceneLoader class (legacy)

Documentation page for SceneLoader class (legacy)

Gaussian Splatting File Loader Plugin

Learn about the Gaussian Splatting File Loader Plugin available in Babylon.js.