
## 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)

If you are using ES6 imports via NPM, you need to reference with side-effects:

```javascript
import 'babylonjs-loaders'
```

You can read more about [NPM support](/setup/frameworkPackages/npmSupport)

### Load

See [how to load from any file type](/features/featuresDeepDive/importers/loadingFileTypes)
Babylon.js will know how to load the obj file and its mtl file automatically:

## Good things to know

- Your model doesn't have to be triangulated, as this loader will do it automatically.
- A Babylon.Mesh will be created for each object/group
- The obj model should be exported with -Z axis forward, and Y axis upward to be compatible with Babylon.js

![Axis](/img/how_to/import-obj/axys.jpg)

- By default, due to optimization in the code for loading time, UVs problems can appear, like this :

![Batman UVs problem](/img/how_to/import-obj/uv-issue.jpg)

If you meet this problem, set the variable:

```
BABYLON.OBJFileLoader.OPTIMIZE_WITH_UV = true;
```

Then, you'll have a better texture, but with a longer loading.

![Batman UVs ok](/img/how_to/import-obj/uv-fixed.jpg)

Depending on the modeling program you export your OBJ files from, textures may appear distorted or inverted. As a workaround, you can modify your imported model's UV coordinate scale via setting the variable:

```
BABYLON.OBJFileLoader.UV_SCALE = new BABYLON.Vector2(xValue, yValue)
```

Although not part of Wavefront OBJ file format, some OBJ files include vertex colors. If you are loading such a file and want vertices with colors, set the variable:

```
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:

```
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:

```
BABYLON.OBJFileLoader.OPTIMIZE_NORMALS = true;
```

To have your imported model inverted on the y-axis, set the variable:

```
BABYLON.OBJFileLoader.INVERT_Y = true;
```

To invert your imported textures on the y-axis, set the variable:

```
BABYLON.OBJFileLoader.INVERT_TEXTURE_Y = true;
```

By default if a 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:

```
BABYLON.OBJFileLoader.MATERIAL_LOADING_FAILS_SILENTLY = false;
```

If a MTL is defined in your OBJ and you wish to have it ignored, set the variable:

```
BABYLON.OBJFileLoader.SKIP_MATERIALS = 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 differents 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/



## How To Load Files with Assets Manager

In order to help developers load multiple assets, Babylon.js (starting with version 1.14) introduced the AssetsManager class.

This class can be used to import meshes into a scene or load text and binary files.

**Note:** Since meshes you import can have a _rotationQuaternion_ set applying a _rotation_ to one will have unforeseen consequences as detailed in this [warning](/features/featuresDeepDive/mesh/transforms/center_origin/rotation_conventions).

## Using AssetsManager

### Initializing and creating tasks

To use it, you just have to instantiate it with a current scene:

```javascript
var assetsManager = new BABYLON.AssetsManager(scene);
```

Then you can add tasks to the manager:

```javascript
var meshTask = assetsManager.addMeshTask("skull task", "", "scenes/", "skull.babylon");
```

Each task provides an ```onSuccess``` and an ```onError``` callback:

```javascript
meshTask.onSuccess = function (task) {
    task.loadedMeshes[0].position = BABYLON.Vector3.Zero();
}
```

```javascript
meshTask.onError = function (task, message, exception) {
    console.log(message, exception);
}
```

You can do the same thing but with text and binary files:

```javascript
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:

```javascript
var imageTask = assetsManager.addImageTask("image task", "img.jpg");
imageTask.onSuccess = function(task) {
    console.log(task.image.width);
}
```

Textures can also be loaded, through textureTask:

```javascript
var textureTask = assetsManager.addTextureTask("image task", "img.jpg");
textureTask.onSuccess = function(task) {
    material.diffuseTexture = task.texture;
}
```

### Task state and error handling

Each task has a state object that represents the current execution state of the task. The state is represented by an enum, `BABYLON.AssetTaskState` and has 4 states:
* INIT - before the task started executing
* RUNNING - when the task started executing but hasn't finished yet.
* DONE - when the task successfully finished execution
* ERROR - when the task failed.

If a task has the error state (`BABYLON.AssetTaskState.ERROR`) a new object will be added to the task: `task.errorObject` . The error object have 2 variables defined, both optional:
* message - a string explaining the error shortly (such as "request returned 404")
* exception - in case an exception was thrown during execution, the exception object will contain the stack trace information

This way the error is accessible also when using the assets manager observers:

```javascript
assetsManager.onTaskErrorObservable.add(function(task) {
    console.log('task failed', task.errorObject.message, task.errorObject.exception);
});
```


### Manager callbacks and observables

The manager itself provides four callbacks:
* onFinish
* onProgress
* onTaskSuccess
* onTaskError

```javascript
assetsManager.onProgress = function(remainingCount, totalCount, lastFinishedTask) {
	engine.loadingUIText = 'We are loading the scene. ' + remainingCount + ' out of ' + totalCount + ' items still need to be loaded.';
};

assetsManager.onFinish = function(tasks) {
    engine.runRenderLoop(function() {
        scene.render();
    });
};
```

