Add AwaitTweener

[KoBeWi]

Closes godotengine/godot-proposals#7337

Implemented more or less as described in the proposal, see the docs for details.

Using custom_step on the tween should finish the Tweener immediately.

This was not possible, because custom step works as if the time has passed. I could maybe add a method to AwaitTweener to force it to finish, but no other Tweener has such method (though maybe it could be in the base class?).

---

Example:

extends RigidBody2D

func _ready() -> void:
	var tween := create_tween().set_process_mode(Tween.TWEEN_PROCESS_PHYSICS)
	tween.tween_property(self, ^"modulate", Color.RED, 1.0)
	tween.tween_property(self, ^"freeze", false, 0)
	tween.tween_await($"../Area2D".body_entered).set_unbinds(1)
	tween.tween_callback(queue_free)

godot.windows.editor.dev.x86_64_gh2jrUpbxv.mp4

[Marigem]

Thinking about it, the only time I use custom_step on tweens is when I want to instantly finalize an animation in a predictable manner. For example:

func animation():
    tween = create_tween().set_process_mode(Tween.TWEEN_PROCESS_PHYSICS).set_ease(Tween.EASE_IN_OUT).set_trans(Tween.TRANS_SINE)
    tween.tween_property(some_control, "modulate:a", 1.0, 0.25)
    tween.tween_property(some_control, "position:x", final_pos, 0.25)
    tween.tween_property(other_control, "modulate:a", 1.0, 0.25)
    tween.tween_property(other_control, "position:x", final_pos2, 0.25)
    ...
    
func skip_animation():
    if tween:
        while(tween.custom_step(10.0)):
            continue
        tween.kill()

When you use skip_animation(), you can know exactly what the final state of the objects will be.

But if you finish an await tween with custom_step, the object that is being waited on to emit its signal, would still be doing it's thing regardless of the tweener, so the animation would end in an unpredictable state. Maybe custom_step shouldn't do anything for the await tweener and shouldn't be expected to. That also should be noted in the docs if it ends up being the case.

[KoBeWi]

custom_step() will only progress the timeout, it does not affect waiting for the signal. AwaitTweener will wait no matter how much time passes.

[Marigem]

Currently, if the timeout is set to 0, it will skip the check and step won't return false.

bool AwaitTweener::step(double &r_delta) {
	if (timeout > 0) {
		timeout -= r_delta;
		if (timeout <= 0) {
			return false;
		}
	}

[KoBeWi]

Changed. 0 timeout makes the tweener finish immediately, so it's a weird use-case, but why not.

[dalexeev]

Maybe I'm worried for nothing, but wouldn't the name tween_await_signal (and AwaitSignalTweener) be more clear? In GDScript, you can use await with signals, coroutines, and arbitrary values (they will just be passed as is). And tween_await can only be used with signals. Yes, this is checked by the method signature, but not everyone uses typed GDScript, and in some rare cases the error will only occur at runtime. This is just a suggestion, not a request.

[KoBeWi]

The autocompletion type hint appears even if your Tween is not typed (not to mention the argument is literally called signal), so I don't think it will cause confusion: