Scene

How To Fast Build a World

There are a number of helpers that, once you have put models into a scene, add cameras, lights, and an environment that automatically adjust to the models, allowing you to view them quickly. You can then make adjustments as needed.

For beginners to Babylon.js, the Fastest Build and Import and Fastest Build sections will quickly give you a viewable world and are a good way to look at models. As such, they are level 1 material. It is worth considering working through Babylon101 and parts of the level 1 material to make the other information and details on this page easier to understand.

Helpers

The following is a list of the methods of the scene object that help in fast building a world, with a link to their API description:

• createDefaultCameraOrLight;
• createDefaultCamera;
• createDefaultLight;
• createDefaultEnvironment;
• createDefaultSkybox;

Fastest Build

To build a world very quickly, just use createDefaultCameraOrLight along with createDefaultEnvironment, as in this example:

scene.createDefaultCameraOrLight(true, true, true);
scene.createDefaultEnvironment();

You can see how the camera automatically adjusts by adding a second box and repositioning it:

More information about these methods, including details about parameters, can be found in the individual sections below.

Create Default Camera or Light

As shown in the Fastest Build section, the createDefaultCameraOrLight helper creates both a camera and a light in one line. The three parameters it takes are the same as for the createDefaultCamera method. The second parameter also applies to the light and replaces any existing camera or light when true. Accessing the camera or light works the same way as with the individual methods.

Create Default Camera

createDefaultCamera takes three boolean parameters, all set to false by default. They are:

• createArcRotateCamera: creates a free camera by default and an arc rotate camera when true;
• replace: when true the created camera will replace the existing active one;
• attachCameraControls: when true attaches control to the canvas.

This code will create an arc rotate camera, replace any existing camera, and attach the camera controls to the canvas:

scene.createDefaultCamera(true, true, true);

For a free camera:

scene.createDefaultCamera(false, true, true);

The camera will adjust depending on the size and position of each mesh in the world.

Accessing the Camera

Since creating the camera this way makes the helper-created camera the active camera, the simplest way to access it is:

scene.createDefaultCamera(true, true, true);

var helperCamera = scene.activeCamera;

An alternative way to access the helper-created camera immediately after creating it is to use the fact that it will be the last one in the scene.cameras array:

scene.createDefaultCamera(true, true, true);

var helperCamera = scene.cameras[scene.cameras.length - 1];

//OR

var helperCamera = scene.cameras.pop();
scene.cameras.push(helperCamera);

Create Default Light

createDefaultLight takes just one boolean parameter, set to false by default:

• replace: when true the created light will replace all the existing ones; when false and there are no existing lights a hemispherical light is created; when false and lights already exist, no change is made to the scene.

When this method is used before any other lights are created, it is usually sufficient to use:

scene.createDefaultLight();

Accessing the Light

Provided you access the helper-created light immediately after creating it, it will be the last one in the scene.lights array.

You can obtain it using

scene.createDefaultLight();

var helperLight = scene.lights[scene.lights.length - 1];

//OR

var helperLight = scene.lights.pop();
scene.lights.push(helperLight);

Create Default Environment

The simple code

scene.createDefaultEnvironment();

adds a skybox and ground to the scene, sets a wide range of environmental parameters, and returns an environmental helper.

You will also find below a helper for just a skybox.

When you look at the following playground:

it is not obvious that a skybox and ground have been added. The defaults have been set to be very subtle and to help give the objects a grounded feel.

Moving the camera further out shows that the skybox is constructed.

You can also see the skybox and ground by using the options parameter and setting different values for the skybox texture and the ground color.

Options Parameters

As you can see in the above playground, the createDefaultEnvironment method takes an options parameter. The full range of environmental helper option properties is available in the API.

So, for example

to prevent the creation of the skybox:

var helper = scene.createDefaultEnvironment({
  createSkybox: false,
});

to enable ground reflection:

var helper = scene.createDefaultEnvironment({
  enableGroundMirror: true,
});

when you see z-fighting with the ground, modify the groundYBias to a larger number:

var helper = scene.createDefaultEnvironment({
  groundYBias: 0.01,
});

Applicable Methods

Since the createDefaultEnvironment method returns an environmentalHelper object, all the properties and methods of this object (as described in the API) are available.

So, for example, if the environment color is not your preferred choice, you can modify it after creation:

import { Color3 } from "@babylonjs/core/Maths/math.color";
var helper = scene.createDefaultEnvironment();
helper.setMainColor(Color3.Teal());

Or, if you wish to dispose of the ground after creating the environment, use:

var helper = scene.createDefaultEnvironment();
helper.ground.dispose();

Or you can change the option parameters:

import { CubeTexture } from "@babylonjs/core/Materials/Textures/cubeTexture";
var helper = scene.createDefaultEnvironment();
var options = {
    skyboxTexture: new CubeTexture("/textures/skybox", scene),
};
helper.updateOptions(options);

Environmental Helper

NOTE: The environment helper relies exclusively on the BackgroundMaterial to be as efficient as possible.

Create Default Skybox

The createDefaultSkybox method can be used when you do not want to create a full environment. The parameters used determine how the skybox is created.

for example

import { CubeTexture } from "@babylonjs/core/Materials/Textures/cubeTexture";
var texture = new CubeTexture("/assets/textures/SpecularHDR.dds", scene);
scene.createDefaultSkybox(texture, true, 100);

In this case the first two parameters used give the texture for the skybox and specify that a PBRMaterial is to be used (second parameter, true) as opposed to a standard material (second parameter, false - default value).

The third parameter defines the scale of your skybox (this value depends on the scale of your scene), the default value is 1000.

Import and Fastest Build

To import models and build a world very quickly, just use createDefaultCameraOrLight along with createDefaultEnvironment, as in this example:

The camera adjusts its position automatically to make the world viewable depending on the scale and position of the models. More information on importing models with the scene helpers follows below.

Importing Models for Your World

Since the createDefault... helpers take into account any models in the scene, they can only be applied after the model is loaded, so they are placed in the callback function. For example:

import { AppendSceneAsync } from "@babylonjs/core/Loading/sceneLoader";
AppendSceneAsync("https://www.babylonjs.com/assets/DamagedHelmet/glTF/", "DamagedHelmet.gltf", scene).then(function ({ meshes }) {
    scene.createDefaultCameraOrLight(true, true, true);
    scene.createDefaultEnvironment();
});

There is then a problem. When creating a scene, Babylon.js checks for a camera. When importing models, the existence of a camera will be checked before the model has finished loading, so the scene will fail.

The solution is to replace the createScene function with the delayCreateScene function. Whether in a playground or in your own project this is a direct replacement.

NOTE: Other scene loader methods are available.

Using Scene Helpers with Import

All the helper methods described earlier on this page behave in exactly the same way when importing models. Just remember to call them within the scene loader callback.

Import Playground Examples