WonderlandEngine

Main Wonderland Engine instance.

Controls the canvas, rendering, and JS <-> WASM communication.

• WonderlandEngine
  • .arSupported: boolean
  • .erasePrototypeOnDestroy: boolean
  • .i18n: I18N
  • .legacyMaterialSupport: boolean
  • .onLoadingScreenEnd: RetainEmitter<void[]>
  • .onResize: Emitter<void[]>
  • .onSceneActivated: Emitter<[Scene, Scene]>
  • .onSceneLoaded: Emitter<void[]>
  • .onXRSessionEnd: Emitter<void[]>
  • .onXRSessionStart: Emitter<[XRSession, XRSessionMode]>
  • .vrSupported: boolean
  • .xr: null | XR
  • .autoResizeCanvas
  • .canvas
  • .fonts
  • .images
  • .imagesPromise
  • .log
  • .materials
  • .meshes
  • .morphTargets
  • .physics
  • .runtimeVersion
  • .scene
  • .textures
  • .xrBaseLayer
  • .xrFrame
  • .xrFramebuffer
  • .xrFramebufferScaleFactor
  • .xrSession
  • .isRegistered(typeOrClass) ⇒ boolean
  • .loadGLTF(opts, progress) ⇒ Promise<PrefabGLTF>
  • .loadGLTFFromBuffer(options) ⇒ PrefabGLTF
  • .loadMainScene(opts, progress) ⇒ Promise<Scene>
  • .loadMainSceneFromBuffer(options) ⇒ Promise<Scene>
  • .loadPrefab(opts, progress) ⇒ Promise<Prefab>
  • .loadPrefabFromBuffer(options) ⇒ Prefab
  • .loadScene(opts, progress) ⇒ Promise<Scene>
  • .loadSceneFromBuffer(options) ⇒ Scene
  • .nextFrame(fixedDelta) ⇒ void
  • .offerXRSession(mode, features, optionalFeatures) ⇒ Promise<XRSession>
  • .registerComponent(…classes) ⇒ void
  • .requestXRSession(mode, features, optionalFeatures) ⇒ Promise<XRSession>
  • .resize(width, height, devicePixelRatio) ⇒ void
  • .setLoadingProgress(percentage) ⇒ void
  • .start() ⇒ void
  • .switchTo(scene, opts) ⇒ Promise<void>
  • .toString() ⇒ string
  • .wrapObject(objectId) ⇒ Object3D

.arSupported: boolean 

Whether AR is supported by the browser.

.erasePrototypeOnDestroy: boolean 

If true, Texture, Object3D, and Component instances have their prototype erased upon destruction.

Object 

1engine.erasePrototypeOnDestroy = true;
2
3const obj = engine.scene.addObject();
4obj.name = 'iamalive';
5console.log(obj.name); // Prints 'iamalive'
6
7obj.destroy();
8console.log(obj.name); // Throws an error

Component 

Components will also be affected:

 1class MyComponent extends Component {
 2    static TypeName = 'my-component';
 3    static Properties = {
 4        alive: Property.bool(true)
 5    };
 6
 7    start() {
 8        this.destroy();
 9        console.log(this.alive) // Throws an error
10    }
11}

A component is also destroyed if its ancestor gets destroyed:

1class MyComponent extends Component {
2    ...
3    start() {
4        this.object.parent.destroy();
5        console.log(this.alive) // Throws an error
6    }
7}

Note: Native components will not be erased if destroyed via object destruction:

1const mesh = obj.addComponent('mesh');
2obj.destroy();
3console.log(mesh.active) // Doesn't throw even if the mesh is destroyed

.i18n: I18N 

Access to internationalization.

.legacyMaterialSupport: boolean 

If true, the materials will be wrapped in a proxy to support pre-1.2.0 material access, i.e.,

1const material = new Material(engine, 'Phong Opaque');
2material.diffuseColor = [1.0, 0.0, 0.0, 1.0];

If false, property accessors will not be available and material properties should be accessed via methods, i.e.,

1const PhongOpaque = engine.materials.getTemplate('Phong Opaque');
2const material = new PhongOpaque();
3material.setDiffuseColor([1.0, 0.0, 0.0, 1.0]);
4...
5const diffuse = material.getDiffuseColor();

When disabled, reading/writing to materials is slightly more efficient on the CPU.

.onLoadingScreenEnd: RetainEmitter<void[]> 

RetainEmitter signalling the end of the loading screen.

Listeners get notified when the first call to () is invoked. At this point the new scene has not become active, and none of its resources or components are initialized.

Compared to onSceneLoaded, this does not wait for all components to be fully initialized and activated. Any handler added inside (), () or () will be called immediately.

Usage:

1this.engine.onLoadingScreenEnd.add(() => console.log("Wait is over!"));

.onResize: Emitter<void[]> 

Emitter for canvas / main framebuffer resize events.

