Animated sprites

Tools to create animated sprites in Pygame. This module also provides a FrameAnchors system, so you may line up two separate animations with frame-specific-coordinate data.

AnimatedSprite overview

An AnimatedSprite is typically loaded from GIF with AnimatedSprite.from_file(), which loads both animation and Anchor data.

classmethod AnimatedSprite.from_file(path_or_readable, anchors_config=None)[source]

The default is to create from gif bytes, but this can also be done from other methods...

  • path_or_readable (str|file-like-object) – Either a string or an object with a read() method. So, either a path to an animated GIF, or a file-like-object/buffer of an animated GIF.
  • anchors_config (configparser) – INI/config file associated with providing anchors for this animation.

Return type:


So to create an AnimatedSprite from a GIF, you’d do something like this code sample below:

>>> sprite = AnimatedSprite.from_file('somedir/walk.gif')
>>> sprite.image
<Surface(10x10x32 SW)>

The AnimatedSprite.from_file() method will build the respective Frame objects and their FrameAnchors. These frames are sent to the AnimatedSprite constructor, as seen below.


Create this AnimatedSprite using a list of Frame instances.

Parameters:frames (list[Frame]) –

A properly assembled list of frames, which assumes that each Frame’s start_time is greater than the previous element and is the previous element’s start time + previous element/Frame’s duration. Here is an example of aformentioned:

>>> frame_one_surface = pygame.Surface((16, 16))
>>> frame_one = Frame(frame_one_surface, 0, 100)
>>> frame_two_surface = pygame.Surface((16, 16))
>>> frame_two = Frame(frame_two_surface, 100, 50)


In the future I may add a method for verifying the validity of Frame start_times and durations.

Here’s what an AnimatedSprite looks like:

class sappho.animatedsprite.AnimatedSprite(frames)[source]

Animated sprite with mask, loaded from GIF.

Supposed to be mostly uniform with the Sprite API.


int – The total duration of of this animation in milliseconds.


pygame.Surface – Current surface belonging to the active frame. Set once per tick through the AnimatedSprite.update() method.


pygame.Rect – Does not reflect position, only area. Updated once per tick, to reflect current frame’s rect, in AnimatedSprite.update().


int – Frame # which is being rendered/to be rendered. Also updated once per tick, see the AnimatedSprite.update() method.


The current surface representing this animation at its current animation position. Set once per tick through the update() method.


int – Animation position in milliseconds; milleseconds elapsed in this animation. This is used for determining which frame to select. Set once per tick through the AnimatedSprite.update() method.

See also

To update the animation, so that it progresses, you need to pass the pygame.time.Clock you pygame.time.Clock.tick() in your main loop. You should look at the included from the GitHub repo, but here’s another sample of how you’d use AnimatedSprite:

screen = pygame.display.set_mode([700, 500])
clock = pygame.time.Clock()
done = False

while not done:
   for event in pygame.event.get():
       if event.type == pygame.QUIT:
           done = True



Anchoring system