# Understanding the Scene
Learn how to access and traverse the Lottie Creator 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**

```mermaid
flowchart TD
  subgraph File
    Scene1[Scene]
    Scene2[Nestable scene]
  end

  Scene1 --> ShapeLayer[Shape layer]
  Scene1 --> Image[Image layer]
  Scene1 --> Text[Text layer]
  Scene1 --> SceneLayer[Scene layer]

  SceneLayer -.->|references| Scene2

  ShapeLayer --> Group
  ShapeLayer --> Shapes

  Group --> Group2[Group]
  Group --> Shapes
```

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

## Node types

### Scenes

```mermaid
flowchart TD
  subgraph File
    Scene1[Scene]
    Scene2[Nestable scene]
  end

  Scene1 --> ShapeLayer[Shape layer]
  Scene1 --> Image[Image layer]
  Scene1 --> Text[Text layer]
  Scene1 --> SceneLayer[Scene layer]

  SceneLayer -.->|references| Scene2

  ShapeLayer --> Group
  ShapeLayer --> Shapes

  Group --> Group2[Group]
  Group --> Shapes

  style Scene1 fill:#E0F7F4,stroke:#00C1A2,stroke-width:4px
```

- 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

```mermaid
flowchart TD
  subgraph File
    Scene1[Scene]
    Scene2[Nestable scene]
  end

  Scene1 --> ShapeLayer[Shape layer]
  Scene1 --> Image[Image layer]
  Scene1 --> Text[Text layer]
  Scene1 --> SceneLayer[Scene layer]

  SceneLayer -.->|references| Scene2

  ShapeLayer --> Group
  ShapeLayer --> Shapes

  Group --> Group2[Group]
  Group --> Shapes

  style Scene2 fill:#E0F7F4,stroke:#00C1A2,stroke-width:4px
  style SceneLayer fill:#E0F7F4,stroke:#00C1A2,stroke-width:4px
  linkStyle 3 stroke:#00C1A2,stroke-width:2px
  linkStyle 4 stroke:#00C1A2,stroke-width:2px
```

- 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

```mermaid
flowchart TD
  subgraph File
    Scene1[Scene]
    Scene2[Nestable scene]
  end

  Scene1 --> ShapeLayer[Shape layer]
  Scene1 --> Image[Image layer]
  Scene1 --> Text[Text layer]
  Scene1 --> SceneLayer[Scene layer]

  SceneLayer -.->|references| Scene2

  ShapeLayer --> Group
  ShapeLayer --> Shapes

  Group --> Group2[Group]
  Group --> Shapes

  style ShapeLayer fill:#E0F7F4,stroke:#00C1A2,stroke-width:4px
  style Image fill:#E0F7F4,stroke:#00C1A2,stroke-width:4px
  style Text fill:#E0F7F4,stroke:#00C1A2,stroke-width:4px
  style SceneLayer fill:#E0F7F4,stroke:#00C1A2,stroke-width:4px
  linkStyle 0,1,2,3 stroke:#00C1A2,stroke-width:2px
```

Layers are top-level elements of a scene:

| Type          | Description                           |
| ------------- | ------------------------------------- |
| `Shape layer` | A layer containing shapes             |
| `Image layer` | A layer containing an image           |
| `Text layer`  | A layer containing text               |
| `Scene layer` | A layer that references another scene |

### Shapes

```mermaid
flowchart TD
  subgraph File
    Scene1[Scene]
    Scene2[Nestable scene]
  end

  Scene1 --> ShapeLayer[Shape layer]
  Scene1 --> Image[Image layer]
  Scene1 --> Text[Text layer]
  Scene1 --> SceneLayer[Scene layer]

  SceneLayer -.->|references| Scene2

  ShapeLayer --> Group
  ShapeLayer --> Shapes

  Group --> Group2[Group]
  Group --> Shapes

  style Group fill:#E0F7F4,stroke:#00C1A2,stroke-width:4px
  style Shapes fill:#E0F7F4,stroke:#00C1A2,stroke-width:4px
  style Group2 fill:#E0F7F4,stroke:#00C1A2,stroke-width:4px
  linkStyle 5,6,7,8 stroke:#00C1A2,stroke-width:2px
```

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

| Type        | Description                       |
| ----------- | --------------------------------- |
| `Group`     | Contains other shapes or groups   |
| `Rectangle` | Rectangle shape                   |
| `Ellipse`   | Ellipse shape                     |
| `Polygon`   | Polygon shape                     |
| `Star`      | Star shape                        |
| `Path`      | Any shape with custom vector data |

## Accessing scene content through `scene`

To access scene content, you can use:

| Entry Point  | Description                           | API                   |
| ------------ | ------------------------------------- | --------------------- |
| Active scene | Access the current active scene       | `creator.activeScene` |
| All scenes   | Access all scenes in the current file | `creator.scenes`      |

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

```typescript
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:

| Entry Point        | API                           |
| ------------------ | ----------------------------- |
| Selected nodes     | `creator.selection.nodes`     |
| Selected keyframes | `creator.selection.keyframes` |

## 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.

```typescript
// 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.

```typescript
// 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);
    });
  }
});
```

{/* TODO(DOCS): add traversal up pattern after the API implements shape.parent */}