Scene

Wonderland Engine (.bin) scene.

Wonderland Engine packages two types of scene:

• Activatable scene: Contains objects, components, views, resources, and rendering data
• Streamable scene: Contains objects, components, and resources

Activation 

Some scenes are activatable, they can thus be attached to the renderer to be updated and rendered on the canvas.

For more information, have a look at the switchTo method.

Instantiation 

Besides activation, a scene can instantiate the content of another scene.

For more information, have a look at the instantiate method.

• Scene
  • .constructor(engine, index) ⇒ Scene
  • .onPostRender: Emitter<void[]>
  • .onPreRender: Emitter<void[]>
  • .activeViews
  • .clearColor
  • .colorClearEnabled
  • .componentsBundle
  • .environment
  • .leftEyeView
  • .mainView
  • .rightEyeView
  • .skyMaterial
  • .views
  • .append(file, options) ⇒ Promise<SceneAppendResult>
  • .destroy() ⇒ void
  • .dispatchReadyEvent() ⇒ void
  • .instantiate(prefab) ⇒ InstantiateResult
  • .load(options) ⇒ Promise<Scene>
  • .rayCast(o, d, groupMask, maxDistance) ⇒ RayHit
  • .reset() ⇒ void
  • .setLoadingProgress(percentage) ⇒ void

.constructor(engine: WonderlandEngine, index: number) ⇒ Scene 

.onPostRender: Emitter<void[]> 

Called after the scene has been rendered

.onPreRender: Emitter<void[]> 

Called before rendering the scene

.activeViews: ViewComponent[] 

Active view components.

.clearColor 

Set the background clear color.

.colorClearEnabled 

Set whether to clear the color framebuffer before drawing.

This function is useful if an external framework (e.g. an AR tracking framework) is responsible for drawing a camera frame before Wonderland Engine draws the scene on top of it.

.componentsBundle: null | string 

Relative url to the js components bundle

Returns null if the scene was built without a components bundle.

.environment: Environment 

Environment lighting properties.

.leftEyeView: null | ViewComponent 

Left eye view.

.mainView: null | ViewComponent 

Main view.

.rightEyeView: null | ViewComponent 

Right eye view.

.skyMaterial: null | Material 

Current sky material, or null if no sky is set.

.skyMaterial 

Set the current material to render the sky.

Note: The sky needs to be enabled in the editor when creating the scene. For more information, please refer to the background tutorial.

.views: ViewComponent[] 

View components.

.append(file: string | ArrayBuffer, options: Partial<SceneAppendParameters>) ⇒ Promise<SceneAppendResult> 

Append a scene file.

Loads and parses the file and its images and appends the result to the currently active scene.

Supported formats are streamable Wonderland scene files (.bin) and glTF 3D scenes (.gltf, .glb).

1WL.scene.append(filename).then(root => {
2    // root contains the loaded scene
3});

In case the loadGltfExtensions option is set to true, the response will be an object containing both the root of the loaded scene and any glTF extensions found on nodes, meshes and the root of the file.

 1WL.scene.append(filename, { loadGltfExtensions: true }).then(({root, extensions}) => {
 2    // root contains the loaded scene
 3    // extensions.root contains any extensions at the root of glTF document
 4    const rootExtensions = extensions.root;
 5    // extensions.mesh and extensions.node contain extensions indexed by Object id
 6    const childObject = root.children[0];
 7    const meshExtensions = root.meshExtensions[childObject.objectId];
 8    const nodeExtensions = root.nodeExtensions[childObject.objectId];
 9    // extensions.idMapping contains a mapping from glTF node index to Object id
10});

If the file to be loaded is located in a subfolder, it might be useful to define the baseURL option. This will ensure any bin files referenced by the loaded bin file are loaded at the correct path.

1WL.scene.append(filename, { baseURL: 'scenes' }).then(({root, extensions}) => {
2    // do stuff
3});

Deprecated: Use the new Prefab and Scene API.

