Understanding the Scene

Lottie Creator organizes animation content in a hierarchy:

• Every Lottie Creator file can have one or more scene

• Scenes and elements in a scene are referred to as nodes

Okay, that's probably confusing at first glance, so let's go through this step-by-step:

Node types

Scenes

• Every Lottie Creator file can have one or more scene

• A scene defines the content of an animation. It has its own canvas, canvas size, framerate, duration, layers, etc.

Nested scenes and scene layers

• Nested scene

  • A scene can be nestable (can be a child of another scene via a scene layer) or non-nestable

• Scene layer

  • A layer that points to a nestable scene. It behaves like a regular layer (you can position, scale, and animate it), but its content comes from the referenced scene.

  • Changes to the source scene automatically reflect in all instances

  • Use sceneLayer.scene to access the referenced scene

  • Use sceneLayer.break() to convert it to a regular layer, breaking the link

Layers

Layers are top-level elements of a scene:

Shapes

Shapes are nodes that represent, well, shapes. They can be children of containers or groups:

Accessing scene content through scene

To access scene content, you can use:

From there, you can access the contents of a scene by traversing its layers:

const scene = creator.activeScene;
const layers = scene.layers;

for (const layer of layers) {
  // do something with the active scene's layers
  console.log(layer.name, layer.type);
}

Accessing scene content through selection

Instead of accessing scene content through the scene object, you might want to access it through the current selection:

Common patterns

When navigating the scene hierarchy, here are patterns you might find helpful:

1. Node filtering

• Filter nodes by type to work only with specific node types.

• Useful for: working with selections or nodes that may contain a mix of different node types.

// Get only image layers from selection
const imageLayers = creator.selection.nodes.filter((node): node is ImageLayer => node.type === "IMAGE_LAYER");

2. Traverse down

• Walk down the node tree to process all children.

• Useful for: finding all shapes within a layer or applying changes recursively.

// Recursively visit all shapes in a layer
function visitShapes(parent: ShapeLayer | Group, callback: (shape: Shape) => void) {
  const shapes = parent.shapes;

  for (const shape of shapes) {
    callback(shape);

    // Groups can contain shapes, so recurse into them
    if (shape.type === "GROUP") {
      visitShapes(shape, callback);
    }
  }
}

// Example: Find all shapes of the selected layer(s)
const selection = creator.selection.nodes;
const shapes: Shape[] = [];

selection.forEach((node) => {
  if (node.type === "SHAPE_LAYER") {
    visitShapes(node, (shape) => {
      shapes.push(shape);
    });
  }
});