# C#: Starting playback

Source: https://tweens.gd/csharp/api/start/

Starting a definition snapshots it into independent playback and returns a handle. A node owns the tweens started on it; a resource tween needs an owner node or a scene tree. [Lifetime & pausing](https://tweens.gd/csharp/lifetime/) introduces ownership.

## On a node

| Entry point | Returns | Purpose |
| --- | --- | --- |
| [`node.Tween(definition, options)`](https://tweens.gd/csharp/api/start/#node-tween-definition-options) | `TweenInstance<TTarget, TValue>` | Start one definition |
| [`node.Tween(first, second, ...rest)`](https://tweens.gd/csharp/api/start/#node-tween-first-second-rest) | `Group` | Start several definitions as one [group](https://tweens.gd/csharp/api/groups/) |
| [`node.Tween(options, first, second, ...rest)`](https://tweens.gd/csharp/api/start/#node-tween-options-first-second-rest) | `Group` | The same, with playback options before the `params` list |
| [`node.Tween(definitions, options)`](https://tweens.gd/csharp/api/start/#node-tween-definitions-options) | `Group` | Start a list of definitions as one group |
| [`node.Chain(definitions, options)`](https://tweens.gd/csharp/api/start/#node-chain-definitions-options) | `Chain` | Start a list as one [linked timeline](https://tweens.gd/csharp/api/chains/) |

`options` is an optional [`PlaybackOptions`](https://tweens.gd/csharp/api/start/#playback-options). `TTarget` is the class the definition targets, which can be a base class of the node: starting a `Tweens.Position2D` on a `Sprite2D` returns a `TweenInstance<Node2D, Vector2>`.

## Shorthand methods

Every catalog definition also has a method that defines and starts it in one call, such as `TweenPosition` or `TweenModulateAlpha`. Each has three overloads:

| Method | Configure with |
| --- | --- |
| [`TweenPosition(to, duration, configure, playback)`](https://tweens.gd/csharp/api/start/#tweenposition-to-duration-configure-playback) | A callback that receives the mutable definition before it starts, such as `o => o.Fill = FillMode.Both` |
| [`TweenPosition(to, duration, ease, delay, playback)`](https://tweens.gd/csharp/api/start/#tweenposition-to-duration-ease-delay-playback) | An ease and an optional delay |
| [`TweenPosition(to, duration, options, playback)`](https://tweens.gd/csharp/api/start/#tweenposition-to-duration-options-playback) | A shared [`TweenOptions`](https://tweens.gd/csharp/api/definitions/#shared-options); the `duration` argument wins over its `Duration` |

-   `configure` and `playback` are optional. `to` accepts every [endpoint form](https://tweens.gd/csharp/api/endpoints/#endpoint-forms).
-   `configure` receives a class-based definition such as `Position2DTween`. Write reusable configure methods against [`TweenOptionsBuilder`](https://tweens.gd/csharp/api/custom/#builders).
-   Material shorthand methods take a scene tree or owner node after the duration; see the [material catalog](https://tweens.gd/csharp/nodes/materials/).

## On a resource

| Entry point | Returns | Purpose |
| --- | --- | --- |
| [`resource.Tween(definition, tree, owner, options)`](https://tweens.gd/csharp/api/start/#resource-tween-definition-tree-owner-options) | `TweenInstance<TResource, TValue>` | Follow the tree’s lifetime, or the optional owner’s |
| [`resource.Tween(definition, owner, options)`](https://tweens.gd/csharp/api/start/#resource-tween-definition-owner-options) | `TweenInstance<TResource, TValue>` | Stop when the owner leaves the tree |
| [`owner.Tween(resource, definition, options)`](https://tweens.gd/csharp/api/start/#owner-tween-resource-definition-options) | `TweenInstance<TResource, TValue>` | The same, written owner first |
| [`resource.Chain(definitions, owner, options)`](https://tweens.gd/csharp/api/start/#resource-chain-definitions-owner-options) | `Chain` | Start a linked timeline on a resource |

To play several resource tweens as one step, combine their handles with `Group.Of`.

## Group, cancel, count

| Entry point | Returns | Purpose |
| --- | --- | --- |
| [`Group.Of(tweens)`](https://tweens.gd/csharp/api/start/#group-of-tweens) | `Group` | Treat running tweens, on any targets, as one step |
| [`node.CancelTweens(includeChildren)`](https://tweens.gd/csharp/api/start/#node-canceltweens-includechildren) | `void` | Cancel the automatic playback this node owns, and optionally its descendants’ |
| [`TweenRuntime.GetActiveCount(node)`](https://tweens.gd/csharp/api/start/#tweenruntime-getactivecount-node) | `int` | Count the unfinished tweens of the node’s scene tree |

## Playback options

`PlaybackOptions` is a readonly record struct holding one start’s clock and pause policy, apart from the reusable motion. A Chain has one policy for every entry.

```csharp
var physics = new PlaybackOptions { ProcessMode = TweenProcessMode.Physics };
sprite.Tween(new Tweens.Position2D((100, 0), 1), physics);
```

| Member | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`ProcessMode`](https://tweens.gd/csharp/api/start/#processmode) | `TweenProcessMode` | `Process` | Which frames advance playback |
| [`PauseMode`](https://tweens.gd/csharp/api/start/#pausemode) | `TweenPauseMode` | `Bound` | Which pause holds playback |
| [`UseUnscaledTime`](https://tweens.gd/csharp/api/start/#useunscaledtime) | `bool` | `false` | Ignore `Engine.TimeScale` |

### TweenProcessMode

| Member | Meaning |
| --- | --- |
| [`TweenProcessMode.Process`](https://tweens.gd/csharp/api/start/#tweenprocessmode-process) | The default. Advance on process frames |
| [`TweenProcessMode.Physics`](https://tweens.gd/csharp/api/start/#tweenprocessmode-physics) | Advance on physics frames |

### TweenPauseMode

| Member | Meaning |
| --- | --- |
| [`TweenPauseMode.Bound`](https://tweens.gd/csharp/api/start/#tweenpausemode-bound) | The default. Follow the owner’s `CanProcess()`: its process mode and tree pause. Without an owner, follow tree pause |
| [`TweenPauseMode.SceneTree`](https://tweens.gd/csharp/api/start/#tweenpausemode-scenetree) | Follow tree pause only |
| [`TweenPauseMode.Always`](https://tweens.gd/csharp/api/start/#tweenpausemode-always) | Play through any pause |

-   Pausing a handle holds it in every mode. `SetProcess(false)` isn’t a pause.
-   The automatic runner updates at process and physics priority 1000, after nodes with default priority.
-   Unscaled process updates use monotonic engine ticks. Unscaled physics updates use `1 / PhysicsTicksPerSecond` per tick, which is simulation time rather than wall-clock time during catch-up.
-   Neither clock setting changes pause or ownership.

## Rules

-   Start a node tween once the node is inside the tree, in `_Ready` or later; starting outside the tree throws. A node always owns its own tweens, and removing or reparenting it ends them.
-   A resource tween ends when its owner leaves the tree, or with its tree. Tweens never duplicate or dispose the resources they animate.
-   Starting snapshots the definition; preparation and capture happen on the first eligible update, before any positive delay. See [copy on start](https://tweens.gd/csharp/api/definitions/#copy-on-start).
-   If starting one definition of a group throws, the members already started are cancelled.
-   Tweens started in a callback or after an await begin on the next eligible update, with no inherited frame time.
-   Start and control tweens on Godot’s main thread; other threads throw.