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.

Currently plugins can be found for:

• .glTF also use for binary version .glb
• .obj
• .stl

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>

For NPM usage see: https://www.npmjs.com/package/babylonjs-loaders

Once the plugin is referenced, the SceneLoader class can be used which provides a few loading methods.

SceneLoader.Append

Loads all babylon assets from the file and appends them to the scene

BABYLON.SceneLoader.Append("./", "duck.gltf", scene, function (scene) {
  // do something with the scene
});

See an example here: Append An Object

Loads all babylon assets from a string and appends them to the scene

BABYLON.SceneLoader.Append("", "data:" + gltfString, scene, function (scene) {
  // do something with the 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:

const base64_model_content = "data:;base64,BASE 64 ENCODED DATA...";
BABYLON.SceneLoader.Append("", base64_model_content, scene, function (scene) {
  // do something with the scene
});

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

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

SceneLoader.Load

Loads all babylon assets from the file and creates a new scene

BABYLON.SceneLoader.Load("/assets/", "batman.obj", engine, function (scene) {
  // do something with the scene
});

SceneLoader.ImportMesh

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

// 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: Import Mesh

SceneLoader.ImportMeshAsync

Asynchronous version of the ImportMesh function. The result can be obtained by calling on the returned Promise or by using the 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).

// The first parameter can be set to null to load all meshes and skeletons
const importPromise = BABYLON.SceneLoader.ImportMeshAsync(["myMesh1", "myMesh2"], "./", "duck.gltf", scene);
importPromise.then((result) => {
  //// Result has meshes, particleSystems, skeletons, animationGroups and transformNodes
});

See an example here: Import Mesh Async with Promises

or

// The first parameter can be set to null to load all meshes and skeletons
const result = await BABYLON.SceneLoader.ImportMeshAsync(["myMesh1", "myMesh2"], "./", "duck.gltf", scene);
// Result has meshes, particleSystems, skeletons, animationGroups and transformNodes

See an example here: Import Mesh Async with await

SceneLoader.LoadAssetContainer

Loads all babylon assets from the file and does not append them to the scene

BABYLON.SceneLoader.LoadAssetContainer("./", "duck.gltf", scene, function (container) {
  const meshes = container.meshes;
  const materials = container.materials;
  //...

  // Adds all elements to the scene
  container.addAllToScene();
});

See an example here: Asset Container Load Example

SceneLoader.ImportAnimations

Loads the animations from the file and merges them to the scene You can customize the import process using options and callbacks

BABYLON.SceneLoader.ImportAnimations("./", "Elf_run.gltf", scene);

See an example here: Importing Animations

SceneLoader.AppendAsync

There are also Async versions of these functions that return promises:

BABYLON.SceneLoader.AppendAsync("./", "duck.gltf", scene).then(function (scene) {
  // do something with the scene
});

See How to Use Promises to learn more about using promises.

Advanced Usage

Use the onPluginActivatedObservable to set properties and call methods specific to a particular loader.

BABYLON.SceneLoader.OnPluginActivatedObservable.add(function (loader) {
  if (loader.name === "gltf") {
    // do something with the loader
    // loader.<option1> = <...>
    // loader.<option2> = <...>
  }
});

Alternatively, the static synchronous SceneLoader functions return the plugin.

const loader = BABYLON.SceneLoader.Load("./", "duck.gltf", engine, function (scene) {
  // do something with the scene
});

// do something with the loader
// loader.<option1> = <...>
// loader.<option2> = <...>

Loading multiple assets

For assistance when load multiple assets the AssetsManager class can be used. See Load Files with Assets Manager

Direct loading base64 encoded models

Babylon.JS supports directly loading models from base64 encoded Data URLs without needing to create an object URL or download the file. When loading from a base64 data url the plugin is not automatically detected (with the exception of some glb formats). The pluginExtension parameter should be set when using base64 data urls in order to ensure the correct plugin is used to load the model.

The format for a minimum base64 encoded model file is:

data:;base64,<base64_encoded_file_contents>

The ; before base64 and the , following it are both required. See here for an example of loading an obj file in base64 encoding:

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.

.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