Scene hierarchy

Note: These docs were adopted from the original Motion Canvas docs

Scenes are collections of nodes displayed in your animation. They're organized in a tree hierarchy, with the scene view at its root. This concept is similar to the Document Object Model used to represent HTML and XML documents.

Here's an example of a simple scene hierarchy together with its object representation:

view.add(
  <>
    <Circle />
    <Layout>
      <Rect />
      <Txt>Hi</Txt>
    </Layout>
  </>,
);

Scene ViewCircleLayoutRecttext 'Hi'

Each node is an instance of a class extending the base Node class. To make the code more readable, Motion Canvas uses a custom JSX runtime. This way, instead of instantiating the nodes ourselves, we can write an XML-like markup. Note that Motion Canvas does not use React itself, only JSX. There's no virtual DOM or reconciliation and the JSX tags are mapped directly to Node instances. These two code snippets are equivalent:

// JSX
view.add(
  <>
    <Circle />
    <Layout>
      <Rect />
      <Txt>Hi</Txt>
    </Layout>
  </>,
);

// No JSX
view.add([
  new Circle({}),
  new Layout({
    children: [
      new Rect({}),
      new Txt({text: 'Hi'}),
    ],
  }),
]);

Modifying the hierarchy​

After the hierarchy has been created, it's still possible to add, remove, and rearrange nodes at any time. The Node class contains the children and parent properties that can be used to traverse the tree. But in order to modify it, it's recommended to use the following helper methods:

Node.add​

public add: : 

Add the given node(s) as the children of this node.

The nodes will be appended at the end of the children list.

Examples

Parameters

• node: ComponentChildren

  A node or an array of nodes to append.

---

Node.insert​

public insert: : number = 0: 

Insert the given node(s) at the specified index in the children list.

Examples

Parameters

• node: ComponentChildren

  A node or an array of nodes to insert.

• index: number = 0

  An index at which to insert the node(s).

---

Node.remove​

public remove(): 

Remove this node from the tree.

---

Node.reparent​

public reparent: : void

Change the parent of this node while keeping the absolute transform.

After performing this operation, the node will stay in the same place visually, but its parent will be changed.

Parameters

• newParent: Node

  The new parent of this node.

---

Node.moveUp​

public moveUp(): 

Move the node up in relation to its siblings.

The node will exchange places with the sibling right above it (if any) and from then on will be rendered on top of it.

---

Node.moveDown​

public moveDown(): 

Move the node down in relation to its siblings.

The node will exchange places with the sibling right below it (if any) and from then on will be rendered under it.

---

Node.moveToTop​

public moveToTop(): 

Move the node to the top in relation to its siblings.

The node will be placed at the end of the children list and from then on will be rendered on top of all of its siblings.

---

Node.moveToBottom​

public moveToBottom(): 

Move the node to the bottom in relation to its siblings.

The node will be placed at the beginning of the children list and from then on will be rendered below all of its siblings.

---

Node.moveTo​

public moveTo: number: 

Move the node to the provided position relative to its siblings.

If the node is getting moved to a lower position, it will be placed below the sibling that's currently at the provided index (if any). If the node is getting moved to a higher position, it will be placed above the sibling that's currently at the provided index (if any).

Parameters

• index: number

  The index to move the node to.

---

Node.moveAbove​

public moveAbove: : boolean = false: 

Move the node above the provided node in the parent's layout.

The node will be moved above the provided node and from then on will be rendered on top of it. By default, if the node is already positioned higher than the sibling node, it will not get moved.

Parameters

• node: Node

  The sibling node below which to move.

• directlyAbove: boolean = false

  Whether the node should be positioned directly above the sibling. When true, will move the node even if it is already positioned above the sibling.

---

Node.moveBelow​

public moveBelow: : boolean = false: 

Move the node below the provided node in the parent's layout.

The node will be moved below the provided node and from then on will be rendered below it. By default, if the node is already positioned lower than the sibling node, it will not get moved.

Parameters

• node: Node

  The sibling node below which to move.

• directlyBelow: boolean = false

  Whether the node should be positioned directly below the sibling. When true, will move the node even if it is already positioned below the sibling.

---

Node.removeChildren​

public removeChildren(): void

Remove all children of this node.

---

Querying the hierarchy​

Sometimes it can be useful to traverse the hierarchy and find some specific nodes. In this documentation, we'll be referring to this process as querying. Consider the following animation:

import {makeScene2D, Layout, Txt, Circle, Rect, is} from '@revideo/2d';
import {all} from '@revideo/core';

export default makeScene2D(function* (view) {
  view.add(
    <Layout layout gap={20} alignItems={'center'}>
      <Txt fill={'white'}>Example</Txt>
      <Rect fill={'#f3303f'} padding={20} gap={20}>
        <Txt fill={'white'}>42</Txt>
        <Circle size={60} fill={'#FFC66D'} />
        <Txt fill={'white'}>!!!</Txt>
      </Rect>
    </Layout>,
  );

  const texts = view.findAll(is(Txt));

  yield* all(...texts.map(text => text.fill('#FFC66D', 1).back(1)));
});

It contains multiple text nodes whose color oscillates between white and yellow. To achieve that, we used view.findAll(is(Txt)) to search through all descendants of the view node and select only those of type Txt. The first argument passed to the findAll method is a so-called predicate. It's a function that takes a node and returns true if it's a node we're looking for.

For instance, if we wanted to find all nodes whose scale x is greater than 1, we could write:

const wideNodes = view.findAll(node => node.scale.x() > 1);

Knowing this, we could try to find all nodes of type Txt as follows:

const texts = view.findAll(node => node instanceof Txt);

But Motion Canvas comes with a helpful utility function called is that can create this predicate for us:

import {is} from '@revideo/2d';
// ...
const texts = view.findAll(is(Txt));

These can be used with any JavaScript function that accepts a predicate. The findAll method has been implemented to traverse all descendants of a node, but if we wanted to query only the direct children, we could retrieve the children array and call the built-in filter method with our predicate:

const textChildren = someParent.children().filter(is(Txt));

There are a few other methods that can be used to query the hierarchy depending on your needs:

Node.findAll​

public findAll extends : : any => node is : []

public findAll extends  = : : any => boolean: []

Find all descendants of this node that match the given predicate.

Type Parameters

• T extends NodeT

Parameters

• predicate: node: any => node is T

  A function that returns true if the node matches.

---

Node.findFirst​

public findFirst extends : :  => node is : null

public findFirst extends  = : :  => boolean: null

Find the first descendant of this node that matches the given predicate.

Type Parameters

• T extends NodeT

Parameters

• predicate: node: Node => node is T

  A function that returns true if the node matches.

---

Node.findLast​

public findLast extends : :  => node is : null

public findLast extends  = : :  => boolean: null

Find the last descendant of this node that matches the given predicate.

Type Parameters

• T extends NodeT

Parameters

• predicate: node: Node => node is T

  A function that returns true if the node matches.

---

Node.findAncestor​

public findAncestor extends : :  => node is : null

public findAncestor extends  = : :  => boolean: null

Find the closest ancestor of this node that matches the given predicate.

Type Parameters

• T extends NodeT

Parameters

• predicate: node: Node => node is T

  A function that returns true if the node matches.