Loading Any File Type

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 (also used for binary version .glb)
• .usd, .usda, .usdc, .usdz
• .obj
• .stl
• .ply, .compressed.ply, .splat, .spz

You can also create your own custom importer for additional file types.

CDN

To quickly add support for all loaders, the following script can be added to your page:

Production links

<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)

<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.

The preferred way to bring in the loaders is via:

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:

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.

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.

import { LoadAssetContainerAsync } from "@babylonjs/core/Loading/sceneLoader";
const container = await LoadAssetContainerAsync("path/to/model", scene);

See an example here: Asset Container Load Example

AppendSceneAsync

Loads all Babylon assets from the file and appends them to the scene.

import { AppendSceneAsync } from "@babylonjs/core/Loading/sceneLoader";
await AppendSceneAsync("path/to/model", scene);

See an example here: Append An Object

LoadSceneAsync

Loads all Babylon assets from the file and creates a new scene.

import { LoadSceneAsync } from "@babylonjs/core/Loading/sceneLoader";
const scene = await 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.

import { ImportAnimationsAsync } from "@babylonjs/core/Loading/sceneLoader";
await ImportAnimationsAsync("path/to/model", scene);

See an example here: Importing Animations

ImportMeshAsync

Loads the meshes from the file and appends them to the scene.

import { ImportMeshAsync } from "@babylonjs/core/Loading/sceneLoader";
await 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.

import { AppendSceneAsync } from "@babylonjs/core/Loading/sceneLoader";
await AppendSceneAsync("data:" + gltfString, scene);

See an example here: Append Assets From A String

You can also load a .glb binary file from a data string as long as the binary data is base64 encoded:

import { AppendSceneAsync } from "@babylonjs/core/Loading/sceneLoader";
const base64_model_content = "data:;base64,BASE 64 ENCODED DATA...";
await AppendSceneAsync(base64_model_content, scene);

Note that two mime types are allowed in the string data:

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: Load .glb From Binary Data

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:

import { AppendSceneAsync } from "@babylonjs/core/Loading/sceneLoader";
const objDataURL = "data:;base64,ZyB0ZXRyYWhlZHJvbgoKdiAx...";
await AppendSceneAsync(objDataURL, scene, { pluginExtension: "obj" });

See example here: Load base64 model

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:

import { AppendSceneAsync } from "@babylonjs/core/Loading/sceneLoader";
await 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:

import { LoadAssetContainerAsync } from "@babylonjs/core/Loading/sceneLoader";
const assetContainer = await 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: Load With Detailed Options

SceneLoader class (legacy)

The SceneLoader class 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.

Further reading

Framework Versions

Learn about the different versions of Babylon.js.

.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.

.obj File Loader Plugin

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

.stl File Loader Plugin

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

Asset Manager

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

The Meshes Library

Learn about the free available meshes in the Babylon.js meshes library.

Using External Assets In the Playground

Learn how to use external assets in the playground in Babylon.js.

• SceneLoader