Implement AnimatedSprite pause() and resume()

godotengine · Jan 9, 2022 · ca49be3 · ca49be3
1 parent b6b81e8
commit ca49be3
Show file tree

Hide file tree

Showing 6 changed files with 80 additions and 42 deletions.
diff --git a/doc/classes/AnimatedSprite2D.xml b/doc/classes/AnimatedSprite2D.xml
@@ -12,18 +12,30 @@
 		<link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/515</link>
 	</tutorials>
 	<methods>
-		<method name="play">
+		<method name="pause">
 			<return type="void" />
-			<argument index="0" name="anim" type="StringName" default="&amp;&quot;&quot;" />
+			<description>
+				Pauses the current animation (does not reset the frame counter). See [method stop] for stopping the animation and resetting the frame counter.
+			</description>
+		</method>
+		<method name="resume">
+			<return type="void" />
+			<description>
+				Resumes a paused animation. See [method pause].
+			</description>
+		</method>
+		<method name="start">
+			<return type="void" />
+			<argument index="0" name="animation" type="StringName" default="&amp;&quot;&quot;" />
 			<argument index="1" name="backwards" type="bool" default="false" />
 			<description>
-				Plays the animation named [code]anim[/code]. If no [code]anim[/code] is provided, the current animation is played. If [code]backwards[/code] is [code]true[/code], the animation will be played in reverse.
+				Starts playing the specified [code]animation[/code] or the current [member animation] if none is specified. Plays the animation from the beginning or the end if [code]backwards[/code] is [code]true[/code]. See [method resume] for resuming an animation from the current frame counter.
 			</description>
 		</method>
 		<method name="stop">
 			<return type="void" />
 			<description>
-				Stops the current animation (does not reset the frame counter).
+				Stops the current animation and resets the frame counter to [code]0[/code] or the last frame if the animation was playing backwards. See [method start] for playing an animation backwards. See [method pause] for pausing an animation without resetting the frame counter.
 			</description>
 		</method>
 	</methods>

diff --git a/doc/classes/AnimatedSprite3D.xml b/doc/classes/AnimatedSprite3D.xml
@@ -10,23 +10,29 @@
 		<link title="2D Sprite animation (also applies to 3D)">$DOCS_URL/tutorials/2d/2d_sprite_animation.html</link>
 	</tutorials>
 	<methods>
-		<method name="is_playing" qualifiers="const">
-			<return type="bool" />
+		<method name="pause">
+			<return type="void" />
+			<description>
+				Pauses the current animation (does not reset the frame counter). See [method stop] for stopping the animation and resetting the frame counter.
+			</description>
+		</method>
+		<method name="resume">
+			<return type="void" />
 			<description>
-				Returns [code]true[/code] if an animation is currently being played.
+				Resumes a paused animation. See [method pause].
 			</description>
 		</method>
-		<method name="play">
+		<method name="start">
 			<return type="void" />
-			<argument index="0" name="anim" type="StringName" default="&amp;&quot;&quot;" />
+			<argument index="0" name="animation" type="StringName" default="&amp;&quot;&quot;" />
 			<description>
-				Plays the animation named [code]anim[/code]. If no [code]anim[/code] is provided, the current animation is played.
+				Starts playing the specified [code]animation[/code] or the current [member animation] if none is specified. Plays the animation from the beginning. See [method resume] for resuming an animation from the current frame counter.
 			</description>
 		</method>
 		<method name="stop">
 			<return type="void" />
 			<description>
-				Stops the current animation (does not reset the frame counter).
+				Stops the current animation and resets the frame counter to [code]0[/code]. See [method pause] for pausing an animation without resetting the frame counter.
 			</description>
 		</method>
 	</methods>
@@ -40,7 +46,7 @@
 		<member name="frames" type="SpriteFrames" setter="set_sprite_frames" getter="get_sprite_frames">
 			The [SpriteFrames] resource containing the animation(s).
 		</member>
-		<member name="playing" type="bool" setter="_set_playing" getter="_is_playing" default="false">
+		<member name="playing" type="bool" setter="set_playing" getter="is_playing" default="false">
 			If [code]true[/code], the [member animation] is currently playing.
 		</member>
 	</members>

