AnimationController

current_animation_name: str

The name of the currently active animation.

Returns

• str — The name of the current animation, or empty string if none is set.

frame_area: Rect

The clip area (atlas region) for the current animation frame.

Returns

• Rect — The source rectangle defining which portion of the texture to display.

Raises

• RuntimeError — If no animation is currently set or the animation has no frames.

frame_index: int

The current frame index in the animation sequence.

Returns the integer frame index (0-based) of the currently displayed frame.

Returns

• int — The current frame index.

looping: bool

Whether the animation should loop when it reaches the end.

playback_speed: float

The playback speed multiplier for animation timing.

A value of 1.0 represents normal speed, 2.0 is double speed, 0.5 is half speed. Setting to 0 will pause the animation.

Returns

• float — The current playback speed multiplier.

progress: float

The normalized progress through the current animation.

Returns a value between 0.0 (start) and 1.0 (end) representing how far through the animation sequence the playback has progressed. Useful for UI progress bars or triggering events at specific points in the animation.

Returns

• float — The animation progress as a value between 0.0 and 1.0.

add_strip(self, frame_width: int, frame_height: int, strip: SheetStrip, strip_index: int = 0) -> None

Add a single animation strip to the controller.

Args

• frame_width (int) — The width of each frame in pixels.
• frame_height (int) — The height of each frame in pixels.
• strip (SheetStrip) — The strip definition.
• strip_index (int, optional) — The index of the strip. Defaults to 0.

Raises

• ValueError — If frame size is not positive or the animation name is a duplicate.
• RuntimeError — If the animation has no frames.

add_strips(self, frame_width: int, frame_height: int, strips: Sequence[SheetStrip]) -> None

Add animations from a sprite sheet.

Divides an atlas into horizontal strips, where each strip represents a different animation. Each strip is divided into equal-sized frames based on the specified frame size. Frames are read left-to-right within each strip, and strips are read top-to-bottom.

Args

• frame_width (int) — The width of each frame in pixels.
• frame_height (int) — The height of each frame in pixels.
• strips (Sequence[SheetStrip]) — List of strip definitions.

Raises

• ValueError — If frame size is not positive, no strips provided, frame count is not positive.
• RuntimeError — If duplicate animation names exist.

is_finished(self) -> bool

Check if the animation completed a full loop during the last update.

Returns True if the animation looped back to the beginning during the most recent frame update. This method is const and can be called multiple times per frame with consistent results.

Returns

• bool — True if the animation completed a loop during the last update.

pause(self) -> None

Pause the animation playback.

Stops animation frame advancement while preserving the current frame position.

play(self, name: str) -> None

Play an animation from the beginning only if it is not already playing.

Args

• name (str) — The name of the animation to play.

Raises

• ValueError — If the specified animation name is not found.

play_from(self, frame_index: int) -> None

Start playing the current animation from a specific frame.

Sets the animation to the specified frame index and resumes playback. Useful for starting animations mid-sequence or implementing custom animation logic.

Args

• frame_index (int) — The frame index to start from (0-based).

Raises

• IndexError — If the frame index is out of range for the current animation.

replay(self, name: str) -> None

Replay an animation from the beginning, regardless of current state.

Args

• name (str) — The name of the animation to replay.

Raises

• ValueError — If the specified animation name is not found.

resume(self) -> None

Resume paused animation playback.

Resumes animation frame advancement if the playback speed is greater than 0. Does nothing if the animation is already playing or playback speed is 0.

rewind(self) -> None

Reset the animation to the beginning.

Sets the animation back to frame 0 and resets loop detection state.

set(self, name: str) -> None

Set the current active animation by name without affecting playback state.

Switches to the specified animation while preserving the current frame index and playback state (paused/playing). Useful for seamless animation transitions.

Args

• name (str) — The name of the animation to activate.

Raises

• ValueError — If the specified animation name is not found.