Animation flow

Motion Canvas uses generator functions to describe animations.

A generator function is a function that can return multiple values:

function* example() {
  yield 1;
  yield 2;
  yield 3;
}

const generator = example();

console.log(generator.next().value); // 1;
console.log(generator.next().value); // 2;
console.log(generator.next().value); // 3;

When the yield keyword is encountered, the execution of the function pauses, and resumes only when the caller requests another value. This is particularly useful when declaring animations - usually we want to change the things on the screen in incremental steps to create an illusion of movement. We also want to wait a constant amount of time between these updates so that our eyes can register what's happening. With generators, we can update things in-between the yield keywords, and then wait for a bit whenever the function yields.

This is the fundamental idea of Motion Canvas. yield means: "The current frame is ready, display it on the screen and come back to me later."

With that in mind, we can make a circle flicker on the screen using the following code:

export default makeScene2D(function* (view) {
  const circle = createRef<Circle>();
  view.add(<Circle ref={circle} width={100} height={100} />);

  circle().fill('red');
  yield;
  circle().fill('blue');
  yield;
  circle().fill('red');
  yield;
});

Needless to say, it would be extremely cumbersome if we had to write all animations like that. Fortunately, JavaScript has another keyword for use within generators - yield*. It allows us to delegate the yielding to another generator.

For instance, we could extract the flickering code from the above example to a separate generator and delegate our scene function to it:

import {ThreadGenerator} from '@motion-canvas/core';

export default makeScene2D(function* (view) {
  const circle = createRef<Circle>();
  view.add(<Circle ref={circle} width={100} height={100} />);

  yield* flicker(circle());
});

function* flicker(circle: Circle): ThreadGenerator {
  circle.fill('red');
  yield;
  circle.fill('blue');
  yield;
  circle.fill('red');
  yield;
}

The resulting animation is exactly the same, but now we have a reusable function that we can use whenever we need some flickering.

Motion Canvas provides a lot of useful generators like this. You may remember this snippet from quickstart:

yield * myCircle().fill('#e6a700', 1);

It animates the fill color of the circle from its current value to #e6a700 over a span of one second. As you may guess, the result of calling fill('#e6a700', 1) is another generator to which we can redirect our scene function. Generators like this are called tweens, because they animate between two values. You can read more about them in the tweening section.

Flow Generators

Another kind of generators are flow generators. They take one or more generators as their input and combine them together. We've mentioned the all() generator in the quickstart section, there's a few more:

all

public all...tasks: ThreadGenerator[]: ThreadGenerator

Run all tasks concurrently and wait for all of them to finish.

Examples

Parameters

• ...tasks: ThreadGenerator[]

  A list of tasks to run.

---

any

public any...tasks: ThreadGenerator[]: ThreadGenerator

Run all tasks concurrently and wait for any of them to finish.

Examples

Parameters

• ...tasks: ThreadGenerator[]

  A list of tasks to run.

---

chain

public chain...tasks: CallbackThreadGenerator[]: ThreadGenerator

Run tasks one after another.

Examples

Parameters

• ...tasks: CallbackThreadGenerator[]

  A list of tasks to run.

---

delay

public delaytime: numbertask: CallbackThreadGenerator: ThreadGenerator

Run the given generator or callback after a specific amount of time.

Examples

Parameters

• time: number

  The delay in seconds

• task: CallbackThreadGenerator

  The task or callback to run after the delay.

---

sequence

public sequencedelay: number...tasks: ThreadGenerator[]: ThreadGenerator

Start all tasks one after another with a constant delay between.

The function doesn't wait until the previous task in the sequence has finished. Once the delay has passed, the next task will start even if the previous is still running.

Examples

Parameters

• delay: number

  The delay between each of the tasks.

• ...tasks: ThreadGenerator[]

  A list of tasks to be run in a sequence.

---

loop

public loopfactory: LoopCallback: ThreadGenerator

public loopiterations: numberfactory: LoopCallback: ThreadGenerator

Run the given generator in a loop.

Each iteration waits until the previous one is completed. Because this loop never finishes it cannot be used in the main thread. Instead, use yield or spawn to run the loop concurrently.

Examples

Parameters

• factory: LoopCallback

  A function creating the generator to run. Because generators can't be reset, a new generator is created on each iteration.

---

Looping

There are many ways to animate multiple objects. Here are some examples. Try using them in the below editor.

Press play to preview the animation

import ...

export default makeScene2D(function* (view) {
  const rects: Rect[] = [];

  // Create some rects
  view.add(
    range(5).map(i => (
      <Rect
        ref={makeRef(rects, i)}
        width={100}
        height={100}
        x={-250 + 125 * i}
        fill="#88C0D0"
        radius={10}
      />
    )),
  );

  yield* waitFor(1);

  // Animate them
  yield* all(
    ...rects.map(rect => rect.position.y(100, 1).to(-100, 2).to(0, 1)),
  );
});

Using Array.map and all

This is one of the most elegant ways to do simple tweens, but requires nesting all to do multiple tweens on an object since the map callback must return a ThreadGenerator.

yield *
  all(
    ...rects.map(rect =>
      // No yield or anything; we return this generator and deal with it outside
      rect.position.y(100, 1).to(-100, 2).to(0, 1),
    ),
  );

Using a for loop and all

This is similar to above, but uses a for loop and an array of generators.

const generators = [];
for (const rect of rects) {
  // No yield here, just store the generators.
  generators.push(rect.position.y(100, 1).to(-100, 2).to(0, 1));
}

// Run all of the generators.
yield * all(...generators);

Using a for loop

This is a bit of a cumbersome option because you have to figure out how long it would take for the generator in the loop to complete, but is useful in some situations.

for (const rect of rects) {
  // Note the absence of a * after this yield
  yield rect.position.y(100, 1).to(-100, 2).to(0, 1);
}

// Wait for the duration of the above generators
yield * waitFor(4);