# GDScript: Core API

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

A definition describes a motion, starting it returns a handle, and the handle controls that one playback. These pages list every field and member of each, with the exact rules the guides leave out. [Anatomy of a Tween](https://tweens.gd/gdscript/anatomy/) draws every field.

Examples use the global `Tweens` class in a node script, with targets inside the scene tree. The native types are global too: `TweensGdDefinition`, `TweensGdHandle`, `TweensGdGroup`, `TweensGdChain`, `TweensGdPlaybackOptions`, `TweensGdScheduler`, and `TweensGdCancellation`. Use these names in type annotations.

## Find a page

Describe

-   [Definitions](https://tweens.gd/gdscript/api/definitions/): factories and `with_*()`
-   [Endpoints & variations](https://tweens.gd/gdscript/api/endpoints/): `from_value`, `to_value`, `by_value`
-   [Timing](https://tweens.gd/gdscript/api/timing/): `duration`, `repeats`, `Tweens.Fill`
-   [Callbacks](https://tweens.gd/gdscript/api/callbacks/): `on_add` through `on_finally`

Shape

-   [Easing](https://tweens.gd/gdscript/api/easing/): `In`, `Out`, `BlendType`, curves
-   [Effects](https://tweens.gd/gdscript/api/effects/): punch, shake, and breathe

Play

-   [Starting playback](https://tweens.gd/gdscript/api/start/): `Tweens.play()`, options
-   [Handles](https://tweens.gd/gdscript/api/handles/): `TweensGdHandle`, `Tweens.Reason`
-   [Groups](https://tweens.gd/gdscript/api/groups/): parallel steps
-   [Chains](https://tweens.gd/gdscript/api/chains/): linked timelines

Extend

-   [Adapters](https://tweens.gd/gdscript/api/custom/): `TweensGdAdapter`
-   [Scheduler](https://tweens.gd/gdscript/api/scheduler/): `TweensGdScheduler`
-   [Catalog](https://tweens.gd/gdscript/nodes/): every named helper

## Coming from Godot’s Tween

Both blink a sprite out three times:

Godot's Tween

```gdscript
var tween := sprite.create_tween().set_loops(3)
tween.tween_property(sprite, "modulate:a", 0.0, 0.2).from(1.0)
```

tweens.gd

```gdscript
var blink := Tweens.modulate_alpha(0.0, 0.2).with_from(1.0).with_repeats(2)

Tweens.play(sprite, blink)
```

| Godot’s `Tween` | tweens.gd |
| --- | --- |
| `tween_property(...)` | A [definition](https://tweens.gd/gdscript/api/definitions/), started with `Tweens.play(node, definition)` |
| `from(value)`, `as_relative()` | [`from_value`](https://tweens.gd/gdscript/api/endpoints/#from-value), [`by_value`](https://tweens.gd/gdscript/api/endpoints/#by-value) |
| `set_trans(...)`, `set_ease(...)` | One [`ease`](https://tweens.gd/gdscript/api/easing/#ease), such as `Out.CUBIC` |
| `set_delay(seconds)` | [`delay`](https://tweens.gd/gdscript/api/timing/#delay) |
| `set_loops(count)` | [`repeats`](https://tweens.gd/gdscript/api/timing/#repeats), which counts cycles after the first: `set_loops(3)` is `repeats = 2`, and `set_loops()` is `Tweens.INFINITE` |
| A second tween back to the start | [`ping_pong`](https://tweens.gd/gdscript/api/timing/#ping-pong) |
| `set_parallel()`, `parallel()` | `Tweens.play_all(node, [...])`, or [`Tweens.group()`](https://tweens.gd/gdscript/api/groups/) |
| Tweeners in sequence, `tween_interval(seconds)` | [`Tweens.chain(node, [...])`](https://tweens.gd/gdscript/api/chains/), with a `delay` on the next entry |
| `tween_callback(...)` | A [callback](https://tweens.gd/gdscript/api/callbacks/), such as `on_end` |
| `tween_method(...)` | `Tweens.value()` and the other [callback values](https://tweens.gd/gdscript/nodes/values/) |
| `finished` signal | `await handle.end`, which also resumes when playback stops early |
| `pause()`, `play()`, `kill()` | `pause()`, `resume()`, `cancel()` |
| `set_process_mode`, `set_pause_mode`, `set_ignore_time_scale` | [`Tweens.playback_options()`](https://tweens.gd/gdscript/api/start/#playback-options) |
| `bind_node(node)` | The node you start on, or a resource tween’s [owner](https://tweens.gd/gdscript/api/start/#owners) |

## Differences from C#

Both implementations share their timing, easing, grouping, and lifetime rules, and shared fixtures test both. The differences come from the languages:

| Area | C# | GDScript |
| --- | --- | --- |
| Names | PascalCase: `From`, `To`, `By` | snake\_case: `from_value`, `to_value`, `by_value` |
| Starts | `node.Tween(definition)`, `node.Tween(a, b)` | `Tweens.play(node, definition)`, `Tweens.play_all(node, [a, b])` |
| Definitions | Immutable values, varied with `with` | Mutable objects, varied with `with_*()` copies |
| Type checks | Generic `TweenInstance<TTarget, TValue>`, checked by the compiler | Target class and value type checked when playback starts |
| Failures | Awaiting faults with an exception; `Error` holds it | Awaiting `end` returns `FAILED`; `error` holds a message |
| Script errors | Exceptions from callbacks and setters fault the tween | Detected problems become `FAILED`; other errors stay Godot script errors |
| Integer values | Saturate at 32-bit limits | Saturate at signed 64-bit limits; shader integers stay 32-bit |
| Callbacks | Synchronous | Synchronous; await `end` from a separate coroutine instead of inside one |

See the [C# core API](https://tweens.gd/csharp/api/) for its entry points, and [compatibility](https://tweens.gd/compatibility/) for validated platforms.