Scene
How To Fast Build a World
There are a number of helpers that, once you to have put models into a scene, add cameras, light and environment that adjust to the models automatically allowing you to quickly view them. You can then make adjustments as you need.
For beginners to Babylon.js these two sections Fastest Build and Import and Fastest Build will quickly give you a viewable world and are a good way of getting a look at models. As such they are level 1 material. It is worth considering working through Babylon101 and parts of the level 1 material in order to make the other information and details on this page more understandable.
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 re-positioning it
Fast Build With Camera AdjustMore information about these methods, including details about parameters, can be found in the individual sections below.
Create Default Camera or Light
As can be seen in the Fastest Build section the helper, createDefaultCameraOrLight
creates both a camera and a light in one line. The three parameters it can take are the same as for the createDefaultCamera
method, the second parameter also refers to the light and replaces any existing camera or light when true. The approach to accessing the camera or light is the same as for the individual methods.
Create Default Camera
The 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 control 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.
Camera Helper AdjustingAccessing the Camera
Since creating the camera this way makes the helper created camera the active camera the simplest way to access it is using
scene.createDefaultCamera(true, true, true);var helperCamera = scene.activeCamera;
An alternative way to access the helper created camera immediately after creating it is, since it will be the last one in the scene.cameras
array, to use
scene.createDefaultCamera(true, true, true);var helperCamera = scene.cameras[scene.cameras.length - 1];//ORvar helperCamera = scene.cameras.pop();scene.cameras.push(helperCamera);
Create Default Light
The createDefaultLight
takes just one boolean parameters, 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 the creation of any other lights then 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];//ORvar 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 to the scene.
You will also find below a helper for just a skybox.
When you look at the following playground
Playground Fast Buildit is not obvious that a skybox and ground have been added. The defaults have been set so as to be really subtle and help give a grounding feeling to the objects
Moving the camera further out shows that the skybox is constructed.
Skybox ExampleYou can also see the skybox and ground by using the options parameter and setting different values for the skybox texture and the ground color.
Skybox and Ground ChangesOptions Parameters
As you can see in the above playground the createDefaultEnvironment
method takes an options parameter. The full range of environmental helper options properties are available from 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 then all the properties and methods of this object (as in the API) are available.
So, for example if the environment color is not your favorite choice you can modify it after creation
var helper = scene.createDefaultEnvironment();helper.setMainColor(BABYLON.Color3.Teal());
or for instance should you wish to dispose of the ground after creation of the environment use
var helper = scene.createDefaultEnvironment();helper.ground.dispose();
or how about changing the options parameters
var helper = scene.createDefaultEnvironment();var options = {skyboxTexture: new BABYLON.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
var texture = new BABYLON.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.
Skybox Scale ExampleImport 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 and so are placed in the callback function. For example
BABYLON.SceneLoader.Append("https://www.babylonjs.com/Assets/DamagedHelmet/glTF/", "DamagedHelmet.gltf", scene, 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 for before the model has finished loading and 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.