Skip to content

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.ts
index 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.ts
index 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.ts
index 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.
*
* @example
diff --git a/packages/docs/docs/guides/getting-started/configuration.mdx b/packages/docs/docs/guides/getting-started/configuration.mdx
new file mode 100644
index 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.mdx
new file mode 100644
index 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.md
new file mode 100644
index 00000000..89ecacc4
--- /dev/null
+++ b/packages/docs/docs/guides/getting-started/properties.md
@@ -0,0 +1,5 @@
+---
+sidebar_position: 4
+---
+
+# Signals and Properties
diff --git a/packages/docs/docs/guides/getting-started/rendering.md b/packages/docs/docs/guides/getting-started/rendering.md
index 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
---
# Rendering
diff --git a/packages/docs/docs/guides/getting-started/time-events.mdx b/packages/docs/docs/guides/getting-started/time-events.mdx
new file mode 100644
index 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 file
diff --git a/packages/docs/docs/guides/getting-started/transitions.mdx b/packages/docs/docs/guides/getting-started/transitions.mdx
new file mode 100644
index 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 file
diff --git a/packages/docs/docs/guides/getting-started/tweening.mdx b/packages/docs/docs/guides/getting-started/tweening.mdx
new file mode 100644
index 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