tuxemon.animation module

class tuxemon.animation.Animation(*targets, delay=0, round_values=False, duration=None, transition=None, initial=None, relative=False, **kwargs)[source]

Bases: Sprite

Change numeric values over time.

To animate a target sprite/object’s position, simply specify the target x/y values where you want the widget positioned at the end of the animation. Then call start while passing the target as the only parameter.

>>> ani = Animation(x=100, y=100, duration=1000)
>>> ani.start(sprite)

The shorthand method of starting animations is to pass the targets as positional arguments in the constructor.

>>> ani = Animation(sprite.rect, x=100, y=0)

If you would rather specify relative values, then pass the relative keyword and the values will be adjusted for you:

>>> ani = Animation(x=100, y=100, duration=1000)
>>> ani.start(sprite, relative=True)

You can also specify a callback that will be executed when the animation finishes:

>>> ani.callback = my_function

Another optional callback is available that is called after each update:

>>> ani.update_callback = post_update_function

Animations must be added to a sprite group in order for them to be updated. If the sprite group that contains them is drawn then an exception will be raised, so you should create a sprite group only for containing Animations.

You can cancel the animation by calling Animation.abort().

When the animation has finished, then it will remove itself from the sprite group that contains it.

You can optionally delay the start of the animation using the delay keyword.

Callable Attributes

Target values can also be callable. In this case, there is no way to determine the initial value unless it is specified in the constructor. If no initial value is specified, it will default to 0.

Like target arguments, the initial value can also refer to a callable.

NOTE: Specifying an initial value will set the initial value

for all target names in the constructor. This limitation won’t be resolved for a while.

Pygame Rects

The ‘round_values’ parameter will be set to True automatically if pygame rects are used as an animation target.

Parameters:
  • targets (object) – Any valid python objects.

  • delay (float) – Delay time before the animation starts.

  • round_values (bool) – Wether the values must be rounded to the nearest integer before being set.

  • duration (Optional[float]) – Time duration of the animation.

  • transition (Union[str, Callable[[float], float], None]) – Transition to use in the animation. Can be the name of a method of AnimationTransition or a callable with the same signature.

  • initial (Union[float, Callable[[], float], None]) – Initial value. Can be numeric or a callable that returns a numeric value. If None the value itself is used.

  • relative (bool) – If the values are relative to the initial value. That is, in order to find the actual value one has to add the initial one.

  • kwargs (Any) – Properties of the targets to be used, and their values.

abort()[source]

Force animation to finish, without any cleanup.

  • Update callback will not be executed.

  • Final callback will be executed.

  • Values will not change.

  • Animation will be removed from group.

Return type:

None

default_duration = 1000.0
default_transition = 'linear'
finish()[source]

Force animation to finish, apply transforms, and execute callbacks.

  • Update callback will be called because the value is changed.

  • Final callback (‘callback’) will be called.

  • Final values will be applied.

  • Animation will be removed from group.

Return type:

None

start(*targets, **kwargs)[source]

Start the animation on a target sprite/object.

Targets must have the attributes that were set when this animation was created.

Parameters:
  • targets (object) – Any valid python objects.

  • kwargs (Any) – Ignored.

Raises:

RuntimeError – If the animation is already started.

Return type:

None

update(dt)[source]

Update the animation.

The unit of time passed must match the one used in the constructor.

Make sure that you start the animation, otherwise your animation will not be changed during update().

Will raise RuntimeError if animation is updated after it has finished.

Parameters:

dt (float) – Time passed since last update.

Return type:

None

class tuxemon.animation.Task(callback, interval=0, times=1)[source]

Bases: TaskBase

Execute functions at a later time and optionally loop it.

This is a silly little class meant to make it easy to create delayed or looping events without any complicated hooks into pygame’s clock or event loop.

Tasks are created and must be added to a normal pygame group in order to function. This group must be updated, but not drawn.

Setting the interval to 0 cause the callback to be called on the next update.

Because the pygame clock returns milliseconds, the examples below use milliseconds. However, you are free to use whatever time unit you wish, as long as it is used consistently.

Parameters:
  • callback (ScheduledFunction) – Function to execute each interval.

  • interval (float) – Time between callbacks.

  • times (int) – Number of intervals.

Examples

>>> task_group = pygame.sprite.Group()
>>> # like a delay
>>> def call_later():
...    pass
>>> task = Task(call_later, 1000)
>>> task_group.add(task)
>>> # do something 24 times at 1 second intervals
>>> task = Task(call_later, 1000, 24)
>>> # do something every 2.5 seconds forever
>>> task = Task(call_later, 2500, -1)
>>> # pass arguments using functools.partial
>>> from functools import partial
>>> task = Task(partial(call_later(1,2,3, key=value)), 1000)
>>> # a task must have at lease on callback, but others can be added
>>> task = Task(call_later, 2500, -1)
>>> task.schedule(some_thing_else)
>>> # chain tasks: when one task finishes, start another one
>>> task = Task(call_later, 2500)
>>> task.chain(Task(something_else))

When chaining tasks, do not add the chained tasks to a group.

abort()[source]

Force task to finish, without executing callbacks.

Return type:

None

chain(callback, interval=0, times=1)[source]

Schedule a callback to execute when this one is finished

If you attempt to chain a task to a task that will never end, RuntimeError will be raised.

This is convenience to make a new Task and set to it to be added to the “on_finish” list.

Parameters:
  • callback (Callable[[], Any]) – Function to execute each interval.

  • interval (float) – Time between callbacks.

  • times (int) – Number of intervals.

Return type:

None

chain_task(*others)[source]

Schedule Task(s) to execute when this one is finished.

If you attempt to chain a task to a task that will never end, RuntimeError will be raised.

Parameters:

others (Task) – Task instances.

Returns:

The sequence of added Tasks.

Return type:

Sequence[Task]

finish()[source]

Force task to finish, while executing callbacks.

Return type:

None

is_finish()[source]
Returns:

Whether the task is finished or not.

Return type:

bool

reset_delay(new_delay)[source]

Reset the delay before starting task to make sure time left is equal or bigger to the provided value

Parameters:

new_delay (float) – the updated delay that should be respected

Return type:

None

update(dt)[source]

Update the Task.

The unit of time passed must match the one used in the constructor.

Task will not ‘make up for lost time’. If an interval was skipped because of a lagging clock, then callbacks will not be made to account for the missed ones.

Parameters:

dt (float) – Time passed since last update.

Return type:

None

tuxemon.animation.remove_animations_of(target, group)[source]

Find animations that target objects and remove those animations.

Parameters:
  • target (object) – Object whose animations should be removed.

  • group (Group) – Pygame group where to remove the animations.

Return type:

None