Updaters¶

def add_updater(
    self,
    update_function: Updater[Self],
    index: int | None = None,
    call_updater: bool = False,
) -> Self:
    """Add an updater: a function that keeps the mobject updated as time passes.

    An updater is a function of the mobject, run once a frame — to keep a relation,
    such as a label beside a dot — or, if it has a parameter named `dt`, of the
    mobject and `dt`: the seconds of scene time since it last ran, or since it was
    added, the mobject joined the scene, or its updating resumed. A time-based
    updater moves the mobject by the time that passed:
    `lambda mob, dt: mob.rotate(dt * PI)` turns it half a turn a second, at any
    frame rate. What an updater returns is ignored.

    The scene runs the updaters of the mobjects in it at every frame, after the
    animations playing have moved them to the frame's instant, and at the end of
    each play and wait: mobject by mobject in the order they were added to the
    scene, a mobject's own before its submobjects', and a
    [recorder][manimgx.mobject.record] after all the rest. So add a mobject
    that follows another after it, or it sees where the other's updaters left it at
    the instant before. Updaters keep running while an animation plays the mobject,
    beneath the animation (see `suspend_mobject_updating` among the
    [animation options][manimgx.animation.timeline.AnimationOptions]). A time-based
    updater steps on the scene's simulation clock, `config.simulation_rate` ticks a
    second, so it takes the same steps at any frame rate; declare one that does the
    same however its time is split a [flow][manimgx.mobject.flow], and it runs
    exactly at every frame instead.

    Args:
        update_function: The updater: a function of the mobject, or of the mobject
            and `dt`.
        index: Where it goes among the mobject's updaters, which run in order; None
            for last.
        call_updater: Whether to run it once right away; a time-based one is handed
            a `dt` of 0.

    Examples:
        ```python
        import manimgx as m


        class MobjectAddUpdaterExample(m.Scene):
            def construct(self) -> None:
                hand = m.Line(m.ORIGIN, 3 * m.RIGHT, color=m.BLUE)
                # time-based: a quarter turn about the origin every second
                hand.add_updater(
                    lambda mob, dt: mob.rotate(dt * m.PI / 2, about_point=m.ORIGIN)
                )
                dot = m.Dot(radius=0.2, color=m.YELLOW)
                # per frame: at the hand's end, wherever it is
                dot.add_updater(lambda mob: mob.move_to(hand.get_end()))
                self.add(hand, dot)
                self.wait(3)
        ```
    """
    if index is None:
        self.updaters.append(update_function)
    else:
        self.updaters.insert(index, update_function)
    if not _per_frame(update_function):
        self._since[update_function] = clock.now  # it integrates from now
    if call_updater:
        if _per_frame(update_function):
            update_function(self)
        else:
            cast("Callable[[Self, float], object]", update_function)(self, 0)
    return self

def remove_updater(self, update_function: Updater[Never]) -> Self:
    """Remove an updater from the mobject, every time it was added.

    This also cancels calls that have not yet run in the current update,
    including a recorder waiting for the other updaters to finish.

    Args:
        update_function: The updater to remove.
    """
    self.updaters = [u for u in self.updaters if u is not update_function]
    since = self.__dict__.get("_since_")
    if since is not None and update_function not in self.updaters:
        since.pop(update_function, None)
    return self

def clear_updaters(self, recursive: bool = True) -> Self:
    """Remove every updater of the mobject, including calls still waiting
    to run in the current update.

    Args:
        recursive: Whether its whole family's updaters are removed too.
    """
    self.updaters = []
    self.__dict__.pop("_since_", None)
    if recursive:
        for sub in self.submobjects:
            sub.clear_updaters()
    return self

def get_updaters(self) -> tuple[Updater[Self], ...]:
    """The mobject's own updaters, in the order they run.

    Change them with [add_updater][manimgx.Mobject.add_updater],
    [remove_updater][manimgx.Mobject.remove_updater] and
    [clear_updaters][manimgx.Mobject.clear_updaters], which keep their clocks with
    them.

    Returns:
        A snapshot of them.
    """
    return tuple(self.updaters)

