Skip to content

Babylon.js plugin

Documentation of the babylon.js plugin. Study the demos for practical examples.

Since: 0.3.0

Basics

Lifecycle

The following diagram shows, in a simplified manner, the lifecycle of an AR experience. The rectangular blocks represent methods of your ARDemo. Function encantar starts the magic.

Lifecycle of an AR experience

Tip

Use event listeners to detect events such as finding an image in a camera feed.

encantar

encantar(demo: ARDemo): Promise<ARSystem>

The encantar function enchants a demo, meaning: it starts the lifecycle of the AR experience.

Arguments

  • demo: ARDemo. Your demo. See also: ARDemo

Returns

A promise that resolves to an ARSystem when the demo starts.

Example

function main()
{
    const demo = new MyDemo(); // class MyDemo extends ARDemo

    encantar(demo).catch(error => {
        alert(error.message);
    });
}

document.addEventListener('DOMContentLoaded', main);

Note

You should not call session.requestAnimationFrame() when using this plugin. The plugin already calls it.

ARDemo

ARDemo is the base class for Augmented Reality experiences. It's an abstract class, meaning that you must extend it. It operates within the lifecycle of your AR experience. The plugin will call its methods and control the flow of the program. Simply call encantar to start the magic!

ar

demo.ar: ARSystem | null, read-only

A reference to the ARSystem, or null if the demo hasn't been started yet. See also: lifecycle

Since: 0.4.0

startSession

demo.startSession(): Promise<Session> | SpeedyPromise<Session>

Start the AR Session. This method receives no arguments. It's supposed to call AR.startSession with the desired settings.

Returns

A promise that resolves to a Session.

Important

This is an abstract method. You must implement it.

Fact

The tracking begins when the session is started.

init

demo.init(): void | Promise<void> | SpeedyPromise<void>

Use this method to initialize your 3D scene. See also: ar, preload

Returns

undefined, or a promise that resolves to undefined.

Example

class MyDemo extends ARDemo
{
    // ...

    init()
    {
        const ar = this.ar;
        const scene = ar.scene;

        // initialize the scene
        // ...
    }

    // ...
}

Tip

Load external assets in preload. Method init shouldn't take too long to run because the session is already started. See also: lifecycle

update

demo.update(): void

Animation step, called during the animation loop. You may want to do something with ar.session or ar.frame.

Example

class MyDemo extends ARDemo
{
    // ...

    update()
    {
        const ar = this.ar;
        const session = ar.session;
        const deltaTime = session.time.delta; // given in seconds

        // ...
    }

    // ...
}

release

release(): void

Release resources soon after the AR session is ended.

preload

preload(): Promise<void> | SpeedyPromise<void>

Preload resources before starting the AR session. See also: init, startSession

Since: 0.4.0

Returns

A promise that resolves to undefined.

ARSystem

ARSystem is a helper for creating Augmented Reality experiences. Access it via ARDemo.ar.

session

ar.session: Session, read-only

A reference to the AR Session.

frame

ar.frame: Frame | null, read-only

A reference to the current Frame. This will be null if the demo hasn't been started yet, or if the session has been ended. See also: lifecycle

viewer

ar.viewer: Viewer | null, read-only

A reference to the Viewer. This will be null if the frame is null.

Since: 0.4.0

pointers

ar.pointers: TrackablePointer[], read-only

An array of TrackablePointers.

Since: 0.4.0

Tip

Make sure to add a PointerTracker to your session in order to use these.

root

ar.root: BABYLON.TransformNode, read-only

A node that is automatically aligned to the physical scene.

Important

In most cases, objects of your virtual scene should be descendants of this node!

camera

ar.camera: BABYLON.Camera, read-only

A camera that is automatically adjusted for AR.

scene

ar.scene: BABYLON.Scene, read-only

The babylon.js scene.

engine

ar.engine: BABYLON.Engine, read-only

The babylon.js engine.

utils

ar.utils: ARUtils, read-only

Utilities object.

Since: 0.4.0

ARUtils

Utilities object.

convertVector2

ar.utils.convertVector2(v: Vector2): BABYLON.Vector2

Convert a Vector2 into a BABYLON.Vector2.

Since: 0.4.0

Arguments

  • v: Vector2. A 2D vector.

Returns

A corresponding BABYLON.Vector2.

convertVector3

ar.utils.convertVector3(v: Vector3): BABYLON.Vector3

Convert a Vector3 into a BABYLON.Vector3.

Since: 0.4.0

Arguments

  • v: Vector3. A 3D vector.

Returns

A corresponding BABYLON.Vector3.

convertQuaternion

ar.utils.convertQuaternion(q: Quaternion): BABYLON.Quaternion

Convert a Quaternion into a BABYLON.Quaternion.

Since: 0.4.0

Arguments

  • q: Quaternion. A quaternion.

Returns

A corresponding BABYLON.Quaternion.

convertRay

ar.utils.convertRay(r: Ray): BABYLON.Ray

Convert a Ray into a BABYLON.Ray.

Since: 0.4.0

Arguments

  • r: Ray. A ray.

Returns

A corresponding BABYLON.Ray.