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

RepeatMode	How repeated :func:tween cycles replay the interpolation.
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(…)’

class simvx.core.animation.tween.RepeatMode

Bases: enum.StrEnum

How repeated :func:tween cycles replay the interpolation.

Members are strings, so both RepeatMode.YOYO and "yoyo" are accepted wherever a repeat mode is expected.

Initialization

Initialize self. See help(type(self)) for accurate signature.

RESTART

‘restart’

Every cycle snaps back to start and replays start -> target.

YOYO

‘yoyo’

Odd cycles play backwards (target -> start), ping-ponging.

INCREMENTAL

‘incremental’

Each cycle offsets both endpoints by the captured target - start.

__new__(*values)

__add__()

__contains__()

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getitem__()

__getnewargs__()

__getstate__()

__gt__()

__hash__()

__iter__()

__le__()

__len__()

__lt__()

__mod__()

__mul__()

__ne__()

__reduce__()

__reduce_ex__()

__repr__()

__rmod__()

__rmul__()

__setattr__()

__sizeof__()

__str__()

__subclasshook__()

capitalize()

casefold()

center()

count()

encode()

endswith()

expandtabs()

find()

format()

format_map()

index()

isalnum()

isalpha()

isascii()

isdecimal()

isdigit()

isidentifier()

islower()

isnumeric()

isprintable()

isspace()

istitle()

isupper()

join()

ljust()

lower()

lstrip()

partition()

removeprefix()

removesuffix()

replace()

rfind()

rindex()

rjust()

rpartition()

rsplit()

rstrip()

split()

splitlines()

startswith()

strip()

swapcase()

title()

translate()

upper()

zfill()

__deepcopy__(memo)

__copy__()

name()

value()

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, *, repeat: int = 1, repeat_mode: simvx.core.animation.tween.RepeatMode | str = RepeatMode.RESTART)

Add a tween step.

repeat and repeat_mode pass straight through to :func:tween, so a single step can loop, yoyo, or increment before the chain advances to the next 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, repeat_mode: simvx.core.animation.tween.RepeatMode | str = RepeatMode.RESTART, 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). repeat_mode: How repeated cycles replay: a :class:RepeatMode or its string value ("restart", "yoyo", "incremental"). 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. What each subsequent cycle plays depends on repeat_mode:

• RepeatMode.RESTART (default): every cycle snaps back to start and replays start -> target. Matches Godot’s tween_property().set_loops(), DOTween’s LoopType.Restart, and GreenSock’s default repeat behaviour. Final value: target.

• RepeatMode.YOYO: odd cycles (the 2nd, 4th, …) play backwards, target -> start, so the value ping-pongs with no snapping. The easing function replays forwards on every cycle, mirroring the curve on backward legs. Final value: start after an even repeat count, target after an odd count.

• RepeatMode.INCREMENTAL: each cycle offsets both endpoints by the delta target - start (walk one tile, then the next): cycle n plays start + n*delta -> start + (n+1)*delta. Final value: start + repeat*delta. The delta is captured once at start time and stays fixed even if the property is moved externally mid-tween. Requires a value type supporting +/- and scalar multiplication (numbers, Vec2, Vec3).

on_repeat fires identically in every mode: after each completed cycle except the last, with the 0-based index of the cycle that just finished (repeat=3 fires it with 0 and 1).

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