Usage from within a component:

1this.engine.onResize.add(() => {
2    const canvas = this.engine.canvas;
3    console.log(`New Size: ${canvas.width}, ${canvas.height}`);
4});

Note: The size of the canvas is in physical pixels, and is set via resize.

.onSceneActivated: Emitter<[Scene, Scene]> 

Emitter for scene activated events.

This listener is notified with the old scene as first parameter, and the new scene as second.

This listener is notified after all resources are loaded and all components had their () as well as (if active) () and () methods called.

Usage from within a component:

1this.engine.onSceneActivated.add((oldScene, newScene) => {
2    console.log(`Scene switch from ${oldScene.filename} to ${newScene.filename}`);
3});

.onSceneLoaded: Emitter<void[]> 

Emitter for scene loaded events.

Listeners get notified when a call to () finishes. At this point all resources are loaded and all components had their () as well as (if active) () and () methods called.

Usage from within a component:

1this.engine.onSceneLoaded.add(() => console.log("Scene switched!"));

Deprecated: Use onSceneActivated instead.

.onXRSessionEnd: Emitter<void[]> 

Emitter for WebXR session end events.

Usage from within a component:

1this.engine.onXRSessionEnd.add(() => console.log("XR session ended."));

.onXRSessionStart: Emitter<[XRSession, XRSessionMode]> 

RetainEmitter for WebXR session start events.

Usage from within a component:

1this.engine.onXRSessionStart.add((session, mode) => console.log(session, mode));

By default, this emitter is retained and will automatically call any callback added while a session is already started:

1// XR session is already active.
2this.engine.onXRSessionStart.add((session, mode) => {
3    console.log(session, mode); // Triggered immediately.
4});

.vrSupported: boolean 

Whether VR is supported by the browser.

.xr: null | XR 

WebXR related state, null if no XR session is active.

.autoResizeCanvas: boolean 

true if the canvas is automatically resized by the engine.

.autoResizeCanvas 

.canvas: HTMLCanvasElement 

Canvas element that Wonderland Engine renders to.

.fonts: ResourceManager<Font> 

Font resources

.images: ImageLike[] 

Get all uncompressed images.

.imagesPromise: Promise<ImageLike[]> 

Promise that resolve once all uncompressed images are loaded.

This is equivalent to calling images, and wrapping each load listener into a promise.

.log: Logger 

Engine Logger. Use it to turn on / off logging.

.materials: MaterialManager 

Material resources

.meshes: MeshManager 

Mesh resources

.morphTargets: ResourceManager<MorphTargets> 

Morph target set resources

.physics: null | Physics 

Physics manager, only available when physx is enabled in the runtime.

.runtimeVersion: Version 

Retrieves the runtime version.

.scene: Scene 

Currently active scene.

.textures: TextureManager 

Texture resources

.xrBaseLayer: null | XRProjectionLayer 

Current WebXR base layer or null if no session active.

Deprecated: Use baseLayer on the xr object instead.

.xrFrame: null | XRFrame 

Current WebXR frame or null if no session active.

Deprecated: Use frame on the xr object instead.

.xrFramebuffer: null | WebGLFramebuffer 

Current WebXR framebuffer or null if no session active.

Deprecated: Use framebuffers on the xr object instead.

.xrFramebufferScaleFactor: number 

Framebuffer scale factor.

.xrFramebufferScaleFactor 

.xrSession: null | XRSession 

Current WebXR session or null if no session active.

Deprecated: Use session on the xr object instead.

.isRegistered(typeOrClass: string | ComponentConstructor<Component>) ⇒ boolean 

Checks whether the given component is registered or not.

Returns: true if the component is registered, false otherwise.

.loadGLTF(opts: Object, progress: ProgressCallback) ⇒ Promise<PrefabGLTF> 

Create a glTF scene from a URL.

Note: This method is a wrapper around loadGLTFFromBuffer.

Returns: A new loaded PrefabGLTF.

.loadGLTFFromBuffer(options: InMemoryLoadOptions & GLTFOptions) ⇒ PrefabGLTF 

Similar to loadGLTF, but loading is done from an ArrayBuffer.

Returns: A new loaded PrefabGLTF.

.loadMainScene(opts: Object, progress: ProgressCallback) ⇒ Promise<Scene> 

Load the scene from a URL, as the main scene of a new Scene.

Usage 

1// The method returns the main scene
2const scene = await engine.loadMainScene();

Destruction 

Loading a new main scene entirely resets the state of the engine, and destroys:

• All loaded scenes, prefabs, and gltf files
• Meshes
• Textures
• Materials

Note: This method can only load Wonderland Engine .bin files.

Returns: The main scene of the new Scene.

.loadMainSceneFromBuffer(options: InMemoryLoadOptions & ActivateOptions) ⇒ Promise<Scene> 