def suspend_updating(self, recursive: bool = True) -> Self:
    """Stop the mobject's updaters from running, and its family's beneath it, until
    [resume_updating][manimgx.Mobject.resume_updating]: nothing updated through a
    suspended mobject runs.

    An animation suspends the updating of the mobject it plays while it plays, and
    runs the updaters beneath it instead (see
    [add_updater][manimgx.Mobject.add_updater]).

    Args:
        recursive: Whether each member of its family is suspended too, so that it stays
            stopped where it is updated apart from the mobject (a member the scene
            also holds by itself), and when the mobject alone resumes.
    """
    self.updating_suspended = True
    if recursive:
        for sub in self.submobjects:
            sub.suspend_updating(recursive)
    return self

def resume_updating(self, recursive: bool = True) -> Self:
    """Let the mobject's updaters run again, from now: the time they were suspended
    is not made up.

    They are not run here: the scene runs them where it next brings the world — at
    the instant it is computing, when an animation resumes them as it finishes,
    else at the next one, such as the next frame.

    Args:
        recursive: Whether its whole family's updaters resume too: resumed alone, the
            mobject runs again, and the members beneath it that are not suspended
            themselves.
    """
    # not run here as well: the instant's own pass runs them, and a per-frame
    # updater would run twice at one instant
    self.updating_suspended = False
    if recursive:
        for sub in self.submobjects:
            sub.resume_updating(recursive)
    self._stamp(clock.now, recursive)
    return self

def update(self, dt: float = 0, recursive: bool = True) -> Self:
    """Run each of the mobject's updaters once, now; nothing runs while its updating
    is suspended.

    The scene runs updaters itself, at every frame: this runs them by hand, now.

    Args:
        dt: The seconds handed to its time-based updaters.
        recursive: Whether its submobjects' updaters run too, after its own.
    """
    # CE's; the scene uses `advance`
    if self.updating_suspended:
        return self
    updaters = self.updaters
    for updater in updaters:
        if updaters is not self.updaters and not _has_updater(
            self.updaters, updater
        ):
            continue
        if _per_frame(updater):
            updater(self)
        else:
            cast("Callable[[Self, float], object]", updater)(self, dt)
    if recursive:
        for sub in self.submobjects:
            sub.update(dt, recursive)
    return self

def flow[U: Callable[..., object]](updater: U) -> U:
    """Declare a time-based updater a flow: one that does the same over some time
    however that time is split into steps.

    A time-based updater is handed `dt`, the seconds since it last ran. Most compose:
    one that moves the mobject at a rate (`mob.shift(dt * velocity)`), or sets it by a
    function of the time it has run, does the same in one step of `dt` as in two of
    `dt / 2`. A flow runs at every instant the scene computes — each frame, and the end
    of each play and wait — handed exactly the time since, so every frame shows it at
    that frame's instant.

    Any other time-based updater is simulated, since what it does may depend on its
    steps (an integrator, a ball that bounces): it steps on a clock of its own,
    `config.simulation_rate` ticks a second (60) and the end of each play and wait, so
    it takes the same steps at any frame rate, and a frame shows it as its last tick
    left it. While one is in the scene, the scene computes every tick, between frames
    too. Declare an updater that composes a flow to make it exact at every frame and to
    spare those ticks; [always_shift][manimgx.always_shift] and
    [always_rotate][manimgx.always_rotate] add flows. An updater that only reads the
    world, as a traced path's does, is a [recorder][manimgx.mobject.record].

    Args:
        updater: A time-based updater: a function of the mobject and `dt`.

    Returns:
        The same updater, declared a flow, to add with
        [add_updater][manimgx.Mobject.add_updater].

    Examples:
        ```python
        import manimgx as m
        from manimgx.mobject import flow


        @flow
        def orbit(dot: m.Mobject, dt: float) -> None:
            dot.rotate(dt * m.PI / 2, about_point=m.ORIGIN)  # a quarter turn a second


        class FlowExample(m.Scene):
            def construct(self) -> None:
                dot = m.Dot(3 * m.RIGHT, radius=0.25, color=m.YELLOW)
                dot.add_updater(orbit)
                self.add(m.Circle(radius=3, color=m.BLUE), dot)
                self.wait(3)
        ```
    """
    _FLOWS.add(_function(updater))
    return updater

