Merge pull request #91765 from chocola-mint/feat-markers

Add markers to Animation

2 files changed, 160 insertions, 0 deletions

diff --git a/doc/classes/Animation.xml b/doc/classes/Animation.xml
index 887e9cda81..609d7eff39 100644
--- a/doc/classes/Animation.xml
+++ b/doc/classes/Animation.xml
@@ -34,6 +34,14 @@
 		<link title="Animation documentation index">$DOCS_URL/tutorials/animation/index.html</link>
 	</tutorials>
 	<methods>
+		<method name="add_marker">
+			<return type="void" />
+			<param index="0" name="name" type="StringName" />
+			<param index="1" name="time" type="float" />
+			<description>
+				Adds a marker to this Animation.
+			</description>
+		</method>
 		<method name="add_track">
 			<return type="int" />
 			<param index="0" name="type" type="int" enum="Animation.TrackType" />
@@ -271,12 +279,60 @@
 				Returns the index of the specified track. If the track is not found, return -1.
 			</description>
 		</method>
+		<method name="get_marker_at_time" qualifiers="const">
+			<return type="StringName" />
+			<param index="0" name="time" type="float" />
+			<description>
+				Returns the name of the marker located at the given time.
+			</description>
+		</method>
+		<method name="get_marker_color" qualifiers="const">
+			<return type="Color" />
+			<param index="0" name="name" type="StringName" />
+			<description>
+				Returns the given marker's color.
+			</description>
+		</method>
+		<method name="get_marker_names" qualifiers="const">
+			<return type="PackedStringArray" />
+			<description>
+				Returns every marker in this Animation, sorted ascending by time.
+			</description>
+		</method>
+		<method name="get_marker_time" qualifiers="const">
+			<return type="float" />
+			<param index="0" name="name" type="StringName" />
+			<description>
+				Returns the given marker's time.
+			</description>
+		</method>
+		<method name="get_next_marker" qualifiers="const">
+			<return type="StringName" />
+			<param index="0" name="time" type="float" />
+			<description>
+				Returns the closest marker that comes after the given time. If no such marker exists, an empty string is returned.
+			</description>
+		</method>
+		<method name="get_prev_marker" qualifiers="const">
+			<return type="StringName" />
+			<param index="0" name="time" type="float" />
+			<description>
+				Returns the closest marker that comes before the given time. If no such marker exists, an empty string is returned.
+			</description>
+		</method>
 		<method name="get_track_count" qualifiers="const">
 			<return type="int" />
 			<description>
 				Returns the amount of tracks in the animation.
 			</description>
 		</method>
+		<method name="has_marker" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="name" type="StringName" />
+			<description>
+				Returns [code]true[/code] if this Animation contains a marker with the given name.
+			</description>
+		</method>
 		<method name="method_track_get_name" qualifiers="const">
 			<return type="StringName" />
 			<param index="0" name="track_idx" type="int" />
@@ -320,6 +376,13 @@
 				Returns the interpolated position value at the given time (in seconds). The [param track_idx] must be the index of a 3D position track.
 			</description>
 		</method>
+		<method name="remove_marker">
+			<return type="void" />
+			<param index="0" name="name" type="StringName" />
+			<description>
+				Removes the marker with the given name from this Animation.
+			</description>
+		</method>
 		<method name="remove_track">
 			<return type="void" />
 			<param index="0" name="track_idx" type="int" />
@@ -363,6 +426,14 @@
 				Returns the interpolated scale value at the given time (in seconds). The [param track_idx] must be the index of a 3D scale track.
 			</description>
 		</method>
+		<method name="set_marker_color">
+			<return type="void" />
+			<param index="0" name="name" type="StringName" />
+			<param index="1" name="color" type="Color" />
+			<description>
+				Sets the given marker's color.
+			</description>
+		</method>
 		<method name="track_find_key" qualifiers="const">
 			<return type="int" />
 			<param index="0" name="track_idx" type="int" />
diff --git a/doc/classes/AnimationPlayer.xml b/doc/classes/AnimationPlayer.xml
index 1ca8ac2fa5..9aeb4b7162 100644
--- a/doc/classes/AnimationPlayer.xml
+++ b/doc/classes/AnimationPlayer.xml
@@ -75,6 +75,24 @@
 				Returns the node which node path references will travel from.
 			</description>
 		</method>
+		<method name="get_section_end_time" qualifiers="const">
+			<return type="float" />
+			<description>
+				Returns the end time of the section currently being played.
+			</description>
+		</method>
+		<method name="get_section_start_time" qualifiers="const">
+			<return type="float" />
+			<description>
+				Returns the start time of the section currently being played.
+			</description>
+		</method>
+		<method name="has_section" qualifiers="const">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code] if an animation is currently playing with section.
+			</description>
+		</method>
 		<method name="is_playing" qualifiers="const">
 			<return type="bool" />
 			<description>
