simvx.core.animation.tween

Tween system and easing functions for property animation.

Tweens are time-based: each yield returns the per-tick dt (in seconds) sent by the coroutine driver, which the tween accumulates as elapsed time. There is no notion of “frames” inside a tween: duration is honoured regardless of frame rate.

Module Contents

Classes

TweenChain	Chainable tween builder for sequential animations.
Tween	Namespace for one-liner tween shorthands.

Functions

ease_linear	Linear interpolation (no easing).
ease_in_quad	Quadratic ease-in.
ease_out_quad	Quadratic ease-out.
ease_in_out_quad	Quadratic ease-in-out.
ease_in_cubic	Cubic ease-in.
ease_out_cubic	Cubic ease-out.
ease_in_out_cubic	Cubic ease-in-out.
ease_in_quart	Quartic ease-in.
ease_out_quart	Quartic ease-out.
ease_in_out_quart	Quartic ease-in-out.
ease_in_quint	Quintic ease-in.
ease_out_quint	Quintic ease-out.
ease_in_out_quint	Quintic ease-in-out.
ease_in_sine	Sine ease-in.
ease_out_sine	Sine ease-out.
ease_in_out_sine	Sine ease-in-out.
ease_in_expo	Exponential ease-in.
ease_out_expo	Exponential ease-out.
ease_in_out_expo	Exponential ease-in-out.
ease_in_back	Back ease-in (overshoots).
ease_out_back	Back ease-out (overshoots).
ease_in_out_back	Back ease-in-out (overshoots).
ease_in_elastic	Elastic ease-in (spring effect).
ease_out_elastic	Elastic ease-out (spring effect).
ease_in_out_elastic	Elastic ease-in-out (spring effect).
ease_in_bounce	Bounce ease-in.
ease_out_bounce	Bounce ease-out.
ease_in_out_bounce	Bounce ease-in-out.
easing_by_name	Resolve a registered easing function by name.
easing_name	Return the canonical registered name for an easing function.
tween	Time-based property tween generator with callbacks and repeating.

Data

log
EASING_FUNCTIONS

API

simvx.core.animation.tween.log

‘getLogger(…)’

simvx.core.animation.tween.ease_linear(t: float) → float

Linear interpolation (no easing).

simvx.core.animation.tween.ease_in_quad(t: float) → float

Quadratic ease-in.

simvx.core.animation.tween.ease_out_quad(t: float) → float

Quadratic ease-out.

simvx.core.animation.tween.ease_in_out_quad(t: float) → float

Quadratic ease-in-out.

simvx.core.animation.tween.ease_in_cubic(t: float) → float

Cubic ease-in.

simvx.core.animation.tween.ease_out_cubic(t: float) → float

Cubic ease-out.

simvx.core.animation.tween.ease_in_out_cubic(t: float) → float

Cubic ease-in-out.

simvx.core.animation.tween.ease_in_quart(t: float) → float

Quartic ease-in.

simvx.core.animation.tween.ease_out_quart(t: float) → float

Quartic ease-out.

simvx.core.animation.tween.ease_in_out_quart(t: float) → float

Quartic ease-in-out.

simvx.core.animation.tween.ease_in_quint(t: float) → float

Quintic ease-in.

simvx.core.animation.tween.ease_out_quint(t: float) → float

Quintic ease-out.

simvx.core.animation.tween.ease_in_out_quint(t: float) → float

Quintic ease-in-out.

simvx.core.animation.tween.ease_in_sine(t: float) → float

Sine ease-in.

simvx.core.animation.tween.ease_out_sine(t: float) → float

Sine ease-out.

simvx.core.animation.tween.ease_in_out_sine(t: float) → float

Sine ease-in-out.

simvx.core.animation.tween.ease_in_expo(t: float) → float

Exponential ease-in.

simvx.core.animation.tween.ease_out_expo(t: float) → float

Exponential ease-out.

simvx.core.animation.tween.ease_in_out_expo(t: float) → float

Exponential ease-in-out.

simvx.core.animation.tween.ease_in_back(t: float) → float

Back ease-in (overshoots).

simvx.core.animation.tween.ease_out_back(t: float) → float

Back ease-out (overshoots).

simvx.core.animation.tween.ease_in_out_back(t: float) → float

Back ease-in-out (overshoots).

simvx.core.animation.tween.ease_in_elastic(t: float) → float

Elastic ease-in (spring effect).

simvx.core.animation.tween.ease_out_elastic(t: float) → float

Elastic ease-out (spring effect).

simvx.core.animation.tween.ease_in_out_elastic(t: float) → float

Elastic ease-in-out (spring effect).

simvx.core.animation.tween.ease_in_bounce(t: float) → float

Bounce ease-in.

simvx.core.animation.tween.ease_out_bounce(t: float) → float

Bounce ease-out.

