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.

Unless you specified global usings, assume using tweens.gd; everywhere.

var arrive = new Tweens.Position2D((400, 180), 0.6, Out.Cubic)
{
    Delay = 0.1,
    Ease = In.Linear | Out.Cubic,
    OnEnd = _ => GD.Print("Arrived"),
};

var oopsVeryLate = arrive with { DeltaDelay = 2.0 };

var movement = sprite.Tween(oopsVeryLate);

await movement.End;

1. Define. A definition struct has optional constructor 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 completes with the reason playback ended.

Parameters

Tween definitions may consist of dozens of parameters. It’s dangerous to go alone, but IntelliSense 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= null

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

• To= null

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

• By= null

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

Timing

When the motion plays, and how often.

• Duration= 0

  Seconds per leg. Zero completes on the first update.

• Delay= 0

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

• Offset= 0

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

• Repeats= 0

  Cycles after the first. TweenOptions.Infinite repeats until cancelled.

• PingPong= false

  Each cycle runs forward, then back to its start.

• PingPongInterval= 0

  Wait at the far end before returning.

• RepeatInterval= 0

  Wait between cycles, never after the last.

• Fill= RetainFinalValue

  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 has a smorgasbord of curves!

• Ease= Linear

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

• BlendType= 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.

• EaseFunction= null

  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.

• ColorSpace= ColorSpace.Oklab

  Working coordinates for whole-color interpolation.

• AlphaMode= AlphaMode.Premultiplied

  Premultiply working coordinates by alpha before interpolation.

• ColorEncoding= ColorEncoding.Srgb

  RGB encoding accepted and returned at the Godot API boundary.

Callbacks

Run code at fixed points of each playback.

• OnAdd

  Runs at activation, after the start value is captured.

• OnStart

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

• OnUpdate

  Runs after each write.

• OnEnd

  Runs on natural completion.

• OnCancel

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

• OnFinally

  Runs last, regardless of how tween playback actually ended.

• SuppressCallbacksWhenTargetInvalid= false

  Skips OnEnd, OnCancel, and OnFinally once the target or owner is gone.

Variations

When a tween starts, each value becomes factor × value + delta. Variations shows them in use.

• FactorFrom= 1

  Multiplies From.

• DeltaFrom= null

  Then adds to From.

• FactorTo= 1

  Multiplies To.

• DeltaTo= null

  Then adds to To.

• FactorBy= 1

  Multiplies By.

• DeltaBy= null

  Then adds to By.

• FactorDuration= 1

  Multiplies Duration.

• DeltaDuration= 0

  Then adds seconds to Duration.

• FactorDelay= 1

  Multiplies Delay.

• DeltaDelay= 0

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

Options holds every timing and easing field as one TweenOptions value. Each name links to its row in the reference.