CancellationCancellation

Awaiting a tween resumes however it ends, cancelled or not. Check the reason when the next step needs the motion to have arrived.

Examples use the global Tweens class in a node script, with targets inside the scene tree.

Cancel playback

movement.cancel() stops a tween where it is and resumes everything awaiting it. Groups and Chains cancel the same way, and Tweens.cancel_tweens(sprite, true) cancels everything a node and its descendants own.

Continue only on success

Godot's Tween

var tween := sprite.create_tween()
tween.tween_property(sprite, "position", Vector2(400, 180), 0.6)
await tween.finished # Not emitted if killed.

sprite.create_tween().tween_property(sprite, "modulate:a", 0.0, 0.3)

tweens.gd

var movement := Tweens.play(sprite, Tweens.position_2d([400, 180], 0.6))
if await movement.end != Tweens.Reason.COMPLETED:
    return

Tweens.play(sprite, Tweens.modulate_alpha(0.0, 0.3))

Godot doesn’t emit finished for a killed tween, so code awaiting it never continues. end always resumes with a reason: here, the fade runs only after the sprite arrives, and never on a sprite freed along the way.

Why it ended

Reason	Meaning
COMPLETED	Reached the natural end
CANCELLED	Cancelled through a handle or cancel_tweens()
TARGET_FREED	Target was queued for deletion, or found freed
OWNER_EXITED	Owner left the tree, or a separate owner was queued for deletion
RUNNER_DISPOSED	Tree or scheduler shut down
FAILED	Start or playback hit a problem; read error
WAIT_CANCELLED	Only the wait was cancelled

Compare against COMPLETED

A node that owns its handle, as node targets do by default, reports TARGET_FREED after queue_free() but OWNER_EXITED after free(), because free() removes it from the tree before deleting it. Test for COMPLETED rather than a particular early reason.

Cancel a wait, not the tween

await movement.wait(cancellation) returns WAIT_CANCELLED once the TweensGdCancellation is cancelled. Playback, other waiters, and the handle’s own reason are unaffected. Groups and Chains have the same method.

HandlesControls, states, wait helpers, and errors.