def record[U: Callable[..., object]](updater: U) -> U:
    """Declare a time-based updater a recorder: one that reads the world and changes
    only its own mobject, as a [TracedPath][manimgx.TracedPath]'s does.

    The scene runs a recorder at every instant it computes — each tick of the
    simulation clock, each frame, and the end of each play and wait — once everything
    else is there: the animations playing, the mobjects' updaters and the scene's. At a
    frame or at the end of a play or wait, it runs twice: first on the world as time
    alone brought it there, as a tick sees it, then once the per-frame updaters have
    run, so it can tell their change apart (a traced path spreads it over the frame
    that ends there). A recorder is simulated (see [flow][manimgx.mobject.flow]):
    while one is in the scene, the scene computes the simulation clock's ticks.

    Args:
        updater: A time-based updater: a function of the mobject and `dt`, or such a
            method, decorated where its class defines it.

    Returns:
        The same updater, declared a recorder, to add with
        [add_updater][manimgx.Mobject.add_updater].
    """
    # the scene computes a frame or an event in two passes (`Scene._instant`) only while
    # a recorder is in it; the second pass is `clock.framing`
    _RECORDERS.add(_function(updater))
    return updater

def always_redraw[M: Mobject](func: Callable[[], M]) -> M:
    """Make a mobject that is built anew every frame, by a function.

    `func` builds the mobject now, and every frame the mobject becomes what `func`
    builds then (see [`become`][manimgx.Mobject.become]): it stays one object in the
    scene, and follows whatever `func` reads — value trackers, other mobjects. Use it
    for a shape that depends on others in a way no motion follows: a brace that fits a
    growing shape, a line between two moving dots, the area under a graph.

    Args:
        func: A function of no arguments that builds the mobject.

    Returns:
        The mobject, with its updater: add it to the scene.

    Examples:
        ```python
        import manimgx as m


        class AlwaysRedrawExample(m.Scene):
            def construct(self) -> None:
                width = m.ValueTracker(2)
                box = m.always_redraw(
                    lambda: m.Rectangle(width=width.get_value(), height=3, color=m.BLUE)
                )
                brace = m.always_redraw(lambda: m.Brace(box, m.DOWN, color=m.YELLOW))
                self.add(box, brace)
                self.play(width.animate.set_value(11), run_time=2)
                self.play(width.animate.set_value(5))
        ```
    """
    mob = func()
    mob.add_updater(lambda m: m.become(func()))
    return mob

def always_rotate[M: Mobject](
    mobject: M,
    rate: float = 20 * DEGREES,
    axis: Vector3DLike = OUT,
    **kwargs: Unpack[Pivot],
) -> M:
    """Keep a mobject turning, at a steady speed.

    It adds a time-based updater, a [flow][manimgx.mobject.flow], so at every frame
    the mobject is at exactly the angle its speed has brought it to, through plays and
    waits alike.

    Args:
        mobject: The mobject to turn.
        rate: The speed, in radians per second; a positive one turns counterclockwise.
        axis: The axis it turns about.
        **kwargs: [Pivot keywords][manimgx.mobject.Pivot]: the point it turns
            about, its center unless given.

    Returns:
        The mobject, with its updater.

    Examples:
        ```python
        import manimgx as m


        class AlwaysRotateExample(m.Scene):
            def construct(self) -> None:
                square = m.Square(side_length=3, color=m.BLUE, fill_opacity=0.5)
                square.shift(3.5 * m.LEFT)
                m.always_rotate(square, rate=m.PI / 2)  # a quarter turn a second
                center = m.Dot(3.5 * m.RIGHT, color=m.YELLOW)
                moon = m.Dot(3.5 * m.RIGHT + 2 * m.UP, radius=0.25, color=m.TEAL)
                m.always_rotate(moon, rate=-m.PI, about_point=center.get_center())
                self.add(square, center, moon)
                self.wait(4)
        ```
    """
    mobject.add_updater(flow(lambda m, dt: m.rotate(dt * rate, axis, **kwargs)))
    return mobject

