
## Forcing the type of loader on a model

Babylon's mesh importer uses the file extension of the model you provided to determine which loader to use. Sometimes, it is not possible to provide a file extension, especially if your server does not allow it. If that is the case, you can force a specific loader for a model.

To do that, use the `model.loader` configuration variable:

```html
<babylon extends="minimal" model.url="https://example.com/Rabbit" model.loader=".gltf"></babylon>
```

This will load [https://example.com/Rabbit](https://example.com/Rabbit) using the glTF loader.

## Retrieving the viewer instance

The viewer has a viewer manager that registers each viewer currently on the page. The viewer manager is event-based and triggers a callback every time a new viewer is added. To register the callback, you can use the following:

```javascript
// using basic callback
BabylonViewer.viewerManager.onViewerAdded = function (viewer) {
  console.log(viewer);
};

// user observers

BabylonViewer.viewerManager.onViewerAddedObservable.add(function (viewer) {
  console.log(viewer);
});
```

Another way to get the viewer is to use the promise-based API:

```javascript
// you will need to set an id attribute to the viewer element and use it here:
BabylonViewer.viewerManager.getViewerPromiseById("viewer-id").then(function (viewer) {
  console.log(viewer.getBaseId());
});
```

The Promise-based API will either wait until the viewer is created or return the viewer itself if it is already initialized. It is therefore the safest way to get the viewer instance.

If you know the viewer was already initialized, there are two simple ways of getting it:

```javascript
// using the id
let viewer = BabylonViewer.viewerManager.getViewerById("viewer-id");
// using the viewer HTML element
let element = document.querySelector("babylon");
let viewer2 = BabylonViewer.viewerManager.getViewerByHTMLElement(element);
```

## Initializing a different HTML tag other than `<babylon>`

Babylon Viewer automatically initializes `babylon` HTML tags and renders a viewer on top of them. If you want to use a different HTML tag, you can. To do that, you need to disable the default initialization and then initialize your own tags. Add the following script at the bottom of your page, after including the viewer JS file:

```javascript
// a simple way of disabling auto init
BabylonViewer.disableInit = true;
// Initializing the viewer on specific HTML tags.
BabylonViewer.InitTags("the-other-tag-name");
```

## Finding the Babylon Engine, Scene, and Camera

The viewer instance exposes the Engine, Scene, and Camera objects it uses.
To access them, get the viewer in any of the ways discussed above, then access the public member you need:

```javascript
let viewer = getMeMyViewer();
viewer.sceneManager.scene instanceOf BABYLON.Scene; // true
viewer.engine instanceOf BABYLON.Engine; // true
viewer.sceneManager.camera instanceOf BABYLON.ArcRotateCamera; // true
```

## Event-based development

Besides the scene, engine, and camera, the viewer exposes observables that are triggered when certain events occur. At the moment, 3 observables are available:

```javascript
public onSceneInitObservable: PromiseObservable<Scene>; // Executed when a scene object was initialized
public onEngineInitObservable: PromiseObservable<Engine>; // Executed after the engine was created
public onModelLoadedObservable: PromiseObservable<AbstractMesh[]>; // Executed after a model was loaded.
```

You will notice that these are Promise-based observables. The difference is that you can return a promise instead of a value, and the viewer will wait for it to resolve.

Let's take a look at a not-very-helpful example: we will delay the entire execution after a scene is created by using `setTimeout()` and a Promise object:

```javascript
// taken from here - https://blog.raananweber.com/2015/12/01/writing-a-promise-delayer/
function DelayPromise(delay) {
  //return a function that accepts a single variable
  return function (data) {
    //this function returns a promise.
    return new Promise(function (resolve, reject) {
      setTimeout(function () {
        //a promise that is resolved after "delay" milliseconds with the data provided
        console.log("done!");
        resolve(data);
      }, delay);
    });
  };
}

// force a 500 ms delay after the scene was created.
viewer.onSceneInitObservable.add(DelayPromise(500));
```

This will print 'done' and then continue loading the model.

If we simply used `setTimeout()` and returned, it would execute asynchronously, and "done" would be logged 500 ms after the model started loading.

The registered function does not have to return a promise. If you register a simple function, it will still work and execute correctly:

```javascript
viewer.onSceneInitObservable.add(function (scene) {
  scene.clearColor = BABYLON.Color4.Blue();
  // returning the scene object. a common practice, not a must
  return scene;
});
```

## Enabling the Inspector

To enable the Inspector, add scene.debug="true" to your HTML tag:

```html
<babylon extends="minimal" scene.debug="true" model="https://playground.babylonjs.com/scenes/Rabbit.babylon"></babylon>
```

## Loading a model async

In certain cases, you may want to load your model using JavaScript after the viewer is initialized. This is useful if, for example, a user clicks a button to load a model or drags and drops a model to be viewed. In this case, your HTML should contain only the configuration for the scene (engine, scene, camera, and lights), without defining anything related to the model itself:

```html
<babylon id="babylon-viewer" camera.behaviors.auto-rotate="0"></babylon>
```

To do so, the viewer exposes the "loadModel" function. Loading a model requires you to wait for the engine to initialize. To make this work correctly, you need to wait for the onEngineInit observable to notify you:

```javascript
BabylonViewer.viewerManager.getViewerPromiseById("babylon-viewer").then(function (viewer) {
  // this will resolve only after the viewer with this specific ID is initialized

  viewer.onEngineInitObservable.add(function (scene) {
    viewer.loadModel({
      title: "Helmet",
      subtitle: "BabylonJS",
      thumbnail: "https://www.babylonjs.com/img/favicon/apple-icon-144x144.png",
      url: "https://www.babylonjs.com/assets/DamagedHelmet/glTF/DamagedHelmet.gltf",
    });

    // load another model after 20 seconds. Just to show it is possible
    setTimeout(() => {
      viewer.loadModel({
        title: "Rabbit",
        subtitle: "BabylonJS",
        thumbnail: "https://www.babylonjs.com/img/favicon/apple-icon-144x144.png",
        url: "https://playground.babylonjs.com/scenes/Rabbit.babylon",
      });
    }, 20000);
  });
});
```

The `loadModel` function returns a `Promise<ViewerModel>` that resolves when the model is fully loaded. This is helpful when you want to tell the user that the model loaded successfully:

```javascript
viewer
  .loadModel({
    title: "Helmet",
    subtitle: "BabylonJS",
    thumbnail: "https://www.babylonjs.com/img/favicon/apple-icon-144x144.png",
    url: "https://www.babylonjs.com/assets/DamagedHelmet/glTF/DamagedHelmet.gltf",
  })
  .then((model) => {
    console.log("model loaded!");
  })
  .catch((error) => {
    console.log("error loading the model!", error);
  });
```



## Configuring the viewer

(Almost) every aspect of the viewer can be configured. The configuration is expressed using a TypeScript interface that is a JSON-like object describing the data that can be provided.

## The default configuration

The viewer currently defines two types of configurations:

1. The default configuration (`default`), including HTML templates for a navigation bar, layouts for help and error pages, a skybox, ground, shadows, and more. It is defined at [https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/types/default.ts](https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/types/default.ts)
2. The minimal configuration (`minimal`), with only the basics needed to show a model. It is defined at [https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/types/minimal.ts](https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/types/minimal.ts)

The default configuration will be loaded by default unless another configuration type is forced on the viewer by the developer. To force a different type of configuration, add the DOM attribute `extends` to the HTML element. For example:

```html
<babylon extends="minimal" model="https://playground.babylonjs.com/scenes/Rabbit.babylon"></babylon>
```

To understand the default configuration in more detail and learn how to recreate it using HTML, see [Recreating the default configuration for the viewer](/legacy/babylonViewer/defaultViewerConfig)

## Extending and changing the default configurations

The default configuration types can be overwritten using the methods described below. As the configuration object never contains arrays, any attribute in it can be referenced using a string and can therefore be overwritten.

The order in which the configuration is loaded is:

1. The DOM configuration
1. (optional) The extra configuration file provided using the `configuration` keyword.
1. The `extends` configuration (for example `default` or `minimal`). This is merged with the DOM configuration, giving the DOM configuration priority.

To explain this further, let's look at a simple example:

```html
<babylon extends="minimal" scene.debug="true" engine.antialiasing="false" model="https://playground.babylonjs.com/scenes/Rabbit.babylon" configuration="http://example.com/viewerConfig.json"></babylon>
```

First, the configuration of the DOM element will be read (represented as JSON for better understanding):

```javascript
{
    extends: "minimal",
    scene: {
        debug: true
    },
    engine: {
        antialiasing: false
    },
    model: "https://playground.babylonjs.com/scenes/Rabbit.babylon",
    configuration="http://example.com/viewerConfig.json"
}
```

Next, the `minimal` configuration will be loaded and appended to the existing configuration:

```javascript
{
    extends: "minimal",
    scene: {
        debug: true
    },
    engine: {
        antialiasing: false
    },
    model: "https://playground.babylonjs.com/scenes/Rabbit.babylon",
    configuration="http://example.com/viewerConfig.json",
    version: "0.1",
    templates: {
        main: {
            html: "<div>.........</div>"
        },
        loadingScreen: {
            html: "<div>.........</div>",
            params: {
                backgroundColor: "#000000",
                loadingImage: "data:image/png;base64....."
            }
        },
        viewer: {
            html: "<div>.........</div>",
        },
        overlay: {
            html: "<div>.........</div>",
            params: {
                closeImage: "data:image/png;base64.....",
                closeText: 'Close'
            }
        },
        error: {
            html: "<div>.........</div>"
        }

    },
}
```

Notice that although the minimal configuration defines antialiasing as `true`, the configuration provided by the user will be used. It only extends and does not overwrite.

Next, the configuration object will be inspected. If it contains a configuration URL, it will be loaded. In our case, the (non-existing) [http://example.com/viewerConfig.json](http://example.com/viewerConfig.json) will be downloaded and appended to the configuration already provided. Notice that this configuration object will overwrite definitions in the current configuration object. So if the JSON file looks like this:

```json
{
  "scene": {
    "debug": false
  }
}
```

The `scene.debug` in the configuration object that will be provided to the viewer will have debug set to false.

### Configuring using the DOM element

The viewer will read each attribute on the `<babylon>` DOM element(s) provided and will create a JSON element out of them.
So, if the DOM element looks like this:

```html
<babylon scene.debug="true" camera.behaviors.auto-rotate="0" model.url="https://playground.babylonjs.com/scenes/Rabbit.babylon" configuration="http://example.com/viewerConfig.json"></babylon>
```

The configuration will look like this:

```javascript
{
    scene: {
        debug: true
    },
    camera: {
        behaviors: {
            autoRotate: 0
        }
    },
    model: {
        url: "https://playground.babylonjs.com/scenes/Rabbit.babylon"
    }
}
```

A few things to notice:

#### camel-case vs. kebab case

DOM attributes are usually written in kebab-case ('looks-like-this'), mainly because some browsers convert attributes to lowercase. Those attributes will be automatically converted to camelCase ('looksLikeThis').

#### Value conversions

Attribute-values are converted to their corresponding types in JSON. If the value can be converted to a number ("1" for example), it will be converted to a number. If the value is "true" or "false", it will be converted to a boolean.

#### Nested attributes

Nested attributes can be separated using ".". So `scene.debug="true"` will nest `debug` into `scene` and set its value to true.

#### Unidirectional definition

The DOM is read once and is not continuously processed. Changing the value of an attribute after the viewer is initialized will not affect the viewer.

### Configuring using nested DOM elements

Another way of using the DOM to configure the viewer is to use nested DOM elements inside the main element. A basic example:

```html
<babylon extends="minimal">
  <model url="https://ugcorigin.s-microsoft.com/12/2e77b8e3-0000-0000-7a48-6505db2f0ef9/952/1508427934473.gltf"> </model>
  <camera>
    <behaviors>
      <auto-rotate type="0"></auto-rotate>
    </behaviors>
  </camera>
  <lights>
    <light1 type="1" shadow-enabled="true"> </light1>
  </lights>
</babylon>
```

This is more human-readable and is easier for web developers to understand. This example is technically the same as:

```html
<babylon extends="minimal" model.url="https://ugcorigin.s-microsoft.com/12/2e77b8e3-0000-0000-7a48-6505db2f0ef9/952/1508427934473.gltf" camera.behaviors.auto-rotate.type="0" lights.light1.type="2" lights.light1.shadow-enabled="true"></babylon>
```

A few things to consider:

#### Extending and using the DOM element configuration

Everything written regarding the DOM element configuration is extended here. The values are converted, kebab-case should be used, and nested attributes will still be correctly read. For example, this is also a valid configuration (notice the `<camera>` HTML tag):

```html
<babylon extends="minimal">
  <model url="https://ugcorigin.s-microsoft.com/12/2e77b8e3-0000-0000-7a48-6505db2f0ef9/952/1508427934473.gltf"> </model>
  <camera behaviors.auto-rotate.type="0"> </camera>
  <lights>
    <light1 type="1" shadow-enabled="true"> </light1>
  </lights>
</babylon>
```

And it is the same as the example above.

### Configuring using external JSON

As previously explained, the viewer configuration has a `configuration` member that can contain an external JSON file, which will be loaded and merged with the selected configuration.

If the following is defined:

```html
<babylon scene.debug="true" camera.behaviors.auto-rotate="0" model.url="https://playground.babylonjs.com/scenes/Rabbit.babylon" configuration="http://example.com/viewerConfig.json"></babylon>
```

The file `http://example.com/viewerConfig.json` will be loaded into the configuration object. This is a great way to create a general/global configuration for a website while providing the detailed model data using HTML.

### Configuring using JavaScript

As discussed further in [Advanced usage](//doc.babylonjs.com/extensions/Advanced_usage), JavaScript can be used to initialize a viewer. When you initialize a viewer using JavaScript, you can provide the initial configuration that will be used with that viewer:

```javascript
let domElement = document.getElementById("my-amazing-element");

let viewer = new BabylonViewer.DefaultViewer(domElement, {
  scene: {
    debug: true,
  },
  camera: {
    behaviors: {
      autoRotate: 0,
    },
  },
  model: {
    url: "https://playground.babylonjs.com/scenes/Rabbit.babylon",
  },
});
```

In this case, the HTML attributes will be ignored(!) and the DOM element will simply serve as the container of the Babylon scene.

### Registering your own configuration parser using the mapper manager

As shown, the Babylon viewer has three types of configuration parsers for you to choose from: "html", "dom", and "json". Those mappers are registered in the mapper manager, which is exposed in the BabylonViewer namespace.

The mapper manager can be extended. If you have your own type of configuration or want to support additional file types, you can create your own mapper and register it. Later, you can define which mapper type the configuration will be read with by using the `configuration.type` variable in the viewer's configuration.

Let's build a pseudo YAML loader and register it:

First, we implement the IMapper interface:

```javascript
// In TypeScript
class YAMLMapper implements IMapper {
  map(yaml: YAMLThing): ViewerConfiguration {
    return this.convertToYaml(yaml);
  }

  // so, this needs to be actually implemented...
  convertYamlToJson(yaml) {}
}

// in JavaScript

let yamlMapper = {
  map: function (yaml) {
    return yaml.toJson();
  },
};
```

Afterwards, we need to register it with the mapperManager:

```javascript
BabylonViewer.mapperManager.registerMapper("yaml", yamlMapper);
```

And finally, we need to tell the manager which mapper to use:

```html
<babylon extends="minimal" scene.debug="true" engine.antialiasing="false" model="https://playground.babylonjs.com/scenes/Rabbit.babylon" configuration.url="http://example.com/viewerConfig.yaml" configuration.mapper="yaml"></babylon>
```

### Using your own payload without downloading a file

The configuration attribute of your HTML element can contain a URL, as shown earlier, or a payload of any type if you already have the configuration loaded on the page in your own format.

This is useful if you want to handle the download yourself or if the data is already available. As a best practice, you will need to:

1. Create your own mapper
1. Register the mapper
1. Set the payload and mapper

For example, let's say we have a predefined JSON configuration loaded in the page already. We could load it this way (notice configuration.payload):

```html
<babylon
  configuration.payload='{"scene": {"debug": true}}'
  model.title="Damaged Helmet"
  model.subtitle="BabylonJS"
  model.thumbnail="https://www.babylonjs.com/img/favicon/apple-icon-144x144.png"
  model.url="https://www.babylonjs.com/assets/DamagedHelmet/glTF/DamagedHelmet.gltf"
  camera.behaviors.auto-rotate="0"
  templates.nav-bar.params.disable-on-fullscreen="true"
></babylon>
```

This will work as the default mapper converts a JSON string to a configuration object. If you input a different style of configuration, you could set the mapper's type (after registering it):

```html
<babylon
  configuration.payload="scene.debug=true&engine.antialiasing=true"
  configuration.mapper="form"
  model.title="Damaged Helmet"
  model.subtitle="BabylonJS"
  model.thumbnail="https://www.babylonjs.com/img/favicon/apple-icon-144x144.png"
  model.url="https://www.babylonjs.com/assets/DamagedHelmet/glTF/DamagedHelmet.gltf"
  camera.behaviors.auto-rotate="0"
  templates.nav-bar.params.disable-on-fullscreen="true"
></babylon>
```

This will use the pre-registered "form" mapper (which does not exist in reality; you should implement it) to read the payload and adjust the configuration.

## The full configuration interface

Please check the configuration on GitHub, as it is constantly updated:
[https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/configuration.ts](https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/configuration/configuration.ts)


This tutorial is meant to show only advanced usage of the viewer's configuration. It explains what can be done and how you can modify the viewer to suit your needs using only HTML.

The default configuration is already implemented and can be used very easily, by adding `extends="default"` to your HTML element. In code, it is a JSON that looks roughly like this (without the HTML and image content):

```javascript
{
    templates: {
        main: {
            html: defaultTemplate,
            params: {
                babylonFont: babylonFont,
                noEscape: true
            }
        },
        fillContainer: {
            html: fillContainer,
            params: {
                disable: false
            }
        },
        loadingScreen: {
            html: loadingScreen,
            params: {
                backgroundColor: "#000000",
                loadingImage: images.loading
            }
        },
        viewer: {
            html: defaultViewer,
            params: {
                enableDragAndDrop: false
            }
        },
        navBar: {
            html: navbar,
            params: {
                speedList: {
                    "0.5x": "0.5",
                    "1.0x": "1.0",
                    "1.5x": "1.5",
                    "2.0x": "2.0",
                },
                logoImage: images.babylonLogo,
                logoText: 'BabylonJS',
                logoLink: 'https://babylonjs.com',
                hideHelp: true,
                hideHd: true,
                hideVr: true,
                disableOnFullscreen: false,
                text: {
                    hdButton: "Toggle HD",
                    fullscreenButton: "Fullscreen",
                    helpButton: "Help",
                    vrButton: "Toggle VR"
                }
            },
            events: {
                pointerdown: {
                    '.navbar-control': true,
                    '.help-button': true
                },
                input: {
                    '.progress-wrapper': true
                },
                pointerup: {
                    '.progress-wrapper': true
                }
            }
        }
    },
    camera: {
        behaviors: {
            autoRotate: {
                type: 0
            },
            framing: {
                type: 2,
                zoomOnBoundingInfo: true,
                zoomStopsAnimation: false
            },
            bouncing: {
                type: 1
            }
        }
    },
    skybox: {
    },
    ground: {
        receiveShadows: true
    },
    engine: {
        antialiasing: true
    }
}
```

## HTML element and viewer script

As a first step, we need to create a basic HTML page and include the viewer script. Since I am creating my own configuration, I will use `extends="none"` so that no configuration is included at construction time.

```html
<html>
  <head>
    <title>Recreating the default configuration for Babylon.js viewer</title>
    <style>
      /* Force the viewer to have a specific size. This can be changed, of course. */
      babylon {
        width: 800px;
        height: 500px;
      }
    </style>
  </head>
  <body>
    <babylon extends="none"> </babylon>

    <script src="https://preview.babylonjs.com/viewer/babylon.viewer.js"></script>
  </body>
</html>
```

This is the basic foundation of the entire tutorial. From this point on, I will show only the content in the `<body>` tag.

## Engine and camera configuration

To add the engine configuration (antialiasing for better image quality), I will add the engine HTML tag to the `babylon` tag:

```html
<babylon extends="none">
  
  <engine antialiasing="true"></engine>
</babylon>
```

The camera configuration is added afterwards, using the camera HTML tag:

```html
<babylon extends="none">
  
  <engine antialiasing="true"></engine>
  
  <camera>
    
    <behaviors>
      
      <auto-rotate type="0"></auto-rotate>
      
      <framing type="2" zoom-on-bounding-info="true" zoom-stops-animation="false"></framing>
      
      <bouncing type="1"></bouncing>
    </behaviors>
  </camera>
</babylon>
```

The camera configuration includes camera behavior configuration, which is a native Babylon.js feature. You can read about it in [Camera behaviors](/legacy/babylonViewer/configuringViewer).

## Adding environment

To add the environment, we need to enable the ground and the skybox. There are two ways to do that. The first is to enable them in the `<babylon>` tag. I use this when I do not want to further configure the element I am extending. For example:

```html
<babylon skybox="true" ground="true"> </babylon>
```

This will enable the default skybox and ground. Another way, which is the one I will use, is to add the HTML elements:

```html
<babylon extends="none">
  
  <ground receive-shadows="true"></ground>
  
  <skybox></skybox>

  
  <engine antialiasing="true"></engine>
  
  <camera>
    
    <behaviors>
      
      <auto-rotate type="0"></auto-rotate>
      
      <framing type="2" zoom-on-bounding-info="true" zoom-stops-animation="false"></framing>
      
      <bouncing type="1"></bouncing>
    </behaviors>
  </camera>
</babylon>
```

The reasons I chose the second way are:

- It is readable and easy to understand
- It is extendible. If I want to change the skybox's configuration, I need to change the tag rather than add a new one.

## Templates - Main template

An important part of the viewer is the templating system. It takes predefined HTML elements, adds them where needed, and attaches Babylon to the created canvas element and the buttons in the navigation bar. To read about it, visit [The templating system](/legacy/babylonViewer/viewerTemplatingSystem).

The default viewer, which is the viewer we are using when using the `<babylon>` tag, expects certain templates to have specific elements (like a full screen button in the navigation bar, or a loading screen). If specific templates aren't included, the viewer will fail silently and will continue rendering the 3D element. The only obligatory template is the main template. Without a main template (which can be a single canvas and that's it) the viewer will fail.

### Adding a new template

To add a new template using HTML, I will place each template inside a `<script id="name-of-template" type="text/x-babylon-viewer-template">`. This template can later be referenced in the viewer configuration using the defined ID.

For example, this is the main template (copied from https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/assets/templates/default/defaultTemplate.html):

```html
<script id="main-template" type="text/x-babylon-viewer-template">
  <style>
      @font-face {
          font-family: 'babylon';
          src: url('{{babylonFont}}') format('woff');
          font-weight: normal;
          font-style: normal;
      }

      .icon {
          font-family: "babylon";
      }
  </style>

  {{#if fillScreen}}
  <style>
      html,
      body {
          width: 100%;
          height: 100%;

          margin: 0;
          padding: 0;
      }
  </style>
  {{/if}}

  <fill-container></fill-container>
</script>
```

Everything inside the script tag will be sent to [handlebars](https://handlebarsjs.com/). Since we are using Handlebars, you can add parameters or conditions inside your templates. Looking at the main template, you can see that there are two parameters that the template expects:

- A link to a font file (that includes the icons we will later use in the navigation bar)
- a flag, `fillScreen` that will add specific style definition if we want the viewer to fill the entire screen

You can also notice that the main template contains a tag called `fill-container`. The fill-container tag will be populated using a template with the same name that I will define later. Using custom HTML tags is how you can define your own templating tree and configure a specific part of the viewer without editing the rest of the elements.

### Adding the template to the viewer

To add the main template to the viewer, we will add the main tag to the `babylon` tag:

```html
<babylon extends="none">
  <templates>
    <main location="#main-template">
      <params no-escape="true" babylon-font="https://viewer.babylonjs.com/babylon.woff"></params>
    </main>
  </templates>

  
  <ground receive-shadows="true"></ground>
  
  <skybox></skybox>

  
  <engine antialiasing="true"></engine>
  
  <camera>
    
    <behaviors>
      
      <auto-rotate type="0"></auto-rotate>
      
      <framing type="2" zoom-on-bounding-info="true" zoom-stops-animation="false"></framing>
      
      <bouncing type="1"></bouncing>
    </behaviors>
  </camera>
</babylon>
```

I'll dissect the templates tag to explain how it is configured.

#### Location parameter

```html
<main location="#main-template"></main>
```

This line adds a new template called "main" to the template manager. It will find its HTML source in the script template tag with the ID `main-template` (which is the one we defined earlier). The location can also be a URL from which the HTML will be downloaded and parsed. For example:

```html
<main location="https://example.com/templates/main.html"></main>
```

#### params element

To pass variables to the template when it is compiled with Handlebars, I pass variables in the params HTML tag. The following tag:

```html
<params no-escape="true" babylon-font="https://viewer.babylonjs.com/babylon.woff"></params>
```

will configure Handlebars not to escape input (`noEscape`, https://handlebarsjs.com/reference.html) and will pass `babylonFont` to the template. It will then populate this in the line `src: url('{{babylonFont}}') format('woff');` of the main template I previously defined. We could also add the `fillScreen` flag to allow a fullscreen viewer:

```html
<params no-escape="true" babylon-font="https://viewer.babylonjs.com/babylon.woff" fill-screen="true"></params>
```

## Further templates

I continue adding the templates as I added the main template. I will show here two more templates that are important. The one holding the canvas, and the navigation bar - to show how to enable events.

### The template holding the canvas

A canvas is needed for Babylon to work correctly. We need to add one (and only one!) canvas element in one of the included templates.

```html
<script id="viewer-template" type="text/x-babylon-viewer-template">
  <style>
      viewer {
          position: relative;
          overflow: hidden;
          /* Start stage */
          z-index: 1;
          justify-content: center;
          align-items: center;

          width: 100%;
          height: 100%;
      }

      .babylonjs-canvas {
          flex: 1;
          width: 100%;
          height: 100%;
          /* enable cross-browser pointer events */
          touch-action: none;
      }
  </style>

  <canvas class="babylonjs-canvas" touch-action="none"></canvas>

  <nav-bar></nav-bar>
</script>
```

To get pointer input to work in all browsers, including iOS devices, I add the touch-action parameter to both the canvas element and the CSS definition of the canvas. This is very important. Otherwise, certain browsers will not accept user input.

### The navigation bar

In the case of the navigation bar, I want to show how to add the navbar's template and enable JS events on specific elements within it. The navbar's HTML code can be found here: https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/assets/templates/default/navbar.html .

This is the full `templates` object, with comments on the navbar definition.

```html
<babylon extends="none">

    <templates>
        <main location="#main-template">
            <params no-escape="true" babylon-font="https://viewer.babylonjs.com/babylon.woff"></params>
        </main>
        <fill-container location="#fill-container-template">
            <params disable="false"></params>
        </fill-container>
        <loading-screen location="#loading-screen-template">
            <params background-color="#000000" loading-image="https://blogs.windows.com/uploads/mswbprod/sites/3/2018/05/b58474ab97a2708346422fe7ce30c15e.png"></params>
        </loading-screen>
        <viewer location="#viewer-template">
            <params enable-drag-and-drop="false"></params>
        </viewer>
        <nav-bar location="#nav-bar-template">
            
            <params logo-image="https://blogs.windows.com/uploads/mswbprod/sites/3/2018/05/b58474ab97a2708346422fe7ce30c15e.png" logo-text="BabylonJS"
                logo-link="https://babylonjs.com" hide-help="true" hide-hd="true" hide-vr="true" disable-on-fullscreen="false">
                
                <speed-list "0.5x"="0.5" "1.0x"="1.0" "2.0x"="2.0"></speed-list>
                
                <text hd-button="Toggle HD" fullscreen-button="Fullscreen"></text>
            </params>
            
            <events pointerdown="true" pointerup="true" input="true"></events>
        </nav-bar>
    </templates>

    
    <ground receive-shadows="true"></ground>
    
    <skybox></skybox>

    
    <engine antialiasing="true"></engine>
    
    <camera>
        
        <behaviors>
            
            <auto-rotate type="0"></auto-rotate>
            
            <framing type="2" zoom-on-bounding-info="true" zoom-stops-animation="false"></framing>
            
            <bouncing type="1"></bouncing>
        </behaviors>
        
        <model url="https://models.babylonjs.com/shark.glb"></model>
    </camera>
</babylon>
```

## Viewing a model

Once the Babylon.js viewer is fully configured, you can specify which 3D model you want to view.

There are two ways to specify a 3D model.

1. Add a `model` attribute on the `<babylon>` tag which can point to a 3D model file.

   ```html
   <babylon extends="none" model="https://models.babylonjs.com/shark.glb"></babylon>
   ```

2. Add a `<model>` HTML tag and set its `url` attribute to a 3D model file.
   `html <babylon extends="none"> <model url="https://models.babylonjs.com/shark.glb"></model> </babylon> `
   The examples point to a sample [shark glTF model](https://github.com/BabylonJS/MeshesLibrary/blob/master/shark.glb). You can also load other formats including `.glTF`, `.babylon`, `.obj`, and `.stl`. Note that the model won't be displayed till the entire configuration is added to the viewer.

## The full example

<p data-height="550" data-theme-id="light" data-slug-hash="KBXVdw" data-default-tab="html,result" data-user="BabylonJS" data-pen-title="[Babylon.js Viewer] Recreating default configuration" class="codepen">See the Pen <a href="https://codepen.io/BabylonJS/pen/KBXVdw/">[Babylon.js Viewer] Recreating default configuration</a> by Babylon.js (<a href="https://codepen.io/BabylonJS">@BabylonJS</a>) on <a href="https://codepen.io">CodePen</a>.</p>
<script async src="https://static.codepen.io/assets/embed/ei.js"></script>


This section contains a list of the current viewer demos.

## Basic usage

[https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/basicExample.html](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/basicExample.html)

A basic example of loading a .babylon model with the default configuration.

[Live demo](https://viewer.babylonjs.com/basicExample.html)

## DOM configuration

[https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/domExample.html](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/domExample.html)

An example of how to use the DOM to configure the viewer.

[Live demo](https://viewer.babylonjs.com/domExample.html)

## Events example

[https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/eventsExample.html](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/eventsExample.html)

An example of how to load the viewer and use its observers with promises, observables, and callbacks.

[Live demo](https://viewer.babylonjs.com/eventsExample.html)

## Animations example

[https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/ufoExample.html](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/viewer/public/ufoExample.html)

An example of the animation system of the default viewer.

[Live demo](https://viewer.babylonjs.com/ufoExample.html)



The viewer has a simple integrated templating system for you to use and extend. Using the templating system, you can decide how viewer components such as the navbar, the error screen, the help screen, and so on look.

The templating system uses [Handlebars.js](https://handlebarsjs.com/) to parse the HTML. We recommend understanding the basic concepts of Handlebars before making major changes to the HTML templates.

## Basics of the templating engine

### Configuration

As with the general configuration, the template configuration is based on a TypeScript interface for ease of usage. These are the interfaces:

```javascript
export interface ITemplateConfiguration {
  location?: string; // #template-id OR http://example.com/loading.html
  html?: string; // raw html string
  id?: string;
  params?: { [key: string]: string | number | boolean | object };
  events?: {
    // pointer events
    pointerdown?: boolean | { [id: string]: boolean },
    pointerup?: boolean | { [id: string]: boolean },
    pointermove?: boolean | { [id: string]: boolean },
    pointerover?: boolean | { [id: string]: boolean },
    pointerout?: boolean | { [id: string]: boolean },
    pointerenter?: boolean | { [id: string]: boolean },
    pointerleave?: boolean | { [id: string]: boolean },
    pointercancel?: boolean | { [id: string]: boolean },
    //click, just in case
    click?: boolean | { [id: string]: boolean },
    // drag and drop
    dragstart?: boolean | { [id: string]: boolean },
    drop?: boolean | { [id: string]: boolean },

    [key: string]: boolean | { [id: string]: boolean } | undefined, // allow injecting further events
  };
}
```

### Location vs. HTML

There are two ways to define where the template is found: the location and the html parameters. One of them must be defined. If both are defined, the 'html' parameter will be used.

The location parameter defines a URL where the HTML can be found, or the ID of a script tag with the type "text/x-babylon-viewer-template". For example, the HTML page can contain the following HTML element:

```html
<script id="loading-screen" type="text/x-babylon-viewer-template">
  <img class="loading-image" src="{{loadingImage}}">
</script>
```

The configuration for using this would be:

```javascript
    ...,
    templates: {
        main: {
            html: "<viewer></viewer><loading-screen></loading-screen>"
        },
        loadingScreen: {
            location: '#loading-screen',
            params: {
                loadingImage: "data:image/png;base64,...."
            }
        },
        viewer: {
            html: '<canvas class="babylonjs-canvas"></canvas>',
        }
    }
```

The 'html' parameter simply contains the raw HTML of the template. For example:

```javascript
    ...,
    templates: {
        viewer: {
            html: '<canvas class="babylonjs-canvas"></canvas>',
        }
    }
```

When the template is a simple HTML file and no other configuration is needed, the template configuration can be a single string of the URL or #id where the template can be found.

So this:

```javascript
    .....,
    templates: {
        main: {
            location: "#main-template"
        }
    },
    ....
```

is equal to this:

```javascript
    .....,
    templates: {
        main: "#main-template"
    },
    ....
```

### Simple walkthrough

The templating engine will load and parse all templates defined in the configuration. As part of the parsing process, it will look for tags that are defined in the template configuration and inject them in the right place. The template that will be injected into the main component (the `<babylon>` HTML tag by default) is always called 'main'.

For example, if the templating configuration looks like this:

```javascript
    templates: {
        main: {
            html: "<viewer></viewer><loading-screen></loading-screen>"
        },
        loadingScreen: {
            html: '<img class="loading-image" src="{{loadingImage}}">',
            params: {
                loadingImage: "data:image/png;base64,...."
            }
        },
        viewer: {
            html: '<canvas class="babylonjs-canvas"></canvas>',
        }
    }
```

the final `<babylon>` tag will look like this:

```html
<babylon .....>
  <viewer>
    <canvas class="babylonjs-canvas"></canvas>
  </viewer>
  <loading-screen>
    <img class="loading-image" src="data:image/png;base64,...." />
  </loading-screen>
</babylon>
```

_Note that the html tag names are in kebab-case. The configuration (when in JSON format) uses camelCase_.

### Handlebars expressions

Going back to the configuration from the last section, you can see that the HTML template of the loading screen is:

```html
<img class="loading-image" src="{{loadingImage}}" />
```

Anything inside `{{` and `}}` is considered a Handlebars expression. This parameter can be defined in the configuration file, as seen in the previous section:

```javascript
    templates: {
        ...,
        loadingScreen: {
            html: '<img class="loading-image" src="{{loadingImage}}">',
            params: {
                loadingImage: "data:image/png;base64,...."
            }
        }
    }
```

Using this method, you can easily support internationalization by injecting the parameters through the configuration instead of embedding them in the HTML.

### Event binding

Any template can have any native JavaScript event registered to it or to one of its children. The callback will be bound to the selected element, and will trigger a callback in the template, which can be used when registering the onEventTriggered observer of the template. But first, let's see how to simply bind events:

Let's take a look at the following configuration (taken from the default configuration with a few changes):

```javascript
        navBar: {
            html: '<div class="button-container flex-container">  <div id="fullscreen-button" class="button"> <span>Full screen</span>> </div> </div>',
            events: {
                pointerdown: { 'fullscreen-button': true, 'some-other-id': true },
                drop: true
            }
        },
```

This event configuration will register two events:

1. A pointerdown event that will be bound to the inner `#fullscreen-button` div
1. A drop event that will be bound to the navbar element itself.

_If you are wondering why the event definition (\{ 'fullscreen-button': true, 'some-other-id': true \}) is a map and not an array of IDs - the template can also be configured using HTML, and HTML DOM elements don't support Arrays. This way the HTML can override the event by setting it to "false"._

The event callback will deliver the following object:

```javascript
export interface EventCallback {
  event: Event; // the native browser event
  template: Template; // the template on which it was executed
  selector: string; // the selector used (for example #fullscreen-button)
  payload?: any; // any extra payload. For future development, currently not being used.
}
```

To register an event listener, load the template using the template manager and add an observer to the `onEventTriggered` observable:

```javascript
// viewer is a viewer instance. See Advanced usage (//doc.babylonjs.com/extensions/Advanced_usage) for further details on how to get it.
let navbar = viewer.templateManager.getTemplate("navBar");
// let's be safe!
if (!navbar) return;

// register a new observer
navbar.onEventTriggered.add((data) => {
  switch (data.event.type) {
    case "pointerdown":
      switch (data.selector) {
        case "#fullscreen-button":
          // let's go full screen!!
          break;
        case "#some-other-id":
          // just do something else please
          break;
      }
      break;
    case "drop":
      // What shall we do with the dropped data?
      break;
  }
});
```

## The template manager

Any template-enabled viewer (the default viewer, for example) has its own template manager, which is in charge of loading and parsing the templates.

The template manager is a public member of the viewer and can be used to retrieve already-parsed templates:

```javascript
// not a part of this section, let's assume the viewer is being retrieved
let viewer = getViewer();

// We have previously defined a "canvas" element in the configuration. We can now retrieve it!
let canvasContainer = viewer.templateManager.getTemplate("canvasContainer");
```

### The template object

Any configured template creates a new instance of the [Template class](https://github.com/BabylonJS/Babylon.js/blob/master/packages/tools/viewer/src/templating/templateManager.ts).

Here are the public variables we can access:

```javascript
public onInit: Observable<Template>;
public onLoaded: Observable<Template>;
public onAppended: Observable<Template>;
public onStateChange: Observable<Template>;
public onEventTriggered: Observable<EventCallback>;

public isLoaded: boolean; // is the template fully loaded

public parent: HTMLElement; // the HTML container of this template. In this case, the <canvas-container> element.
```

The Template class also has a few promise-based helper functions for common tasks:

```javascript
public show(visibilityFunction?: (template: Template) => Promise<Template>): Promise<Template>;
public hide(visibilityFunction?: (template: Template) => Promise<Template>): Promise<Template>;
```

If you call those functions without any parameters, the `display` of this template will be set to `flex` or `none`, respectively.

To define your own show or hide functions, simply provide the visibilityFunction as the first parameter. The following is a real example from the default viewer:

```javascript
template.hide((template) => {
  // set the opacity to '0'. Opacity transition is set using CSS.
  template.parent.style.opacity = "0";
  // define a function for when the transition has ended:
  let onTransitionEnd = () => {
    template.parent.removeEventListener("transitionend", onTransitionEnd);
    // set display none when opacity is '0'
    template.parent.style.display = "none";
  };
  // add the transitionend event listener
  template.parent.addEventListener("transitionend", onTransitionEnd);
  // return immediately, don't wait for the transition to end
  return Promise.resolve(template);
});
```

## Templates of the default viewer

The default viewer comes with predefined templates that can be simply changed if needed.

The delivered templates are:

- main - the main template (must always be present)
- viewer - containing the canvas
- loading screen - a simple loading screen template
- nav-bar - the bottom navigation bar
- overlay - a container for overlays, such as error or help
- error - an error screen
- help - a help screen
- share - a share screen

All templates can be found in the viewer's assets directory: [https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/Viewer/assets/templates/default](https://github.com/BabylonJS/Babylon.js/tree/master/packages/tools/Viewer/assets/templates/default). The templates include CSS internally and are self-contained.

### Changing an existing template

If you want to change one of the templates, simply create a new HTML structure and set it in the viewer configuration. For example, if we want to change the loading screen so it will not show an image at all:

The new loadingScreen HTML injected into the page as a `<script>` tag:

```html
<script id="loading-screen" type="text/x-babylon-viewer-template">
    <style>
      loading-screen {
          position: absolute;
          z-index: 100;
          opacity: 1;
          pointer-events: none;
          display: flex;
          justify-content: center;
          align-items: center;
          -webkit-transition: opacity 2s ease;
          -moz-transition: opacity 2s ease;
          transition: opacity 2s ease;
      }
  </style>

  <span> LOADING... </span>
</script>
```

This can be added to the configuration of the viewer element:

```html
<babylon templates.loading-screen.location="#loading-screen" templates.loading-screen.html="" model="...."></babylon>
```

### Extending an existing template

The nav bar, for example, can be extended to hold additional buttons. The default navbar configuration is:

```javascript
navBar: {
    html: require("../../../assets/templates/default/navbar.html"),
    params: {
        buttons: [
            {
                id: 'fullscreen-button',
                altText: "Fullscreen",
                image: require('../../../assets/img/fullscreen.png')
            }
        ],
        visibilityTimeout: 2000
    },
    events: {
        pointerdown: { 'fullscreen-button': true }
    }
}
```

If you want, for example, to change the visibilityTimeout to 1 second, set it using your viewer configuration:

```html
<babylon templates.nav-bar.params.visibility-timeout="1000" model="...."></babylon>
```

## Creating your own templates

If you do not want to use the default templates and want to create your own completely, here are a few important notes.

### The main template

You should always have a template named "main", which will be the starting point of your template. Apart from "main", it is up to you to decide how to organize your templates. The main template can technically contain everything, so there is no actual need to create any other templates unless you want to internally overwrite certain templates.

The main template can technically be a single canvas element, and that's about it.

### You need a canvas

Well, a canvas is needed, obviously, **and only one!** To avoid creating additional unneeded configuration parameters, the first canvas found inside the parsed main template will be used as the canvas for Babylon.

## If help is needed

Look at the code or contact us, we will be more than happy to help!



<Alert severity="warning" title="Deprecated">
  The Babylon Viewer V1 is deprecated. When building new experiences, please use the [Babylon Viewer V2](/features/featuresDeepDive/babylonViewer).
</Alert>

## Display 3D models on your webpage

The Babylon.js viewer is the simplest way to display 3D content on a web page.

To display a 3D model on your web page:

1. Add a script reference to the viewer

    ```html
    <script src="https://cdn.babylonjs.com/viewer/babylon.viewer.js"></script>
    ```

2. Add a `<babylon>` tag and set the _model_ attribute to point to a `.gltf` or `.glb` file

    ```html
    <babylon model="model.gltf"></babylon>
    ```

    We recommend using the [glTF format](https://github.com/khronosgroup/gltf) (`.gltf` or `.glb`) for displaying 3D models on your webpage. Other formats supported by Babylon.js loaders are also supported by the viewer component, including `.babylon`, `.obj`, and `.stl`.

The Babylon.js viewer automatically provides a [default viewing experience](#default-viewing-experience) for 3D models. All aspects of this experience are configurable. See [Configuring the viewer](//doc.babylonjs.com/extensions/babylonViewer/configuringViewer) for more information on customizing the viewing experience.

## Example

<CodePen pen="QxzBPd" tab="html,result" title="Babylon.js Viewer - Display a 3D model" />

## Resizing

Controlling the size of the viewer is one of the most common configuration operations. It is fairly easy, as the viewer in default mode fills 100% of the width and height of its container. To control the viewer, you can simply style its enclosing container.

<CodePen pen="qMBwar" tab="html,result" title="Babylon.js Viewer - Resize the viewer" />

## Using the viewer in your project

The Babylon.js viewer is available on a CDN as well as an NPM package. The Babylon.js viewer is a wrapper around the Babylon.js engine and follows the same versioning scheme as the engine. The current stable version of the Babylon.js viewer uses the current stable version of the Babylon.js engine, and the preview version of the Babylon.js viewer uses the preview version of the Babylon.js engine.

## CDN

Stable versions of the viewer are available on:

-   https://cdn.babylonjs.com/viewer/babylon.viewer.js (minified)
-   https://cdn.babylonjs.com/viewer/babylon.viewer.max.js

Preview releases (nightlies) of the viewer are available on:

-   https://preview.babylonjs.com/viewer/babylon.viewer.js (minified)
-   https://preview.babylonjs.com/viewer/babylon.viewer.max.js

## NPM

To install the Babylon.js viewer through NPM, use:

```javascript
npm install --save babylonjs-viewer
```

This will install the latest stable version of the viewer, including its needed dependencies.

Afterward, it can be imported into the project using:

```javascript
import "babylonjs-viewer";
```

This will enable the `BabylonViewer` namespace.



# How To Use Advanced Physics Features

## The Heightmap

One of the best ways to interact with a ground object is the Heightmap impostor (currently supported only with the CannonJS plugin).

A heightmap is not a mesh impostor. It is possible that objects coming from the side will not collide with it. The heightmap impostor takes the height Y value at a certain point in a mesh and sets a collision point. To understand what a heightmap impostor is, think of a regular house with a triangle roof. If we set the heightmap impostor to the house, the only part that will have collision detection is the roof. Anything below the roof will be ignored, including the walls.

On the positive side, a heightmap can collide with most other objects, as opposed to the mesh impostor which only collides against spheres. Performance is also much better with a heightmap than with a mesh impostor.

There are certain conditions in which a heightmap can be initialized:

* It must be square (x === z). The most important values are the y values in each point of the heightmap.
* It cannot contain holes or missing textures
* It is recommended that the heightmap be generated from a GroundMesh, generated from a heightmap image

To create a ground from an image-based ground mesh:

```javascript
var ground = BABYLON.MeshBuilder.CreateGroundFromHeightMap("ground", "textures/worldHeightMap.jpg", { width: 200, height: 200, subdivisions: 50, minHeight: 0, maxHeight: 30, onReady: function () {
    ground.physicsImpostor = new BABYLON.PhysicsImpostor(ground, BABYLON.PhysicsImpostor.HeightmapImpostor, { mass: 0 });
} }, scene);
```

To create a heightmap from a square ribbon:

```javascript
var exponentialPath = function (p) {
    var path = [];
    for (let i = -50; i <= 50; i++) {
        path.push(new BABYLON.Vector3(p-50, (Math.sin(p / 3) * 10 * Math.exp((i - p) / 100) + i / 3), i));
    }
    return path;
};
// let's populate arrayOfPaths with all these different paths
var arrayOfPaths = [];
for (let p = 0; p <= 100; p++) {
    arrayOfPaths[p] = exponentialPath(p);

}

var mesh = BABYLON.MeshBuilder.CreateRibbon("ribbon", { pathArray: arrayOfPaths, closeArray: false, closePath: false, offset: 0 }, scene);
mesh.physicsImpostor = new BABYLON.PhysicsImpostor(mesh, BABYLON.PhysicsImpostor.HeightmapImpostor, { mass: 0, friction:1, restitution: 0.5 });
```

A demo for both of these examples can be found here:
<Playground id="#D3LQD#7" title="Creating Ground From An Image-Based Ground Mesh" description="Simple example of creating ground from an image based ground mesh."/>
<Playground id="#EXL6K#9" title="Creating A Heightmap From A Square Ribbon" description="Simple example of creating a heightmap from a square ribbon."/>

## Mesh Impostor

A mesh impostor wraps a complex mesh with a physics body, allowing exact collision detection with the object. As opposed to the heightmap impostor, a mesh impostor has the entire mesh covered.

A mesh impostor is only available with cannon.js, and only collides against spheres.

Regarding performance - you will notice that the mesh impostor doesn't influence performance too much, until an object collides against it. Then the calculations are rather complex and can lower your FPS significantly, depending on the mesh's complexity.

A simple example of the mesh impostor can be found here - <Playground id="#3B3135#1" title="Mesh Impostor Example" description="Simple example of a mesh impostor."/>

To generate a mesh impostor, simply set the MeshImpostor type when creating the physics impostor of the mesh:

```javascript
mesh.physicsImpostor = new BABYLON.PhysicsImpostor(mesh, BABYLON.PhysicsImpostor.MeshImpostor, {mass: 0});
```

The rest will be done by Babylon and the physics engine.

A wonderful example of the abilities of the mesh impostor can be found here - https://ajna4taiga.tk/PerplexusShadowOpen/Home.html

## Motors

Certain joint types, like the wheel (hinge) joint, can run a motor that moves the impostor connected to the joint in the direction set by the user.

Motors can be used to move a car wheel, simulate an elevator, or create a gear system. The motor is responsible for enabling the circular movement in those simulations.

A simple example can be seen here: <Playground id="#5W5B6W#1" title="Simple Motor Example" description="Simple example of a motor joint."/>

Motor.enabled joints are using the `IMotorEnabledJoint` :

```javascript
interface IMotorEnabledJoint {
    physicsJoint: any; //the native physics joint object. Coming from the selected engine.
    setMotor(force?: number, maxForce?: number, motorIndex?: number): void; // provide force to the motor
    setLimit(upperLimit: number, lowerLimit?: number, motorIndex?: number): void; // set limits to the motor
}
```

Setting a motor on a hinge joint (assuming impostors are already set):

```javascript
var joint1 = new BABYLON.HingeJoint({
    mainPivot: new BABYLON.Vector3(0, 0, 0), // Pivot on the main mesh
    connectedPivot: new BABYLON.Vector3(0, 0, 0), // pivot (connecting point) on the connected pivot
    mainAxis: new BABYLON.Vector3(0, 0, -1), // the hinge will turn on the Z axis
    connectedAxis: new BABYLON.Vector3(0, 0, -1) // Same as above - Z axis on the connected mesh
});
holder.physicsImpostor.addJoint(wheel.physicsImpostor, joint1); // attach holder (main) and wheel using the defined hinge joint

joint1.setMotor(3, 20); // start turning!
```

## Compounds and Babylon's parenting system

Babylon.js supports creating physics compounds. A compound is a collection of physics bodies connected together to create a single physics body with the combined geometry of all the connected meshes.

To create a compound, use Babylon's parenting system. A single object should be the parent of the rest of the compound shapes:

```javascript
// Create a 2-sphere compound
 var sphere = BABYLON.MeshBuilder.CreateSphere("sphere1", { segments: 16, diameter: 2 }, scene);
sphere.position.y = 10;

var sphere2 = BABYLON.MeshBuilder.CreateSphere("sphere2", { segments: 16, diameter: 2 }, scene);
sphere2.position.x = 2;
sphere.position.y = 1;
sphere2.parent = sphere;
```

After creating the meshes, we need to initialize the impostors. It is important to first initialize the child impostors and initialize the parent impostor at the end:

```javascript
sphere2.physicsImpostor = new BABYLON.PhysicsImpostor(sphere2, BABYLON.PhysicsImpostor.SphereImpostor, {mass: 2, restitution: 0.8});
sphere.physicsImpostor = new BABYLON.PhysicsImpostor(sphere, BABYLON.PhysicsImpostor.SphereImpostor, {mass: 2, restitution: 0.8});
```

The mass will be accumulated. So this single physics body's mass will be 4. `sphere2`'s physics impostor will be "disabled" and joined to `sphere`'s impostor, which is the main impostor. To apply impulses, set the linear velocity, etc., use `sphere.physicsImpostor`.

<Playground id="#PRHF00#6" title="Advanced Physics Compounds Example 1" description="Advanced example of physics compounds."/>

An advanced example of compounds can be seen here: <Playground id="#5W5B6W#3" title="Advanced Physics Compounds Example 2" description="Advanced example of physics compounds."/>. The boxes connected to the disc use Babylon's parenting system.

### ignoreParent

You can disable Babylon's compound behavior by setting the `ignoreParent` flag when creating the impostor.
It is important to note that this will only work if your parent has no impostor attached to it. Otherwise the results can vary from weird physics calculations to missing collisions.

To create an impostor for a child mesh using the ignoreParent flag:

```javascript
sphere2.physicsImpostor = new BABYLON.PhysicsImpostor(sphere2, BABYLON.PhysicsImpostor.SphereImpostor, {ignoreParent: true, mass: 2, restitution: 0.8});
```

A simple example can be found here - <Playground id="#PRHF00#4" title="Ignore Parent Example" description="Simple example of ignoring a physics parent."/>

## Substeps

It is possible to run the physics ticks at a different frequency than the frame rate while keeping the display consistent.
This means you can display at 60 frames per second while updating the physics 1000 times a second.
With substeps, the physics will look like it's running at 60 frames per second but will perform smaller steps.
This is useful when the physics update needs more precision. For example, simulating a bullet against a wall or more accurate physics for a car.
Substeps can also be used to reduce the physics update frequency, for example by doing an update every 2 frames.
In the following example, the physics is computed 10 times a second instead of 60. 

```javascript
var physicsEngine = scene.getPhysicsEngine();
physicsEngine.setSubTimeStep(100);
```

<Playground id="#YUNAST#21" title="Substeps Example" description="Simple example of using substeps."/>

## Cloth simulation

Raanan Weber wrote an article about cloth simulation in his blog: [https://blog.raananweber.com/2016/04/03/cloth-physics-simulation-for-babylon-js/](https://blog.raananweber.com/2016/04/03/cloth-physics-simulation-for-babylon-js/)

## An Oimo Demo

* Oimo car demo - <Playground id="#SFELK#3" title="Oimo Car Demo" description="Oimo Car Demo"/>


Babylon.js Viewer (V1)

Display 3D models on your webpage

Example

Resizing

Using the viewer in your project

CDN

NPM

Further reading

Configuring the Babylon.js Viewer

How to configure the Babylon.js viewer.

Babylon.js Viewer Templating System

Using and extending the viewer's simple integrated templating system.

Modify the Babylon.js Viewer

Modifying the Babylon.js viewer using HTML.

Babylon.js Viewer - Advanced usage

Advanced uses of the viewer.

Babylon.js Viewer Examples

Examples of using the viewer

Coming next