Returns: Promise that resolves when the scene was appended.

.destroy() ⇒ void 

Destroy this scene and remove it from the engine.

Note: Destroying a scene doesn’t remove the materials, meshes, and textures it references in the engine. Those should be cleaned up either by loading another main scene via loadMainScene, or manually using destroy.

Throws: If the scene is currently active.

.dispatchReadyEvent() ⇒ void 

Dispatch an event ‘wle-scene-ready’ in the document.

Note: This is used for automatic testing.

.instantiate(prefab: Prefab) ⇒ InstantiateResult 

.instantiate(scene: PrefabGLTF) ⇒ InstantiateGltfResult

Instantiate scene into this instance.

Any scene can be instantiated into one another. It’s thus possible to instantiate a PrefabGLTF into this instance, or another Scene instance.

Usage 

1const prefabScene = await engine.loadScene('Prefab.bin');
2// Instantiate `prefabScene` into `scene`
3engine.scene.instantiate(prefabScene);

Shared Resources 

Instantiating does not duplicate resources. Each instance will reference the same assets stored in the Scene, e.g.,

1// `zombie` has one mesh and one material
2const zombie = await engine.loadScene('Zombie.bin');
3
4for (let i = 0; i < 100; ++i) {
5    engine.scene.instantiate(zombie);
6}
7
8console.log(engine.meshes.count) // Prints '1'
9console.log(engine.materials.count) // Prints '1'

glTF extensions 

Instantiating a prefab loaded from a .glb automatically retargets the extensions to the created hierarchy:

1const gltf = await engine.loadGLTF({url: 'Model.glb', extensions: true});
2const {root, extensions} = engine.scene.instantiate(gltf);
3
4// Retrieve Object3D instance from extension nodes list
5for (const key in extensions.node) {
6    const object3d = engine.scene.wrap(extensions.node[key]);
7}

Returns: An object containing the instantiated root Object3D. When a glTF is instantiated, the result can contain extra metadata. For more information, have a look at the InstantiateResult type.

.load(options: string | SceneLoadOptions) ⇒ Promise<Scene> 

Load a scene file (.bin).

Will replace the currently active scene with the one loaded from given file. It is assumed that JavaScript components required by the new scene were registered in advance.

Once the scene is loaded successfully and initialized, onSceneLoaded is notified.

ArrayBuffer 

The load() method accepts an in-memory buffer:

1scene.load({
2    buffer: new ArrayBuffer(...),
3    baseURL: 'https://my-website/assets'
4})

Note: The baseURL is mandatory. It’s used to fetch images and languages.

Use setLoadingProgress to update the loading progress bar when using an ArrayBuffer.

Deprecated: Use the new loadMainScene API.

Returns: Promise that resolves when the scene was loaded.

.rayCast(o: Readonly<NumberArray>, d: Readonly<NumberArray>, groupMask: number, maxDistance: number) ⇒ RayHit 

Cast a ray through the scene and find intersecting collision components.

The resulting ray hit will contain up to 4 closest ray hits, sorted by increasing distance.

Example:

 1const hit = engine.scene.rayCast(
 2    [0, 0, 0],
 3    [0, 0, 1],
 4    1 << 0 | 1 << 4, // Only check against components in groups 0 and 4
 5    25
 6);
 7if (hit.hitCount > 0) {
 8    const locations = hit.getLocations();
 9    console.log(`Object hit at: ${locations[0][0]}, ${locations[0][1]}, ${locations[0][2]}`);
10}

Returns: The RayHit instance, cached by this class.

Note: The returned RayHit object is owned by the Scene instance and will be reused with the next rayCast call.

.reset() ⇒ void 

Reset the scene.

This method deletes all used and allocated objects, and components.

Deprecated: Load a new scene and activate it instead.

.setLoadingProgress(percentage: number) ⇒ void 

Update the loading screen progress bar.

Deprecated: Use setLoadingProgress.