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.
To use it, you just have to instantiate it with a current scene:
var assetsManager = new BABYLON.AssetsManager(scene);
Then you can add tasks to the manager:
var meshTask = assetsManager.addMeshTask("skull task", "", "scenes/", "skull.babylon");
Each task provides an onSuccess
and an onError
callback:
meshTask.onSuccess = function (task) {
task.loadedMeshes[0].position = BABYLON.Vector3.Zero();
}
meshTask.onError = function (task, message, exception) {
console.log(message, exception);
}
You can do the same thing but with text and binary files:
var textTask = assetsManager.addTextFileTask("text task", "msg.txt");
textTask.onSuccess = function(task) {
console.log(task.text);
}
var binaryTask = assetsManager.addBinaryFileTask("binary task", "grass.jpg");
binaryTask.onSuccess = function (task) {
// Do something with task.data
}
Images are also supported through imageTask:
var imageTask = assetsManager.addImageTask("image task", "img.jpg");
imageTask.onSuccess = function(task) {
console.log(task.image.width);
}
Textures can also be loaded, through textureTask:
var textureTask = assetsManager.addTextureTask("image task", "img.jpg");
textureTask.onSuccess = function(task) {
material.diffuseTexture = task.texture;
}
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:
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:
This way the error is accessible also when using the assets manager observers:
assetsManager.onTaskErrorObservable.add(function(task) {
console.log('task failed', task.errorObject.message, task.errorObject.exception);
});
The manager itself provides four callbacks:
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:
assetsManager.onTaskSuccessObservable.add(function(task) {
console.log('task successful', task)
});
assetsManager.onTasksDoneObservable.add(function(tasks) {
var errors = tasks.filter(function(task) {return task.taskState === BABYLON.AssetTaskState.ERROR});
var successes = tasks.filter(function(task) {return task.taskState !== BABYLON.AssetTaskState.ERROR});
});
To launch all the tasks, you have to call:
assetsManager.load();
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:
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.
The mesh asset task is used to load a model externally (a .babylon, .obj, .gltf and so on).
Constructor signature:
constructor(name: string, meshesNames: any, rootUrl: string, sceneFilename: string)
Extra properties:
public loadedMeshes: Array<AbstractMesh>;
public loadedParticleSystems: Array<ParticleSystem>;
public loadedSkeletons: Array<Skeleton>;
Is used to async-load a (text) file.
Constructor signature:
constructor(name: string, url: string)
Extra properties:
public url: string;
public text: string;
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
Constructor signature:
constructor(name: string, url: string)
Extra properties:
public url: string;
public data: ArrayBuffer;
This function will load an image (.png, .jpg, .gif). It will create an HTMLImageElement object
Constructor signature:
constructor(name: string, url: string)
Extra properties:
public url: string;
public image: HTMLImageElement;
This will create a new BABYLON.Texture from a provided single url.
Constructor signature:
constructor(name: string, url: string, noMipmap?: boolean, invertY?: boolean, samplingMode: number = BABYLON.Texture.TRILINEAR_SAMPLINGMODE)
Extra properties:
public texture: Texture;
The same as the TextureAssetTask but for a cube texture
Constructor signature:
constructor(name: string, url: string, extensions?: string[], noMipmap?: boolean, files?: string[])
Extra properties:
public texture: CubeTexture;
Same as the CubeTextureAssetTask, but for HDR cube textures
constructor(name: string, url: string, size?: number, noMipmap = false, generateHarmonics = true, useInGammaSpace = false, usePMREMGenerator = false)
Extra properties:
public texture: HDRCubeTexture;
By default, the AssetsManager will display a loading screen while loading assets:
If you want to disable the loading screen, you have to set useDefaultLoadingScreen
to false:
assetsManager.useDefaultLoadingScreen = false;
The loading screen will also be displayed while loading a scene using SceneLoader if ShowLoadingScreen
is set to true (by default).
BABYLON.SceneLoader.ShowLoadingScreen = false;
In the same way, you can also display or hide the loading screen manually using these functions:
engine.displayLoadingUI();
engine.hideLoadingUI();
Loading text is controlled using loadingUIText
:
engine.loadingUIText = "text";
Background color is controlled using loadingUIBackgroundColor
:
engine.loadingUIBackgroundColor = "red";