Visualize Your Ideas With Code
docs: add flow and config pages (#98)
Jacob9385765d08dd
diff --git a/packages/core/src/flow/all.ts b/packages/core/src/flow/all.tsindex 9923d2b7..3f8aeec1 100644--- a/packages/core/src/flow/all.ts+++ b/packages/core/src/flow/all.ts@@ -6,7 +6,7 @@ decorate(all, threadable());* Run all tasks concurrently and wait for all of them to finish.** @example- * ```+ * ```ts* // current time: 0s* yield* all(* rect.fill('#ff0000', 2),diff --git a/packages/core/src/flow/any.ts b/packages/core/src/flow/any.tsindex 2212a935..c6bab58e 100644--- a/packages/core/src/flow/any.ts+++ b/packages/core/src/flow/any.ts@@ -6,7 +6,7 @@ decorate(any, threadable());* Run all tasks concurrently and wait for any of them to finish.** @example- * ```+ * ```ts* // current time: 0s* yield* any(* rect.fill('#ff0000', 2),diff --git a/packages/core/src/flow/sequence.ts b/packages/core/src/flow/sequence.tsindex 0b444c6d..dabac6a1 100644--- a/packages/core/src/flow/sequence.ts+++ b/packages/core/src/flow/sequence.ts@@ -8,7 +8,7 @@ decorate(sequence, threadable());** @remarks* The function doesn't wait until the previous task in the sequence has- * finished. Once the delay has passed, the next task will start event if+ * finished. Once the delay has passed, the next task will start even if* the previous is still running.** @examplediff --git a/packages/docs/docs/guides/getting-started/configuration.mdx b/packages/docs/docs/guides/getting-started/configuration.mdxnew file mode 100644index 00000000..2114811f--- /dev/null+++ b/packages/docs/docs/guides/getting-started/configuration.mdx@@ -0,0 +1,98 @@+---+sidebar_position: 8+---++# Configuration++Motion Canvas is configured in the Vite's configuration file:++```ts title="vite.config.ts"+import {defineConfig} from 'vite';+import motionCanvas from '@motion-canvas/vite-plugin';++export default defineConfig({+ plugins: [+ motionCanvas({+ // custom options+ }),+ ],+});+```++### `project`++- Type: `string | string[]`+- Default: `./src/project.ts`++The import path of the project file, relative to the configuration file.+A project file must contain a default export with an instance of the `Project` class.++When set to an array, the Editor will display a project selection screen,+making it possible to change the project without restarting Vite.++```ts+motionCanvas({+ project: [+ // highlight-start+ './src/firstProject.ts',+ './src/secondProject.ts',+ ],+});+```++### `output`++- Type: `string`+- Default: `./output`++An output path to which the animation will be saved. Relative to the configuration file.++When rendering, the complete path has the following format:++```+[output]/[projectName]/[frameNumber].[extension]+```++Stills are saved to a `still` subdirectory:++```+[output]/still/[projectName]/[frameNumber].[extension]+```++### `bufferedAssets`++- Type: `RegExp`+- Default: `/\.(wav|mp3|ogg)$/`++Defines which assets should be buffered before being sent to the browser.++Streaming larger assets directly from the drive my cause issues with other+applications. For instance, if an audio file is being used in the project,+Adobe Audition will perceive it as "being used by another application"+and refuse to override it.++Buffered assets are first loaded to the memory and then streamed from+there. This leaves the original files open for modification with hot module+replacement still working.++### `editor`++- Type: `string`+- Default: `@motion-canvas/ui`++The import path of the editor package.++This option can be used to develop/use an editor different than the official one.+The path will be resolved using Node.js module resolution rules.+It should lead to a directory containing the following files:++- `editor.html` - The HTML template for the editor.+- `styles.css` - The editor styles.+- `main.js` - A module exporting necessary factory functions.++`main.js` should export the following functions:++- `editor` - Receives the project as its first argument and creates the+ user interface.+- `index` - Receives a list of all projects as its first argument and+ creates the initial page for selecting a project.diff --git a/packages/docs/docs/guides/getting-started/flow.mdx b/packages/docs/docs/guides/getting-started/flow.mdxnew file mode 100644index 00000000..d8f65e49--- /dev/null+++ b/packages/docs/docs/guides/getting-started/flow.mdx@@ -0,0 +1,96 @@+---+sidebar_position: 2+---++# Animation flow++Motion Canvas uses generator functions to describe animations.++A generator function is a function that can return multiple values:++```ts+function* example() {+ yield 1;+ yield 2;+ yield 3;+}++const generator = example();++console.log(generator.next()); // 1;+console.log(generator.next()); // 2;+console.log(generator.next()); // 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:++```tsx+export default makeScene2D(function* (view) {+ const circle = useRef<Circle>();+ view.add(<Circle ref={circle} width={100} height={100} />);++ circle.value.fill('red');+ yield;+ circle.value.fill('blue');+ yield;+ circle.value.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 withing 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:++```tsx+export default makeScene2D(function* (view) {+ const circle = useRef<Circle>();+ view.add(<Circle ref={circle} width={100} height={100} />);++ yield* flicker(circle.value);+});++function* flicker(circle: Circle) {+ 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](/guides/getting-started/quickstart):++```ts+yield * myCircle.value.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 be**tween** two values.+You can read more about them in the [tweening](/guides/getting-started/tweening) section.++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, but you can find them all in [the API documentation](/core-api/modules/flow).diff --git a/packages/docs/docs/guides/getting-started/properties.md b/packages/docs/docs/guides/getting-started/properties.mdnew file mode 100644index 00000000..89ecacc4--- /dev/null+++ b/packages/docs/docs/guides/getting-started/properties.md@@ -0,0 +1,5 @@+---+sidebar_position: 4+---++# Signals and Propertiesdiff --git a/packages/docs/docs/guides/getting-started/rendering.md b/packages/docs/docs/guides/getting-started/rendering.mdindex f5e0afc3..f4577114 100644--- a/packages/docs/docs/guides/getting-started/rendering.md+++ b/packages/docs/docs/guides/getting-started/rendering.md@@ -1,5 +1,5 @@----sidebar_position: 2+sidebar_position: 7---# Renderingdiff --git a/packages/docs/docs/guides/getting-started/time-events.mdx b/packages/docs/docs/guides/getting-started/time-events.mdxnew file mode 100644index 00000000..4ca1f9ab--- /dev/null+++ b/packages/docs/docs/guides/getting-started/time-events.mdx@@ -0,0 +1,5 @@+---+sidebar_position: 5+---++# Time Events\ No newline at end of filediff --git a/packages/docs/docs/guides/getting-started/transitions.mdx b/packages/docs/docs/guides/getting-started/transitions.mdxnew file mode 100644index 00000000..8217e098--- /dev/null+++ b/packages/docs/docs/guides/getting-started/transitions.mdx@@ -0,0 +1,5 @@+---+sidebar_position: 6+---++# Transitions\ No newline at end of filediff --git a/packages/docs/docs/guides/getting-started/tweening.mdx b/packages/docs/docs/guides/getting-started/tweening.mdxnew file mode 100644index 00000000..ec708934--- /dev/null+++ b/packages/docs/docs/guides/getting-started/tweening.mdx@@ -0,0 +1,5 @@+---+sidebar_position: 3+---++# Tweening\ No newline at end of file