The manager also allows you to use observers in order to handle onFinish, onProgress, onTaskSuccess and onTaskError:
* onTaskSuccessObservable - registered observers will be executed when a single task finished successfully.
* onTaskErrorObservable - registered observers will be executed when a single task failed.
* onProgressObservable - registered observers will be executed when a single task finished successfully or failed.
* onTasksDoneObservable - registered observers will be execute 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) {
    var errors = tasks.filter(function(task) {return task.taskState === BABYLON.AssetTaskState.ERROR});
    var successes = tasks.filter(function(task) {return task.taskState !== BABYLON.AssetTaskState.ERROR});
});
```

### Executing the tasks

To launch all the tasks, you have to call:

```javascript
assetsManager.load();
```

* You can see a live demo [here](https://www.babylonjs.com/scenes/assets)
* Playground demo: <Playground id="#ZJYNY#0" title="Asset Manager Example" description="Simple Example of using the asset manager in your scene." image="/img/playgroundsAndNMEs/divingDeeperAssetManager1.jpg"/>

## Available tasks

There are 7 types of tasks that can be executed using the assets manager.

Each task is extending the AbstractAssetTask class (and implementing IAssetTask interface) with the following properties:

```javascript
onSuccess: (task: IAssetTask) => void;
onError: (task: IAssetTask, message?: string, exception?: any) => void;

isCompleted: boolean = false;
name: string;
taskState: AssetTaskState;
errorObject: { message?: string; exception?: any; };
```

Note that the properties required to initialize a task are always corresponding to the object type it creates. Foe example, the constructor signature of the CubeTextureAssetTask takes the same variables as the class BABYLON.CubeTexture . The order of the variables might vary.

### MeshAssetTask

The mesh asset task is used to load a model externally (a .babylon, .obj, .gltf and so on).

Constructor signature:

```javascript
constructor(name: string, meshesNames: any, rootUrl: string, sceneFilename: string | File)
```

Extra properties:

```javascript
public loadedMeshes: Array<AbstractMesh>;
public loadedParticleSystems: Array<ParticleSystem>;
public loadedSkeletons: Array<Skeleton>;
```

### TextFileAssetTask

Is used to async-load a (text) file.

Constructor signature:

```javascript
constructor(name: string, url: string)
```

Extra properties:

```javascript
public url: string;
public text: string;
```

### BinaryFileAssetTask

This task is used to load a binary file. The main difference between this and the TextFileAssetTask is that the data will be stored in an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)

Constructor signature:

```javascript
constructor(name: string, url: string)
```

Extra properties:

```javascript
public url: string;
public data: ArrayBuffer;
```

### ImageAssetTask

This function will load an image (.png, .jpg, .gif). It will create an [HTMLImageElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement) object

Constructor signature:

```javascript
constructor(name: string, url: string)
```

Extra properties:

```javascript
public url: string;
public image: HTMLImageElement;
```

### TextureAssetTask

This will create a new BABYLON.Texture from a provided single url.

Constructor signature:

```javascript
constructor(name: string, url: string, noMipmap?: boolean, invertY?: boolean, samplingMode: number = BABYLON.Texture.TRILINEAR_SAMPLINGMODE)
```

Extra properties:

```javascript
public texture: Texture;
```

### CubeTextureAssetTask

The same as the TextureAssetTask but for a cube texture

Constructor signature:

```javascript
constructor(name: string, url: string, extensions?: string[], noMipmap?: boolean, files?: string[])
```

Extra properties:

```javascript
public texture: CubeTexture;
```

### HDRCubeTextureAssetTask

Same as the CubeTextureAssetTask, but for HDR cube textures

```javascript
constructor(name: string, url: string, size?: number, noMipmap = false, generateHarmonics = true, useInGammaSpace = false, usePMREMGenerator = false)
```

Extra properties:

```javascript
public texture: HDRCubeTexture;
```

### EquiRectangularCubeTextureAssetTask

Same as the CubeTextureAssetTask, but for Equirectangular cube textures

```javascript
constructor(name: string, url: string, size: number, noMipmap = false, useInGammaSpace = true)
```

Extra properties:

```javascript
public texture: EquiRectangularCubeTexture;
```

## Using a loading screen

By default, the AssetsManager will display a loading screen while loading assets:

<img src="/img/features/scene/loader.jpg" title="Babylon.js Loading Spinner"/>

If you want to disable the loading screen, you have to set ```useDefaultLoadingScreen``` to false:

```javascript
assetsManager.useDefaultLoadingScreen = false;
```

The loading screen will also be displayed while loading a scene using SceneLoader if ```ShowLoadingScreen``` is set to true (by default).

```javascript
BABYLON.SceneLoader.ShowLoadingScreen = false;
```

In the same way, you can also display or hide the loading screen manually using these functions:

```javascript
engine.displayLoadingUI();
engine.hideLoadingUI();
```

Loading text is controlled using ```loadingUIText``` :

```javascript
engine.loadingUIText = "text";
```

Background color is controlled using ```loadingUIBackgroundColor``` :

```javascript
engine.loadingUIBackgroundColor = "red";
```



# STL File Import

You can find the STL loader [here](https://cdn.babylonjs.com/loaders/babylon.stlFileLoader.js)

To use it you just have to reference it after Babylon.js:

```html
<script src="Babylon.js"></script>
<script src="babylon.stlFileLoader.js"></script>
```

Then you can use one of the static functions on the `SceneLoader` to load.
See [how to load from any file type](/features/featuresDeepDive/importers/loadingFileTypes)

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;
```


.obj File Loader Plugin

OBJ File Import

Load

Good things to know

Supported

Not supported currently