
## How to use Actions

Actions are a simple way to add interactions in your scenes. An action is launched when its trigger is fired. For instance, you can specify that when the user clicks (or touches) a mesh, an action is executed.

To use actions, you have to attach a `BABYLON.ActionManager` to a mesh or to your scene:

```javascript
mesh.actionManager = new BABYLON.ActionManager(scene);
```

Once the ActionManager is created, you can start registering actions:

```javascript
mesh.actionManager.registerAction(new BABYLON.InterpolateValueAction(BABYLON.ActionManager.OnPickTrigger, light, "diffuse", BABYLON.Color3.Black(), 1000));
```

For instance, this action will animate the `light.diffuse` property to black in 1000ms when the user picks the mesh.

You can also chain actions:

```javascript
mesh.actionManager.registerAction(new BABYLON.InterpolateValueAction(BABYLON.ActionManager.OnPickTrigger, light, "diffuse", BABYLON.Color3.Black(), 1000)).then(new BABYLON.SetValueAction(BABYLON.ActionManager.NothingTrigger, mesh.material, "wireframe", false));
```

In this case, the first click will animate the `light.diffuse` property, and the second click will set `mesh.material.wireframe` to false.
The third click will start again and animate the `light.diffuse` property, and so on...

Finally, you can add a condition to your actions. In this case, actions are launched when the trigger is fired if the condition is true:

```javascript
mesh.actionManager.registerAction(
  new BABYLON.InterpolateValueAction(
    BABYLON.ActionManager.OnPickTrigger,
    camera,
    "alpha",
    0,
    500,
    new BABYLON.PredicateCondition(mesh.actionManager, function () {
      return light.diffuse.equals(BABYLON.Color3.Red());
    }),
  ),
);
```

In this example, the `camera.alpha` property will be animated to 0 in 500ms when the user clicks the mesh only if the `light.diffuse` property is equal to red.

## Triggers

Currently, there are 14 different triggers available for meshes, and three for scenes.

The triggers available for meshes are:

- `BABYLON.ActionManager.NothingTrigger`: Never raised. Used for sub-actions with the `action.then` function.
- `BABYLON.ActionManager.OnPickTrigger`: Raised when the user touches/clicks on a mesh.
- `BABYLON.ActionManager.OnDoublePickTrigger`: Raised when the user double touches/clicks on a mesh.
- `BABYLON.ActionManager.OnPickDownTrigger`: Raised when the user touches/clicks down on a mesh.
- `BABYLON.ActionManager.OnPickUpTrigger`: Raised when the user touches/clicks up on a mesh.
- `BABYLON.ActionManager.OnPickOutTrigger`: Raised when the user touches/clicks down on a mesh and then moves off the mesh.
- `BABYLON.ActionManager.OnLeftPickTrigger`: Raised when the user touches/clicks on a mesh with the left button.
- `BABYLON.ActionManager.OnRightPickTrigger`: Raised when the user touches/clicks on a mesh with the right button.
- `BABYLON.ActionManager.OnCenterPickTrigger`: Raised when the user touches/clicks on a mesh with the center button.
- `BABYLON.ActionManager.OnLongPressTrigger`: Raised when the user touches/clicks up on a mesh for a long period of time in milliseconds (defined by BABYLON.Scene.LongPressDelay).
- `BABYLON.ActionManager.OnPointerOverTrigger`: 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!
- `BABYLON.ActionManager.OnPointerOutTrigger`: Raised when the pointer is no longer over a mesh. Raised just once.
- `BABYLON.ActionManager.OnIntersectionEnterTrigger`: Raised when the mesh intersects with a specific mesh. Raised just once.
- `BABYLON.ActionManager.OnIntersectionExitTrigger`: Raised when the mesh no longer intersects with a specific mesh. Raised just once.

Note that the two intersection triggers require you to specify a specific mesh, which can be done like so:

```javascript
mesh.actionManager.registerAction(
  new BABYLON.SetValueAction(
    {
      trigger: BABYLON.ActionManager.OnIntersectionEnterTrigger,
      parameter: {
        mesh: otherMesh,
        usePreciseIntersection: true,
      },
    },
    mesh,
    "scaling",
    new BABYLON.Vector3(1.2, 1.2, 1.2),
  ),
);
```

Note the optional `usePreciseIntersection` property. If you don't want to use precise intersections, you can simply pass the mesh being targeted as the value of the parameter property:

```javascript
mesh.actionManager.registerAction(
  new BABYLON.SetValueAction(
    {
      trigger: BABYLON.ActionManager.OnIntersectionEnterTrigger,
      parameter: otherMesh,
    },
    mesh,
    "scaling",
    new BABYLON.Vector3(1.2, 1.2, 1.2),
  ),
);
```

The triggers available for scenes are:

- `BABYLON.ActionManager.OnEveryFrameTrigger`: Raised once per frame.
- `BABYLON.ActionManager.OnKeyDownTrigger`: Raised when a key is pressed.
- `BABYLON.ActionManager.OnKeyUpTrigger`: Raised when a key is released.

