# GDScript: Endpoints & variations

Source: https://tweens.gd/gdscript/api/endpoints/

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](https://tweens.gd/gdscript/anatomy/#endpoints) and [variations](https://tweens.gd/gdscript/variations/) introduce both.

## Endpoints

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`from_value`](https://tweens.gd/gdscript/api/endpoints/#from-value) | `Variant` | `null` | Start value; `null` uses the property’s value at start |
| [`to_value`](https://tweens.gd/gdscript/api/endpoints/#to-value) | `Variant` | `null` | End value; `null` uses the property’s value at start |
| [`by_value`](https://tweens.gd/gdscript/api/endpoints/#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`](https://tweens.gd/gdscript/api/endpoints/#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`](https://tweens.gd/gdscript/api/endpoints/#factor-from), `factor_to`, `factor_by` | `float` | `1.0` | Multiply `from_value`, `to_value`, or `by_value` |
| [`delta_from`](https://tweens.gd/gdscript/api/endpoints/#delta-from), `delta_to`, `delta_by` | `Variant` | `null` | Then add this, in the property’s value type; `null` adds nothing |
| [`factor_duration`](https://tweens.gd/gdscript/api/endpoints/#factor-duration) | `float` | `1.0` | Multiply `duration` |
| [`delta_duration`](https://tweens.gd/gdscript/api/endpoints/#delta-duration) | `float` | `0.0` | Then add these seconds |
| [`factor_delay`](https://tweens.gd/gdscript/api/endpoints/#factor-delay) | `float` | `1.0` | Multiply `delay` |
| [`delta_delay`](https://tweens.gd/gdscript/api/endpoints/#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](https://tweens.gd/gdscript/nodes/values/) 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.