API
Legacy|
Babylon.js Viewer V1|
Configuring The Viewer

Configuring the Babylon.js Viewer

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
  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

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:

<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

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
  2. (optional) The extra configuration file provided using the configuration keyword.
  3. 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:

<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):

{
    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:

{
    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 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:

{
  "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:

<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:

{
    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:

<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:

<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):

<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:

<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, 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:

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:

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

BabylonViewer.mapperManager.registerMapper("yaml", yamlMapper);

And finally, we need to tell the manager which mapper to use:

<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
  2. Register the mapper
  3. 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):

<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):

<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

Further reading

Babylon.js Viewer (V1)
The viewer is the simplest way to display 3D content on a web page.
Babylon.js Viewer (V1)
Babylon.js Viewer Templating System
Using and extending the viewer's simple integrated templating system.
Babylon.js Viewer Templating System
Modify the Babylon.js Viewer
Modifying the Babylon.js viewer using HTML.
Modify the Babylon.js Viewer
Babylon.js Viewer - Advanced usage
Advanced uses of the viewer.
Babylon.js Viewer - Advanced usage
Babylon.js Viewer Examples
Examples of using the viewer
Babylon.js Viewer Examples