Skip to main content

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

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

Examples

Parameters


any

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

Examples

Parameters


chain

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

Run tasks one after another.

Examples

Parameters


delay

public delaytime: numbertask: CallbackThreadGenerator: ThreadGenerator

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

Examples

Parameters


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


loop

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);