# GDScript: Timing

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

Timing places a tween in time: how long each leg takes, when the first one starts, how often it repeats, and what the property shows before and after. [Loops & delays](https://tweens.gd/gdscript/loops/) introduces it.

## Members

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`duration`](https://tweens.gd/gdscript/api/timing/#duration) | `float` | `0.0` | Seconds per leg; zero completes on the first eligible update |
| [`delay`](https://tweens.gd/gdscript/api/timing/#delay) | `float` | `0.0` | Signed wait before the first leg; a negative delay pre-rolls |
| [`offset`](https://tweens.gd/gdscript/api/timing/#offset) | `float` | `0.0` | Start this far into the first forward leg, between zero and `duration`; the delay still comes first |
| [`repeats`](https://tweens.gd/gdscript/api/timing/#repeats) | `int` | `0` | Cycles after the first; `Tweens.INFINITE` (-1) repeats until cancelled |
| [`ping_pong`](https://tweens.gd/gdscript/api/timing/#ping-pong) | `bool` | `false` | Each cycle runs forward, then back |
| [`ping_pong_interval`](https://tweens.gd/gdscript/api/timing/#ping-pong-interval) | `float` | `0.0` | Wait at the far endpoint before returning |
| [`repeat_interval`](https://tweens.gd/gdscript/api/timing/#repeat-interval) | `float` | `0.0` | Wait between cycles, never after the last |
| [`fill`](https://tweens.gd/gdscript/api/timing/#fill) | `Tweens.Fill` | `RETAIN_FINAL_VALUE` | What the property shows during the delay and after [natural completion](https://tweens.gd/gdscript/api/timing/#fill-and-restoration) |

`factor_duration`, `delta_duration`, `factor_delay`, and `delta_delay` adjust `duration` and `delay` for each start; see [variations](https://tweens.gd/gdscript/api/endpoints/#variations).

Times are in seconds, as GDScript `float` values. The helper factories set `duration` and `delay` from their second and fourth arguments, as in `Tweens.position_2d_y(to, 0.8, InOut.SINE, 0.2)`.

## Cycles

A cycle is one leg, or a forward leg, the ping-pong interval, and a return leg. Repeat intervals separate cycles:

```gdscript
var bob := Tweens.position_2d_y()
bob.by_value = -20.0
bob.duration = 0.5
bob.ping_pong = true
bob.ping_pong_interval = 0.2
bob.repeat_interval = 0.3
bob.repeats = 1
```

Interactive preview: https://tweens.gd/gdscript/api/timing/

A ping-pong tween ends at its starting endpoint, so that endpoint is its final value.

## Fill and restoration

| `Tweens.Fill` | During the initial delay | On natural completion |
| --- | --- | --- |
| `RETAIN_FINAL_VALUE` | Leave the property alone | Keep the final value |
| `APPLY_FROM_DURING_DELAY` | Apply `from_value` | Restore the captured initial value |
| `BOTH` | Apply `from_value` | Keep the final value |
| `NONE` | Leave the property alone | Restore the captured initial value |

-   `RETAIN_FINAL_VALUE` is the default. `BOTH` suits staggered entrances: items still waiting show their `from_value`.
-   Cancelling always keeps the latest value, whatever the fill mode.
-   Restoring a shader uniform also restores whether the material had an explicit override; see the [material reference](https://tweens.gd/gdscript/nodes/materials/).

## Rules

-   Non-finite times, and negative durations, intervals, or offsets, reject the start: `Tweens.play()` returns a handle whose `end` reports `FAILED`.
-   An infinitely repeating cycle that takes zero time is rejected.
-   A long frame advances to the correct phase, even across several cycles, without losing time at boundaries. It doesn’t replay the callbacks of the cycles it skipped.
-   In a [Chain](https://tweens.gd/gdscript/api/chains/#timeline), each entry’s delay counts from the end of the entry before it.
-   The clock that advances a tween, and whether time scale applies, is chosen when it starts; see [playback options](https://tweens.gd/gdscript/api/start/#playback-options).