---
name: tween-animation
description: Use when implementing tweens — property animation, method tweening, chaining, parallel sequences, easing, and common UI/gameplay motion recipes
title: tween-animation
canonical_url: https://skilld.dev/gh/jame581/godotprompter/tween-animation
last_updated: 2026-10-23T04:19:05.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/common-recipes.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/tween-animation/references/common-recipes.md), [references/lifecycle.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/tween-animation/references/lifecycle.md), [references/looping-and-signals.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/tween-animation/references/looping-and-signals.md), [references/property-tweener-modifiers.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/tween-animation/references/property-tweener-modifiers.md).
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/tween-animation`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/tween-animation`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/tween-animation) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/tween-animation`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/tween-animation --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/tween-animation --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Tweens in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.

> **Related skills:** **animation-system** for AnimationPlayer/AnimationTree (keyframe-based), **godot-ui** for UI transitions, **shader-basics** for tweening shader parameters, **camera-system** for camera shake and transitions, **math-essentials** for easing curves and interpolation math, **particles-vfx** for code-driven VFX timing and sequencing.

---

## 1. Core Concepts

### Tween vs AnimationPlayer

| Feature         | Tween (code-driven)                        | AnimationPlayer (data-driven)              |
|-----------------|--------------------------------------------|--------------------------------------------|
| Setup           | Code only — no editor needed               | Animation panel with keyframes             |
| Best for        | Procedural motion, UI transitions, VFX     | Complex multi-track, artist-driven clips   |
| Reusability     | Recreated per use — lightweight            | Saved as resources, reusable across scenes |
| Blending        | No — one tween per property at a time      | Yes — AnimationTree supports blending      |
| Method calls    | `tween_callback()` at any point            | Call Method tracks at keyframed times      |

**Rule of thumb:** Use Tweens for one-off procedural animations (fade in, bounce, slide). Use AnimationPlayer for repeating, artist-tuned animations (walk cycle, attack sequence).

### Creating a Tween

Tweens are created from any `Node` and auto-bind to it. When the node is freed, the tween stops automatically.

```gdscript
# Creates a tween bound to this node
var tween := create_tween()
tween.tween_property(self, "position", Vector2(400, 300), 1.0)
```

```csharp
var tween = CreateTween();
tween.TweenProperty(this, "position", new Vector2(400, 300), 1.0f);
```

> **Important:** Each call to `create_tween()` creates a new tween. Previous tweens on the same property are **not** automatically killed — they compete. Kill old tweens before creating new ones on the same property if you don't want conflicts.

---

## 2. Tweener Types

### tween_property() — Animate any property

```gdscript
var tween := create_tween()
# Animate position over 0.5 seconds
tween.tween_property($Sprite2D, "position", Vector2(200, 100), 0.5)
# Animate modulate alpha (fade out)
tween.tween_property($Sprite2D, "modulate:a", 0.0, 0.3)
```

```csharp
var tween = CreateTween();
tween.TweenProperty(GetNode("Sprite2D"), "position", new Vector2(200, 100), 0.5);
tween.TweenProperty(GetNode("Sprite2D"), "modulate:a", 0.0f, 0.3);
```

**Sub-property access:** Use `:` to target individual components — `"position:x"`, `"modulate:a"`, `"scale:y"`.

### tween_callback() — Call a method at a point in the sequence

```gdscript
var tween := create_tween()
tween.tween_property(self, "position", Vector2.ZERO, 0.5)
tween.tween_callback(func(): print("Arrived!"))
tween.tween_callback(queue_free)
```

```csharp
var tween = CreateTween();
tween.TweenProperty(this, "position", Vector2.Zero, 0.5f);
tween.TweenCallback(Callable.From(() => GD.Print("Arrived!")));
tween.TweenCallback(Callable.From(QueueFree));
```

### tween_interval() — Wait/delay between steps

```gdscript
var tween := create_tween()
tween.tween_property(self, "modulate:a", 0.0, 0.3)  # fade out
tween.tween_interval(1.0)                             # wait 1 second
tween.tween_property(self, "modulate:a", 1.0, 0.3)  # fade back in
```

```csharp
var tween = CreateTween();
tween.TweenProperty(this, "modulate:a", 0.0f, 0.3);
tween.TweenInterval(1.0f);
tween.TweenProperty(this, "modulate:a", 1.0f, 0.3);
```

### tween_method() — Animate a custom method with interpolated values

```gdscript
# Animate a method that receives interpolated float values
func _ready() -> void:
    var tween := create_tween()
    tween.tween_method(_set_health_bar, 100.0, 0.0, 2.0)

func _set_health_bar(value: float) -> void:
    $HealthBar.value = value
    $HealthLabel.text = "%d%%" % int(value)
```

```csharp
public override void _Ready()
{
    var tween = CreateTween();
    tween.TweenMethod(Callable.From<float>(SetHealthBar), 100.0f, 0.0f, 2.0f);
}

