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.
- 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.
- 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