WonderlandEngine API reference

Main Wonderland Engine instance.

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

.arSupported: boolean 

Whether AR is supported by the browser.

.erasePrototypeOnDestroy: boolean 


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


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


Components will also be affected:

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

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    }

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

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

.i18n: I18N 

Access to internationalization.

.onResize: Emitter<void[]> 

Emitter for canvas / main framebuffer resize events.

Usage from a within a component:

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

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

.onSceneLoaded: Emitter<void[]> 

Emitter for scene loaded events.

Listeners get notified when a call to () finishes, which also happens after the main scene has replaced the loading screen.

Usage from a within a component:

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

.onXRSessionEnd: Emitter<void[]> 

Emitter for WebXR session end events.

Usage from a within a component:

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

.onXRSessionStart: Emitter<[XRSession, XRSessionMode]> 

Emitter for WebXR session start events.

Usage from a 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.

.scene: Scene 

Current main scene.

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


.canvas: HTMLCanvasElement 

Canvas element that Wonderland Engine renders to.

.physics: null | Physics 

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

.runtimeVersion: Version 

Retrieves the runtime version.

.textures: TextureManager 

Texture managger.

Use this to load or programmatically create new textures at runtime.

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


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

typeOrClassstring | ComponentConstructor<Component>A string representing the component typename (e.g., 'cursor-component'), or a component class (e.g., CursorComponent).

.nextFrame(fixedDelta: number) ⇒ void 

Run the next frame.

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

fixedDeltanumberThe elapsed time between this frame and the previous one.

.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';
 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() {}
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.
classesComponentConstructor<Component>[]Custom component(s) extending Component.

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

Request a 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.

modeXRSessionModeThe XR mode.
featuresstring[]An array of required features, e.g., ['local-floor', 'hit-test'].
optionalFeaturesstring[]An array of optional features, e.g., ['bounded-floor', 'depth-sensing'].

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

widthnumberThe width, in CSS pixels.
heightnumberThe height, in CSS pixels.
devicePixelRationumberThe pixel ratio factor.

.start() ⇒ void 

Start the engine if it’s not already running.

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

.wrapObject(objectId: number) ⇒ Object3D 

Wrap an object ID using Object.

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

Returns: The object

objectIdnumberID of the object to create.