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.tsindex 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.mdxindex 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 todiff --git a/packages/docs/docs/guides/getting-started/quickstart.mdx b/packages/docs/docs/guides/getting-started/quickstart.mdxindex 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 ouranimations. Open `example.tsx` in a text editor, and replace all code inthe 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 andreflected 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.mdxindex 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 Eventsdiff --git a/packages/docs/docs/guides/getting-started/transitions.mdx b/packages/docs/docs/guides/getting-started/transitions.mdxindex 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+# Transitionsdiff --git a/packages/docs/docs/guides/getting-started/tweening.mdx b/packages/docs/docs/guides/getting-started/tweening.mdxindex 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 filediff --git a/packages/docs/src/components/Api/Preview/SignaturePreview.tsx b/packages/docs/src/components/Api/Preview/SignaturePreview.tsxindex 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.tsxindex 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.metanew file mode 100644index 00000000..0e33e3fe--- /dev/null+++ b/packages/examples/src/scenes/tweening-color.meta@@ -0,0 +1,3 @@+{+ "version": 0+}\ No newline at end of filediff --git a/packages/examples/src/scenes/tweening-color.tsx b/packages/examples/src/scenes/tweening-color.tsxnew file mode 100644index 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.metanew file mode 100644index 00000000..0e33e3fe--- /dev/null+++ b/packages/examples/src/scenes/tweening-cubic.meta@@ -0,0 +1,3 @@+{+ "version": 0+}\ No newline at end of filediff --git a/packages/examples/src/scenes/tweening-cubic.tsx b/packages/examples/src/scenes/tweening-cubic.tsxnew file mode 100644index 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.metanew file mode 100644index 00000000..0e33e3fe--- /dev/null+++ b/packages/examples/src/scenes/tweening-linear.meta@@ -0,0 +1,3 @@+{+ "version": 0+}\ No newline at end of filediff --git a/packages/examples/src/scenes/tweening-linear.tsx b/packages/examples/src/scenes/tweening-linear.tsxnew file mode 100644index 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.metanew file mode 100644index 00000000..0e33e3fe--- /dev/null+++ b/packages/examples/src/scenes/tweening-vector.meta@@ -0,0 +1,3 @@+{+ "version": 0+}\ No newline at end of filediff --git a/packages/examples/src/scenes/tweening-vector.tsx b/packages/examples/src/scenes/tweening-vector.tsxnew file mode 100644index 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.metanew file mode 100644index 00000000..0e33e3fe--- /dev/null+++ b/packages/examples/src/tweening-color.meta@@ -0,0 +1,3 @@+{+ "version": 0+}\ No newline at end of filediff --git a/packages/examples/src/tweening-color.ts b/packages/examples/src/tweening-color.tsnew file mode 100644index 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.metanew file mode 100644index 00000000..0e33e3fe--- /dev/null+++ b/packages/examples/src/tweening-cubic.meta@@ -0,0 +1,3 @@+{+ "version": 0+}\ No newline at end of filediff --git a/packages/examples/src/tweening-cubic.ts b/packages/examples/src/tweening-cubic.tsnew file mode 100644index 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.metanew file mode 100644index 00000000..0e33e3fe--- /dev/null+++ b/packages/examples/src/tweening-linear.meta@@ -0,0 +1,3 @@+{+ "version": 0+}\ No newline at end of filediff --git a/packages/examples/src/tweening-linear.ts b/packages/examples/src/tweening-linear.tsnew file mode 100644index 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.metanew file mode 100644index 00000000..0e33e3fe--- /dev/null+++ b/packages/examples/src/tweening-vector.meta@@ -0,0 +1,3 @@+{+ "version": 0+}\ No newline at end of filediff --git a/packages/examples/src/tweening-vector.ts b/packages/examples/src/tweening-vector.tsnew file mode 100644index 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.tsindex 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.tsindex 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.htmlindex 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>