# How to Use the Scene Embedding System with CheckpointManager for State Management in Manim

> Master Manim state management with CheckpointManager and scene embedding. Snapshot and restore scene states easily for faster animation development. Learn how now.

- Repository: [Grant Sanderson/manim](https://github.com/3b1b/manim)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Manim's interactive embedding system lets you snapshot and restore scene states using CheckpointManager by prefixing clipboard code blocks with comments, enabling rapid iterative animation development without restarting the renderer.**

The `3b1b/manim` repository includes a powerful **scene embedding system** that pauses animation execution and drops you into an IPython shell for real-time manipulation. By leveraging the **CheckpointManager** for **state management**, you can save complex animation configurations using simple comment-based keys and instantly restore them when iterating on subsequent code blocks.

## Core Architecture of the Embedding System

### InteractiveSceneEmbed and IPython Integration

The embedding functionality is orchestrated by `InteractiveSceneEmbed`, defined in [`manimlib/scene/scene_embed.py`](https://github.com/3b1b/manim/blob/main/manimlib/scene/scene_embed.py). When you invoke `self.embed()` from any `Scene` method (specifically implemented in [`manimlib/scene/scene.py`](https://github.com/3b1b/manim/blob/main/manimlib/scene/scene.py) at lines 202-216), Manim constructs an `InteractiveSceneEmbed` instance and launches an `InteractiveShellEmbed` configured with the scene's module as its user namespace.

This setup injects essential shortcuts into the shell environment, including:

- `checkpoint_paste` – Executes clipboard content while managing checkpoint logic automatically
- `clear_checkpoints` – Wipes the internal `CheckpointManager.checkpoint_states` dictionary for a fresh start

### CheckpointManager State Persistence

The `CheckpointManager` class (lines 96-138 in [`manimlib/scene/scene_embed.py`](https://github.com/3b1b/manim/blob/main/manimlib/scene/scene_embed.py)) provides the underlying **state management** mechanism. It maintains a dictionary called `checkpoint_states` that maps leading comment strings to saved scene configurations. When you trigger a save, the manager stores the output of `scene.get_state()`, which returns a `SceneState` object capturing the current time, play count, and deep copies of all mobjects.

## How to Create and Restore Checkpoints

The workflow relies on clipboard content prefixed with comments to trigger state saves versus restores:

1. **Initialize embedding** – Call `self.embed()` at any point in your `construct()` method to launch the IPython shell.

2. **Copy code with a leading comment** – Copy a Python block starting with a comment (e.g., `# step 1`). The comment serves as the checkpoint key.

3. **Execute with checkpoint_paste** – Run `checkpoint_paste()` in the embed shell. The first execution with a specific comment captures and stores the scene state; subsequent executions with the identical comment automatically call `scene.restore_state()` to roll back before executing the new code block.

4. **Clear when needed** – Run `clear_checkpoints()` to delete all saved snapshots and prevent unwanted restorations.

## State Capture and Restoration Mechanics

### Deep Copying Mobject States

When `CheckpointManager` saves a checkpoint, it invokes `Scene.get_state()`, which constructs a `SceneState` object containing the renderer's current time, play count, and deep copies of every mobject in the scene. The restoration process uses `Scene.restore_state()`, which internally calls `SceneState.restore_scene` and utilizes `Mobject.become(..., match_updaters=True)` (defined in [`manimlib/mobject/mobject.py`](https://github.com/3b1b/manim/blob/main/manimlib/mobject/mobject.py)) to ensure updaters, sub-mobjects, and animation progress remain synchronized with the saved snapshot.

### Checkpoint Storage Structure

The manager stores checkpoints in `checkpoint_states` as a dictionary mapping comment strings to the specific format required by `scene.restore_state()`—typically structured data allowing precise reconstruction of the mobject family tree without reloading the Python module.

## Practical Implementation Examples

### Basic Checkpoint Workflow

```python
from manimlib import *

class CheckpointDemo(Scene):
    def construct(self):
        dot = Dot().shift(LEFT)
        circ = Circle(radius=1).shift(RIGHT)
        self.add(dot, circ)
        
        # Launch the interactive shell

        self.embed()

```

**In the embed shell:**

```text

# step 1

dot.move_to(ORIGIN)

```

Run the checkpoint paste command:

```python
checkpoint_paste()  # Saves state under "# step 1"

```

Later, paste a different block with the same comment:

```text

# step 1

circ.set_fill(BLUE)

```

Execute again:

```python
checkpoint_paste()  # Restores to post-step-1 state, then applies fill change

```

### Clearing Checkpoints Programmatically

```python

# In the embed shell:

clear_checkpoints()  # Removes all saved checkpoints

```

### Advanced State Chaining

```text

# init

dot = Dot()
self.add(dot)

```

```python
checkpoint_paste()  # Saves baseline state

```

```text

# move left

dot.shift(LEFT * 2)

```

```python
checkpoint_paste()  # Updates checkpoint for this comment key

```

## Key Source Files

- **[`manimlib/scene/scene_embed.py`](https://github.com/3b1b/manim/blob/main/manimlib/scene/scene_embed.py)** – Defines `InteractiveSceneEmbed`, the `CheckpointManager` class (lines 96-138), and shell shortcut injection.
- **[`manimlib/scene/scene.py`](https://github.com/3b1b/manim/blob/main/manimlib/scene/scene.py)** – Contains the `Scene.embed()` method (lines 202-216) that wires the embedding system into any scene.
- **[`manimlib/mobject/mobject.py`](https://github.com/3b1b/manim/blob/main/manimlib/mobject/mobject.py)** – Provides `Mobject.become()` and deep copy utilities used by `SceneState` for snapshots.
- **[`manimlib/utils/family_ops.py`](https://github.com/3b1b/manim/blob/main/manimlib/utils/family_ops.py)** – Supplies `extract_mobject_family_members` and related helpers for state serialization.

## Summary

- The **scene embedding system** in `3b1b/manim` launches an IPython shell via `InteractiveSceneEmbed` to enable real-time scene manipulation.
- **CheckpointManager** (defined in [`scene_embed.py`](https://github.com/3b1b/manim/blob/main/scene_embed.py)) saves scene states using comment-prefixed clipboard content as dictionary keys.
- The first `checkpoint_paste()` with a specific comment saves the state; subsequent pastes with the same comment trigger `scene.restore_state()` before executing new code.
- State restoration uses `SceneState` objects and `Mobject.become()` to ensure faithful replication of mobject properties, updaters, and sub-mobjects.
- Use `clear_checkpoints()` from the embed shell to reset the state management dictionary during long development sessions.

## Frequently Asked Questions

### How do I start an interactive embedding session in Manim?

Call `self.embed()` from within your `Scene.construct()` method. According to the source code in [`manimlib/scene/scene.py`](https://github.com/3b1b/manim/blob/main/manimlib/scene/scene.py) (lines 202-216), this instantiates `InteractiveSceneEmbed` and launches an `InteractiveShellEmbed` with your scene's local namespace pre-loaded, allowing direct access to all mobjects and methods.

### What triggers a checkpoint save versus a restore?

The `CheckpointManager.handle_checkpoint_key` method checks if the leading comment of your pasted code block exists in `checkpoint_states`. If the key is absent, `scene.get_state()` captures and stores the current snapshot. If the key exists, `scene.restore_state()` rolls back to the previously saved condition before executing the new code block.

### How does Manim restore the exact state of mobjects?

Restoration relies on `SceneState.restore_scene`, which iterates through saved mobject copies and applies `become(..., match_updaters=True)` to each target mobject. This technique, implemented in [`manimlib/mobject/mobject.py`](https://github.com/3b1b/manim/blob/main/manimlib/mobject/mobject.py), ensures that updaters, sub-mobject hierarchies, and animation timestamps synchronize perfectly with the checkpointed snapshot.

### Can I use checkpoints without the clipboard paste workflow?

Yes. While the standard workflow uses `checkpoint_paste()` to process clipboard content, you can interact with `CheckpointManager` directly through `self.checkpoint_manager` from the embed shell. However, the clipboard method is the primary supported interface for rapid iteration, as it automates the key extraction from comment prefixes.