godotengine / godotengine/godot-docs
Tween parallel/chain behavior description is ambiguous
- 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:

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.

- 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.

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.