godotengine / godotengine/godot-docs

Tween parallel/chain behavior description is ambiguous

Open
#10,305 0 comments 1 reaction 0 assignees View on GitHub
area:class reference enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**Your Godot version:** 4.4

**Issue description:**

As of my writing this, this is the documentation for the `Tween.parallel` and `Tween.set_parallel` methods:

> [`Tween parallel()`](https://docs.godotengine.org/en/stable/classes/class_tween.html#class-tween-method-parallel)
> Makes the next Tweener run parallelly to the previous one.

> [`Tween set_parallel(parallel: bool = true)`](https://docs.godotengine.org/en/stable/classes/class_tween.html#class-tween-method-set-parallel)
> If `parallel` is `true`, the Tweeners appended after this method will by default run simultaneously, as opposed to sequentially.
> **Note:** Just like with parallel, the tweener added right before this method will also be part of the parallel step.

I was discussing the precise behavior of the Tween class's parallel functionality with another user, and we agreed that it seemed rather ambiguous. To demonstrate, consider the following scenario:

We create a new tween and add a PropertyTweener to it, then join it with another PropertyTweener, like so:
```gdscript
var tween = create_tween()
tween.tween_property(self, "rotation_degrees", 180.0, 10.0) # A
tween.parallel().tween_property(self, "position:x", 100.0, 5.0) # B
```
The tween's timeline so far would look like this:
![Image](https://github.com/user-attachments/assets/e7f9c457-c4d2-4b5a-a39e-c7fdd607359b)

Now, we chain what we have with a third PropertyTweener:
```gdscript
tween.tween_property(self, "position:x", 200.0, 5.0) # C
```
It seems like there are two possibilities for how the timeline could now look:
- Tweener C plays immediately after Tweener A (technically the "group" that both A and B are part of, but that A defines the total length of since it ends last). Thus, the total length of this Tween is 15 seconds.
![Image](https://github.com/user-attachments/assets/d7c51263-8ba5-4928-adb7-692f5d2c8bbf)

- Tweener C plays immediately after Tweener B, since B was the previous Tweener. Thus, the length of this Tween is 10 seconds, since B and C together play at the same time as A.
![Image](https://github.com/user-attachments/assets/429177e1-4575-4ce8-a568-dffd0f6a63f0)

I created a small test project to find out, and Godot goes with the first case - A and B play simultaneously, and then once A is complete, C plays.

As it currently is, the documentation doesn't make this clear. I think it would be perfectly reasonable to think that C would run after B - in fact, I think that's more what the documentation implies. The wording should be improved so that the order of tweeners is clearer and more correct. If possible, I think it could also help to include small diagrams like what I've provided here.

**URL to the documentation page (if already existing):**

https://docs.godotengine.org/en/stable/classes/class_tween.html#class-tween

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.