Discourage reusing Tweens

[KoBeWi]

Closes #74245
Hopefully this will discourage people from even thinking about this 🙄

[follower]

A pointer for anyone else looking for more context re: Tween/SceneTreeTween + pause()/stop() code/behaviour, see:

• Split pause() from AnimationPlayer's stop() #71218
• f64dd73

Update: Additionally, the related code has diverged between v4.0 & v3.x backport:

godot/scene/animation/tween.cpp

Lines 156 to 192 in 31eccb5

	void Tween::stop() {
	_stop_internal(true);
	}
	void Tween::pause() {
	_stop_internal(false);
	}
	void Tween::play() {
	ERR_FAIL_COND_MSG(!valid, "Tween invalid. Either finished or created outside scene tree.");
	ERR_FAIL_COND_MSG(dead, "Can't play finished Tween, use stop() first to reset its state.");
	running = true;
	}
	void Tween::kill() {
	running = false; // For the sake of is_running().
	dead = true;
	}
	bool Tween::is_running() {
	return running;
	}
	bool Tween::is_valid() {
	return valid;
	}
	void Tween::clear() {
	valid = false;
	for (List<Ref<Tweener>> &step : tweeners) {
	for (Ref<Tweener> &tweener : step) {
	tweener->clear_tween();
	}
	}
	tweeners.clear();
	}

godot/scene/animation/scene_tree_tween.cpp

Lines 128 to 169 in e90ac4b

	void SceneTreeTween::stop() {
	started = false;
	running = false;
	dead = false;
	total_time = 0;
	}
	void SceneTreeTween::pause() {
	running = false;
	}
	void SceneTreeTween::play() {
	ERR_FAIL_COND_MSG(!valid, "SceneTreeTween invalid. Either finished or created outside scene tree.");
	ERR_FAIL_COND_MSG(dead, "Can't play finished SceneTreeTween, use stop() first to reset its state.");
	running = true;
	}
	void SceneTreeTween::kill() {
	running = false; // For the sake of is_running().
	dead = true;
	}
	bool SceneTreeTween::is_running() const {
	return running;
	}
	bool SceneTreeTween::is_valid() const {
	return valid;
	}
	void SceneTreeTween::clear() {
	valid = false;
	for (int i = 0; i < tweeners.size(); i++) {
	List<Ref<Tweener>> &step = tweeners.write[i];
	for (int j = 0; j < step.size(); j++) {
	Ref<Tweener> &tweener = step[j];
	tweener->clear_tween();
	}
	}
	tweeners.clear();
	}

[KoBeWi]

Ok I reworked the PR. Instead of saying "this is somewhat supported, but don't do it", I removed all documentation notes that imply reusing (pretending it's not supported at all) and only left a comment that it results in undefined behavior.

[bend-n]

just saw some english problems

[bend-n]

Suggested change

	[b]Note:[/b] Tweens are processing after all of nodes in the current frame, i.e. after [method Node._process] or [method Node._physics_process] (depending on [enum TweenProcessMode]).
	[b]Note:[/b] Tweens are processed after all of the nodes in the current frame, i.e. after [method Node._process] or [method Node._physics_process] (depending on [enum TweenProcessMode]).

[YuriSizov]

Overall, this version seems good to me.

[akien-mga]

Thanks!

[naturally-intelligent]

What are best practices for persistent Tweens?

https://godotengine.org/qa/148332/best-practices-for-creating-a-persistent-tween-in-godot-4

I'm kinda stuck because if we are supposed to use AnimationPlayer for this, not sure how to dynamically add Animations at runtime either:

https://godotengine.org/qa/148336/how-can-i-add-animations-to-animationplayer-by-gdscript

[KoBeWi]

The answer is in the docs, although probably not obvious for this particular question:

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

Create the Tween inside play_effect() instead of _ready(). Still store it in a member variable, but use kill() on the old Tween (note that you don't need to check if it's still running).

[YuriSizov]

Cherry-picked for 4.0.1.