Tween Animation

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

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.

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

csharpCopy code
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

gdscriptCopy code
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)

csharpCopy code
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

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

csharpCopy code
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

gdscriptCopy code
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

csharpCopy code
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

gdscriptCopy code
# 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)

csharpCopy code
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.

gdscriptCopy code
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

gdscriptCopy code
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)

csharpCopy code
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

gdscriptCopy code
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)

csharpCopy code
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

gdscriptCopy code
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

gdscriptCopy code
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)

csharpCopy code
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

gdscriptCopy code
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)

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

Transition Types

Ease Types

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 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).

See 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, set_ignore_time_scale for runtime control.

See 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.

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

csharpCopy code
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 for ready-to-use code for each recipe.

9. Common Pitfalls

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)