Both the OnKeyUpTrigger and OnKeyDownTrigger triggers accept a string parameter value, which is compared to the event's `sourceEvent.key` value.
This allows you to create key triggers that will only trigger on specific keys, like so:

```javascript
scene.actionManager.registerAction(
  new BABYLON.ExecuteCodeAction(
    {
      trigger: BABYLON.ActionManager.OnKeyUpTrigger,
      parameter: "r",
    },
    function () {
      console.log("r button was pressed");
    },
  ),
);
```

For more advanced use cases, you can pass a callback function as a parameter value (available since 5.47.0):

```javascript
scene.actionManager.registerAction(
  new BABYLON.ExecuteCodeAction(
    {
      trigger: BABYLON.ActionManager.OnKeyUpTrigger,
      parameter: function (actionEvent) {
        return actionEvent.sourceEvent.key === "R";
      },
    },
    function () {
      console.log("R button was pressed");
    },
  ),
);
```

## Available Actions

Most actions have a `propertyPath` property. This string defines the path to the property affected by the action.
You can use direct values like `position` or `diffuse`, but you can also provide complex paths like `position.x`.

- `BABYLON.SwitchBooleanAction(trigger, target, propertyPath, condition)`: Switches a boolean property.
- `BABYLON.SetValueAction(trigger, target, propertyPath, value, condition)`: Sets a direct value for a property.
- `BABYLON.IncrementValueAction(trigger, target, propertyPath, value, condition)`: Adds a number to a number property.
- `BABYLON.PlayAnimationAction(trigger, target, from, to, loop, condition)`: Plays an animation on a target.
- `BABYLON.StopAnimationAction(trigger, target, condition)`: Stops any animation being played by the target.
- `BABYLON.DoNothingAction(trigger, condition)`: Does nothing :)
- `BABYLON.CombineAction(trigger, children[], condition)`: Executes multiple actions simultaneously. The children property must be an array of actions.
- `BABYLON.ExecuteCodeAction(trigger, func, condition)`: Executes code.
- `BABYLON.SetParentAction(trigger, target, parent, condition)`: Sets the parent of the target.
- `BABYLON.PlaySoundAction(trigger, sound, condition)`: Plays a given sound.
- `BABYLON.StopSoundAction(trigger, sound, condition)`: Stops a given sound
- `BABYLON.InterpolateValueAction(trigger, target, propertyPath, value, duration, condition, stopOtherAnimations)`: Creates an animation to interpolate the current value of a property to a given target. The following types are supported:
  - `number`
  - `BABYLON.Color3`
  - `BABYLON.Vector3`
  - `BABYLON.Quaternion`

## Conditions

There are three kinds of conditions:

- `BABYLON.ValueCondition(actionManager, target, propertyPath, value, operator)`: true when the given property and value conform to the operator. The following operators are supported:
  - `BABYLON.ValueCondition.IsEqual`
  - `BABYLON.ValueCondition.IsDifferent`
  - `BABYLON.ValueCondition.IsGreater`
  - `BABYLON.ValueCondition.IsLesser`
- `BABYLON.PredicateCondition(actionManager, predicate)`: true when the given predicate function returns true.
- `BABYLON.StateCondition(actionManager, target, value)`: true when the `state` property of the target matches the given value.

## Experimenting with Actions

Imagine you want to almost hide a mesh when the user touches it.

First, you'd add a `BABYLON.ActionManager` to the mesh in question:

```javascript
mesh.actionManager = new BABYLON.ActionManager(scene);
```

Secondly, you'd register an action associated with the `BABYLON.ActionManager.OnPickTrigger` trigger.
This action will interpolate the `mesh.visibility` property to 0.2.

```javascript
mesh.actionManager.registerAction(new BABYLON.InterpolateValueAction(BABYLON.ActionManager.OnPickTrigger, mesh, "visibility", 0.2, 1000));
```

And you're done! Easy, right?

If, after fading out the mesh, you want it to fade back in, you can do so by chaining an action
to restore the `mesh.visibility` property to its default value:

```javascript
mesh.actionManager.registerAction(new BABYLON.InterpolateValueAction(BABYLON.ActionManager.OnPickTrigger, mesh, "visibility", 0.2, 1000)).then(new BABYLON.InterpolateValueAction(BABYLON.ActionManager.OnPickTrigger, mesh, "visibility", 1.0, 1000));
```

In this case, the first click will hide the mesh, the following click will restore it, and so on...

## Sprites

Starting with Babylon.js 2.3, sprites can have an action manager: <Playground id="#9RUHH#5" title="Sprite Action Manager" description="Simple example of a sprite with an attached action manager."/>

Please note that the SpriteManager must enable picking support by using `spriteManager.isPickable = true`.
Sprites can also control picking with `sprite.isPickable = false / true` (false by default).

## Playground

