Daniel's Notes

tweens in Godot

4 min read

Deep Dives

Terminology

TermCodeMeaning
runningis_running()Whether the Tween is currently running, i.e. it wasn’t paused and it’s not finished.
validis_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
playplay(), is_playing()Resumes a paused or stopped Tween.
pausePauses 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
finished() signalfinished() signalEmitted when the Tween has finished all tweening. Never emitted when the Tween is set to infinite looping (see set_loops).
stopStops 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.
TweenerTweeners 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()).
bindtween.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

CallbackTweenertween_callback(callback: Callable)
IntervalTweenertween_interval(time: float)
MethodTweenertween_method(method: Callable, from: Variant, to: Variant, duration: float)
PropertyTweenertween_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:

  1. Tween.new(): This method is invalid.
  2. get_tree().create_tween(): This is calling the create_tween() method on SceneTree.
  3. 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.

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

Tween Process Modes (Order of Operations)

See docs.

  1. TWEEN_PROCESS_PHYSICS
  2. TWEEN_PROCESS_IDLE
    • The Tween updates after each process frame (see Node._process).

Graph View

Backlinks