simvx.core.animation.tween.ease_in_out_bounce(t: float) → float

Bounce ease-in-out.

simvx.core.animation.tween.EASING_FUNCTIONS: dict[str, collections.abc.Callable[[float], float]]

None

simvx.core.animation.tween.easing_by_name(name: str) → collections.abc.Callable[[float], float]

Resolve a registered easing function by name.

Falls back to :func:ease_linear (with a warning) for unknown names, so a forward-compatible save written with a newer easing never fails to load.

simvx.core.animation.tween.easing_name(fn: collections.abc.Callable[[float], float]) → str

Return the canonical registered name for an easing function.

Registered functions resolve directly. An unregistered callable (e.g. a user-supplied lambda) is matched by __name__ if that name happens to be registered; otherwise it is recorded as "ease_linear" with a warning, since an anonymous function cannot be round-tripped by name.

class simvx.core.animation.tween.TweenChain(obj, prop: str, start_value=None)

Chainable tween builder for sequential animations.

Example: TweenChain(obj, ‘position’, Vec3(0, 0, 0))
.to(Vec3(10, 0, 0), 1.0, ease_out_quad)
.wait(0.5)
.to(Vec3(0, 0, 0), 1.0, ease_in_quad)
.on_complete(lambda: print(“Done!”))
.build()

Initialization

to(target, duration: float, easing=ease_linear)

Add a tween step.

wait(duration: float)

Add a wait step (in seconds).

on_complete(callback: collections.abc.Callable)

Set completion callback.

build() → simvx.core.descriptors.Coroutine

Build the coroutine chain.

simvx.core.animation.tween.tween(obj, prop: str, target, duration: float, easing=ease_linear, delay: float = 0, repeat: int = 1, on_step: collections.abc.Callable[[float], None] | None = None, on_repeat: collections.abc.Callable[[int], None] | None = None, on_complete: collections.abc.Callable | None = None) → simvx.core.descriptors.Coroutine

Time-based property tween generator with callbacks and repeating.

The coroutine driver sends dt (per-tick delta time in seconds) on every resume; this generator accumulates it as elapsed time, so the animation runs in real time regardless of frame rate.

Args: obj: Object to animate. prop: Property name to animate. target: Target value. duration: Animation duration in seconds. easing: Easing function (default: linear). delay: Delay before starting animation in seconds. repeat: Number of times to repeat (1 = play once, 2 = repeat once, etc). on_step: Called each tick with current progress (0.0 to 1.0). on_repeat: Called when a repeat cycle completes, with repeat index. on_complete: Called when all repeats complete.

Repeat semantics

The start value is captured once before the first iteration. Every repeat replays the same start -> target interpolation, snapping back to start at the beginning of each cycle. Matches Godot’s tween_property().set_loops(), DOTween’s LoopType.Restart default, and GreenSock’s default repeat behavior. For ping-pong or incremental modes, see the repeat_mode enum TODO entry.

Example::

yield from tween(
    player, 'position',
    Vec3(10, 0, 0), 2.0,
    easing=ease_out_quad,
    delay=0.5,
    repeat=2,
    on_complete=lambda: print("Done!"),
)

class simvx.core.animation.tween.Tween

Namespace for one-liner tween shorthands.

These wrap :func:tween for the common case where the developer is just fading or tinting a node. They never construct a node, attach to a scene tree, or require an AnimationPlayer – yield from the returned coroutine inside a Node lifecycle method (run, on_process, etc.).

Example::

# Fade a UI overlay to fully transparent over half a second.
yield from Tween.alpha(overlay, 0.0, 0.5)

# Cross-fade the modulate tint to red.
yield from Tween.colour(sprite, (1.0, 0.2, 0.2, 1.0), 0.3)

static alpha(node, target: float, duration: float, *, attr: str = 'modulate', easing: collections.abc.Callable[[float], float] = ease_linear, callback: collections.abc.Callable | None = None) → simvx.core.descriptors.Coroutine

Tween only the alpha channel of an RGB(A) colour attribute.

Sprite2D exposes the channel as colour; Sprite3D, NinePatch, MeshInstance2D, etc. expose it as modulate. Pass attr= when the node uses a different name.

For 3-component sources the function transparently widens to RGBA so the alpha component can be animated; this requires the attribute to accept a 4-tuple (Colour Properties built with has_alpha=False will reject the widening and raise – that’s correct, you can’t animate alpha on an alpha-less colour).

static colour(node, target: tuple, duration: float, *, attr: str = 'modulate', easing: collections.abc.Callable[[float], float] = ease_linear, callback: collections.abc.Callable | None = None) → simvx.core.descriptors.Coroutine

Tween a full RGB(A) tuple on node over duration seconds.

Source and target are auto-aligned: a 3-tuple target against a 4-tuple source is widened with alpha=1.0; the inverse truncates.