Similar to loadMainScene, but loading is done from an ArrayBuffer.

Returns: The main scene of the new Scene.

.loadPrefab(opts: LoadOptions, progress: ProgressCallback) ⇒ Promise<Prefab> 

Load a Prefab from a URL.

Usage 

1const prefab = await engine.loadPrefab('Prefab.bin');

Note: This method can only load Wonderland Engine .bin files.

Note: This method is a wrapper around loadPrefabFromBuffer.

Returns: The loaded Prefab.

.loadPrefabFromBuffer(options: InMemoryLoadOptions) ⇒ Prefab 

Similar to loadPrefab, but loading is done from an ArrayBuffer.

Returns: A new loaded Prefab.

.loadScene(opts: LoadOptions, progress: ProgressCallback) ⇒ Promise<Scene> 

Load a scene from a URL.

At the opposite of loadMainScene, the scene loaded will be added to the list of existing scenes, and its resources will be made available for other scenes/prefabs/gltf to use.

Resources Sharing 

Upon loading, the scene resources are added in the engine, and references to those resources are updated.

It’s impossible for a scene loaded with this method to import pipelines. Thus, the loaded scene will reference existing pipelines in the main scene, based on their names.

Usage 

1const scene = await engine.loadScene('Scene.bin');

Note: This method can only load Wonderland Engine .bin files.

Note: This method is a wrapper around loadSceneFromBuffer.

Returns: A new loaded Scene.

.loadSceneFromBuffer(options: InMemoryLoadOptions) ⇒ Scene 

Similar to loadScene, but loading is done from an ArrayBuffer.

Throws: If the scene is streamable.

Returns: A new loaded Scene.

.nextFrame(fixedDelta: number) ⇒ void 

Run the next frame.

Note: The engine automatically schedules next frames. You should only use this method for testing.

.offerXRSession(mode: XRSessionMode, features: string[], optionalFeatures: string[]) ⇒ Promise<XRSession> 

Offer an XR session.

Adds an interactive UI element to the browser interface to start an XR session. Browser support is optional, so it’s advised to still allow requesting a session with a UI element on the website itself.

Note: Please use this call instead of directly calling navigator.xr.offerSession(). Wonderland Engine requires to be aware that a session is started, and this is done through this call.

Returns: A promise resolving with the XRSession, a string error message otherwise.

.registerComponent(…classes: ComponentConstructor<Component>[][]) ⇒ void 

Register a custom JavaScript component type.

You can register a component directly using a class inheriting from Component:

 1import { Component, Type } from '@wonderlandengine/api';
 2
 3export class MyComponent extends Component {
 4    static TypeName = 'my-component';
 5    static Properties = {
 6        myParam: {type: Type.Float, default: 42.0},
 7    };
 8    init() {}
 9    start() {}
10    update(dt) {}
11    onActivate() {}
12    onDeactivate() {}
13    onDestroy() {}
14});
15
16// Here, we assume we have an engine already instantiated.
17// In general, the registration occurs in the `index.js` file in your
18// final application.
19engine.registerComponent(MyComponent);

.requestXRSession(mode: XRSessionMode, features: string[], optionalFeatures: string[]) ⇒ Promise<XRSession> 

Request an XR session.

Note: Please use this call instead of directly calling navigator.xr.requestSession(). Wonderland Engine requires to be aware that a session is started, and this is done through this call.

Returns: A promise resolving with the XRSession, a string error message otherwise.

.resize(width: number, height: number, devicePixelRatio: number) ⇒ void 

Resize the canvas and the rendering context.

Note: The width and height parameters will be scaled by the devicePixelRatio value. By default, the pixel ratio used is window.devicePixelRatio.

.setLoadingProgress(percentage: number) ⇒ void 

Update the loading screen progress bar.

.start() ⇒ void 

Start the engine if it’s not already running.

When using the loadRuntime function, this method is called automatically.

.switchTo(scene: Scene, opts: ActivateOptions) ⇒ Promise<void> 

Switch the current active scene.

Once active, the scene will be updated and rendered on the canvas.

The currently active scene is accessed via scene:

1import {Component} from '@wonderlandengine/api';
2
3class MyComponent extends Component{
4    start() {
5        console.log(this.scene === this.engine.scene); // Prints `true`
6    }
7}

Note: This method will throw if the scene isn’t activatable.

Component Lifecycle 

Marking a scene as active will:

• Call onDeactivate for all active components of the previous scene
• Call onActivate for all active components of the new scene

Usage 

1const scene = await engine.loadScene('Scene.bin');
2engine.switchTo(scene);

Returns: A promise that resolves once the scene is ready.

.toString() ⇒ string 

.wrapObject(objectId: number) ⇒ Object3D 

Wrap an object ID using Object.

Note: This method performs caching and will return the same instance on subsequent calls.

Deprecated: Use wrap instead.

Returns: The object