
# How To Use Promises

## Introduction

Starting with v3.2, we introduced (without breaking backward compatibility of course) a new pattern: the 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 having to deal with pyramids of callbacks intricated in a non easy to maintain way.
Regarding portability, Babylon.js provides a custom polyfill for browsers where promises are not supported so you can blindly use them.

## Examples

### Basic usage

```javascript
BABYLON.SceneLoader.LoadAssetContainerAsync("https://playground.babylonjs.com/scenes/", "skull.babylon", scene).then(function (container) {
    container.addAllToScene();
});
```

<Playground id="#JA1ND3#63" title="Simple Promise Example" description="Simple example loading an asset into a scene after the file has been loaded." image="/img/playgroundsAndNMEs/features/divingDeeperPromises1.jpg"/>

### Chaining multiple promises together

```javascript
var scene = new BABYLON.Scene(engine);
var xrPromise = scene.createDefaultXRExperienceAsync();
xrPromise
    .then((xrExperience) => {
        return BABYLON.SceneLoader.AppendAsync("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
var main = async function () {
    var scene = new BABYLON.Scene(engine);
    var helper = scene.createDefaultVRExperience();
    var supported = await helper.webVRCamera.useStandingMatrixAsync();
    console.log(supported);
    await BABYLON.SceneLoader.AppendAsync("https://playground.babylonjs.com/scenes/", "skull.babylon", scene);
};
```

### Loading two glTF assets in parallel

```javascript
var scene = new BABYLON.Scene(engine);

var baseUrl = "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/";

Promise.all([
    BABYLON.SceneLoader.ImportMeshAsync(null, baseUrl + "BoomBox/glTF/", "BoomBox.gltf", scene).then(function (result) {
        result.meshes[0].position.x = 0.01;
    }),
    BABYLON.SceneLoader.ImportMeshAsync(null, 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#1" title="Load 2 Asset At Once" description="Simple example of loading 2 assets at once inside of a promise." image="/img/playgroundsAndNMEs/features/divingDeeperPromises2.jpg"/>



# Coroutines in Babylon.js

## Introduction

Babylon 5.0 brings with it a new way for writing 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 Asynchrony

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 subsequent
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, which the coroutine system will
interpret as a command to pause the coroutine now and resume it 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 again until the
first time the `Observable` is notified _after_ the `yield`ed `Promise`
has been resolved. Thus, `yield`ing 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 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);
        }
      };
      // 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/divingDeeper/gui) and [scene](/features/divingDeeper/events/observables#scene-observables) Observables will be needed, particularly [scene.onPointerObservable](/features/divingDeeper/scene/interactWithScenes).

## Introduction

Babylon.js provides a lot of events (like scene.beforeRender) and before v2.4 there was not a 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 which represents a given event (like beforeRender for instance).
Users that want to have their own piece of code running in response to such event will register an Observer to the appropriate Observable. Then it's the duty of the Observable to execute the Observers, when appropriate.

The implementer uses an Observable to create a property which will trigger all the registered observers. The Generic type T is used to communicate a given data type from the Observable to the Observer.

Most users will simply be adding 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/features/divingDeeperObservable1.jpg"/>
  An Observable - onXChange- is added to the master sphere. The two minion spheres and the actions they have to undertake form the two Observers which react when a change in the x position of the master 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 giving the callback instead of the Observer instance
- [notifyObservers](/typedoc/classes/babylon.observable#notifyobservers)(): used to notify all the 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 the 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 search facility of the Documentation 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 be 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 is formed from an object set to watch the Observable and the objects 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.

Set the Observable that notifies its Observers before the scene starts the rendering each frame.

```javascript
var 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/features/divingDeeperObservable2.jpg"/>

To remove an Observer, you need to store it during it's creation to refer to it with remove. The following example remove the Observer before it is notified of even the first frame rendering.

```javascript
var alpha = 0;
var 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/features/divingDeeperObservable3.jpg"/>

The following example removes the Observer during the rendering cycle. Since it is not possible to remove an Observer that does not exist there is a need to check whether the Observable still has the Observer.

```javascript
var alpha = 0;
var 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

TheBabylon.js Scene Object has over 20 observables that 'fire' under various conditions. Most of them are checked EACH frame/render, and in a deterministic/predictable order or sequence. Below is a list of Scene observables checked during each renderLoop... 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)
- [onBeforeRenderTargetsRenderObservable](/typedoc/classes/babylon.scene#onbeforerendertargetsrenderobservable)
- [onAfterRenderTargetsRenderObservable](/typedoc/classes/babylon.scene#onafterrendertargetsrenderobservable)
- [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 observers: onReady, onDataLoaded, onDispose, but they do not happen within a rendering/frame.

Also, [onBeforeStepObservable](/typedoc/classes/babylon.scene#onbeforestepobservable) and [onAfterStepObservable](/typedoc/classes/babylon.scene#onafterstepobservable) are available when using [deterministic lock step](/features/divingDeeper/animation/advanced_animations#deterministic-lockstep)

However possibly the most useful Observable is the one that checks what is happening to the screen pointer whether with mouse or with finger or controller. [scene.onPointerObservable](/typedoc/classes/babylon.scene#onpointerobservable) . For more details on that have a look into the [Interactions HowTo](/features/divingDeeper/scene/interactWithScenes)

## Observable-based countdown function

Starting Babylon 4.2 a new way of setting a delay call for a function was added. This method is calculating the time delay using observables. Think about a setTimeout function, but inside the babylon context. The best way to explain is to show 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 is taking an observable as context. This observable is the most important part of this code - the observable is the context in which the rest of the time functions will be called and is in charge of calculating the delta time until finished. 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)
  },
});
```

As you can understand, any observable can be used here, but some don't really make any sense. If, for example, we use pointer down observable, it might take a long time until the next call of the observer, 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 can be used to make the user touch something for 3 seconds (while indicating that the 3 seconds is counting):

```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 brings a bit more flexibility but is a lot more verbose. The object itself is reusable, so it can eventually saved a few unneeded calls and object creations. The last example using the AdvancedTimer will look 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();
}
```
