# GDScript: Anatomy of a Tween

Source: https://tweens.gd/gdscript/anatomy/

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.

```gdscript
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](https://tweens.gd/gdscript/api/definitions/) helper has optional arguments for [endpoint](https://tweens.gd/gdscript/api/endpoints/), [timing](https://tweens.gd/gdscript/api/timing/), [easing](https://tweens.gd/gdscript/api/easing/), and [delay](https://tweens.gd/gdscript/api/timing/#delay).
2.  **Initialize.** Set or mutate specifics you want when you’re getting into the weeds during production.
3.  **React.** [Callbacks](https://tweens.gd/gdscript/api/callbacks/) run at fixed points of each playback.
4.  **Tweak.** Last-minute modifications close to the action.
5.  **Start.** [Starting playback](https://tweens.gd/gdscript/api/start/) snapshots the definition and returns a [handle](https://tweens.gd/gdscript/api/handles/).
6.  **Await.** `end` resumes with the [reason](https://tweens.gd/gdscript/api/handles/#tweensreason) 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`](https://tweens.gd/gdscript/api/endpoints/#from-value)\= null
    
    Start value. Leave it out to read the property’s current value as the tween starts.
    
-   [`to_value`](https://tweens.gd/gdscript/api/endpoints/#to-value)\= null
    
    End value. Leave it out to end at the value the property had at start.
    
-   [`by_value`](https://tweens.gd/gdscript/api/endpoints/#by-value)\= null
    
    An offset instead of `to_value`. It adds on top of other changes to the property.
    
-   [`initial_value`](https://tweens.gd/gdscript/api/endpoints/#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`](https://tweens.gd/gdscript/api/timing/#duration)\= 0.0
    
    Seconds per leg. Zero completes on the first update.
    
-   [`delay`](https://tweens.gd/gdscript/api/timing/#delay)\= 0.0
    
    Wait before the first leg. A negative delay starts partway in.
    
-   [`offset`](https://tweens.gd/gdscript/api/timing/#offset)\= 0.0
    
    Start this far into the first forward leg. The delay still comes first.
    
-   [`repeats`](https://tweens.gd/gdscript/api/timing/#repeats)\= 0
    
    Cycles after the first. `Tweens.INFINITE` repeats until cancelled.
    
-   [`ping_pong`](https://tweens.gd/gdscript/api/timing/#ping-pong)\= false
    
    Each cycle runs forward, then back to its start.
    
-   [`ping_pong_interval`](https://tweens.gd/gdscript/api/timing/#ping-pong-interval)\= 0.0
    
    Wait at the far end before returning.
    
-   [`repeat_interval`](https://tweens.gd/gdscript/api/timing/#repeat-interval)\= 0.0
    
    Wait between cycles, never after the last.
    
-   [`fill`](https://tweens.gd/gdscript/api/timing/#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](https://tweens.gd/easings/) draws every curve.

-   [`ease`](https://tweens.gd/gdscript/api/easing/#ease)\= LINEAR
    
    The curve: an In, an Out, or one of each joined with `|`.
    
-   [`blend_type`](https://tweens.gd/gdscript/api/easing/#blend-type)\= MAKIMA
    
    How a mixed pair joins in the middle.
    
-   [`blend`](https://tweens.gd/gdscript/api/easing/#blend)\= 0.1
    
    Width of the join window, from 0 to 1.
    
-   [`skew`](https://tweens.gd/gdscript/api/easing/#skew)\= 0.5
    
    Where the forward leg hands over from In to Out.
    
-   [`weks`](https://tweens.gd/gdscript/api/easing/#weks)\= 0.5
    
    Where the ping-pong return hands over: skew, backwards.
    
-   [`ease_function`](https://tweens.gd/gdscript/api/easing/#ease-function)\= Callable()
    
    Your own function of progress. It replaces `ease`.
    
-   [`curve`](https://tweens.gd/gdscript/api/easing/#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`](https://tweens.gd/gdscript/api/definitions/#color-space)\= Tweens.ColorSpace.OKLAB
    
    Working coordinates for whole-color interpolation.
    
-   [`alpha_mode`](https://tweens.gd/gdscript/api/definitions/#alpha-mode)\= Tweens.AlphaMode.PREMULTIPLIED
    
    Premultiply working coordinates by alpha before interpolation.
    
-   [`color_encoding`](https://tweens.gd/gdscript/api/definitions/#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`](https://tweens.gd/gdscript/api/callbacks/#on-add)
    
    Runs at activation, after the start value is captured.
    
-   [`on_start`](https://tweens.gd/gdscript/api/callbacks/#on-start)
    
    Runs once, when the delay ends and the motion begins.
    
-   [`on_update`](https://tweens.gd/gdscript/api/callbacks/#on-update)
    
    Runs after each write.
    
-   [`on_end`](https://tweens.gd/gdscript/api/callbacks/#on-end)
    
    Runs on natural completion.
    
-   [`on_cancel`](https://tweens.gd/gdscript/api/callbacks/#on-cancel)
    
    Runs when playback stops early: cancelled, target freed, owner exited, or runner disposed.
    
-   [`on_finally`](https://tweens.gd/gdscript/api/callbacks/#on-finally)
    
    Runs last, regardless of how tween playback actually ended.
    
-   [`suppress_callbacks_when_target_invalid`](https://tweens.gd/gdscript/api/callbacks/#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](https://tweens.gd/gdscript/variations/) has a smorgasbord of curves!

-   [`factor_from`](https://tweens.gd/gdscript/api/endpoints/#factor-from)\= 1.0
    
    Multiplies `from_value`.
    
-   [`delta_from`](https://tweens.gd/gdscript/api/endpoints/#delta-from)\= null
    
    Then adds to `from_value`.
    
-   [`factor_to`](https://tweens.gd/gdscript/api/endpoints/#factor-from)\= 1.0
    
    Multiplies `to_value`.
    
-   [`delta_to`](https://tweens.gd/gdscript/api/endpoints/#delta-from)\= null
    
    Then adds to `to_value`.
    
-   [`factor_by`](https://tweens.gd/gdscript/api/endpoints/#factor-from)\= 1.0
    
    Multiplies `by_value`.
    
-   [`delta_by`](https://tweens.gd/gdscript/api/endpoints/#delta-from)\= null
    
    Then adds to `by_value`.
    
-   [`factor_duration`](https://tweens.gd/gdscript/api/endpoints/#factor-duration)\= 1.0
    
    Multiplies `duration`.
    
-   [`delta_duration`](https://tweens.gd/gdscript/api/endpoints/#delta-duration)\= 0.0
    
    Then adds seconds to `duration`.
    
-   [`factor_delay`](https://tweens.gd/gdscript/api/endpoints/#factor-delay)\= 1.0
    
    Multiplies `delay`.
    
-   [`delta_delay`](https://tweens.gd/gdscript/api/endpoints/#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`](https://tweens.gd/gdscript/api/definitions/#property)\= ^""
    
    Property path, set by the named helpers and `Tweens.property()`.
    
-   [`adapter`](https://tweens.gd/gdscript/api/definitions/#adapter)\= null
    
    An adapter for other storage. Use it or `property`, not both.
    
-   [`target_class`](https://tweens.gd/gdscript/api/definitions/#target-class)\= &""
    
    The class a named helper checks at start.
    
-   [`value_type`](https://tweens.gd/gdscript/api/definitions/#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](https://tweens.gd/gdscript/api/definitions/) lists them. Each name links to its row in the reference.