Better API for "if tween then kill" check

[samsface]

Describe the project you are working on

A game that relies heavily on tweens, tweens which frequently need to be stopped and restarted.

For example, when the player hovers over a UI element, a tween starts to scale it. If the player then moves the mouse to hover over a different UI element, we want to stop the original tween and reuse it to start scaling the new element instead.

Describe the problem or limitation you are having in your project

When reusing a tween, we must always type 3 lines of code:

if member_variable_tween:
   member_variable_tween.kill()

member_variable_tween = create_tween()

These three lines of code show up constantly in Godot projects that use tweens.

This leads to two main issues:

• It’s tedious and repetitive to write.
• It’s easy to forget the “if exists, then kill” check, which can introduce subtle bugs.

Describe the feature / enhancement and how it helps to overcome the problem or limitation

Let’s add a new function that lets us kill and create a tween with a one liner.

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

# we can add a new method adjacent to create_tween
member_variable_tween = create_or_replace_tween(member_variable_tween)

# we can add a new param to create_tween, and this would kill the passed tween (I don't really like this option personally but it's shorter to write)
member_variable_tween = create_tween(member_variable_tween)

If this enhancement will not be used often, can it be worked around with a few lines of script?

N/A as this enhancement would be used often.

Is there a reason why this should be core and not an add-on in the asset library?

While it’s trivial to work around with a helper method, this issue is so common for Godot users that it deserves a first-class solution in the engine core.

---

I've read this similar proposal. Not a fan of the approach. Often, I want to rerun the tween but with slightly different parameters, so reusing the exact same tween isn't always ideal.
#8966

[jinyangcruise]

I always use:

if tween:
    if tween.is_running():
        await tween.finished
    tween.kill()
tween = create_tween()

Can I have a new method for this?◖⚆ᴥ⚆◗

[CarpenterBlue]

Sadly, I don't think that is feasible because of the await.

[KeyboardDanni]

+1. I find myself writing a lot of code that looks like this:

if tween:
	tween.kill();
	
tween = create_tween();
tween.set_process_mode(Tween.TWEEN_PROCESS_PHYSICS);
tween.set_ease(Tween.EASE_IN_OUT);
tween.set_trans(Tween.TRANS_SINE);
tween.tween_property(self, "camera_window_current", camera_window_assigned, 0.5);

In my case, not only do I need to manually kill the existing tween, but I also have to set TWEEN_PROCESS_PHYSICS (as the default value of TWEEN_PROCESS_IDLE can cause a wide range of unforeseen problems). Ideally, I should only be doing three things:

1. Creating the new tween, immediately stopping the existing one.
2. Setting the ease and trans properties.
3. Setting the properties to tween.

I wouldn't mind having a function that both kills the existing tween and sets the desired process mode, though I suppose it's not too difficult to work around via script.

I always use:

if tween:
    if tween.is_running():
        await tween.finished
    tween.kill()
tween = create_tween()

Can I have a new method for this?◖⚆ᴥ⚆◗

The call to tween.kill() is largely pointless here as the purpose of kill() is to interrupt a currently running tween. If you wait for the tween to finish, there is nothing to interrupt. This is essentially just adding a second tween to the end of the first one. If you want to sequence a bunch of tweens together, there are better ways to do this, IMO.

If you're doing a tween in response to some gameplay event, typically you want the existing tween to stop immediately. For example, let's say you have a camera that you're slow-panning between several points of interest during a cutscene. If the player advances the dialogue, you want the camera to focus on the next point of interest. Usually, if the camera is mid-pan and you advance the dialogue, you want to interrupt the pan and have the camera immediately proceed toward the second point. If you wait for the first pan to finish completely, it will feel sluggish and confusing.

[Meorge]

The pattern of

if tw: tw.kill()
tw = create_tween()

is so common for me I have a VS Code snippet set up to autogenerate it 😅

This is perhaps best suited to a separate proposal, but for cases like this I could see it being nice to have a way to specify some sort of identifier for a tween. If a new tween is created with the same identifier as the old tween, the old tween would be killed.

[Kaleb-Reid]

I think that godotengine/godot#112075 partially solves this. It allows you to initialize a property with an invalid tween by setting it to Tween.new(), which currently prints an error. If you never set the tween variable to null, then you never need the if tween: part since kill() can be called on invalid tweens no problem. It just cant be called on null.

[Kaleb-Reid]

@KeyboardDanni set_process_mode(), set_ease(), and set_trans() all return the Tween, so

if tween:
	tween.kill();
	
tween = create_tween();
tween.set_process_mode(Tween.TWEEN_PROCESS_PHYSICS);
tween.set_ease(Tween.EASE_IN_OUT);
tween.set_trans(Tween.TRANS_SINE);
tween.tween_property(self, "camera_window_current", camera_window_assigned, 0.5);

Can be shortened to:

if tween:
	tween.kill();
	
tween = create_tween().set_process_mode(Tween.TWEEN_PROCESS_PHYSICS).set_ease(Tween.EASE_IN_OUT).set_trans(Tween.TRANS_SINE);
tween.tween_property(self, "camera_window_current", camera_window_assigned, 0.5);

Or any similar combination to avoid wrapping lines.

Additionally, godotengine/godot#112075 makes it more convenient to do:

tween.kill();
tween = create_tween().set_process_mode(Tween.TWEEN_PROCESS_PHYSICS).set_ease(Tween.EASE_IN_OUT).set_trans(Tween.TRANS_SINE);
tween.tween_property(self, "camera_window_current", camera_window_assigned, 0.5);