godot-tweening

name	godot-tweening
description	Expert blueprint for programmatic animation using Tween for smooth property transitions, UI effects, camera movements, and juice. Covers easing functions, parallel tweens, chaining, and lifecycle management. Use when implementing UI animations OR procedural movement. Keywords Tween, easing, interpolation, EASE_IN_OUT, TRANS_CUBIC, tween_property, tween_callback.

Decision Tree — Tween vs AnimationPlayer

Situation	Choose
One-off UI juice, hover, popup, score count, recoil	Tween (create_tween)
Authored multi-track clips, scrubbable timelines, blend trees	AnimationPlayer / AnimationTree
Camera continuous follow behind a moving target	Camera2D.position_smoothing / spring follow — not a new Tween every _process
Menu motion while Engine.time_scale == 0	Tween with set_ignore_time_scale(true) — MANDATORY time_scale_ignored_ui.gd
Retriggerable property (button spam, dodge cancel)	Kill-before-recreate — MANDATORY safe_tween_interruption.gd
Physics body / net correction motion	TWEEN_PROCESS_PHYSICS + reset_physics_interpolation

Available Scripts

MANDATORY: Read the script for the case above before writing tween glue.

safe_tween_interruption.gd

MANDATORY for any retriggerable tween — kill active tweens before starting new ones.

time_scale_ignored_ui.gd

MANDATORY for pause-menu / time_scale == 0 UI motion.

nested_subtween_cutscene.gd

MANDATORY for composable cutscene timelines via tween_subtween.

parallel_popup_animation.gd

set_parallel(true) + chain() for multi-property UI transitions.

text_counter_method_tween.gd

tween_method for non-property values (score strings).

custom_curve_tween.gd

Curve resources for bespoke easing.

camera_shake_tween_logic.gd

Procedural screen shake with looping tweens (offset, not follow).

relative_recoil_tween.gd

as_relative() / from_current() for recoil nudges.

staggered_inventory_entry.gd

Sequential collection entry on one Tween.

looped_hover_vfx.gd

Infinite ping-pong ambient juice.

juice_manager.gd / tween_builder.gd

Central juice dispatch / builder helpers when many systems share feel presets.

NEVER Do in Tweening

• NEVER instantiate a Tween using Tween.new() — Always use create_tween() or get_tree().create_tween() [3, 4].
• NEVER attempt to reuse a finished Tween — Single-use; recreate to replay [4].
• NEVER manually instantiate PropertyTweener or CallbackTweener — Only via parent Tween methods [5].
• NEVER create an infinite loop containing only 0-duration animations — Freezes the engine [10].
• NEVER use multiple Tweens to animate the same property simultaneously — kill() the old reference first [11, 12].
• NEVER use linear interpolation for UI/Juice — Prefer EASE_OUT + TRANS_QUAD or EASE_IN_OUT + TRANS_CUBIC [22].
• NEVER create tweens in _process without guards — Creating 60 tweens per second will crash the app.
• NEVER skip bind_node(self) for non-global tweens — Binding ensures death with the node [13].
• NEVER use 0-duration tweens for state changes — Set the property directly [20].
• NEVER forget to call chain() when returning from set_parallel(true) [15].

---

Lifecycle Golden Path

var _tween: Tween

func animate_to(pos: Vector2) -> void:
    if _tween and _tween.is_valid():
        _tween.kill()
    _tween = create_tween().bind_node(self)
    _tween.set_ease(Tween.EASE_OUT).set_trans(Tween.TRANS_QUAD)
    _tween.tween_property(self, "position", pos, 0.35)

MANDATORY pattern source: safe_tween_interruption.gd.

Camera Follow (Correct)

Continuous follow is not a Tween job:

extends Camera2D
@export var target: Node2D

func _ready() -> void:
    position_smoothing_enabled = true
    position_smoothing_speed = 5.0

func _physics_process(_delta: float) -> void:
    if target:
        global_position = target.global_position

If you must tween a one-shot camera punch/return, keep one Tween reference and kill before recreate — never create_tween() inside unguarded _process.

Expert Patterns (keep)

Physics-Sync-Tweening

func apply_physics_tween(target: Node3D, start_pos: Vector3, goal: Vector3) -> void:
    target.global_position = start_pos
    target.reset_physics_interpolation()
    var tween := create_tween().bind_node(target)
    tween.set_process_mode(Tween.TWEEN_PROCESS_PHYSICS)
    tween.tween_property(target, "global_position", goal, 0.5)

Juice-Config-Resource

Store duration/trans/ease in a Resource (see juice scripts) so feel is data-driven.

Tween-Event-Sequencing

Parallel block → chain() → interval/callback → exit. Prefer nested_subtween_cutscene.gd for nested modules.

Bezier-Path-Tween

Tween PathFollow2D.progress_ratio instead of hand-rolled Bezier math.

Deep recipes (on demand)

LLM-ignorance rule: if a general agent would not know it before reading, it lives here or in scripts/ — never delete, only move.

Topic	Reference
Chains, kill, gotchas	tween-recipes-and-gotchas.md

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Tween — create_tween, parallel/chain, loops, process mode, ignore_time_scale, and kill/lifecycle rules.
• PropertyTweener — tween_property details: as_relative, from_current, custom interpolators, and per-step ease/trans.
• MethodTweener — tween_method for non-property values (score counters, shader params, Curve-sampled motion).
• CallbackTweener — tween_callback for sequenced side effects without inventing fake 0-duration property steps.
• IntervalTweener — tween_interval delays inside a single Tween timeline.
• SubtweenTweener — tween_subtween for nested cutscene modules under one parent timeline.
• Interpolation — lerp/smoothstep foundations behind easing choices and custom interpolators.
• Beziers, curves and paths — Curve/PathFollow patterns used when property tweens alone cannot describe the path.
• Introduction to the animation features — when Tween juice is enough versus AnimationPlayer/AnimationTree authored tracks.
• Using SceneTree — SceneTree.create_tween and node lifetime when bind_node is not enough.
• Idle and Physics Processing — idle vs physics process modes for TWEEN_PROCESS_PHYSICS sync.
• Physics interpolation quick start guide — reset_physics_interpolation when tweening transforms on interpolated bodies.

Related Skills

Prerequisites

• godot-project-foundations — scene tree, Node ownership, and resource basics before create_tween/bind_node lifecycle patterns.
• godot-gdscript-mastery — typed callables, lambdas, and await/signal idioms used in tween_method and finished handlers.

Complements

• godot-2d-animation — sprite/skeleton motion that often coexists with Tween juice and needs shared kill/lifecycle discipline.
• godot-animation-player — authored clips for complex timelines; Tweens stay for runtime/procedural UI and one-off juice.
• godot-ui-containers — Control size/pivot/layout context for popup scale-fade and staggered inventory entry tweens.
• godot-signal-architecture — finished/callback wiring without dangling connections when Tweens are killed and recreated.
• godot-camera-systems — camera follow, shake offsets, and look targets driven by procedural Tweens.
• godot-resource-data-patterns — JuiceConfig-style Resources that store duration/trans/ease outside gameplay scripts.
• godot-particles — burst timing and one-shot VFX that should start from tween_callback steps, not parallel ad-hoc timers.
• godot-shaders-basics — shader params animated via tween_method / set when property paths are not enough.

Downstream / consumers

• godot-inventory-system — slot/item entry, drag feedback, and equip juice built on staggered and interruptible Tweens.
• godot-genre-card-game — hand arcs, draw/discard flights, and resolve polish that depend on Tween chaining.
• godot-ui-theming — theme-driven hover/focus motion that still needs safe Tween interruption under the same Control.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.