simvx.core.animation.player

AnimationPlayer – timeline-based animation playback node.

Module Contents

Classes

AnimationPlayer

Plays timeline-based animation clips on a target node.

API

class simvx.core.animation.player.AnimationPlayer(target=None, skeleton=None, **kwargs)

Bases: simvx.core.node.Node

Plays timeline-based animation clips on a target node.

As a Node subclass, it participates in the scene tree and gets on_process(dt) called automatically. By default it animates its parent.

Supports crossfading between clips, firing track events, and skeletal animation via SkeletalAnimationClip + Skeleton.

Attributes: target: The node whose properties are animated. Defaults to parent if not set explicitly. clips: Dictionary of registered AnimationClip objects keyed by name. skeletal_clips: Dictionary of SkeletalAnimationClip objects keyed by name. skeleton: Optional Skeleton node for bone-track playback. current_clip: Name of the currently playing clip, or None. current_time: Playback position within the current clip (seconds). playing: Whether playback is active. speed_scale: Playback speed multiplier (1.0 = normal). loop: Whether the current clip should loop when finished. animation_finished: Signal emitted when a non-looping clip ends.

Example::

player = AnimationPlayer()
player.add_clip(jump_clip)
player.add_clip(run_clip)
player.play("jump")
player.crossfade("run", duration=0.3)

# Skeletal animation:
player.skeleton = skeleton_node
player.add_clip(walk_skeletal_clip)
player.play("walk", loop=True)

Initialization

add_clip(clip: simvx.core.animation.track.AnimationClip | simvx.core.animation.skeletal.SkeletalAnimationClip)

Register an animation clip (property-based or skeletal).

play(clip_name: str, loop: bool = False)

Play animation clip, cancelling any active crossfade.

crossfade(clip_name: str, duration: float = 0.3)

Blend from the current clip to a new clip over duration seconds.

If no clip is playing or the target clip is unknown, falls back to play().

stop()

Stop playback and reset to the start of the current clip.

playing becomes False, the playhead resets to current_time = 0, and any crossfade in progress is cancelled.

pause()

Pause playback, preserving the playhead.

playing becomes False but current_time is left untouched; resume() continues from where playback left off.

resume()

Resume playback from the current playhead position.

seek(time: float)

Jump to time in current clip.

on_process(dt: float)

Advance animation playback each frame (called by SceneTree).

to_dict() → dict

Serialize player state.

Both property clips and skeletal clips are persisted (skeletal clips carry a "kind": "skeletal" tag so :meth:from_dict rebuilds the right type). Resumable playback state (current_clip, current_time, speed_scale, loop, playing) is included. A crossfade in progress is not persisted: on load the player settles onto the incoming clip (current_clip), which is the steady state the crossfade is converging toward anyway.

classmethod from_dict(data: dict, target=None)

Deserialize player. Loads in a settled state (no active crossfade).

strict_errors: ClassVar[bool]

True

script_error_raised

‘Signal(…)’

classmethod __init_subclass__(**kwargs)

property name: str

property process_mode: simvx.core.descriptors.ProcessMode

property visible: bool

reset_error() → None

add_child(node: simvx.core.node.Node) → simvx.core.node.Node

remove_child(node: simvx.core.node.Node)

reparent(new_parent: simvx.core.node.Node)

get_node(path: str) → simvx.core.node.Node

find_child(name: str, recursive: bool = False) → simvx.core.node.Node | None

find(target: type | str, recursive: bool = True) → simvx.core.node.Node | None

find_all(node_type: type, recursive: bool = True) → list

walk(*, include_self: bool = True) → collections.abc.Iterator[simvx.core.node.Node]

property path: str

add_to_group(group: str)

remove_from_group(group: str)

is_in_group(group: str) → bool

on_ready() → None

on_enter_tree() → None

on_exit_tree() → None

on_physics_process(dt: float) → None

on_draw(renderer) → None

on_picked(event: simvx.core.events.InputEvent) → None

on_unhandled_input(event: simvx.core.events.TreeInputEvent) → None

start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle

stop_coroutine(gen_or_handle)

clear_children()

destroy()

property app

property tree: simvx.core.scene_tree.SceneTree

__getitem__(key: str)

classmethod get_properties() → dict[str, simvx.core.descriptors.Property]

__repr__()