Listening events

Listen to pointer and keyboard events in attached scripts with @onPointerEvent and @onKeyboardEvent.

Introduction

The editor provides some helpers for listening events in the scene. Those helpers are provided as decorators and can be used in any attached script in the scene.

Each decorator can be used to decorate a method in the class. Method that will be called each time an event of the provided type(s) is raised in the scene.

Package dependency

Those decorators are available in the babylonjs-editor-tools package that is provided as a dependency in the package.json file. In case a decorator that is documented here is not available in the code, make sure to install the up-to-date package in your project.

@onPointerEvent

When a method is decorated with @onPointerEvent, this method will be called each time the provided pointer event type(s) is raised in the scene:

typescript

import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { PointerEventTypes } from "@babylonjs/core/Events/pointerEvents";

import { onPointerEvent } from "babylonjs-editor-tools";

export default class MyMeshComponent {
    public constructor(public mesh: Mesh) { }

    @onPointerEvent(PointerEventTypes.POINTERTAP)
    public pointerTap(): void {
        console.log("A pointer tap has been raised in the scene!");
    }
}

Multiple event types can be listened at the same time by providing an array of event types to the decorator.
The decorated method always receives a parameter of type PointerInfo that contains more information about the event that has been raised.

typescript

import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { PointerEventTypes, PointerInfo } from "@babylonjs/core/Events/pointerEvents";

import { onPointerEvent } from "babylonjs-editor-tools";

export default class MyMeshComponent {
    public constructor(public mesh: Mesh) { }

    @onPointerEvent([
        PointerEventTypes.POINTERTAP,
        PointerEventTypes.POINTERDOUBLETAP
    ])
    public pointerTap(info: PointerInfo): void {
        console.log("A pointer tap has been raised in the scene!", info.type);
    }
}

Filtering per mesh

By default, the @onPointerEvent decorator listens for global events. In other words, anywhere the pointer event is raised in the scene, the decorated method will be called.

Scripts that are attached to meshes (extending AbstractMesh class) can listen for events that are raised only on the attached mesh by changing the listening mode.

Meshes only

The following mode is only available for scripts attached to meshes. If the attached object is not a Mesh then an error will be thrown at runtime when loading the scene.

typescript

import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { PointerEventTypes } from "@babylonjs/core/Events/pointerEvents";

import { onPointerEvent } from "babylonjs-editor-tools";

export default class MyMeshComponent {
    public constructor(public mesh: Mesh) { }

    /**
     * Listen for double tap event only if the mesh over the pointer is the attached mesh of this script.
     */
    @onPointerEvent(PointerEventTypes.POINTERTAP, {
        mode: "attachedMeshOnly"
    })
    public pointerTap(): void {
        console.log("The attached mesh has been tapped!", this.mesh.name);
    }
}

Including descendants

When importing meshes, from a GLB file for example, it can be useful to listen for events on the entire hierarchy of imported meshes. Especially when the imported hierarchy is complex and contains multiple meshes.

To do so, the listening mode can be set to includeDescendants and the decorated method will be called when the event is raised on the attached mesh or any of its descendants.

That way, this mode is available on any node (TransformNode, Light, etc.) the script is attached to and is not limited to meshes only like the mode attachedMeshOnly.

typescript

import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { PointerEventTypes, PointerInfo } from "@babylonjs/core/Events/pointerEvents";

import { onPointerEvent } from "babylonjs-editor-tools";

export default class MyMeshComponent {
    public constructor(public mesh: Mesh) { }

    /**
     * Listen for double tap event only if the mesh over the pointer is the attached mesh of this script.
     */
    @onPointerEvent(PointerEventTypes.POINTERTAP, {
        mode: "includeDescendants"
    })
    public pointerTap(info: PointerInfo): void {
        console.log("The attached mesh or one of its descendants has been tapped!", this.mesh.name);
    }
}

@onKeyboardEvent

As well as the @onPointerEvent decorator, the editor provides a @onKeyboardEvent decorator that can be used to listen for keyboard events in the scene.

When a method is decorated with @onKeyboardEvent, this method will be called each time the provided keyboard event type(s) is raised in the scene:

typescript

import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { KeyboardEventTypes, KeyboardInfo } from "@babylonjs/core/Events/keyboardEvents";

import { onKeyboardEvent } from "babylonjs-editor-tools";

export default class MyMeshComponent {
    public constructor(public mesh: Mesh) { }

    @onKeyboardEvent(KeyboardEventTypes.KEYDOWN)
    public keyDown(info: KeyboardInfo): void {
        console.log("A key down event has been raised in the scene!", info.event.key);
    }
}

As well as for pointer events, multiple event types can be listened at the same time by providing an array of event types to the decorator:

typescript

import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { KeyboardEventTypes, KeyboardInfo } from "@babylonjs/core/Events/keyboardEvents";

import { onKeyboardEvent } from "babylonjs-editor-tools";

export default class MyMeshComponent {
    public constructor(public mesh: Mesh) { }

    @onKeyboardEvent([
        KeyboardEventTypes.KEYUP,
        KeyboardEventTypes.KEYDOWN
    ])
    public keyDown(info: KeyboardInfo): void {
        console.log("A key down event has been raised in the scene!", info.type, " with key: ", info.event.key);
    }
}

Customizing scripts

Linking assets