Merge pull request #73014 from TokageItLab/animation-tree-docs

Add document for AnimationNodes which have setter as request property

5 files changed, 69 insertions, 7 deletions

diff --git a/doc/classes/AnimationNodeOneShot.xml b/doc/classes/AnimationNodeOneShot.xml
index 9e8193868c..0a8998cb9e 100644
--- a/doc/classes/AnimationNodeOneShot.xml
+++ b/doc/classes/AnimationNodeOneShot.xml
@@ -5,6 +5,27 @@
 	</brief_description>
 	<description>
 		A resource to add to an [AnimationNodeBlendTree]. This node will execute a sub-animation and return once it finishes. Blend times for fading in and out can be customized, as well as filters.
+		After setting the request and changing the animation playback, the one-shot node automatically clears the request on the next process frame by setting its [code]request[/code] value to [constant ONE_SHOT_REQUEST_NONE].
+		[codeblocks]
+		[gdscript]
+		# Play child animation connected to "shot" port.
+		animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE)
+		# Alternative syntax (same result as above).
+		animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE
+
+		# Abort child animation connected to "shot" port.
+		animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT)
+		# Alternative syntax (same result as above).
+		animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT
+		[/gdscript]
+		[csharp]
+		// Play child animation connected to "shot" port.
+		animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE);
+
+		// Abort child animation connected to "shot" port.
+		animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT);
+		[/csharp]
+		[/codeblocks]
 	</description>
 	<tutorials>
 		<link title="AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
@@ -13,6 +34,7 @@
 	<members>
 		<member name="autorestart" type="bool" setter="set_autorestart" getter="has_autorestart" default="false">
 			If [code]true[/code], the sub-animation will restart automatically after finishing.
+			In other words, to start auto restarting, the animation must be played once with the [constant ONE_SHOT_REQUEST_FIRE] request. The [constant ONE_SHOT_REQUEST_ABORT] request stops the auto restarting, but it does not disable the [member autorestart] itself. So, the [constant ONE_SHOT_REQUEST_FIRE] request will start auto restarting again.
 		</member>
 		<member name="autorestart_delay" type="float" setter="set_autorestart_delay" getter="get_autorestart_delay" default="1.0">
 			The delay after which the automatic restart is triggered, in seconds.
@@ -21,22 +43,30 @@
 			If [member autorestart] is [code]true[/code], a random additional delay (in seconds) between 0 and this value will be added to [member autorestart_delay].
 		</member>
 		<member name="fadein_time" type="float" setter="set_fadein_time" getter="get_fadein_time" default="0.0">
+			The fade-in duration. For example, setting this to [code]1.0[/code] for a 5 second length animation will produce a crossfade that starts at 0 second and ends at 1 second during the animation.
 		</member>
 		<member name="fadeout_time" type="float" setter="set_fadeout_time" getter="get_fadeout_time" default="0.0">
+			The fade-in duration. For example, setting this to [code]1.0[/code] for a 5 second length animation will produce a crossfade that starts at 4 second and ends at 5 second during the animation.
 		</member>
 		<member name="mix_mode" type="int" setter="set_mix_mode" getter="get_mix_mode" enum="AnimationNodeOneShot.MixMode" default="0">
+			The blend type.
 		</member>
 	</members>
 	<constants>
 		<constant name="ONE_SHOT_REQUEST_NONE" value="0" enum="OneShotRequest">
+			The default state of the request. Nothing is done.
 		</constant>
 		<constant name="ONE_SHOT_REQUEST_FIRE" value="1" enum="OneShotRequest">
+			The request to play the animation connected to "shot" port.
 		</constant>
 		<constant name="ONE_SHOT_REQUEST_ABORT" value="2" enum="OneShotRequest">
+			The request to stop the animation connected to "shot" port.
 		</constant>
 		<constant name="MIX_MODE_BLEND" value="0" enum="MixMode">
+			Blends two animations. See also [AnimationNodeBlend2].
 		</constant>
 		<constant name="MIX_MODE_ADD" value="1" enum="MixMode">
+			Blends two animations additively. See also [AnimationNodeAdd2].
 		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/AnimationNodeSync.xml b/doc/classes/AnimationNodeSync.xml
index 21cac11d50..c0e7741ac0 100644
--- a/doc/classes/AnimationNodeSync.xml
+++ b/doc/classes/AnimationNodeSync.xml
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AnimationNodeSync" inherits="AnimationNode" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		The base class for [AnimationNode] which has more than two input ports and needs to synchronize them.
 	</brief_description>
 	<description>
 	</description>