@@ -110,6 +128,54 @@
 				This method is a shorthand for [method play] with [code]custom_speed = -1.0[/code] and [code]from_end = true[/code], so see its description for more information.
 			</description>
 		</method>
+		<method name="play_section">
+			<return type="void" />
+			<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
+			<param index="1" name="start_time" type="float" default="-1" />
+			<param index="2" name="end_time" type="float" default="-1" />
+			<param index="3" name="custom_blend" type="float" default="-1" />
+			<param index="4" name="custom_speed" type="float" default="1.0" />
+			<param index="5" name="from_end" type="bool" default="false" />
+			<description>
+				Plays the animation with key [param name] and the section starting from [param start_time] and ending on [param end_time]. See also [method play].
+				Setting [param start_time] to a value outside the range of the animation means the start of the animation will be used instead, and setting [param end_time] to a value outside the range of the animation means the end of the animation will be used instead. [param start_time] cannot be equal to [param end_time].
+			</description>
+		</method>
+		<method name="play_section_backwards">
+			<return type="void" />
+			<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
+			<param index="1" name="start_time" type="float" default="-1" />
+			<param index="2" name="end_time" type="float" default="-1" />
+			<param index="3" name="custom_blend" type="float" default="-1" />
+			<description>
+				Plays the animation with key [param name] and the section starting from [param start_time] and ending on [param end_time] in reverse.
+				This method is a shorthand for [method play_section] with [code]custom_speed = -1.0[/code] and [code]from_end = true[/code], see its description for more information.
+			</description>
+		</method>
+		<method name="play_section_with_markers">
+			<return type="void" />
+			<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
+			<param index="1" name="start_marker" type="StringName" default="&amp;&quot;&quot;" />
+			<param index="2" name="end_marker" type="StringName" default="&amp;&quot;&quot;" />
+			<param index="3" name="custom_blend" type="float" default="-1" />
+			<param index="4" name="custom_speed" type="float" default="1.0" />
+			<param index="5" name="from_end" type="bool" default="false" />
+			<description>
+				Plays the animation with key [param name] and the section starting from [param start_marker] and ending on [param end_marker].
+				If the start marker is empty, the section starts from the beginning of the animation. If the end marker is empty, the section ends on the end of the animation. See also [method play].
+			</description>
+		</method>
+		<method name="play_section_with_markers_backwards">
+			<return type="void" />
+			<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
+			<param index="1" name="start_marker" type="StringName" default="&amp;&quot;&quot;" />
+			<param index="2" name="end_marker" type="StringName" default="&amp;&quot;&quot;" />
+			<param index="3" name="custom_blend" type="float" default="-1" />
+			<description>
+				Plays the animation with key [param name] and the section starting from [param start_marker] and ending on [param end_marker] in reverse.
+				This method is a shorthand for [method play_section_with_markers] with [code]custom_speed = -1.0[/code] and [code]from_end = true[/code], see its description for more information.
+			</description>
+		</method>
 		<method name="play_with_capture">
 			<return type="void" />
 			<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
@@ -139,6 +205,12 @@
 				[b]Note:[/b] If a looped animation is currently playing, the queued animation will never play unless the looped animation is stopped somehow.
 			</description>
 		</method>
+		<method name="reset_section">
+			<return type="void" />
+			<description>
+				Resets the current section if section is set.
+			</description>
+		</method>
 		<method name="seek">
 			<return type="void" />
 			<param index="0" name="seconds" type="float" />
@@ -180,6 +252,23 @@
 				Sets the node which node path references will travel from.
 			</description>
 		</method>
+		<method name="set_section">
+			<return type="void" />
+			<param index="0" name="start_time" type="float" default="-1" />
+			<param index="1" name="end_time" type="float" default="-1" />
+			<description>
+				Changes the start and end times of the section being played. The current playback position will be clamped within the new section. See also [method play_section].
+			</description>
+		</method>
+		<method name="set_section_with_markers">
+			<return type="void" />
+			<param index="0" name="start_marker" type="StringName" default="&amp;&quot;&quot;" />
+			<param index="1" name="end_marker" type="StringName" default="&amp;&quot;&quot;" />
+			<description>
+				Changes the start and end markers of the section being played. The current playback position will be clamped within the new section. See also [method play_section_with_markers].
+				If the argument is empty, the section uses the beginning or end of the animation. If both are empty, it means that the section is not set.
+			</description>
+		</method>
 		<method name="stop">
 			<return type="void" />
 			<param index="0" name="keep_state" type="bool" default="false" />