From 4cb2085543c26fb4315634b9d739b5b05195c415 Mon Sep 17 00:00:00 2001
From: John Pennycook <john.pennycook@gmail.com>
Date: Mon, 20 Mar 2023 20:49:31 -0700
Subject: [PATCH] Add get_loops_left() function to Tween

Implements godotengine/godot-proposals#5141.

Adds a new get_loops_left() function to Tween, allowing developers to
reason about how many times a tweening sequence will repeat and whether
to expect finished or loop_finished as the next signal.

Co-authored-by: Tomek <kobewi4e@gmail.com>
---
 doc/classes/Tween.xml     | 6 ++++++
 scene/animation/tween.cpp | 9 +++++++++
 scene/animation/tween.h   | 1 +
 3 files changed, 16 insertions(+)

diff --git a/doc/classes/Tween.xml b/doc/classes/Tween.xml
index f091ce66f85..7e313c3d4c9 100644
--- a/doc/classes/Tween.xml
+++ b/doc/classes/Tween.xml
@@ -131,6 +131,12 @@
 				Returns [code]true[/code] if the [Tween] still has [Tweener]s that haven't finished.
 			</description>
 		</method>
+		<method name="get_loops_left" qualifiers="const">
+			<return type="int" />
+			<description>
+				Returns the number of remaining loops for this [Tween] (see [method set_loops]). A return value of [code]-1[/code] indicates an infinitely looping [Tween], and a return value of [code]0[/code] indicates that the [Tween] has already finished.
+			</description>
+		</method>
 		<method name="get_total_elapsed_time" qualifiers="const">
 			<return type="float" />
 			<description>
diff --git a/scene/animation/tween.cpp b/scene/animation/tween.cpp
index e05c24ae09b..42f03426105 100644
--- a/scene/animation/tween.cpp
+++ b/scene/animation/tween.cpp
@@ -228,6 +228,14 @@ Ref<Tween> Tween::set_loops(int p_loops) {
 	return this;
 }
 
+int Tween::get_loops_left() const {
+	if (loops <= 0) {
+		return -1; // Infinite loop.
+	} else {
+		return loops - loops_done;
+	}
+}
+
 Ref<Tween> Tween::set_speed_scale(float p_speed) {
 	speed_scale = p_speed;
 	return this;
@@ -442,6 +450,7 @@ void Tween::_bind_methods() {
 
 	ClassDB::bind_method(D_METHOD("set_parallel", "parallel"), &Tween::set_parallel, DEFVAL(true));
 	ClassDB::bind_method(D_METHOD("set_loops", "loops"), &Tween::set_loops, DEFVAL(0));
+	ClassDB::bind_method(D_METHOD("get_loops_left"), &Tween::get_loops_left);
 	ClassDB::bind_method(D_METHOD("set_speed_scale", "speed"), &Tween::set_speed_scale);
 	ClassDB::bind_method(D_METHOD("set_trans", "trans"), &Tween::set_trans);
 	ClassDB::bind_method(D_METHOD("set_ease", "ease"), &Tween::set_ease);
diff --git a/scene/animation/tween.h b/scene/animation/tween.h
index b7dc941111f..87fdbe52fd5 100644
--- a/scene/animation/tween.h
+++ b/scene/animation/tween.h
@@ -160,6 +160,7 @@ public:
 
 	Ref<Tween> set_parallel(bool p_parallel);
 	Ref<Tween> set_loops(int p_loops);
+	int get_loops_left() const;
 	Ref<Tween> set_speed_scale(float p_speed);
 	Ref<Tween> set_trans(TransitionType p_trans);
 	TransitionType get_trans();