private void SetHealthBar(float value)
{
    GetNode<ProgressBar>("HealthBar").Value = value;
    GetNode<Label>("HealthLabel").Text = $"{(int)value}%";
}
```

---

## 3. Sequencing — Chain vs Parallel

### Sequential (Default)

By default, tweeners run **sequentially** — each waits for the previous to finish.

```gdscript
var tween := create_tween()
tween.tween_property(self, "position:x", 300.0, 0.5)   # Step 1
tween.tween_property(self, "position:y", 200.0, 0.5)   # Step 2 (after Step 1)
tween.tween_property(self, "rotation", PI, 0.3)         # Step 3 (after Step 2)
```

### Parallel — Run tweeners simultaneously

#### Option 1: `set_parallel(true)` — All tweeners run at once

```gdscript
var tween := create_tween().set_parallel(true)
tween.tween_property(self, "position", Vector2(300, 200), 0.5)
tween.tween_property(self, "rotation", PI, 0.5)
tween.tween_property(self, "modulate:a", 0.5, 0.5)
```

```csharp
var tween = CreateTween().SetParallel(true);
tween.TweenProperty(this, "position", new Vector2(300, 200), 0.5f);
tween.TweenProperty(this, "rotation", Mathf.Pi, 0.5f);
tween.TweenProperty(this, "modulate:a", 0.5f, 0.5f);
```

#### Option 2: `chain()` — Switch back to sequential mid-tween

```gdscript
var tween := create_tween().set_parallel(true)
# These two run at the same time
tween.tween_property(self, "position", Vector2(300, 200), 0.5)
tween.tween_property(self, "scale", Vector2(2, 2), 0.5)
# Switch back to sequential for the next step
tween.chain().tween_property(self, "modulate:a", 0.0, 0.3)
tween.tween_callback(queue_free)
```

```csharp
var tween = CreateTween().SetParallel(true);
tween.TweenProperty(this, "position", new Vector2(300, 200), 0.5f);
tween.TweenProperty(this, "scale", new Vector2(2, 2), 0.5f);
tween.Chain().TweenProperty(this, "modulate:a", 0.0f, 0.3f);
tween.TweenCallback(Callable.From(QueueFree));
```

#### Option 3: `parallel()` — Make the next tweener parallel with the previous

```gdscript
var tween := create_tween()
tween.tween_property(self, "position", Vector2(300, 200), 0.5)
# This runs at the same time as position, not after
tween.parallel().tween_property(self, "rotation", PI, 0.5)
# This runs after both finish (back to sequential)
tween.tween_callback(func(): print("done"))
```

---

## 4. Easing & Transitions

### Setting Easing

```gdscript
var tween := create_tween()
# Set defaults for the entire tween
tween.set_trans(Tween.TRANS_CUBIC).set_ease(Tween.EASE_OUT)
tween.tween_property(self, "position", Vector2(400, 300), 0.6)
```

```csharp
var tween = CreateTween();
tween.SetTrans(Tween.TransitionType.Cubic).SetEase(Tween.EaseType.Out);
tween.TweenProperty(this, "position", new Vector2(400, 300), 0.6f);
```

### Per-Tweener Override

```gdscript
var tween := create_tween()
# This tweener uses bounce, overriding the tween default
tween.tween_property(self, "position:y", 0.0, 0.5) \
    .set_trans(Tween.TRANS_BOUNCE).set_ease(Tween.EASE_OUT)
```

```csharp
var tween = CreateTween();
tween.TweenProperty(this, "position:y", 0.0f, 0.5f)
    .SetTrans(Tween.TransitionType.Bounce)
    .SetEase(Tween.EaseType.Out);
