Actions

In Babylon.js, Actions are a powerful feature within the events system that allow you to define specific behaviors or responses to user interactions or other triggers in the scene. Actions are used to create interactive, dynamic experiences, such as animating objects, changing properties, or triggering events when certain conditions are met. Actions are typically registered on Babylon.js nodes and are executed when specific triggers occur, such as a mouse click, a keyboard input, or an intersection between objects.

Scene Triggers

In Babylon.js there are 3 triggers for a scene:

TYPE	DESCRIPTION
`OnEveryFrameTrigger`	Raised once per frame.
`OnKeyDownTrigger`	Raised when a key is pressed.
`OnKeyUpTrigger`	Raised when a key is released.

In the example below, two actions are triggered within the scene. To observe them in action, open the Developer Console, click anywhere in the scene, and then press a random key on your keyboard.

const scene = useScene();
 
useEffect(() => {
    scene.actionManager = new ActionManager();
    scene.actionManager.registerAction(
        new ExecuteCodeAction({ trigger: ActionManager.OnKeyUpTrigger },
            event => console.log(`${event.sourceEvent.key} was released.`),
        ),
    );
    scene.actionManager.registerAction(
        new ExecuteCodeAction({ trigger: ActionManager.OnKeyDownTrigger },
            event => console.log(`${event.sourceEvent.key} was pressed.`),
        ),
    );
}, []);

Meshes Triggers

There are also 14 triggers for the meshes:

TYPE	PROP	DESCRIPTION
`NothingTrigger`	/	Never raised. Used for sub-actions with action.then function.
`OnPickTrigger`	`onPick`	Raised when the user touches/clicks on a mesh.
`OnDoublePickTrigger`	`onDoublePick`	Raised when the user double touches/clicks on a mesh.
`OnPickDownTrigger`	`onPickDown`	Raised when the user touches/clicks down on a mesh
`OnPickUpTrigger`	`onPickUp`	Raised when the user touches/clicks up on a mesh.
`OnPickOutTrigger`	`onPickOut`	Raised when the user touches/clicks down on a mesh and then move off-of the mesh.
`OnLeftPickTrigger`	`onLeftPick`	Raised when the user touches/clicks on a mesh with left button.
`OnRightPickTrigger`	`onRightPick`	Raised when the user touches/clicks on a mesh with right button.
`OnCenterPickTrigger`	`onCenterPick`	Raised when the user touches/clicks on a mesh with center button.
`OnLongPressTrigger`	`onLongPress`	Raised when the user touches/clicks up on a mesh for a long period of time in milliseconds (defined by BABYLON.Scene.LongPressDelay).
`OnPointerOverTrigger`	`onPointerOver`	Raised when the pointer is over a mesh. Raised just once - Warning: if you set AbstractMesh.pointerOverDisableMeshTesting to true, this trigger will be triggered every time you move the mouse and you are still over the mesh!
`OnPointerOutTrigger`	`onPointerOut`	Raised when the pointer is no more over a mesh. Raised just once.
`OnIntersectionEnterTrigger`	`onIntersectionEnter`	Raised when the mesh is in intersection with a specific mesh. Raised just once.
`OnIntersectionExitTrigger`	`onIntersectionExit`	Raised when the mesh is no more in intersection with a specific mesh. Raised just once.

Reactylon provides an abstraction layer over Babylon.js triggers, simplifying event handling for 3D meshes within a React-like framework. It automatically maps these props to Babylon.js triggers behind the scenes. Developers interact with the simpler Reactylon props, while Babylon.js triggers handle the actual event flow.

How It Works:

Reactylon props: these are the high-level props that are exposed to developers in Reactylon. They are camelCased versions of the Babylon.js trigger names, with the “Trigger” suffix removed, making it easier to work with them in a React-like syntax.
Babylon.js triggers: these are the low-level events raised by Babylon.js when a user interacts with a mesh.

In the following example, several actions are attached to the sphere. To observe them in action, open the Developer Console and interact with the sphere by clicking on it. As you do, you’ll see the box move to the left. When the box intersects with the sphere, the actions onIntersectionEnter and onIntersectionExit will be triggered in sequence. Afterward, executing other actions on the sphere will result in additional behaviors or effects being triggered.

const scene = useScene();
 
function handlePick(){
    console.log('onPick');
    function rotation() {
        boxRef.current!.position.x -= 0.01 * scene.getAnimationRatio();
        if (boxRef.current!.position.x < -2) {
            scene.unregisterBeforeRender(rotation);
        }
    }
    scene.registerBeforeRender(rotation);
}
 
// ...
 
return (
    <>
        <box name='box' ref={boxRef} positionX={2} />
        <sphere
            name='sphere'
            onPick={handlePick}
            onPointerOver={() => console.log('onPointerOver')}
            onPointerOut={() => console.log('onPointerOut')}
            onPickDown={() => console.log('onPickDown')}
            onPickUp={() => console.log('onPickUp')}
            onDoublePick={() => console.log('onDoublePick')}
            onPickOut={() => console.log('onPickOut')}
            onLeftPick={() => console.log('onLeftPick')}
            onRightPick={() => console.log('onRightPick')}
            onCenterPick={() => console.log('onCenterPick')}
            onLongPress={() => console.log('onLongPress')}
            onIntersectionEnter={() => console.log('onIntersectionEnter')}
            onIntersectionExit={() => console.log('onIntersectionExit')}
            intersectionMeshId='box'
        />
    </>
);

Check out the Custom Props section to learn more about the intersectionMeshId property.

Learn More

For other actions and additional context, please refer to Babylon.js documentation: https://doc.babylonjs.com/features/featuresDeepDive/events/actions.

Animations Custom Loading Screen