Animation

class pygamelib.gfx.core.Animation(display_time=0.05, auto_replay=True, frames=None, animated_object=None, refresh_screen=None, initial_index=None, parent=None)

Bases: object

The Animation class is used to give the ability to have more than one model for a BoardItem. A BoardItem can have an animation and all of them that are available to the Game object can be animated through Game.animate_items(lvl_number). To benefit from that, BoardItem.animation must be set explicitely. An animation is controlled via the same state system than the Actuators.

The frames are all stored in a list called frames, that you can access through Animation.frames.

Parameters:
  • display_time (float) – The time each frame is displayed

  • auto_replay (bool) – controls the auto replay of the animation, if false once the animation is played it stays on the last frame of the animation.

  • frames (array[str| Sprixel | Sprite ] | SpriteCollection) – an array of “frames” (string, sprixel, sprite) or a sprite collection

  • animated_object (BoardItem) – The object to animate. This parameter is deprecated. Please use parent instead. It is only kept for backward compatibility. The parent parameter always takes precedence over this one.

  • parent (BoardItem) – The parent object. It is also the object to animate. Important: We cannot animate anything else that BoardItems and subclasses.

  • refresh_screen (function) – The callback function that controls the redrawing of the screen. This function reference should come from the main game.

Important

When a SpriteCollection is used as the frames parameter the sprites’ names are ordered so the frames are displayed in correct order. This means that ‘walk_1’ is going to be displayed before ‘walk_2’. Otherwise SpriteCollection is un-ordered.

Example

def redraw_screen(game_object):
    game_object.clear_screen()
    game_object.display_board()

item = BoardItem(model=Sprite.ALIEN, name='Friendly Alien')
# By default BoardItem does not have any animation, we have to
# explicitly create one
item.animation = Animation(display_time=0.1, parent=item,
                           refresh_screen=redraw_screen)
__init__(display_time=0.05, auto_replay=True, frames=None, animated_object=None, refresh_screen=None, initial_index=None, parent=None)

Methods

__init__([display_time, auto_replay, ...])

add_frame(frame)

Add a frame to the animation.

current_frame()

Return the current frame.

load(data)

Load a serialized Animation object.

next_frame()

Update the parent's model, sprixel or sprite with the next frame of the animation.

pause()

Set the animation state to PAUSED.

play_all()

Play the entire animation once.

remove_frame(index)

Remove a frame from the animation.

reset()

Reset the Animation to the first frame.

search_frame(frame)

Search a frame in the animation.

serialize()

Serialize the Animation object.

start()

Set the animation state to State.RUNNING.

stop()

Set the animation state to STOPPED.

Attributes

dtanimate

The time elapsed since the last frame was displayed.

add_frame(frame)

Add a frame to the animation.

The frame has to be a string (that includes sprites from the Sprite module and squares from the Utils module).

Raise an exception if frame is not a string.

Parameters:

frame (str|:class:Sprite`|:class:`Sprixel) – The frame to add to the animation.

Raise:

pygamelib.base.PglInvalidTypeException

Example:

item.animation.add_frame(Sprite.ALIEN)
item.animation.add_frame(Sprite.ALIEN_MONSTER)
current_frame()

Return the current frame.

Example:

item.model = item.animation.current_frame()
property dtanimate

The time elapsed since the last frame was displayed.

classmethod load(data)

Load a serialized Animation object.

Parameters:

data (dict) – The serialized Animation object.

Returns:

The loaded Animation object.

Return type:

Animation

next_frame()

Update the parent’s model, sprixel or sprite with the next frame of the animation.

That method takes care of automatically resetting the animation if the last frame is reached if the state is State.RUNNING.

If the the state is PAUSED it still update the parent.model and returning the current frame. It does NOT actually go to next frame.

If parent is not a sub class of BoardItem an exception is raised.

Raise:

PglInvalidTypeException

Example:

item.animation.next_frame()

Warning

If you use Sprites as frames, you need to make sure your Animation is attached to a BoardComplexItem.

pause()

Set the animation state to PAUSED.

Example:

item.animation.pause()
play_all()

Play the entire animation once.

That method plays the entire animation only once, there is no auto replay as it blocks the game (for the moment).

If the the state is PAUSED or STOPPED, the animation does not play and the method return False.

If parent is not a sub class of BoardItem an exception is raised.

If screen_refresh is not defined or is not a function an exception is raised.

Raise:

PglInvalidTypeException

Example:

item.animation.play_all()
remove_frame(index)

Remove a frame from the animation.

That method remove the frame at the specified index and return it if it exists.

If the index is out of bound an exception is raised. If the index is not an int an exception is raised.

Parameters:

index (int) – The index of the frame to remove.

Return type:

str

Raise:

IndexError, PglInvalidTypeException

Example:

item.animation.remove_frame( item.animation.search_frame(
    Sprite.ALIEN_MONSTER)
)
reset()

Reset the Animation to the first frame.

Example:

item.animation.reset()
search_frame(frame)

Search a frame in the animation.

That method is returning the index of the first occurrence of “frame”.

Raise an exception if frame is not a string.

Parameters:

frame (str) – The frame to find.

Return type:

int

Raise:

PglInvalidTypeException

Example:

item.animation.remove_frame(
    item.animation.search_frame(Sprite.ALIEN_MONSTER)
)
serialize()

Serialize the Animation object.

The refresh_screen callback function is not serialized. Neither is the parent.

Returns:

A dictionary containing the Animation object’s data.

Return type:

dict

start()

Set the animation state to State.RUNNING.

If the animation state is not State.RUNNING, animation’s next_frame() function return the last frame returned.

Example:

item.animation.start()
stop()

Set the animation state to STOPPED.

Example:

item.animation.stop()