```

### Transition Types

| Transition       | Character                              | Common Use                          |
|------------------|----------------------------------------|-------------------------------------|
| `TRANS_LINEAR`   | Constant speed                         | Progress bars, timers               |
| `TRANS_SINE`     | Gentle acceleration                    | Subtle UI animations                |
| `TRANS_QUAD`     | Moderate curve                         | General movement                    |
| `TRANS_CUBIC`    | Smooth curve                           | Most UI transitions                 |
| `TRANS_QUART`    | Strong curve                           | Dramatic entrances                  |
| `TRANS_QUINT`    | Very strong curve                      | Emphasis effects                    |
| `TRANS_EXPO`     | Exponential — sharp start/stop         | Snap-to-position                    |
| `TRANS_CIRC`     | Circular — smooth deceleration         | Natural motion                      |
| `TRANS_BACK`     | Overshoots target slightly             | Bouncy UI buttons                   |
| `TRANS_ELASTIC`  | Spring oscillation                     | Playful/cartoon effects             |
| `TRANS_BOUNCE`   | Bounces at the end                     | Dropping objects, landing           |

### Ease Types

| Ease          | Behavior                                |
|---------------|-----------------------------------------|
| `EASE_IN`     | Slow start, fast end                    |
| `EASE_OUT`    | Fast start, slow end (most natural)     |
| `EASE_IN_OUT` | Slow at both ends                       |
| `EASE_OUT_IN` | Fast at both ends (rarely used)         |

> **Most common combo:** `TRANS_CUBIC` + `EASE_OUT` for natural-feeling UI transitions. `TRANS_BACK` + `EASE_OUT` for playful bounce-in effects.

---

## 5. PropertyTweener Modifiers

Each `tween_property()` call returns a `PropertyTweener` you can chain modifiers on: `.from(value)` for a custom start, `.from_current()` to capture current value, `.as_relative()` to add (not replace), `.set_delay(seconds)` to delay this tweener's start.

> See [references/property-tweener-modifiers.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/tween-animation/references/property-tweener-modifiers.md) for full code examples of each modifier.

---

## 6. Looping and Signals

`tween.set_loops(N)` repeats N times (`0` = infinite). Signals: `finished` (whole tween done), `step_finished(idx)` (one step done), `loop_finished(loop_count)` (one full cycle done; not emitted after the last loop, where `finished` fires).

> See [references/looping-and-signals.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/tween-animation/references/looping-and-signals.md) for loop-count semantics and signal wiring.

---

## 7. Tween Lifecycle

Tweens are owned by their host SceneTree. Kill running tweens with `tween.kill()` before starting a new one to avoid stacking. Use `set_pause_mode`, `set_speed_scale` and (Godot 4.4+) `set_ignore_time_scale` for runtime control.

> See [references/lifecycle.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/tween-animation/references/lifecycle.md) for kill/replace patterns, pause modes, speed scale, ignore-time-scale.

### has_tweeners() (Godot 4.7+)

`Tween.has_tweeners()` (const) returns `true` if any `Tweener` has been added to the tween and the tween is valid — useful when tweeners are appended dynamically and the tween can end up empty. Killing an empty tween before it starts prevents errors.

```gdscript
var tween := create_tween()
_add_intro_steps(tween)  # may append zero tweeners
if not tween.has_tweeners():
    tween.kill()
```

```csharp
var tween = CreateTween();
AddIntroSteps(tween); // may append zero tweeners
if (!tween.HasTweeners())
    tween.Kill();
```

---

## 8. Common Recipes

The patterns most projects need: fade in/out, UI panel slide in/out, button press bounce, damage number popup, pulsing/breathing effect, screen shake, shader parameter animation.

> See [references/common-recipes.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/tween-animation/references/common-recipes.md) for ready-to-use code for each recipe.

---

## 9. Common Pitfalls

| Symptom                             | Cause                                            | Fix                                                                |
|-------------------------------------|---------------------------------------------------|--------------------------------------------------------------------|
| Tween jumps or jitters              | Multiple tweens competing on the same property    | Kill the old tween before creating a new one                       |
| Tween does nothing                  | Node was freed before tween finished              | Check `is_valid()` or use `tween_callback` instead of `await`      |
| Tween runs or stops during pause    | Default `TWEEN_PAUSE_BOUND` follows the bound node's `process_mode` | `TWEEN_PAUSE_STOP` to always pause, `TWEEN_PAUSE_PROCESS` to keep running |
| `from()` value ignored              | The `from()` value is applied only when that tweener starts | Set the property to the start value first if it must show earlier |
| Tween doesn't loop smoothly         | End value doesn't match start for seamless loop   | Use `as_relative()` for rotation, or match start/end values        |
| Relative tween drifts over loops    | `as_relative()` accumulates each loop             | Use absolute values for looping; relative for one-shot moves       |
| Callback fires at wrong time        | Callback added to parallel section                | Use `chain()` to switch back to sequential before the callback     |
| Tween property path not found       | Typo or wrong path format                         | Use `"property:component"` — e.g., `"position:x"`, `"modulate:a"` |
| Tween faster/slower than expected   | `Engine.time_scale` affects tween                 | Use `set_ignore_time_scale()` (4.4+) for UI tweens during slow-mo  |

---

## 10. Implementation Checklist

- [ ] Old tweens are killed before creating new ones on the same property
- [ ] Tween references are stored in variables when they need to be killed later
- [ ] Easing is set (`TRANS_CUBIC` + `EASE_OUT` for natural motion, not default `TRANS_LINEAR`)
- [ ] `set_parallel(true)` is used when multiple properties should animate simultaneously
- [ ] `chain()` is used to switch back to sequential after parallel sections
- [ ] `from()` or `from_current()` is used when the start value matters (not just the end value)
- [ ] `as_relative()` is used for incremental movement instead of computing absolute targets
- [ ] Looping tweens use `set_loops()` — not manual recreation
- [ ] Tweens that must run during pause use `set_pause_mode(TWEEN_PAUSE_PROCESS)`
- [ ] `tween_callback(queue_free)` is used at the end of fire-and-forget sequences (damage numbers, particles)