def always_shift[M: Mobject](
    mobject: M, direction: Vector3DLike = RIGHT, rate: float = 0.1
) -> M:
    """Keep a mobject moving in a direction, at a steady speed.

    It adds a time-based updater, a [flow][manimgx.mobject.flow], so at every frame
    the mobject is exactly where its speed has brought it, through plays and waits
    alike.

    Args:
        mobject: The mobject to move.
        direction: The direction to move in; only its direction counts, not its length.
        rate: The speed, in scene units per second.

    Returns:
        The mobject, with its updater.

    Examples:
        ```python
        import manimgx as m


        class AlwaysShiftExample(m.Scene):
            def construct(self) -> None:
                square = m.Square(side_length=2, color=m.BLUE, fill_opacity=0.8)
                square.shift(5 * m.LEFT)
                m.always_shift(square, m.RIGHT, rate=2.5)
                self.add(square)
                self.play(square.animate.set_color(m.YELLOW), run_time=2)
                self.wait(2)
        ```
    """
    unit = normalize(direction)
    mobject.add_updater(flow(lambda m, dt: m.shift(dt * rate * unit)))
    return mobject

def turn_animation_into_updater(
    animation: Animation, cycle: bool = False, delay: float = 0
) -> Mobject:
    """Play an animation from an updater of its mobject, on the mobject's own time,
    instead of in a play.

    The animation begins at once: it takes its mobject as it is now, and shows its
    start. Its time then runs with the scene's, from now or from when the mobject joins
    the scene; after `delay` seconds it plays, at its run time and rate function. When
    it ends, it finishes and its updater is removed; with `cycle`, it starts over from
    its beginning instead, again and again. Nothing is added to the scene or taken out
    of it: add the mobject yourself. The animation and its time are the mobject's: a
    copy of it plays a copy of them, on itself.

    Args:
        cycle: Whether it repeats forever.
        delay: How long it waits before it starts, in seconds.

    Returns:
        The animation's mobject, with its updater.

    Examples:
        ```python
        import manimgx as m


        class TurnAnimationIntoUpdaterExample(m.Scene):
            def construct(self) -> None:
                shape = m.Square(side_length=2, color=m.BLUE, fill_opacity=0.5)
                squares = m.VGroup(*(shape.copy() for _ in range(3))).arrange(buff=1.5)
                self.add(squares)
                for i, square in enumerate(squares):  # half a second apart
                    m.turn_animation_into_updater(
                        m.Rotate(square, m.PI / 2, run_time=1), delay=0.5 * i
                    )
                self.wait(2.5)
        ```
    """
    mobject = animation.mobject
    animation.suspend_mobject_updating = False
    animation.begin()
    animation.interpolate(
        0
    )  # the object is the animation's from now: at its start, until then
    # the animation and its time are kept on the mobject, so that a copy of it plays a copy
    # of them: the updater holds only their key, and plays those of the mobject it runs on
    key = next(_PLAYED_KEYS)
    played: dict[int, _Played] = mobject.__dict__.setdefault("_played", {})
    played[key] = _Played(animation, -delay)

    def update(m: Mobject, dt: float) -> None:
        state = m.__dict__.get("_played", {}).get(key)
        if state is None:  # nothing of its own to play
            return
        state.elapsed += dt  # its time now: what this frame shows
        if state.elapsed < 0:
            return
        animation, elapsed = state.animation, state.elapsed
        run_time = animation.get_run_time()
        if run_time > 0 and (cycle or elapsed < run_time):
            animation.interpolate(
                (elapsed / run_time) % 1 if cycle else elapsed / run_time
            )
            animation.advance(clock.now)
        else:
            animation.finish()
            m.remove_updater(update)
            del m.__dict__["_played"][key]

    mobject.add_updater(flow(update))  # the animation at the time it has run
    return mobject

def cycle_animation(animation: Animation, delay: float = 0) -> Mobject:
    """Play an animation over and over, from an updater of its mobject:
    [`turn_animation_into_updater`][manimgx.turn_animation_into_updater] with `cycle`.

    Each cycle starts the animation over from its beginning: an animation that does not
    end where it began jumps back at every cycle.

    Args:
        delay: How long it waits before its first cycle, in seconds.

    Returns:
        The animation's mobject, with its updater.

    Examples:
        ```python
        import manimgx as m


        class CycleAnimationExample(m.Scene):
            def construct(self) -> None:
                orbit = m.Circle(radius=3, color=m.BLUE)
                planet = m.Dot(orbit.get_start(), radius=0.25, color=m.YELLOW)
                m.cycle_animation(
                    m.MoveAlongPath(planet, orbit, rate_func=m.linear, run_time=2)
                )
                self.add(orbit, planet)
                self.wait(4)
        ```
    """
    return turn_animation_into_updater(animation, cycle=True, delay=delay)