Anatomy of a TweenAnatomy of a Tween

Each tween is backed by a definition, describing where it goes, when it plays, how it paces, and what runs along the way. Every field has a default, so a definition sets only what it changes.

Once the addon is installed, you can use the Tweens class in a node script.

var arrive := Tweens.position_2d([400, 180], 0.6, Out.CUBIC)
arrive.delay = 0.1
arrive.ease |= In.LINEAR
arrive.on_end = func(_handle): print("Arrived")

var oops_very_late := arrive.with_delta_delay(2.0)

var movement := Tweens.play(sprite, oops_very_late)

await movement.end

1. Define. A definition helper has optional arguments for endpoint, timing, easing, and delay.
2. Initialize. Set or mutate specifics you want when you’re getting into the weeds during production.
3. React. Callbacks run at fixed points of each playback.
4. Tweak. Last-minute modifications close to the action.
5. Start. Starting playback snapshots the definition and returns a handle.
6. Await. end resumes with the reason playback ended.

Parameters

Tween definitions may consist of dozens of parameters. It’s dangerous to go alone, but the script editor’s autocompletion has got your back. Usually, you’ll find yourself relying on at most three or four of these, but there might be different needs for each tween.

Endpoints

Where the motion starts and ends.

• from_value= null

  Start value. Leave it out to read the property’s current value as the tween starts.

• to_value= null

  End value. Leave it out to end at the value the property had at start.

• by_value= null

  An offset instead of to_value. It adds on top of other changes to the property.

• initial_value= 0.0

  Start value of a callback-only definition, which has no property to read.

Timing

When the motion plays, and how often.

• duration= 0.0

  Seconds per leg. Zero completes on the first update.

• delay= 0.0

  Wait before the first leg. A negative delay starts partway in.

• offset= 0.0

  Start this far into the first forward leg. The delay still comes first.

• repeats= 0

  Cycles after the first. Tweens.INFINITE repeats until cancelled.

• ping_pong= false

  Each cycle runs forward, then back to its start.

• ping_pong_interval= 0.0

  Wait at the far end before returning.

• repeat_interval= 0.0

  Wait between cycles, never after the last.

• fill= RETAIN_FINAL_VALUE

  What the property shows during the delay and after the end. Dashed: the alternatives.

Easing

How the motion paces between its endpoints. The easing playground draws every curve.

• ease= LINEAR

  The curve: an In, an Out, or one of each joined with |.

• blend_type= MAKIMA

  How a mixed pair joins in the middle.

• blend= 0.1

  Width of the join window, from 0 to 1.

• skew= 0.5

  Where the forward leg hands over from In to Out.

• weks= 0.5

  Where the ping-pong return hands over: skew, backwards.

• ease_function= Callable()

  Your own function of progress. It replaces ease.

• curve= null

  A Godot Curve sampled over progress. It replaces ease.

Color interpolation

Whole-color interpolation coordinates, alpha handling, and the target API’s RGB encoding. These settings do not affect scalar alpha channels.

• color_space= Tweens.ColorSpace.OKLAB

  Working coordinates for whole-color interpolation.

• alpha_mode= Tweens.AlphaMode.PREMULTIPLIED

  Premultiply working coordinates by alpha before interpolation.

• color_encoding= Tweens.ColorEncoding.SRGB

  RGB encoding accepted and returned at the Godot API boundary.

Callbacks

Run code at fixed points of each playback.

• on_add

  Runs at activation, after the start value is captured.

• on_start

  Runs once, when the delay ends and the motion begins.

• on_update

  Runs after each write.

• on_end

  Runs on natural completion.

• on_cancel

  Runs when playback stops early: cancelled, target freed, owner exited, or runner disposed.

• on_finally

  Runs last, regardless of how tween playback actually ended.

• suppress_callbacks_when_target_invalid= false

  Skips on_end, on_cancel, and on_finally once the target or owner is gone.

Variations

When a tween starts, each value becomes factor × value + delta. Variations has a smorgasbord of curves!

• factor_from= 1.0

  Multiplies from_value.

• delta_from= null

  Then adds to from_value.

• factor_to= 1.0

  Multiplies to_value.

• delta_to= null

  Then adds to to_value.

• factor_by= 1.0

  Multiplies by_value.

• delta_by= null

  Then adds to by_value.

• factor_duration= 1.0

  Multiplies duration.

• delta_duration= 0.0

  Then adds seconds to duration.

• factor_delay= 1.0

  Multiplies delay.

• delta_delay= 0.0

  Then adds seconds to delay, as in a per-start stagger.

Target

What the definition writes. The named helpers and Tweens.property() set these for you.

• property= ^""

  Property path, set by the named helpers and Tweens.property().

• adapter= null

  An adapter for other storage. Use it or property, not both.

• target_class= &""

  The class a named helper checks at start.

• value_type= TYPE_NIL

  The value type a named helper checks at start.

Most fields have a with_*() copy method, such as with_skew(); the definition reference lists them. Each name links to its row in the reference.