diff --git a/scene/2d/animated_sprite_2d.cpp b/scene/2d/animated_sprite_2d.cpp
@@ -375,27 +375,36 @@ void AnimatedSprite2D::set_playing(bool p_playing) {
 	set_process_internal(playing);
 }
 
-bool AnimatedSprite2D::is_playing() const {
-	return playing;
-}
-
-void AnimatedSprite2D::play(const StringName &p_animation, const bool p_backwards) {
-	backwards = p_backwards;
-
+void AnimatedSprite2D::start(const StringName &p_animation, const bool p_backwards) {
 	if (p_animation) {
 		set_animation(p_animation);
-		if (frames.is_valid() && backwards && get_frame() == 0) {
-			set_frame(frames->get_frame_count(p_animation) - 1);
-		}
 	}
+	backwards = p_backwards;
+	if (backwards && frames.is_valid()) {
+		set_frame(frames->get_frame_count(p_animation) - 1);
+	} else {
+		set_frame(0);
+	}
+	set_playing(true);
+}
+
+void AnimatedSprite2D::pause() {
+	set_playing(false);
+}
 
+void AnimatedSprite2D::resume() {
 	set_playing(true);
 }
 
 void AnimatedSprite2D::stop() {
+	set_frame(backwards ? (frames->get_frame_count(animation) - 1) : 0);
 	set_playing(false);
 }
 
+bool AnimatedSprite2D::is_playing() const {
+	return playing;
+}
+
 double AnimatedSprite2D::_get_frame_duration() {
 	if (frames.is_valid() && frames->has_animation(animation)) {
 		double speed = frames->get_animation_speed(animation) * speed_scale;
@@ -451,12 +460,13 @@ void AnimatedSprite2D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_animation", "animation"), &AnimatedSprite2D::set_animation);
 	ClassDB::bind_method(D_METHOD("get_animation"), &AnimatedSprite2D::get_animation);
 
+	ClassDB::bind_method(D_METHOD("start", "animation", "backwards"), &AnimatedSprite2D::start, DEFVAL(StringName()), DEFVAL(false));
+	ClassDB::bind_method(D_METHOD("pause"), &AnimatedSprite2D::pause);
+	ClassDB::bind_method(D_METHOD("resume"), &AnimatedSprite2D::resume);
+	ClassDB::bind_method(D_METHOD("stop"), &AnimatedSprite2D::stop);
 	ClassDB::bind_method(D_METHOD("set_playing", "playing"), &AnimatedSprite2D::set_playing);
 	ClassDB::bind_method(D_METHOD("is_playing"), &AnimatedSprite2D::is_playing);
 
-	ClassDB::bind_method(D_METHOD("play", "anim", "backwards"), &AnimatedSprite2D::play, DEFVAL(StringName()), DEFVAL(false));
-	ClassDB::bind_method(D_METHOD("stop"), &AnimatedSprite2D::stop);
-
 	ClassDB::bind_method(D_METHOD("set_centered", "centered"), &AnimatedSprite2D::set_centered);
 	ClassDB::bind_method(D_METHOD("is_centered"), &AnimatedSprite2D::is_centered);
 

diff --git a/scene/2d/animated_sprite_2d.h b/scene/2d/animated_sprite_2d.h
@@ -81,7 +81,9 @@ class AnimatedSprite2D : public Node2D {
 	void set_sprite_frames(const Ref<SpriteFrames> &p_frames);
 	Ref<SpriteFrames> get_sprite_frames() const;
 
-	void play(const StringName &p_animation = StringName(), const bool p_backwards = false);
+	void start(const StringName &p_animation = StringName(), const bool p_backwards = false);
+	void pause();
+	void resume();
 	void stop();
 
 	void set_playing(bool p_playing);

diff --git a/scene/3d/sprite_3d.cpp b/scene/3d/sprite_3d.cpp
@@ -1156,7 +1156,7 @@ void AnimatedSprite3D::_res_changed() {
 	_queue_update();
 }
 
-void AnimatedSprite3D::_set_playing(bool p_playing) {
+void AnimatedSprite3D::set_playing(bool p_playing) {
 	if (playing == p_playing) {
 		return;
 	}
@@ -1165,19 +1165,25 @@ void AnimatedSprite3D::_set_playing(bool p_playing) {
 	set_process_internal(playing);
 }
 
-bool AnimatedSprite3D::_is_playing() const {
-	return playing;
-}
-
-void AnimatedSprite3D::play(const StringName &p_animation) {
+void AnimatedSprite3D::start(const StringName &p_animation) {
 	if (p_animation) {
 		set_animation(p_animation);
 	}
-	_set_playing(true);
+	set_frame(0);
+	set_playing(true);
+}
+
+void AnimatedSprite3D::pause() {
+	set_playing(false);
+}
+
+void AnimatedSprite3D::resume() {
+	set_playing(true);
 }
 
 void AnimatedSprite3D::stop() {
-	_set_playing(false);
+	set_frame(0);
+	set_playing(false);
 }
 
 bool AnimatedSprite3D::is_playing() const {
@@ -1233,11 +1239,11 @@ void AnimatedSprite3D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_animation", "animation"), &AnimatedSprite3D::set_animation);
 	ClassDB::bind_method(D_METHOD("get_animation"), &AnimatedSprite3D::get_animation);
 
-	ClassDB::bind_method(D_METHOD("_set_playing", "playing"), &AnimatedSprite3D::_set_playing);
-	ClassDB::bind_method(D_METHOD("_is_playing"), &AnimatedSprite3D::_is_playing);
-
-	ClassDB::bind_method(D_METHOD("play", "anim"), &AnimatedSprite3D::play, DEFVAL(StringName()));
+	ClassDB::bind_method(D_METHOD("start", "animation"), &AnimatedSprite3D::start, DEFVAL(StringName()));
+	ClassDB::bind_method(D_METHOD("pause"), &AnimatedSprite3D::pause);
+	ClassDB::bind_method(D_METHOD("resume"), &AnimatedSprite3D::resume);
 	ClassDB::bind_method(D_METHOD("stop"), &AnimatedSprite3D::stop);
+	ClassDB::bind_method(D_METHOD("set_playing", "playing"), &AnimatedSprite3D::set_playing);
 	ClassDB::bind_method(D_METHOD("is_playing"), &AnimatedSprite3D::is_playing);
 
 	ClassDB::bind_method(D_METHOD("set_frame", "frame"), &AnimatedSprite3D::set_frame);
@@ -1251,7 +1257,7 @@ void AnimatedSprite3D::_bind_methods() {
 	ADD_PROPERTY(PropertyInfo(Variant::OBJECT, "frames", PROPERTY_HINT_RESOURCE_TYPE, "SpriteFrames"), "set_sprite_frames", "get_sprite_frames");
 	ADD_PROPERTY(PropertyInfo(Variant::STRING, "animation"), "set_animation", "get_animation");
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "frame"), "set_frame", "get_frame");
-	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "playing"), "_set_playing", "_is_playing");
+	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "playing"), "set_playing", "is_playing");
 }
 
 AnimatedSprite3D::AnimatedSprite3D() {

diff --git a/scene/3d/sprite_3d.h b/scene/3d/sprite_3d.h
@@ -212,8 +212,6 @@ class AnimatedSprite3D : public SpriteBase3D {
 	void _res_changed();
 
 	void _reset_timeout();
-	void _set_playing(bool p_playing);
-	bool _is_playing() const;
 
 	RID last_shader;
 	RID last_texture;
@@ -228,8 +226,12 @@ class AnimatedSprite3D : public SpriteBase3D {
 	void set_sprite_frames(const Ref<SpriteFrames> &p_frames);
 	Ref<SpriteFrames> get_sprite_frames() const;
 
-	void play(const StringName &p_animation = StringName());
+	void start(const StringName &p_animation = StringName());
+	void pause();
+	void resume();
 	void stop();
+
+	void set_playing(bool p_playing);
 	bool is_playing() const;
 
 	void set_animation(const StringName &p_animation);