simvx.core.animation.player

AnimationPlayer – timeline-based animation playback node.

Module Contents

Classes

AnimationPlayer

Plays timeline-based animation clips on a target node.

Data

log

API

simvx.core.animation.player.log

‘getLogger(…)’

class simvx.core.animation.player.AnimationPlayer(**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_update(dt) called automatically. By default it animates its parent.

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

Properties: target: The node whose properties are animated. Defaults to parent if not set explicitly. skeleton: Optional Skeleton node for bone-track playback. Only a 3D Skeleton (or None) is accepted; see :class:_SkeletonProperty. playing: Whether playback is active. speed_scale: Playback speed multiplier (1.0 = normal). loop: Whether the current clip should loop when finished.

Attributes: clips: Dictionary of registered AnimationClip objects keyed by name. skeletal_clips: Dictionary of SkeletalAnimationClip objects keyed by name. current_clip: Name of the currently playing clip, or None. current_time: Playhead position within the current clip, in seconds. Playback state rather than authoring state, so it is transient: a scene saved mid-clip reloads at the start of that clip, not at whatever second the save happened to catch. Move it with :meth:seek. 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

target

‘Property(…)’

skeleton

‘_SkeletonProperty(…)’

playing

‘Property(…)’

speed_scale

‘Property(…)’

loop

‘Property(…)’

__transient__

‘frozenset(…)’

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.

Raises: KeyError: no clip is registered under clip_name.

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

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

A clip that is still playing keeps playing as it fades out. A non-looping clip that has already run to its end holds its final pose for the length of the blend instead of the player snapping straight onto the incoming clip, so crossfading out of a one-shot that has just finished blends the way an author expects.

Falls back to play() when there is nothing to blend from: no clip has been played, or playback was stopped or paused part-way through. An unregistered clip_name raises KeyError.

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_update(dt: float)

Advance animation playback each frame (called by SceneTree).

strict_errors: ClassVar[bool]

True

dev_checks: ClassVar[bool]

None

dev_warnings: ClassVar[bool]

None

freeze_check_interval: ClassVar[float]

1.0

dynamic: bool

False

visible

‘Property(…)’

update_mode

‘Property(…)’

focus_mode

‘Property(…)’

drag_threshold

‘Property(…)’

focus_entered

‘Signal(…)’

focus_exited

‘Signal(…)’

__properties__: ClassVar[dict[str, simvx.core.descriptors.Property]]

None

classmethod __init_subclass__(**kwargs)

property name: str

property visible_in_tree: bool

property input_player: simvx.core.input.players.InputPlayer

property input_context: simvx.core.input.contexts.InputContext | None

reset_error() → None

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

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

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

node_at(path, default=_NO_DEFAULT)

find(target, *, direct: bool = False)

find_all(target, *, direct: bool = False)

expect(target, *, direct: bool = False)

ancestor(target)

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

property path: str

property is_scene_root: bool

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_fixed_update(dt: float) → None

on_draw(canvas) → None

on_draw_3d(gizmos) → None

on_picked(event: simvx.core.input.events.PickEvent) → bool | None

on_gui_input(event: simvx.core.input.events.GuiInputEvent) → bool | None

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

stop_coroutine(gen_or_handle)

property focused: bool

property focus_rect: tuple[float, float, float, float] | None

drag_threshold_for(pointer_type: simvx.core.input.enums.PointerType | str) → float

grab_focus() → None

release_focus() → None

capture_pointer(pointer_id: int | None = None) → None

release_pointer(pointer_id: int | None = None) → None

queue_redraw() → None

property render_dirty: bool

clear_children()

destroy()

property destroying: bool

property destroyed: bool

call_deferred(method: collections.abc.Callable[..., Any], *args: Any) → None

property app

property tree: simvx.core.scene_tree.SceneTree

property viewport_size: simvx.core.math.types.Vec2

property viewport_insets: tuple[float, float, float, float]

property physics

property physics_2d

__getitem__(key: str)

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

__repr__()