
## Introduction
Skinning in glTF 2.0 is a bit different than how skinning typically works in Babylon.js. This document will describe a couple of important implementation details in the glTF 2.0 loader regarding skinning. All mentions of glTF below is scoped to glTF 2.0.

## Bones with Linked Nodes

The skeleton joints in glTF (a.k.a. bones in Babylon.js) point to nodes that are part of the scene hierarchy. Because these joint nodes are also normal scene nodes, they can also have child nodes that have meshes or additional hierarchies. Furthermore, nodes in the scene hierarchy can be referenced by multiple skeletons. This is different than how Babylon.js skinning works. Babylon.js separates the skeleton of the skinned mesh into a separate object. The separate skeleton holds bones which are not tied to the scene hierarchy by default. To acommodate this difference, the glTF loader in Babylon.js creates bones that are linked to the corresponding nodes in the scene via [`bone.linkTransformNode`](/typedoc/classes/babylon.bone#linktransformnode).

For example, for the [SimpleSkin model](https://playground.babylonjs.com/#SRVW8J), the first bone `joint1` is linked to the node `node1` in the scene.

![LinkedTransformNode](/img/importers/glTF/glTF_Skinning_LinkedTransformNode.jpg "Bone linked with transform node")

The transform of `joint1` will change if the transform of `node1` changes. Similarly, `joint2` is linked with `node2` and the transform of `joint2` will change if the transform of `node2` changes. If there are more bones, they will all be linked to the corresponding node in the scene.

Because of this, modifications to the transforms of bones with linked nodes will be lost since they are updated from the transform of the corresponding node every frame. Changing bone transforms with linked nodes must be performed on the linked node.

## Ignoring the Transform of the Skinned Mesh

In the [skinning section of the glTF 2.0 specification](https://www.khronos.org/registry/glTF/specs/2.0/glTF-2.0.html#skins), it states:

> Only the joint transforms are applied to the skinned mesh; the transform of the skinned mesh node MUST be ignored.

This statement is here to prevent the transforms from being applied twice to the skinned mesh, once via the path to the skinned mesh, and another via the path to the skeleton joints (a.k.a. bones in Babylon.js).

For example, for the [CesiumMan model](https://playground.babylonjs.com/#T1IFZA), there are two parent nodes above the skinned mesh node that have non-identity transforms.

![ParentTransforms1](/img/importers/glTF/glTF_Skinning_ParentTransforms1.jpg "Skinned mesh with non-identity parent transforms 1")
![ParentTransforms2](/img/importers/glTF/glTF_Skinning_ParentTransforms2.jpg "Skinned mesh with non-identity parent transforms 2")

These nodes are parents of both the skinned mesh `Cesium_Man` and the skeleton root node `Skeleton_torso_joint1`. Having the parent transforms be applied to both will result in the parent transforms being applied twice. _For more details and discussions on this issue, see [this comment](https://github.com/KhronosGroup/glTF/pull/1195#issuecomment-364597428) from the glTF GitHub repo._

One of these parent transform branches must be ignored. The glTF specification ignores the skinned mesh branch since this matches the behavior of Unity3D. Unfortunately, this does not match what Babylon.js does. Babylon.js has a separated skeleton object and the parent transforms apply to the skinned mesh.

To satisfy this requirement from glTF, the glTF loader loads the skinned mesh without its own transform and parents the skinned mesh as a sibling of the skeleton root node. For the CesiumMan model, this is at the same location, but for other cases, it might not be in the same location in the scene hierarchy. Furthermore, the skinned mesh is allowed to have child nodes that have meshes or additional hierarchies. Thus, in additional to creating a skinned mesh, the glTF loader also creates a node that represents the glTF node with the skinned mesh, in case this node is animated or has additional child nodes.

_NOTE: Before Babylon.js 5.0, the glTF loader uses a property `overrideMesh` that on the skeleton to override the mesh used by the skeleton in order to ignore the parent transform up to the glTF root node which contained the right-hand to left-hand conversion. This method, however, caused all sort of issues that are outside the scope of this document to explain. This property has since been removed from the skeleton class._



## Introduction

Downloading large assets is often slow even with a decent internet connection. Progressively loading discrete levels of detail (LODs) is one technique to combat this. The idea is to store multiple LODs in the asset and progressively load them from low to high quality. This method improves the time to first render since the lowest quality LOD is often dramatically smaller than the highest quality LOD.

<Playground id="#ARN6TJ#5" title="Progressive Loading With LODs" description="Simple Example of progressively loading assets with levels of detail." image="/img/playgroundsAndNMEs/divingDeeperProgressivelyLoading1.jpg"/>

This demo playground loads a glTF binary (a.k.a. GLB) asset which is a single file store on the server. It uses HTTP range requests to partially download parts of the GLB. The glTF loader minimizes the amount of HTTP requests sent to the server for optimal efficiency. It also shows progress of each stage of the download. Console logging is enabled to show what the glTF loader is doing.

## About MSFT_lod

[MSFT_lod](https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/MSFT_lod) is a Microsoft glTF extension for discrete LODs. It has support for both node and material LODs. Babylon.js supports progressively loading these LODs, for the purpose of reducing the time to first render, as well as selecting LODs based on screen coverage.  
You can use the property `MSFT_screencoverage` in the gltf file to indicate to Babylon.js which LOD level to select. Screen coverage is calculated as a ratio between the screen surface the mesh occupies, and the total screen surface.

[This playground](https://playground.babylonjs.com/#2YZFA0#228) demonstrates loading a simple gltf file that contains 3 LOD levels. You can retrieve the file [here](https://playground.babylonjs.com/scenes/msft-lod.gltf) if you want to inspect it.

There are not many tools that can create assets with MSFT_lod at the moment. The car asset in the first demo above is exported from [Adobe Dimension](https://www.adobe.com/products/dimension.html) for sharing on the web. [BabylonPolymorph](https://github.com/BabylonJS/BabylonPolymorph) will eventually be able to do this, but this project is still very early. There is also [glTF-Toolkit](https://github.com/Microsoft/glTF-Toolkit) for Windows Mixed Reality which unfortunately is not well suited for Babylon.js, but perhaps it can be modified to work better.

## Using HTTP Range Requests

A glTF asset can be either loose files or packed together into a glTF binary (GLB). Serving files as GLB on a server is typically not a good idea except when using [HTTP range requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests). Using range requests will enable the loader to partially download a range of the asset instead of all at once. The glTF loader in Babylon.js supports range requests. It can be enabled like this:

```javascript
BABYLON.SceneLoader.OnPluginActivatedObservable.addOnce(function (loader) {
    if (loader.name === "gltf") {
        loader.useRangeRequests = true;
    }
});
```

## Caveats
- The HTTP server hosting the asset must support range requests.
- The LODs in the GLB should be authored with a contiguous range per LOD for maximum efficiency.

## Showing Progress

When loading large assets either using loose files or with range requests, it is useful to show the download progress. Progress is supported through the progress callback of `BABYLON.SceneLoader` methods which is a small subset of the HTTP request [progress event](https://developer.mozilla.org/en-US/docs/Web/API/ProgressEvent). Here is an example from the demo above:

```javascript
BABYLON.SceneLoader.AppendAsync(url, undefined, scene, function (event) {
    // Compute the percentage for each stage unless the length is not computable.
    // The lengthComputable is often false when serving content that is gzipped.
    const percentage = event.lengthComputable ? " " + Math.floor(event.loaded / event.total * 100) + "%" : "";

    // Check if an LOD is loading yet.
    if (lodNext === null) {
        // Ignore GLB header progress.
        if (event.total === 20) return;

        // Show that the glTF is downloading.
        bottomLine.text = "Loading glTF..." + percentage;
    }
    else {
        // Show that the LOD is downloading.
        bottomLine.text = "Loading '" + lodNames[lodNext] + "' LOD..." + percentage;
    }
}, ".glb")
```

## Key Notes
- Gzipped content hosted on server often results in `lengthComputable` equaling `false` which in turn causes the `total` to be zero. When this happens, the only choices are to not show the progress or show the number of bytes downloaded instead.
- When using HTTP range requests with a GLB, the first thing that is downloaded is the GLB header which downloads very quickly and is almost always 20 bytes loaded and 20 bytes total when the progress event fires. Ignore it by checking when `total` is exactly 20.

## Debugging LODs

It is useful to stop at a specific LOD to inspect the results. This can be achieved by setting the `maxLODsToLoad` property on the MSFT_lod loader extension:

```javascript
BABYLON.SceneLoader.OnPluginActivatedObservable.addOnce(function (loader) {
    if (loader.name === "gltf") {
        loader.onExtensionLoadedObservable.add(function (extension) {
            if (extension.name === "MSFT_lod") {
                // Stop at the first LOD.
                extension.maxLODsToLoad = 1;
            }
        }
    }
}
```

## Enabling Logging

Enabling logging is often useful to understand and debug the loading of a glTF asset. This is especially true for MSFT_lod assets. Logging can be enabled like this:

```javascript
BABYLON.SceneLoader.OnPluginActivatedObservable.addOnce(function (loader) {
    if (loader.name === "gltf") {
        loader.loggingEnabled = true;
    }
});
```

Here is an example console log from the demo above:
```
BJS - [16:31:29]: Binary version: 2
BJS - [16:31:29]: JSON length: 59200
BJS - [16:31:29]: Loading 0
BJS - [16:31:29]: Asset version: 2.0
BJS - [16:31:29]: Asset generator: Adobe Dimension - 9ce31d2be91132df879a9b9136f9df4ef7b7fa2c
BJS - [16:31:29]: LOADING
BJS - [16:31:29]: /scenes/0 scene
BJS - [16:31:29]:   /nodes/0 render_camera_n3d
BJS - [16:31:29]:     /cameras/0 render_camera
BJS - [16:31:29]:   /nodes/1 ground_plane_n3d
BJS - [16:31:29]:   /nodes/2 sportsCar_4K
BJS - [16:31:29]:     /nodes/3 car_lores.obj
BJS - [16:31:29]:       /nodes/4 g car_lores_gt_lores_lowdetails group1
BJS - [16:31:29]:         /nodes/5 car_lores_gt_lores_lowdetails group1
BJS - [16:31:29]:           /meshes/0 car_lores_gt_lores_lowdetails group1
BJS - [16:31:29]:             /meshes/0/primitives/0
BJS - [16:31:29]:               deferred
BJS - [16:31:30]:               /materials/12/extensions/MSFT_lod
BJS - [16:31:30]:                 /materials/0 details_lod2
BJS - [16:31:30]:                   /materials/0/normalTexture
BJS - [16:31:30]:                     /textures/2 tmp_image_pie_10f1_2c55_943e
BJS - [16:31:30]:                       /images/2 normal
BJS - [16:31:30]:                         deferred
BJS - [16:31:30]:                   /materials/0/occlusionTexture
BJS - [16:31:30]:                     /textures/1 ambient_roughness_metallic
BJS - [16:31:30]:                       /images/1 ambient_roughness_metallic
BJS - [16:31:30]:                         deferred
...
BJS - [16:31:32]: Loading buffer range [0-4864522]
BJS - [16:31:37]: READY
BJS - [16:31:37]: Loading buffer range [4864523-8856965]
BJS - [16:31:39]: Loaded material LOD 1
BJS - [16:31:39]: Loading buffer range [8856966-67953580]
BJS - [16:32:00]: Loaded material LOD 2
BJS - [16:32:00]: COMPLETE
```

Note the `deferred` message when loading primitives and images. The loader is deferring the download until it has determined what ranges of the GLB is necessary for the LODs. Once the ranges are determined, the loader loads the range for the first LOD before the state changes to `READY` which indicates the asset is ready for viewing. Then it loads the remaining LODs in sequence until all the LODs are loaded before the state changes to `COMPELTE` which indicates the asset is completely loaded.


## Setup

You can find the loader here [here](https://cdn.babylonjs.com/loaders/babylon.glTFFileLoader.js)

## Full Version

This loader supports both glTF 1.0 and 2.0 and will use the correct loader based on the glTF version string.

```html
<script src="babylon.js"></script>
<script src="babylon.glTFFileLoader.js"></script>
```

## Loading files locally

By default, the gltf loader will request additional files for [draco compression](https://google.github.io/draco/) from *preview.babylonjs.com*. In case you want to deliver these files locally (e.g. for GDPR compliance), you can set the [DracoCompression.Configuration](https://doc.babylonjs.com/typedoc/classes/BABYLON.DracoCompression) object to use local files:

```typescript
DracoCompression.Configuration = {
  decoder: {
    wasmUrl: "/babylon-draco-files/draco_wasm_wrapper_gltf.js",
    wasmBinaryUrl: "/babylon-draco-files/draco_decoder_gltf.wasm",
    fallbackUrl: "/babylon-draco-files/draco_decoder_gltf.js",
  },
};
```

Be sure to download the files first (from `https://preview.babylonjs.com/[FILENAME]`) and put them in a local path (`public/babylon-draco-files`, in this case).

## Warning

A \_root\_ node is added to hold all the **glTF** and **glb** models and model parts are stored as sub-meshes. This is so applications that save models using a right handed system will be loaded correctly into Babylon.js when you add to your create scene function

```javascript
scene.useRightHandedSystem = true;
```

This also means that _loadedMeshes[0]_ will point to the added \_root\_ node and _loadedMeshes[1]_ will point to your first loaded mesh.

## Version 2 Only

This loader supports only glTF 2.0 and will fail to load glTF 1.0.

```html
<script src="babylon.js"></script>
<script src="babylon.glTF2FileLoader.js"></script>
```

See [Skinning](/features/featuresDeepDive/importers/glTF/glTFSkinning) for details on how skinning is implementated in Babylon.js for glTF 2.0.

## Version 1 Only

This loader supports only glTF 1.0 and will fail to load glTF 2.0.

```html
<script src="babylon.js"></script>
<script src="babylon.glTF1FileLoader.js"></script>
```

## Loading the Scene

Use one of the static function on the `SceneLoader` to load a glTF asset.
See [Load from any file type](/features/featuresDeepDive/importers/loadingFileTypes).

See an example here: <Playground id="#WGZLGJ" title="Load a glTF Asset" description="Simple example showing how load a .glTF asset into your scene." image="/img/playgroundsAndNMEs/divingDeeperglTF1.jpg" isMain={true} category="Import"/>

## API (Version 2)

## Properties and Methods

See the available [properties and methods](/typedoc/classes/babylon.gltffileloader) from the API documentation.

## Extensions

See the available [extensions](/typedoc/modules/babylon.gltf2.loader.extensions) from the API documentation.

## API (Version 1)

## 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 loads 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;
```

## Extensions

[KHR_binary_glTF](https://github.com/KhronosGroup/glTF/tree/master/extensions/1.0/Khronos/KHR_binary_glTF)  
[KHR_materials_common](https://github.com/KhronosGroup/glTF/tree/master/extensions/1.0/Khronos/KHR_materials_common)



## How To Use the Incremental Loading System

In order to support incremental loading (introduced by v1.5.0), you just have to go to [this page](https://github.com/BabylonJS/Exporters/tree/master/Tools/MakeIncremental) in order to get a tool to convert your .babylon file to a .incremental.babylon file alongside 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#84" title="Incremental Loading Example" description="Simple Example of incremental loading assets." image="/img/playgroundsAndNMEs/divingDeeperIncrementalLoading1.jpg"/>

## Detailed Step by step
For users less experienced with command line tools, here's a more detailed step by step of what you need to use the tool:

1. Get the Exporters project (by either using git or downloading the ZIP):
![Exporters project](/img/importers/incremental_loading/incr_step_1.png "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.png "Navigating to the MakeIncremental directory")

4. Type `dotnet build` on the command prompt:
![.NET build](/img/importers/incremental_loading/incr_step_4.png "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.png "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.png "Running the MakeIncremental command")

7. The script is going to generate quite a few files, you will need all of them, except your original `my-scene.babylon`. Copy them to a directory your project has access to (on this example, it's `/src`):
![Generated files](/img/importers/incremental_loading/incr_step_7.png "Files generated by the MakeIncremental command")

8. And you're ready to load it into Babylon!
```javascript
BABYLON.SceneLoader.Append("src/", "my-scene.incremental.babylon", scene, function() {
    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 ran 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).


.glTF File Loader Plugin

Setup

Full Version

Loading files locally

Warning

Version 2 Only

Version 1 Only

Loading the Scene

API (Version 2)

Properties and Methods

Extensions

API (Version 1)

Properties

IncrementalLoading

HomogeneousCoordinates

Extensions

Coming next

glTF 2.0 Skinning

Learn about the implementation details for how skinning is implemented in Babylon.js

Progressively Load .glTF Files

Learn about progressively loading .glTF files in Babylon.js.