# Reference

This page is the API inventory. Start with [`guide.md`](guide.md) if you are
learning the library for the first time.

## Everyday API

- `ReactiveScene`
- `ReactiveThreeDScene`
- `self.state(...)`
- `lift(...)`
- `jump(...)`
- `d.<ManimMobject>(...)`
- `d.call(...)`
- `value.animate_to(...)`
- `state.animate_to(...)`
- `state.animate.transform(...).using({...})`
- `mobject.d.<method>(...)`
- `mobject.d.apply(...)`
- `mobject.d.on_frame(...)`

The everyday pattern is:

```text
state -> lift -> d.Object / d.call -> mobject.d.<method>
```

## Lifecycle And Advanced Control

- `mobject.d.pause()`
- `mobject.d.resume(...)`
- `self.suspend_reactive(...)`

These pause or suspend Manim Stateflow effects. They do not pause Manim
animations or remove user updaters.

## Frame Effects

Use `mobject.d.on_frame(...)` when a behavior must run every Manim frame and needs
`dt`:

```python
square.d.on_frame(lambda mob, dt, speed: mob.rotate(speed * dt), state.speed)
```

The callback receives the target mobject, `dt`, then resolved dependency
values.

## Diagnostics

Use `runtime_snapshot(...)` when debugging dependency ownership or scene
performance. It returns plain data that can be printed, inspected, or turned
into your own visualization.

Use `runtime.snapshot_stats()` when you want a small measurement window for
flushes, renderers, effects, rebuilds, and patches.

## State Immutability

State should be treated as immutable. Update source values with `.set(...)`,
`.animate_to(...)`, or `state.animate.transform(...)`.

Manim Stateflow snapshots common mutable values at the state boundary:

- NumPy arrays
- lists
- tuples
- dicts

Custom objects are stored by the discipline you choose. Manim Stateflow does not
deep-copy arbitrary custom objects, so custom state should usually be immutable
or replaced with a new object when it changes.

## Animation Values

Use `.animate_to(...)` for a single state value:

```python
self.play(x.animate_to(3), run_time=3)
```

Use `state.animate_to(...)` for named state values:

```python
self.play(state.animate_to(x=2, y=-1), run_time=3)
self.play(state.animate_to(mode=jump("done")), run_time=1)
```

Use `jump(...)` for discrete values that should switch instead of interpolate:

```python
self.play(mode.animate_to(jump("recursive", "memoized", "iterative")))
```

Numeric values, NumPy arrays, numeric lists/tuples, and hex color strings such
as `"#ff0000"` can interpolate. Other values should use `jump(...)`.

Interpolated values use Manim's effective animation timing, including the
default `smooth` rate function. Passing `rate_func=...` to `self.play(...)` or
to `animate_to(...)` changes the interpolation just like a normal Manim
animation. `jump(...)` is the default linear-timing exception: jump stages use
raw timeline positions unless you explicitly pass a `rate_func`.

`animate_to(...)` also accepts a per-value `rate_func`:

```python
self.play(
    x.animate_to(3, rate_func=smooth),
    phase.animate_to(TAU, rate_func=linear),
)
```

Use `state.animate.transform(...).using(...)` when you want named state values
to update and specific target mobjects to animate from their old reactive
appearance to the new one:

```python
self.play(
    state.animate.transform(
        n=jump(8),
        label=jump("8"),
    ).using({
        value_display: Transform,
    }),
    run_time=1,
)
```

`using(...)` accepts a dictionary whose keys are mobjects or tuples of
mobjects, and whose values are Manim animation classes or callables:

```python
state.animate.transform(x=10).using({
    (mob1, mob2): Transform,
})

state.animate.transform(x=10, y=jump(5)).using({
    mob1: Transform,
    mob2: ReplacementTransform,
})
```

This is the fluent form of "apply these state updates, then animate these
reactive targets to their new rendered state."

For `jump(...)` targets, `.using(...)` works as a smooth visual transform
between discrete snapshots. That means the target mobject is exact at each jump
state, but in-between frames are a Manim transform between those states rather
than a full geometric recomputation of every intermediate shape. For geometry
such as secant lines, large jump gaps can therefore look less exact than a
continuous `animate_to(...)`. In practice:

- use smaller jump steps when you want staged but visually faithful geometry
- use `animate_to(...)` when you want mathematically exact continuous motion
- keep graph-constrained dots out of the `.using({...})` mapping so they remain reactive
  instead of being transformed off-curve

## Runtime Stats

`DRuntime.stats` accumulates counters for flushes, nodes, renderers, effects,
rebuilds, and patches. Use `runtime.snapshot_stats()` to read and reset the
current window of counters:

```python
stats = self.runtime.snapshot_stats()
```

## Extension Internals

These names are exported for extension, tests, and advanced use:

- `DValue`
- `DNode`
- `DState`
- `DRuntime`
- `DRender`
- `reactive(...)`
- `register_mutator(...)`
- `DMethodEffect`
- `DApplyEffect`
- `DFrameEffect`

Beginner docs avoid these names because the first mental model should be about
state values, computed values, reactive objects, and object effects.
