Skip to content

Visualize Your Ideas With Code

docs: add tweening section (#115)

Jacob369ded5c92ba
diff --git a/packages/core/src/player/Player.ts b/packages/core/src/player/Player.ts
index 5bd4493e..ea9519c4 100644
--- a/packages/core/src/player/Player.ts
+++ b/packages/core/src/player/Player.ts
@@ -388,7 +388,7 @@ export class Player {
private request() {
this.requestId = requestAnimationFrame(async time => {
- if (time - this.renderTime >= 990 / this.state.current.fps) {
+ if (time - this.renderTime >= 1000 / (this.state.current.fps + 5)) {
this.renderTime = time;
try {
await this.run();
diff --git a/packages/docs/docs/guides/getting-started/flow.mdx b/packages/docs/docs/guides/getting-started/flow.mdx
index 792b5997..d49b4eb9 100644
--- a/packages/docs/docs/guides/getting-started/flow.mdx
+++ b/packages/docs/docs/guides/getting-started/flow.mdx
@@ -51,7 +51,7 @@ export default makeScene2D(function* (view) {
```
Needless to say, it would be extremely cumbersome if we had to write all animations like that.
-Fortunately, JavaScript has another keyword for use withing generators - `yield*`.
+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
diff --git a/packages/docs/docs/guides/getting-started/quickstart.mdx b/packages/docs/docs/guides/getting-started/quickstart.mdx
index ab1e3968..4755f9c8 100644
--- a/packages/docs/docs/guides/getting-started/quickstart.mdx
+++ b/packages/docs/docs/guides/getting-started/quickstart.mdx
@@ -3,6 +3,8 @@ sidebar_position: 1
---
import AnimationPlayer from '@site/src/components/AnimationPlayer';
+import CodeBlock from '@theme/CodeBlock';
+import source from '!!raw-loader!@motion-canvas/examples/src/scenes/quickstart';
# Quickstart
@@ -69,32 +71,9 @@ going to focus on `src/scenes/example.tsx`, which is where we can add our
animations. Open `example.tsx` in a text editor, and replace all code in
the file with the following snippet.
-```tsx title="src/scenes/example.tsx"
-import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
-import {Circle} from '@motion-canvas/2d/lib/components';
-import {useRef} from '@motion-canvas/core/lib/utils';
-import {all} from '@motion-canvas/core/lib/flow';
-
-export default makeScene2D(function* (view) {
- const myCircle = useRef<Circle>();
-
- view.add(
- <Circle
- //highlight-start
- ref={myCircle}
- x={-300}
- width={240}
- height={240}
- fill="#e13238"
- />,
- );
-
- yield* all(
- myCircle.value.fill('#e6a700', 1).to('#e13238', 1),
- myCircle.value.position.x(300, 1).to(-300, 1),
- );
-});
-```
+<CodeBlock language="tsx" title="src/scenes/example.tsx">
+ {source}
+</CodeBlock>
Now save the file. Any changes you make are automatically picked up and
reflected in the preview. You should see a gray circle in the preview pane at
@@ -299,32 +278,9 @@ Now they'll happen at the same time.
This brings us back to our initial example:
-```tsx title="src/scenes/example.tsx"
-import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
-import {Circle} from '@motion-canvas/2d/lib/components';
-import {useRef} from '@motion-canvas/core/lib/utils';
-import {all} from '@motion-canvas/core/lib/flow';
-
-export default makeScene2D(function* (view) {
- const myCircle = useRef<Circle>();
-
- view.add(
- <Circle
- //highlight-start
- ref={myCircle}
- x={-300}
- width={240}
- height={240}
- fill="#e13238"
- />,
- );
-
- yield* all(
- myCircle.value.fill('#e6a700', 1).to('#e13238', 1),
- myCircle.value.position.x(300, 1).to(-300, 1),
- );
-});
-```
+<CodeBlock language="tsx" title="src/scenes/example.tsx">
+ {source}
+</CodeBlock>
[installation]: /guides/getting-started/installation
[generators]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*
diff --git a/packages/docs/docs/guides/getting-started/time-events.mdx b/packages/docs/docs/guides/getting-started/time-events.mdx
index 4ca1f9ab..19b5aacd 100644
--- a/packages/docs/docs/guides/getting-started/time-events.mdx
+++ b/packages/docs/docs/guides/getting-started/time-events.mdx
@@ -2,4 +2,4 @@
sidebar_position: 5
---
-# Time Events
\ No newline at end of file
+# Time Events
diff --git a/packages/docs/docs/guides/getting-started/transitions.mdx b/packages/docs/docs/guides/getting-started/transitions.mdx
index 8217e098..d759d213 100644
--- a/packages/docs/docs/guides/getting-started/transitions.mdx
+++ b/packages/docs/docs/guides/getting-started/transitions.mdx
@@ -2,4 +2,4 @@
sidebar_position: 6
---
-# Transitions
\ No newline at end of file
+# Transitions
diff --git a/packages/docs/docs/guides/getting-started/tweening.mdx b/packages/docs/docs/guides/getting-started/tweening.mdx
index ec708934..4044fd87 100644
--- a/packages/docs/docs/guides/getting-started/tweening.mdx
+++ b/packages/docs/docs/guides/getting-started/tweening.mdx
@@ -2,4 +2,181 @@
sidebar_position: 3
---
-# Tweening
\ No newline at end of file
+import AnimationPlayer from '@site/src/components/AnimationPlayer';
+import CodeBlock from '@theme/CodeBlock';
+import linearSource from '!!raw-loader!@motion-canvas/examples/src/scenes/tweening-linear';
+
+# Tweening
+
+Tweens are one of the fundamental building blocks of animation.
+They are a special type of generators that animate between two values
+over given time.
+
+## `tween` function
+
+The simplest way to create a tween is via the
+[`tween`](/api/core/tweening#tween) function:
+
+<CodeBlock language="tsx">{linearSource}</CodeBlock>
+
+In the example above, we animate the x coordinate of our circle
+from `-300` to `300` over a span of `2` second.
+
+The [`tween`](/api/core/tweening#tween) function takes two parameters.
+The first one specifies the tween duration in seconds. The second is
+a callback function that will be called each frame the tween takes
+place. The `value` parameter it recieves is a number ranging from `0`
+to `1`, informing us about the progress of the tween. We can use it to
+calculate the values that our tween animates. In the case of our circle,
+we use the `map` function to map the `value` range from `[0, 1]` to
+`[-300, 300]` and set it as the `x` coordinate:
+
+<AnimationPlayer small name="tweening-linear" />
+
+## Timing functions
+
+At the moment, our animation feels a bit unnatural. The speed with which
+the `value` parameter changes is constant, which in turn makes the circle
+move with constant speed. In real life, however, objects have inertia -
+they take time to speed up and slow down. We can simulate this behavior
+with [timing functions](/api/core/tweening).
+
+A timing function takes a number in the range `[0, 1]` and returns another
+number in the same range but with a modified rate of change.
+Motion Canvas provides all
+[the most popular timing functions](https://easings.net/) (sometimes called
+easing functions) but since it's a normal JavaScript function you can create
+your own.
+
+Let's use the [`easeInOutCubic`](/api/core/tweening#easeInOutCubic) function
+to fix our animation:
+
+```ts
+yield* tween(2, value => {
+ circle.value.position.x(map(-300, 300, easeInOutCubic(value)));
+});
+```
+
+<AnimationPlayer small name="tweening-cubic" />
+
+`easeInOut` means that the object will speed up at the start (`in`) and slow
+down at the end (`Out`). `Cubic` denotes the mathematical function used -
+in this case it's a cubic equation. Knowing that, a function called
+`easeOutQuad` would make the object start with full speed and then slow down
+at the end using a quadratic equation.
+
+Because using timing functions to map a range of values is a really common
+pattern, it's possible to skip `map` entirely and pass the range to the
+timing function itself:
+
+```ts
+// This:
+map(-300, 300, easeInOutCubic(value));
+// Can be simplified to:
+easeInOutCubic(value, -300, 300);
+```
+
+## Interplation functions
+
+So far, we've only animated a single, numeric value.
+The [`map`](/api/core/tweening#map) function can be used to interpolate between
+two numbers but to animate more complex types we'll need to use interpolation
+functions. Consider the following example:
+
+```ts
+yield* tween(2, value => {
+ circle.value.color(
+ Color.lerp(
+ new Color('#e6a700'),
+ new Color('#e13238'),
+ easeInOutCubic(value),
+ ),
+ );
+});
+```
+
+[`Color.lerp`](/api/core/types/Color#lerp) is a static function that
+interpolates between two colors:
+
+<AnimationPlayer small name="tweening-color" />
+
+:::tip
+
+All [complex types](/api/core/types) in Motion Canvas provide a static method
+called `lerp` that interpolates between two instances of said type.
+
+:::
+
+Aside from the default linear interpolation, some types offer more advanced
+functions such as the [`Vector2.arcLerp`](/api/core/types/Vector2#arcLerp).
+It makes the object follow a curved path from point a to b:
+
+```ts
+yield* tween(2, value => {
+ circle.value.position(
+ // highlight-next-line
+ Vector2.arcLerp(
+ new Vector2(-300, 200),
+ new Vector2(300, -200),
+ easeInOutCubic(value),
+ ),
+ );
+});
+```
+
+<AnimationPlayer small name="tweening-vector" />
+
+## Tweening properties
+
+The [`tween`](/api/core/tweening#tween) function is useful when we need to
+orchestrate complex animations. However, there's a better way of tweening
+individual properties. You may recall from the
+[quickstart](/guides/getting-started/quickstart) section that the following
+tween:
+
+```ts
+yield* tween(2, value => {
+ circle.value.color(
+ Color.lerp(
+ new Color('#e6a700'),
+ new Color('#e13238'),
+ easeInOutCubic(value),
+ ),
+ );
+});
+```
+
+Can be written as:
+
+```ts
+yield* circle.value.color('#e13238', 2);
+```
+
+Here, we use a [`SignalTween`](/api/core/utils/SignalTween) signature that
+looks similar to a setter, except it accepts the transition duration as its
+second argument. Under the hood, this will also create a tween - one that
+starts with the current value and ends with the newly provided one.
+
+By default, it will use `easeInOutCubic` as the timing function.
+We can override that by providing a third argument:
+
+```ts
+yield* circle.value.color(
+ '#e13238',
+ 2,
+ // highlight-next-line
+ easeOutQuad
+);
+```
+
+Similarly, we can pass a custom interpolation function as the forth argument:
+
+```ts
+yield* circle.value.position(
+ new Vector2(300, -200),
+ 2,
+ easeInOutCubic,
+ // highlight-next-line
+ Vector2.arcLerp
+);
+```
\ No newline at end of file
diff --git a/packages/docs/src/components/Api/Preview/SignaturePreview.tsx b/packages/docs/src/components/Api/Preview/SignaturePreview.tsx
index 877d5241..55b86bf5 100644
--- a/packages/docs/src/components/Api/Preview/SignaturePreview.tsx
+++ b/packages/docs/src/components/Api/Preview/SignaturePreview.tsx
@@ -51,7 +51,7 @@ export default function SignaturePreview({
) : isArrow ? (
''
) : (
- <Token type="plain">{reflection.name}</Token>
+ <Token type="function">{reflection.name}</Token>
)}
{!!reflection.typeParameter?.length && (
<TokenList type={ListType.Angle}>
diff --git a/packages/examples/src/scenes/quickstart.tsx b/packages/examples/src/scenes/quickstart.tsx
index 733ee088..b46c69ca 100644
--- a/packages/examples/src/scenes/quickstart.tsx
+++ b/packages/examples/src/scenes/quickstart.tsx
@@ -7,7 +7,14 @@ export default makeScene2D(function* (view) {
const myCircle = useRef<Circle>();
view.add(
- <Circle x={-300} ref={myCircle} width={240} height={240} fill="#e13238" />,
+ <Circle
+ //highlight-start
+ ref={myCircle}
+ x={-300}
+ width={240}
+ height={240}
+ fill="#e13238"
+ />,
);
yield* all(
diff --git a/packages/examples/src/scenes/tweening-color.meta b/packages/examples/src/scenes/tweening-color.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/scenes/tweening-color.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/scenes/tweening-color.tsx b/packages/examples/src/scenes/tweening-color.tsx
new file mode 100644
index 00000000..44995381
--- /dev/null
+++ b/packages/examples/src/scenes/tweening-color.tsx
@@ -0,0 +1,30 @@
+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
+import {Circle} from '@motion-canvas/2d/lib/components';
+import {useRef} from '@motion-canvas/core/lib/utils';
+import {tween, easeInOutCubic} from '@motion-canvas/core/lib/tweening';
+import {Color} from '@motion-canvas/core/lib/types';
+
+export default makeScene2D(function* (view) {
+ const circle = useRef<Circle>();
+
+ view.add(
+ <Circle
+ //highlight-start
+ ref={circle}
+ width={240}
+ height={240}
+ fill="#e13238"
+ />,
+ );
+ //highlight-start
+ yield* tween(2, value => {
+ circle.value.fill(
+ Color.lerp(
+ new Color('#e13238'),
+ new Color('#e6a700'),
+ easeInOutCubic(value),
+ ),
+ );
+ });
+ //highlight-end
+});
diff --git a/packages/examples/src/scenes/tweening-cubic.meta b/packages/examples/src/scenes/tweening-cubic.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/scenes/tweening-cubic.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/scenes/tweening-cubic.tsx b/packages/examples/src/scenes/tweening-cubic.tsx
new file mode 100644
index 00000000..6d32a5c6
--- /dev/null
+++ b/packages/examples/src/scenes/tweening-cubic.tsx
@@ -0,0 +1,24 @@
+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
+import {Circle} from '@motion-canvas/2d/lib/components';
+import {useRef} from '@motion-canvas/core/lib/utils';
+import {tween, map, easeInOutCubic} from '@motion-canvas/core/lib/tweening';
+
+export default makeScene2D(function* (view) {
+ const circle = useRef<Circle>();
+
+ view.add(
+ <Circle
+ //highlight-start
+ ref={circle}
+ x={-300}
+ width={240}
+ height={240}
+ fill="#e13238"
+ />,
+ );
+ //highlight-start
+ yield* tween(2, value => {
+ circle.value.position.x(map(-300, 300, easeInOutCubic(value)));
+ });
+ //highlight-end
+});
diff --git a/packages/examples/src/scenes/tweening-linear.meta b/packages/examples/src/scenes/tweening-linear.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/scenes/tweening-linear.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/scenes/tweening-linear.tsx b/packages/examples/src/scenes/tweening-linear.tsx
new file mode 100644
index 00000000..7904b18e
--- /dev/null
+++ b/packages/examples/src/scenes/tweening-linear.tsx
@@ -0,0 +1,24 @@
+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
+import {Circle} from '@motion-canvas/2d/lib/components';
+import {useRef} from '@motion-canvas/core/lib/utils';
+import {tween, map} from '@motion-canvas/core/lib/tweening';
+
+export default makeScene2D(function* (view) {
+ const circle = useRef<Circle>();
+
+ view.add(
+ <Circle
+ //highlight-start
+ ref={circle}
+ x={-300}
+ width={240}
+ height={240}
+ fill="#e13238"
+ />,
+ );
+ //highlight-start
+ yield* tween(2, value => {
+ circle.value.position.x(map(-300, 300, value));
+ });
+ //highlight-end
+});
diff --git a/packages/examples/src/scenes/tweening-vector.meta b/packages/examples/src/scenes/tweening-vector.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/scenes/tweening-vector.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/scenes/tweening-vector.tsx b/packages/examples/src/scenes/tweening-vector.tsx
new file mode 100644
index 00000000..254fb047
--- /dev/null
+++ b/packages/examples/src/scenes/tweening-vector.tsx
@@ -0,0 +1,32 @@
+import {makeScene2D} from '@motion-canvas/2d/lib/scenes';
+import {Circle} from '@motion-canvas/2d/lib/components';
+import {useRef} from '@motion-canvas/core/lib/utils';
+import {tween, easeInOutCubic} from '@motion-canvas/core/lib/tweening';
+import {Vector2} from '@motion-canvas/core/lib/types';
+
+export default makeScene2D(function* (view) {
+ const circle = useRef<Circle>();
+
+ view.add(
+ <Circle
+ //highlight-start
+ ref={circle}
+ x={-300}
+ y={200}
+ width={240}
+ height={240}
+ fill="#e13238"
+ />,
+ );
+ //highlight-start
+ yield* tween(2, value => {
+ circle.value.position(
+ Vector2.arcLerp(
+ new Vector2(-300, 200),
+ new Vector2(300, -200),
+ easeInOutCubic(value),
+ ),
+ );
+ });
+ //highlight-end
+});
diff --git a/packages/examples/src/tweening-color.meta b/packages/examples/src/tweening-color.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/tweening-color.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/tweening-color.ts b/packages/examples/src/tweening-color.ts
new file mode 100644
index 00000000..7adf85b6
--- /dev/null
+++ b/packages/examples/src/tweening-color.ts
@@ -0,0 +1,7 @@
+import {Project} from '@motion-canvas/core/lib';
+
+import scene from './scenes/tweening-color?scene';
+
+export default new Project({
+ scenes: [scene],
+});
diff --git a/packages/examples/src/tweening-cubic.meta b/packages/examples/src/tweening-cubic.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/tweening-cubic.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/tweening-cubic.ts b/packages/examples/src/tweening-cubic.ts
new file mode 100644
index 00000000..0f9d8103
--- /dev/null
+++ b/packages/examples/src/tweening-cubic.ts
@@ -0,0 +1,7 @@
+import {Project} from '@motion-canvas/core/lib';
+
+import scene from './scenes/tweening-cubic?scene';
+
+export default new Project({
+ scenes: [scene],
+});
diff --git a/packages/examples/src/tweening-linear.meta b/packages/examples/src/tweening-linear.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/tweening-linear.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/tweening-linear.ts b/packages/examples/src/tweening-linear.ts
new file mode 100644
index 00000000..d07c86b3
--- /dev/null
+++ b/packages/examples/src/tweening-linear.ts
@@ -0,0 +1,7 @@
+import {Project} from '@motion-canvas/core/lib';
+
+import scene from './scenes/tweening-linear?scene';
+
+export default new Project({
+ scenes: [scene],
+});
diff --git a/packages/examples/src/tweening-vector.meta b/packages/examples/src/tweening-vector.meta
new file mode 100644
index 00000000..0e33e3fe
--- /dev/null
+++ b/packages/examples/src/tweening-vector.meta
@@ -0,0 +1,3 @@
+{
+ "version": 0
+}
\ No newline at end of file
diff --git a/packages/examples/src/tweening-vector.ts b/packages/examples/src/tweening-vector.ts
new file mode 100644
index 00000000..768a32ca
--- /dev/null
+++ b/packages/examples/src/tweening-vector.ts
@@ -0,0 +1,7 @@
+import {Project} from '@motion-canvas/core/lib';
+
+import scene from './scenes/tweening-vector?scene';
+
+export default new Project({
+ scenes: [scene],
+});
diff --git a/packages/examples/vite.config.ts b/packages/examples/vite.config.ts
index bc072eac..6ee7982e 100644
--- a/packages/examples/vite.config.ts
+++ b/packages/examples/vite.config.ts
@@ -4,7 +4,13 @@ import motionCanvas from '@motion-canvas/vite-plugin';
export default defineConfig({
plugins: [
motionCanvas({
- project: ['./src/quickstart.ts'],
+ project: [
+ './src/quickstart.ts',
+ './src/tweening-linear.ts',
+ './src/tweening-cubic.ts',
+ './src/tweening-color.ts',
+ './src/tweening-vector.ts',
+ ],
}),
],
build: {
diff --git a/packages/player/src/main.ts b/packages/player/src/main.ts
index ca7d9237..ae963901 100644
--- a/packages/player/src/main.ts
+++ b/packages/player/src/main.ts
@@ -212,8 +212,7 @@ class MotionCanvasPlayer extends HTMLElement {
this.runId ??= requestAnimationFrame(async time => {
this.runId = null;
if (!this.shouldPlay()) return;
-
- if (time - this.renderTime >= 990 / this.project.framerate) {
+ if (time - this.renderTime >= 1000 / (this.project.framerate + 5)) {
this.renderTime = time;
try {
await this.run();
diff --git a/packages/player/src/template.html b/packages/player/src/template.html
index dd913cf3..00ccdeb5 100644
--- a/packages/player/src/template.html
+++ b/packages/player/src/template.html
@@ -1,6 +1,6 @@
<canvas class="canvas"></canvas>
<div class="overlay">
- <button title='Play / Pause' class="button ready" tabindex='0'> </button>
+ <button title="Play / Pause" class="button ready" tabindex="0"></button>
<div class="message error">
An error occurred while loading the animation.
</div>