Endpoints & variationsEndpoints & variations

Endpoints say where a tween goes. Variations derive a stronger, slower, or later version from a definition’s own values each time it starts. Anatomy and variations introduce both.

Endpoints

Field	Type	Default	Meaning
from_value	Variant	null	Start value; null uses the property’s value at start
to_value	Variant	null	End value; null uses the property’s value at start
by_value	Variant	null	Offset to add instead of a to_value, on top of other changes to the property while it plays
initial_value	Variant	0.0	Start value of a callback-only definition, which has no property to read

Endpoint forms

An array of numbers can stand in for a vector or color endpoint, delta, or offset. The start converts it to the captured value’s type:

Endpoint	Array	Example
Vector2, Vector3, Vector4	One number per component	[400, 180]
Color	Three or four components	[1, 0.5, 0], [1, 0.5, 0, 0.8]

• Three color components leave the alpha at 1.
• An array that doesn’t match the captured type rejects the start.
• Uniform scales and named colors take explicit values, such as Vector2.ONE * 1.2 and Color("tomato").

Relative offsets

• Set to_value or by_value, not both. A to_value tween on the same property still sets it outright.
• With from_value, the tween runs from from_value to from_value plus by_value, like a to_value tween.
• Each repeat adds by_value again, so repeats = 2 moves three times as far. A ping-pong cycle comes back to where it started.
• A fill that doesn’t retain the final value takes the offset back out at the end, and keeps other changes.
• A quaternion offset rotates about the node’s own axes, so the tween ends at start * by_value.

Variations

When a tween starts, each of these values becomes factor × value + delta:

Field	Type	Default	Meaning
factor_from, factor_to, factor_by	float	1.0	Multiply from_value, to_value, or by_value
delta_from, delta_to, delta_by	Variant	null	Then add this, in the property’s value type; null adds nothing
factor_duration	float	1.0	Multiply duration
delta_duration	float	0.0	Then add these seconds
factor_delay	float	1.0	Multiply delay
delta_delay	float	0.0	Then add these seconds, as in a per-start stagger

With to_value left out, factor_to scales the value captured at the start.

Rules

• Factors and deltas apply once, when the tween starts. A non-retaining fill restores the captured value, not an adjusted one.
• For a quaternion, the factor scales the rotation angle and the delta rotates about the node’s own axes.
• factor_by and delta_by need a by_value. factor_to and delta_to don’t apply to a by_value tween. Both combinations are rejected.
• Adjusting from_value fixes the start of a by_value tween, as an explicit from_value does.
• The adjusted duration and delay must not be negative, and offset must fit within the adjusted duration.
• Factors and deltas must be finite. Invalid values reject the start.

Callback endpoints

Callback-only definitions, such as Tweens.value() and Tweens.float_value(), animate no property; on_update receives each value. With no from_value or to_value, they use initial_value for that endpoint: the from passed to Tweens.value(), or zero, transparent black, or identity for the named value helpers. They add by_value to initial_value. The catalog lists them.

When tweens compete

Two tweens may animate the same property. Tweens write in the order they started, so each update the one started last wins. Component paths, such as position:x or modulate:a, read the other components on every write, so an x tween and a y tween combine.