AnimationController

Manages and controls sprite animations with multiple animation sequences.

Constructor

Manages and controls sprite animations with multiple animation sequences.

Properties

NameDescriptionType
current_animation_nameThe name of the currently active animation.str
frame_areaThe clip area (atlas region) for the current animation frame.Rect
frame_indexThe current frame index in the animation sequence.int
progressThe normalized progress through the current animation.float
playback_speedThe playback speed multiplier for animation timing.float
loopingWhether the animation should loop when it reaches the end.bool

Methods

Add Sheet

add_sheet(
    frame_width: int,
    frame_height: int,
    strips: Sequence[SheetStrip]
) → None

Add animations from a sprite sheet definition.

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 : The width of each frame in pixels.
  • frame_height : The height of each frame in pixels.
  • strips : 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.

Set

set(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 : The name of the animation to activate.

Raises

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

Play

play(name: str) → None

Play an animation from the beginning.

Switches to the specified animation, rewinds it to frame 0, and starts playback.

Args

  • name : The name of the animation to play.

Raises

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

Play From

play_from(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 : The frame index to start from (0-based).

Raises

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

Is Finished

is_finished() → 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.

Rewind

rewind() → None

Reset the animation to the beginning.

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

Pause

pause() → None

Pause the animation playback.

Stops animation frame advancement while preserving the current frame position.

Resume

resume() → 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.