If you want to play with actions, you can try them out in our playground here: <Playground id="#J19GYK#0" title="Play with Actions" description="Simple examples of actions in a scene." image="/img/playgroundsAndNMEs/divingDeeperActions1.webp"/>



# Coroutines in Babylon.js

## Introduction

Babylon 5.0 brings with it a new way to write logic that runs over time:
coroutines!

Developers with experience using
[Unity 3D](https://docs.unity3d.com/Manual/Coroutines.html) and certain [native APIs](https://en.cppreference.com/w/cpp/language/coroutines) may already be familiar with some ideas and usages of coroutines. Broadly speaking, a coroutine is simply a function which can be paused and resumed.
In Babylon.js, we provide coroutine support through the `Observable` class to allow logic to be "spread" across multiple moments -- most commonly across multiple frames.

## Multi-frame Logic

Suppose you had a sequence of actions which were logically contiguous, but which you didn't want to all happen on the same frame. For example, suppose you want to spawn three meshes, but you don't want to spawn them all on the same frame and risk causing a frame hitch. Logically, then, what you want to do is something like the following:

- Spawn the first mesh.
- Wait until the next frame.
- Spawn the second mesh.
- Wait until the next frame.
- Spawn the third mesh.

Without coroutines, there are a number of varyingly-tricky things you could do to accomplish this with work queues, daisy-chained promises/callbacks, etc. With coroutines, however, you can do this pretty much by writing out the logic above directly.

```javascript
const spawnMeshesCoroutine = function* () {
  spawnTheFirstMesh();
  yield;
  spawnTheSecondMesh();
  yield;
  spawnTheThirdMesh();
};
scene.onBeforeRenderObservable.runCoroutineAsync(spawnMeshesCoroutine());
```

This coroutine will cause the logic of spawning the three meshes to be spread across three frames. If you run the above code on frame 100, for example, then `spawnTheFirstMesh` will be called on frame 100, `spawnTheSecondMesh` will be called on frame 101, and `spawnTheThirdMesh` will be called on frame 102. And, just like that, you've got logic running over multiple frames!

## How It Works

Babylon.js coroutines combine
[JavaScript generators](https://javascript.info/generators) with [`Observable`s](https://doc.babylonjs.com/divingDeeper/events/observables) to make it as easy as possible to spread logic across multiple frames.
At a high level, generator functions (an ES6 feature characterized by the `function*` syntax) don't return a simple return value object like traditional functions do. Instead, they return an intermediate object which allows the code inside the function to be run in "chunks," with the different chunks separated using the keyword `yield`. This intermediate object can then be invoked repeatedly, and each time it's invoked the generator function will "resume" from the last place it "paused" and keep going until it either gets to the next `yield` or reaches the end of the function.

This intermediate, repeatedly-invokable object is what `Observable.runCoroutineAsync` takes as an argument. The observable on which the coroutine is running will then invoke the generator -- causing another "chunk" of the coroutine's code to run -- every time that `Observable` itself is notified. This makes it very easy to write logic that "advances" every time a certain event monitored by an `Observable` occurs.

## Coroutines and Asynchronism

Coroutines are a clean and easy way to spread logic out over time, but they are not truly asynchronous in the same way as, for example, `Promise`s. Coroutines are polled per frame (or, more accurately, per `Observable`
notification), so they work very well for logic that happens densely -- for example, a logic sequence taking place over a series of consecutive frames. `Promise`s, by contrast, work very well for logic that happens
more sparsely -- network requests, file I/O, WebWorker calls, etc.
Coroutines and true asynchrony thus have separate but complementary strengths, so Babylon.js makes it easy to use a coroutine within a true async method and _vice versa_.

`Observable.runCoroutineAsync`, as the name implies, returns a `Promise<void>` which will either be resolved when the coroutine finishes or rejected if the coroutine is cancelled. This allows coroutines to be `await`ed as though they were true async functions. For example, the following code will print "Start", wait one second, print "A" and then "B" on back-to-back frames, then wait another second before printing "End".

```javascript
const coroutineFunc = function* () {
  console.log("A");
  yield;
  console.log("B");
};

const asynchronousFunc = async function () {
  console.log("Start");
  await BABYLON.Tools.DelayAsync(1000);
  await scene.onBeforeRenderObservable.runCoroutineAsync(coroutineFunc());
  await BABYLON.Tools.DelayAsync(1000);
  console.log("End");
};

asynchronousFunction();
```

Similarly, it's just as easy to pause a coroutine until a truly asynchronous function has completed. This is achieved using the `yield` keyword. The specifics are beyond the scope of this document, but `yield` can be thought of as an intermediate `return` command that pauses a generator function rather than terminating it. In Babylon.js coroutines, we typically use `yield` by itself to "return" nothing. The coroutine system will
interpret this as a command to pause the coroutine now and resume it the next time the `Observable` is notified. However, we can also `yield` a `Promise`:

```javascript
yield BABYLON.Tools.DelayAsync(1000);
```

When we `yield` a `Promise`, the coroutine system will again immediately pause the coroutine for now; however, it won't resume it until the first time the `Observable` is notified _after_ the yielded `Promise` has been resolved. Thus, yielding a `Promise` in a coroutine is very much like `await`ing a `Promise` in a true asynchronous function: it suspends execution of the function in question until the `Promise` is resolved.

```javascript
const asynchronousFunc = async function () {
  await BABYLON.Tools.DelayAsync(1000);
};

const coroutineFunc = function* () {
  console.log("A");
  yield;
  console.log("B");
  yield asynchronousFunc();
  console.log("C");
  yield;
  console.log("D");
};

scene.onBeforeRenderObservable.runCoroutineAsync(coroutineFunc());
```

This code snippet shows a coroutine `yield`ing a `Promise`; it will print "A" and "B" in back-to-back frames, then wait for one second, then print "C" and "D" in back-to-back frames.

## Advanced Usage

The examples above have all illustrated simple, linear, finite logic sequences, but coroutines are not confined to this. Coroutines can be infinite, branching, and arbitrarily complex. In fact, it is entirely possible to write an entire core logic loop using coroutines.

```javascript
const playGame = function* () {
  displayGameLogo();

  while (!enterKeyPressed() && !escapeKeyPressed()) {
    yield;
  }

  if (escapeKeyPressed()) {
    return;
  }

  yield loadTheSceneAsync();

  spawnTheFirstMesh();
  yield;
  spawnTheSecondMesh();
  yield;
  spawnTheThirdMesh();
  yield;

  while (!escapeKeyPressed()) {
    if (jumpButtonPressed()) {
      // 30 frame uninterruptable parametric jump animation
      const jump = function* () {
        for (let t = 0; t <= Math.PI; t += Math.PI / 30) {
          playerCharacter.y = Math.sin(t);
          yield;
        }
      };
      // Suspend game logic until jump animation is complete
      // (Nonsensical thing to do, just for demonstration purposes)
      yield scene.onBeforeRenderObservable.runCoroutineAsync(jump());
    }

    yield;
  }

  yield saveGameStateAsync();

  showGoodbyeMessage();
};
scene.onBeforeRenderObservable.runCoroutineAsync(playGame());
```



## How To Use Observables

For many of you creating Babylon.js projects, only [GUI](/features/featuresDeepDive/gui) and [scene](/features/featuresDeepDive/events/observables#scene-observables) Observables will be needed, particularly [scene.onPointerObservable](/features/featuresDeepDive/scene/interactWithScenes).

## Introduction

Babylon.js provides a lot of events (like scene.beforeRender), and before v2.4 there was no unified way to handle them.
Starting with v2.4, we introduced (without breaking backward compatibility of course) a new pattern: the Observables.

There are two parts: the [Observable](/typedoc/classes/babylon.observable) and the [Observer](/typedoc/classes/babylon.observer). The Observable is a property of an object that represents a given event (like beforeRender, for instance).
Users who want to run their own code in response to such an event will register an Observer with the appropriate Observable. Then it's the Observable's job to execute the Observers when appropriate.

The implementer uses an Observable to create a property that will trigger all registered observers. The generic type T is used to communicate a given data type from the Observable to the Observer.

Most users will simply add their own Observers to the Observables that Babylon.js provides. But it is also possible to create your own Observables (a simple example of which is below). For those who want to delve deeper, please see the [API](/typedoc/classes/babylon.observable).

- <Playground id="#6IGFM2" title="Simple Custom Observable Example" description="Simple example of using an observable in a scene." image="/img/playgroundsAndNMEs/divingDeeperObservable1.webp"/>
  An Observable, `onXChange`, is added to the master sphere. The two minion spheres and the actions they perform form the two Observers, which react when a change in the master's x position is observed.

## Observable Methods and Properties

The following are available:

- [add](/typedoc/classes/babylon.observable#add)(): to add an Observer
- [addOnce](/typedoc/classes/babylon.observable#addonce)(): to add an Observer which will be executed once and then removed
- [remove](/typedoc/classes/babylon.observable#remove)(): to remove a previously registered Observer
- [removeCallback](/typedoc/classes/babylon.observable#removecallback)(): same as above, but by giving the callback instead of the Observer instance
- [notifyObservers](/typedoc/classes/babylon.observable#notifyobservers)(): used to notify all registered Observers
- [notifyObserversWithPromise](/typedoc/classes/babylon.observable#notifyobserverswithpromise)(): calling this will execute each callback, expecting it to be a promise or return a value. If at any point in the chain one function fails, the promise will fail and execution will not continue.
- [hasObservers](/typedoc/classes/babylon.observable#hasobservers): a property that returns true if at least one Observer is registered
- [hasSpecificMask](/typedoc/classes/babylon.observable#hasspecificmask)(mask): a function that returns true if at least one Observer is registered with this mask
- [clear](/typedoc/classes/babylon.observable#clear)() to remove all Observers
- [clone](/typedoc/classes/babylon.observable#clone)() to simply clone the object but not the registered Observers.

The following static methods are available:

- [FromPromise](/typedoc/classes/babylon.observable#fromPromise)(): to create an Observable from a Promise.

Many Babylon.js objects have a range of available Observables. Here is an [unordered list](//doc.babylonjs.com/search/?bjsq=observable) from the Documentation search facility, with links to the API.

## Creating An Observable

It is not necessary to create a new Observable in order to add an Observer to an Observable that Babylon.js provides, but you may wish to create your own Observables. In particular, Observables can be very useful for connecting external libraries to Babylon.js:

```javascript
import { io } from "socket.io-client";

const socket = io("/admin");

const onConnectObservable = new Observable();
const text1 = new BABYLON.GUI.TextBlock();

socket.on("connect", () => {
  onConnectObservable.notifyObservers();
});

onConnectObservable.add(() => {
  text1.text = "Connected";
});
```

There is also a utility method `Observable.FromPromise` to create an Observable from a Promise:

```javascript
const onStatusObservable = Observable.FromPromise(axios("/ping").then((response) => response.statusText));

onStatusObservable.add((statusText) => {
  text1.text = "Server status: " + statusText;
});
```

Creating your own Observables can help reduce coupling between different components. Instead of a hierarchy of components depending on each other, you can create multiple independent components and then simply connect them using a single parent component.

## Add An Observer

An Observer consists of an object set to watch the Observable and the object's reaction to the observation.

In the following example, the sphere and its scale change create an Observer through the Observable.[add](/typedoc/classes/babylon.observable#add)() method.

Use the Observable that notifies its Observers before the scene starts rendering each frame.

```javascript
const alpha = 0;
scene.onBeforeRenderObservable.add(function () {
  sphere.scaling.y = Math.cos(alpha);

  alpha += 0.01;
});
```

- <Playground id="#UP2O8#0" title="Add an Observer" description="Simple example of how to add an observer to a scene." image="/img/playgroundsAndNMEs/divingDeeperObservable2.webp"/>

To remove an Observer, you need to store it during its creation so you can refer to it with remove. The following example removes the Observer before it is notified for even the first rendered frame.

```javascript
const alpha = 0;
const observer = scene.onBeforeRenderObservable.add(function () {
  sphere.scaling.y = Math.cos(alpha);

  alpha += 0.01;
});

scene.onBeforeRenderObservable.remove(observer);
```

- <Playground id="#UP2O8#1" title="Add and Remove an Observer" description="Simple example of how to add and remove an observer from a scene." image="/img/playgroundsAndNMEs/divingDeeperObservable3.webp"/>

The following example removes the Observer during the rendering cycle. Since it is not possible to remove an Observer that does not exist, you need to check whether the Observable still has that Observer.

```javascript
const alpha = 0;
const observer = scene.onBeforeRenderObservable.add(function () {
  sphere.scaling.y = Math.cos(alpha);

  alpha += 0.01;

  if (scene.onBeforeRenderObservable.hasObservers && alpha > 3) {
    scene.onBeforeRenderObservable.remove(observer);
  }
});
```

## Scene Observables

The Babylon.js Scene object has over 20 observables that 'fire' under various conditions. Most of them are checked on each frame/render in a deterministic order. Below is a list of Scene observables checked during each render loop, in the order they are checked:

- [onBeforeAnimationsObservable](/typedoc/classes/babylon.scene#onbeforeanimationsobservable)
- [onAfterAnimationsObservable](/typedoc/classes/babylon.scene#onafteranimationsobservable)
- [onBeforePhysicsObservable](/typedoc/classes/babylon.scene#onbeforephysicsobservable)
- [onAfterPhysicsObservable](/typedoc/classes/babylon.scene#onafterphysicsobservable)
- [onBeforeRenderObservable](/typedoc/classes/babylon.scene#onbeforerenderobservable)
- [onBeforeRenderTargetsRenderObservable](/typedoc/classes/babylon.scene#onbeforerendertargetsrenderobservable)
- [onAfterRenderTargetsRenderObservable](/typedoc/classes/babylon.scene#onafterrendertargetsrenderobservable)
- [onBeforeCameraRenderObservable](/typedoc/classes/babylon.scene#onbeforecamerarenderobservable)
- [onBeforeActiveMeshesEvaluationObservable](/typedoc/classes/babylon.scene#onbeforeactivemeshesevaluationobservable)
- [onAfterActiveMeshesEvaluationObservable](/typedoc/classes/babylon.scene#onafteractivemeshesevaluationobservable)
- [onBeforeParticlesRenderingObservable](/typedoc/classes/babylon.scene#onbeforeparticlesrenderingobservable)
- [onAfterParticlesRenderingObservable](/typedoc/classes/babylon.scene#onafterparticlesrenderingobservable)
- [onBeforeDrawPhaseObservable](/typedoc/classes/babylon.scene#onbeforedrawphaseobservable)
- [onAfterDrawPhaseObservable](/typedoc/classes/babylon.scene#onafterdrawphaseobservable)
- [onAfterCameraRenderObservable](/typedoc/classes/babylon.scene#onaftercamerarenderobservable)
- [onAfterRenderObservable](/typedoc/classes/babylon.scene#onafterrenderobservable)

The Scene object also has observables: onReady, onDataLoaded, and onDispose, but they are not triggered during rendering.

Also, [onBeforeStepObservable](/typedoc/classes/babylon.scene#onbeforestepobservable) and [onAfterStepObservable](/typedoc/classes/babylon.scene#onafterstepobservable) are available when using [deterministic lock step](/features/featuresDeepDive/animation/advanced_animations#deterministic-lockstep).

However, possibly the most useful Observable is the one that checks what is happening to the screen pointer, whether by mouse, finger, or controller: [scene.onPointerObservable](/typedoc/classes/babylon.scene#onpointerobservable). For more details, have a look at the [Interactions HowTo](/features/featuresDeepDive/scene/interactWithScenes).

## Observable-based countdown function

Starting with Babylon 4.2, a new way to set a delayed function call was added. This method calculates the delay using observables. Think of it as a setTimeout function, but inside the Babylon context. The best way to explain it is with an example:

```javascript
// classic set timeout:
setTimeout(() => {
  // code running here is not guaranteed to be called inside the render loop
  // Actually, it is most likely that it will be called OUTSIDE the render loop
}, 3000);

// the new and simple way
BABYLON.setAndStartTimer({
  timeout: 3000,
  contextObservable: scene.onBeforeRenderObservable,
  onEnded: () => {
    // code running here is guaranteed to run inside the beforeRender loop
  },
});
```

### setAndStartTimer

As you can see in the example, the Babylon countdown timer takes an observable as context. This observable is the most important part of the code: it is the context in which the remaining time functions will be called, and it is responsible for calculating the delta time until the timer finishes. To explain it simply, these are the steps for the function we implemented before:

1. set time = 0, add an observer to scene.onBeforeRenderObservable
2. wait for the observer to be called.
3. in the observer - check if time-passed-since-start > timeout
4. If not, go to 2
5. If yes, call onEnded, remove the observer
6. We are done

A full example of the function's API:

```javascript
BABYLON.setAndStartTimer({
  timeout: 3000,
  contextObservable: scene.onBeforeRenderObservable,
  breakCondition: () => {
    // this will check if we need to break before the timeout has reached
    return scene.isDisposed();
  },
  onEnded: (data) => {
    // this will run when the timeout has passed
  },
  onTick: (data) => {
    // this will run
  },
  onAborted: (data) => {
    // this function will run when the break condition has met (premature ending)
  },
});
```

In theory, any observable can be used here, but some do not really make sense. If, for example, we use the pointer down observable, it might take a long time until the observer is called again, making it impractical. But if you need to process pointer-down input for the next 2 minutes, you can use it this way:

```javascript
let gameIsOn = true;
BABYLON.setAndStartTimer({
    timeout: 2 * 60 * 1000,
    contextObservable: scene.onPointerObservable,
    observableParameters: { mask: BABYLON.PointerEventTypes.POINTERDOWN },
    breakCondition: () => {
        // break if the game ended prior to this timeout
        return !gameIsOn;
    },
    onEnded: () { console.log('time is over'); },
    onTick: (data) => {
        // data.payload is the pointerInfo object from the onPointerObservable
        doSomethingWithTheData(data);
    }
});
```

A more practical example is making the user touch something for 3 seconds while indicating that the 3 seconds are being counted:

```javascript
const guiButton = // created a GUI button
const guiButtonMaterial = ... // get the material
let pressed = false;
scene.onPointerDown = () => {
    pressed = true;
    BABYLON.setAndStartTimer({
        timeout: 2 * 60 * 1000,
        contextObservable: scene.onBeforeRenderObservable,
        breakCondition: () => {
            // break if no longer pressed
            return !pressed;
        },
        onEnded: () {
            console.log('Button pressed!');
            // back to a black button
            guiButtonMaterial.diffuseColor.set(0,0,0);
         },
        onTick: (data) => {
            // turn it slowly green on each call to the registered observer
            guiButtonMaterial.diffuseColor.set(0,data.completeRate,0);
        },
        onAborted: () => {
            // Aborted, back to a black button
            guiButtonMaterial.diffuseColor.set(0,0,0);
        }
    });
}

scene.onPointerUp = () => {
    pressed = false;
}
```

### Advanced Timer

Apart from this quick function, you can use the AdvancedTimer class, which offers a bit more flexibility but is also much more verbose. The object itself is reusable, so it can eventually save a few unnecessary calls and object creations. The last example using AdvancedTimer looks like this:

```javascript
const guiButton = // created a GUI button
const guiButtonMaterial = ... // get the material
const advancedTimer : BABYLON.AdvancedTimer<Scene> = new BABYLON.AdvancedTimer({
    timeout: 3000,
    contextObservable: scene.onBeforeRenderObservable
});
advancedTimer.onEachCountObservable.add(() => {
    // turn it slowly green on each call to the registered observer
    guiButtonMaterial.diffuseColor.set(0,data.completeRate,0);
});
advancedTimer.onTimerAbortedObservable.add(() => {
    // Aborted, back to a black button
    guiButtonMaterial.diffuseColor.set(0,0,0);
});
advancedTimer.onTimerEndedObservable.add(() => {
    // back to a black button
    guiButtonMaterial.diffuseColor.set(0,0,0);
    console.log('Button pressed!');
});

scene.onPointerDown = () => {
    advancedTimer.start();
}

scene.onPointerUp = () => {
    advancedTimer.stop();
}
```

## Usage with RxJS

[RxJS](https://rxjs.dev/) is a common library for handling Observables which are compliant with the [current ECMAScript Observable proposal](https://github.com/tc39/proposal-observable#ecmascript-observable). It provides a wide range of operators, allowing for advanced execution patterns.

The following (TypeScript) code can be used to convert a Babylon Observable into its RxJS equivalent:

````typescript
/**
 * Wraps a Babylon Observable into an rxjs Observable
 *
 * @param bjsObservable The Babylon Observable you want to observe
 * @example
 * ```
 * import { Engine, Scene, AbstractMesh } from '@babylonjs/core'
 *
 * const canvas = document.getElementById('canvas') as HTMLCanvasElement
 * const engine = new Engine(canvas)
 * const scene = new Scene(engine)
 *
 * const render$: Observable<Scene> = fromBabylonObservable(scene.onAfterRenderObservable)
 * const onMeshAdded$: Observable<AbstractMesh> = fromBabylonObservable(scene.onNewMeshAddedObservable)
 * ```
 */
export function fromBabylonObservable<T>(bjsObservable: BJSObservable<T>): Observable<T> {
  return new Observable<T>((subscriber) => {
    if (!(bjsObservable instanceof BJSObservable)) {
      throw new TypeError("the object passed in must be a Babylon Observable");
    }

    const handler = bjsObservable.add((v) => subscriber.next(v));

    return () => bjsObservable.remove(handler);
  });
}
````



# How To Use Promises

## Introduction

Starting with v3.2, we introduced (without breaking backward compatibility, of course) a new pattern: promises.
To learn more about promises, please read this great [MDN web documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).

In a nutshell, the basic idea is to rely on promises instead of dealing with pyramids of callbacks that are intricate and hard to maintain.
For portability, Babylon.js provides a custom polyfill for browsers where promises are not supported, so you can use them without worrying about support.

## Examples

### Basic usage

```javascript
BABYLON.LoadAssetContainerAsync("https://playground.babylonjs.com/scenes/", "skull.babylon", scene).then(function (container) {
  container.addAllToScene();
});
```

<Playground id="/#JA1ND3#1052" title="Simple Promise Example" description="Simple example loading an asset into a scene after the file has been loaded." image="/img/playgroundsAndNMEs/divingDeeperPromises1.webp"/>

### Chaining multiple promises together

```javascript
const scene = new BABYLON.Scene(engine);
const xrPromise = scene.createDefaultXRExperienceAsync();
xrPromise
  .then((xrExperience) => {
    return BABYLON.AppendSceneAsync("https://playground.babylonjs.com/scenes/", "skull.babylon", scene);
  })
  .then(function () {
    // xr resolved, skull added to the scene
  });
```

### Using async/await with promises

Note: This is not supported in all browsers.

```javascript
const main = async function () {
  const scene = new BABYLON.Scene(engine);
  const xrPromise = await scene.createDefaultXRExperienceAsync();
  return BABYLON.AppendSceneAsync("https://playground.babylonjs.com/scenes/", "skull.babylon", scene);
};
```

### Loading two glTF assets in parallel

```javascript
const scene = new BABYLON.Scene(engine);

const baseUrl = "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/";

Promise.all([
  BABYLON.ImportMeshAsync(baseUrl + "BoomBox/glTF/BoomBox.gltf", scene).then(function (result) {
    result.meshes[0].position.x = 0.01;
  }),
  BABYLON.ImportMeshAsync(baseUrl + "Avocado/glTF/Avocado.gltf", scene).then(function (result) {
    result.meshes[0].position.x = -0.01;
    result.meshes[0].position.y = -0.01;
    result.meshes[0].scaling.scaleInPlace(0.25);
  }),
]).then(() => {
  scene.createDefaultCameraOrLight(true, true, true);
  scene.activeCamera.alpha += Math.PI;
});
```

<Playground id="#U2KKMK#308" title="Load 2 Asset At Once" description="Simple example of loading 2 assets at once inside of a promise." image="/img/playgroundsAndNMEs/divingDeeperPromises2.webp"/>



## Event Handling

Naturally, the main sources of events are the mouse, keyboard, touch, device movement, and game controllers. In this section, we will consider how to manage some of these. In terms of coding, Babylon.js has two features that handle events: actions and observables. It is also possible to use plain JavaScript.



## How To 360 Video

360 Video is a simple mix of specific geometry, textures, and material properties. However, rather than put the burden on you to figure out how to connect them, we've created the VideoDome.

Note that the video dome also supports 180-degree video. Read below for more information.

## VideoDome

VideoDomes rely heavily on the [VideoTexture](/features/featuresDeepDive/materials/using/videoTexture) class. Check out its documentation so that some parameters make more sense.
The source video itself should be "Equirectangular". Without an equirectangular source, the class won't function correctly.

## VideoDome Code

Within the Playground, you can copy and paste the following into your scene and then adjust the options.

```javascript
videoDome = new BABYLON.VideoDome("videoDome", url, { < options >
}, scene);
```

All of the settings in the options object are optional, but the object itself is not. Please provide an empty object at minimum.

All the options are passed through to the corresponding classes, mainly the dome geometry and the VideoTexture:

- resolution = 32: Integer, defines the resolution of the sphere used to host the video. Lower resolutions have more artifacts at extreme FOVs
- clickToPlay = false: Add a click to play listener to the video, does not prevent autoplay
- autoPlay = true: Automatically attempts to begin playing the video. It will auto-mute the audio and try again if the first attempt to play fails due to browser policy.
- loop = true: Automatically loop video on end
- size = 1000: Physical radius to create the dome at, defaults to approximately half the far clip plane
- poster: URL of the image displayed during the video loading or until the user interacts with the video
- useDirectMapping = true: Use a direct mapping technique to render the video. You should leave this value on unless you want to use the `fovMultiplier` property
- halfDomeMode = false: Enable the support for 180 videos instead of 360.

<Playground id="#SQ5UC1#457" title="Playground Example of a VideoDome" description="Simple example of using a videoDome in your scene." image="/img/playgroundsAndNMEs/divingDeeperVideoDome1.webp"/>

## Auto Play

Modern browsers have strict policies for autoplaying video. See the [VideoTexture](/features/featuresDeepDive/materials/using/videoTexture) documentation for details. The underlying VideoTexture used by VideoDome is available as `videoTexture`. Code to manually play the video might look like this:

```javascript
scene.onPointerDown = function () {
  videoDome.videoTexture.video.play();
  scene.onPointerDown = null;
};
```

That is essentially what the `clickToPlay=true` option does. However, there can be non-obvious interactions with `autoPlay` in certain browsers, especially when `autoPlay=false`.

## FOV adjustment

Sometimes 360 Video can feel uncomfortably distant from the camera. To help with this, a material-based FOV adjustment is available.
Adjust it between 0.0 and 2.0 with the following code.

```javascript
videoDome.fovMultiplier = newValue;
```

Please note that `fovMultiplier` only works when using the `useDirectMapping = false` creation option.

As a warning, the further the value gets from 1, the more distortion will be visible. Higher resolutions on the video dome help reduce this, but not eliminate it.

<Playground id="#SQ5UC1#458" title="VideoDome with fovMultiplier" description="Simple example of using a videoDome with an fovMultiplier." image="/img/playgroundsAndNMEs/divingDeeperVideoDome2-fov.webp"/>

## Video Types

Several types of 360 video exist today. The most common are Monoscopic Panoramic, Stereoscopic Side-by-Side panoramic, and Top-Bottom panoramic.

The first one represents a panoramic view dedicated to one eye. The second one contains two panoramic views dedicated to each eye, whereas the last one contains both panoramic views on the top and bottom of the video, respectively.

In the VideoDome, you can adapt it to the type of your source video by using:

```javascript
videoDome.videoMode = BABYLON.VideoDome.MODE_MONOSCOPIC;
// or
videoDome.videoMode = BABYLON.VideoDome.MODE_SIDEBYSIDE;
// or
videoDome.videoMode = BABYLON.VideoDome.MODE_TOPBOTTOM;
```

## 180 Video

Another VR-enabled video format is 180-degree video. The area in front of the user is recorded, but the back is black.

There are two ways to enable 180 video mode (which we call `half dome mode`):

- During construction, enable `halfDomeMode` in the options:

```javascript
let videoDome = new BABYLON.VideoDome(
  "videoDome",
  ["https://videourl.com/videos/180.mp4"],
  {
    resolution: 32,
    clickToPlay: true,
    halfDomeMode: true,
  },
  scene,
);
```

- Set `videoDome.halfDome` to true:

```javascript
let videoDome = ....
videoDome.halfDome = true;
```

## Disposal

When disposing a video dome, the second parameter is important to make sure the texture resources are also disposed.

```javascript
videoDome.dispose(false, true);
```

See also documentation regarding [VideoTexture disposal](/features/featuresDeepDive/materials/using/videoTexture#disposal).


Events

Event Handling

Coming next

Observables

Learn all about observables in Babylon.js.

Actions

Learn how to use actions in Babylon.js.

Promises

Learn all about the power of promises in Babylon.js.

Coroutines

Easily extend logic over time with Babylon.js coroutines.