diff --git a/doc/classes/AnimationNodeTimeSeek.xml b/doc/classes/AnimationNodeTimeSeek.xml
index 0a7da8ba07..5033059927 100644
--- a/doc/classes/AnimationNodeTimeSeek.xml
+++ b/doc/classes/AnimationNodeTimeSeek.xml
@@ -4,25 +4,26 @@
 		A time-seeking animation node to be used with [AnimationTree].
 	</brief_description>
 	<description>
-		This node can be used to cause a seek command to happen to any sub-children of the animation graph. Use this node type to play an [Animation] from the start or a certain playback position inside the [AnimationNodeBlendTree]. After setting the time and changing the animation playback, the seek node automatically goes into sleep mode on the next process frame by setting its [code]seek_position[/code] value to [code]-1.0[/code].
+		This node can be used to cause a seek command to happen to any sub-children of the animation graph. Use this node type to play an [Animation] from the start or a certain playback position inside the [AnimationNodeBlendTree].
+		After setting the time and changing the animation playback, the time seek node automatically goes into sleep mode on the next process frame by setting its [code]seek_request[/code] value to [code]-1.0[/code].
 		[codeblocks]
 		[gdscript]
 		# Play child animation from the start.
-		animation_tree.set("parameters/Seek/seek_position", 0.0)
+		animation_tree.set("parameters/TimeSeek/seek_request", 0.0)
 		# Alternative syntax (same result as above).
-		animation_tree["parameters/Seek/seek_position"] = 0.0
+		animation_tree["parameters/TimeSeek/seek_request"] = 0.0
 
 		# Play child animation from 12 second timestamp.
-		animation_tree.set("parameters/Seek/seek_position", 12.0)
+		animation_tree.set("parameters/TimeSeek/seek_request", 12.0)
 		# Alternative syntax (same result as above).
-		animation_tree["parameters/Seek/seek_position"] = 12.0
+		animation_tree["parameters/TimeSeek/seek_request"] = 12.0
 		[/gdscript]
 		[csharp]
 		// Play child animation from the start.
-		animationTree.Set("parameters/Seek/seek_position", 0.0);
+		animationTree.Set("parameters/TimeSeek/seek_request", 0.0);
 
 		// Play child animation from 12 second timestamp.
-		animationTree.Set("parameters/Seek/seek_position", 12.0);
+		animationTree.Set("parameters/TimeSeek/seek_request", 12.0);
 		[/csharp]
 		[/codeblocks]
 	</description>
diff --git a/doc/classes/AnimationNodeTransition.xml b/doc/classes/AnimationNodeTransition.xml
index bc3e5716dd..7e4d87bd2c 100644
--- a/doc/classes/AnimationNodeTransition.xml
+++ b/doc/classes/AnimationNodeTransition.xml
@@ -5,6 +5,35 @@
 	</brief_description>
 	<description>
 		Simple state machine for cases which don't require a more advanced [AnimationNodeStateMachine]. Animations can be connected to the inputs and transition times can be specified.
+		After setting the request and changing the animation playback, the transition node automatically clears the request on the next process frame by setting its [code]transition_request[/code] value to empty.
+		[codeblocks]
+		[gdscript]
+		# Play child animation connected to "state_2" port.
+		animation_tree.set("parameters/Transition/transition_request", "state_2")
+		# Alternative syntax (same result as above).
+		animation_tree["parameters/Transition/transition_request"] = "state_2"
+
+		# Get current state name.
+		animation_tree.get("parameters/Transition/current_state")
+		# Alternative syntax (same result as above).
+		animation_tree["parameters/Transition/current_state"]
+
+		# Get current state index.
+		animation_tree.get("parameters/Transition/current_index"))
+		# Alternative syntax (same result as above).
+		animation_tree["parameters/Transition/current_index"]
+		[/gdscript]
+		[csharp]
+		// Play child animation connected to "state_2" port.
+		animationTree.Set("parameters/Transition/transition_request", "state_2");
+
+		// Get current state name.
+		animationTree.Get("parameters/Transition/current_state");
+
+		// Get current state index.
+		animationTree.Get("parameters/Transition/current_index");
+		[/csharp]
+		[/codeblocks]
 	</description>
 	<tutorials>
 		<link title="AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
diff --git a/doc/classes/AnimationRootNode.xml b/doc/classes/AnimationRootNode.xml
index d364c15f77..cdcec3787a 100644
--- a/doc/classes/AnimationRootNode.xml
+++ b/doc/classes/AnimationRootNode.xml
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AnimationRootNode" inherits="AnimationNode" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
+		The [AnimationNode] which can be set as the root of an [AnimationTree].
 	</brief_description>
 	<description>
 	</description>