tweens in Godot - Daniel Lyons' Notes

Term	Code	Meaning
running	`is_running()`	Whether the Tween is currently running, i.e. it wasn't paused and it's not finished.
valid	`is_valid()`	A valid Tween is a Tween contained by the scene tree (i.e. the array from SceneTree.get_processed_tweens will contain this Tween). A Tween might become invalid when it has finished tweening, is killed, or when created with `Tween.new()`. Invalid Tweens can't have Tweeners appended.
kill (invalidate)	`kill()`	Aborts all tweening operations and invalidates the Tween
play	`play()`, `is_playing()`	Resumes a paused or stopped Tween.
pause		Pauses the tweening. The animation can be resumed by using play. Note: If a Tween is paused and not bound to any node, it will exist indefinitely until manually started or invalidated. If you lose a reference to such Tween, you can retrieve it using SceneTree.get_processed_tweens. See Pausing and Pause Modes
`finished()` signal	`finished()` signal	Emitted when the Tween has finished all tweening. Never emitted when the Tween is set to infinite looping (see set_loops).
stop		Stops the tweening and resets the Tween to its initial state. This will not remove any appended Tweeners. Note: If a Tween is stopped and not bound to any node, it will exist indefinitely until manually started or invalidated. If you lose a reference to such Tween, you can retrieve it using SceneTree.get_processed_tweens.
Tweener		Tweeners are objects that perform a specific animating task, e.g. interpolating a property or calling a method at a given time. A Tweener can't be created manually, you need to use a dedicated method from Tween, typically a method that starts with `tween_` (for example `tween_method()` and `tween_property()`).
bind	`tween.bind_node(node)`	Binds this Tween with the given `node`. Tweens are processed directly by the SceneTree, so they run independently of the animated nodes. When you bind a Node with the Tween, the Tween will halt the animation when the object is not inside tree and the Tween will be automatically killed when the bound object is freed. Also TWEEN_PAUSE_BOUND will make the pausing behavior dependent on the bound node. For a shorter way to create and bind a Tween, you can use Node.create_tween.

Tweeners


CallbackTweener	tween_callback(callback: Callable)
IntervalTweener	tween_interval(time: float)
MethodTweener	tween_method(method: Callable, from: Variant, to: Variant, duration: float)
PropertyTweener	tween_property(object: Object, property: NodePath, final_val: Variant, duration: float)

Easing and Transitions

Tween Lifecycle

Tweens Are Processed After All Nodes In The Current Frame

See: Quote from “Tween — Godot Engine (stable) documentation in English”
Note: The tween is processed after all of the nodes in the current frame, i.e. node's Node._process method would be called before the tween (or Node._physics_process depending on the value passed to set_process_mode).

Pausing and Pause Modes

See also:

Conflicts

Only Use One Tween Per Object Property

See: Quote from “Tween — Godot Engine (stable) documentation in English”
You should avoid using more than one Tween per object's property. If two or more tweens animate one property at the same time, the last one created will take priority and assign the final value. If you want to interrupt and restart an animation, consider assigning the Tween to a variable:

var tween
func animate():
	if tween:
		tween.kill() # Abort the previous animation.
	tween = create_tween()

Don't Re-use Tweens

See: Quote from “Tween — Godot Engine (stable) documentation in English”
Note: Tweens are not designed to be re-used and trying to do so results in an undefined behavior. Create a new Tween for each animation and every time you replay an animation from start. Keep in mind that Tweens start immediately, so only create a Tween when you want to start animating.

`get_tree().create_tween()` vs. `create_tween()`

There are three ways to create a Tween but only two are valid:

Tween.new(): This method is invalid.
get_tree().create_tween(): This is calling the create_tween() method on SceneTree.
create_tween(): When you see this in code, it is usually within a script of a Node subclass. Therefore you are calling the create_tween() method from Node (implicitly you are calling self.create_tween() )

How to decide

The general rule of thumb is:

Use create_tween() when the animation is specific to a node and should stop if the node is removed
Use get_tree().create_tween() when you need the animation to persist independently of node lifecycle or when managing animations globally

2. `get_tree().create_tween()`

Remember this is a method on SceneTree. See docs.

This will create and return a new Tween.
This will not automatically kill the Tween when the animation is finished or the Node is freed.
- If you want the Tween to be automatically killed when the Node is freed, use Node.create_tween or Tween.bind_node.

3. `create_tween()`

Remember this is a method on Node. See [docs](get_tree().create_tween() vs. create_tween()).

This will create and return a new Tween
This will also bind the tween to this node (self)
- This means that the Tween will automatically be freed when the Node is freed.
- See Binding Tweens to Nodes for more info
The Tween will start automatically on the next process frame or physics frame (depending on TweenProcessMode).

Binding Tweens to Nodes

See Tween.bind_node for more info on Tweens bound to nodes.

Tween Process Modes (Order of Operations)

See docs.

TWEEN_PROCESS_PHYSICS
- The Tween updates after each physics frame (see Node._physics_process).
TWEEN_PROCESS_IDLE
- The Tween updates after each process frame (see Node._process).

tweens in Godot

Interactive graph

On this page

Deep Dives

Terminology