Merge pull request #76616 from TokageItLab/implement-anim-node-sub2

Implement `AnimationNodeSub2` to `AnimationTree` and allow less or greater value in mathematical `AnimationNode`

doc/classes/AnimationNode.xml

@@ -5,7 +5,7 @@
 	</brief_description>
 	<description>
 		Base resource for [AnimationTree] nodes. In general, it's not used directly, but you can create custom ones with custom blending formulas.
-		Inherit this when creating nodes mainly for use in [AnimationNodeBlendTree], otherwise [AnimationRootNode] should be used instead.
+		Inherit this when creating animation nodes mainly for use in [AnimationNodeBlendTree], otherwise [AnimationRootNode] should be used instead.
 	</description>
 	<tutorials>
 		<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
@@ -14,46 +14,46 @@
 		<method name="_get_caption" qualifiers="virtual const">
 			<return type="String" />
 			<description>
-				When inheriting from [AnimationRootNode], implement this virtual method to override the text caption for this node.
+				When inheriting from [AnimationRootNode], implement this virtual method to override the text caption for this animation node.
 			</description>
 		</method>
 		<method name="_get_child_by_name" qualifiers="virtual const">
 			<return type="AnimationNode" />
 			<param index="0" name="name" type="StringName" />
 			<description>
-				When inheriting from [AnimationRootNode], implement this virtual method to return a child node by its [param name].
+				When inheriting from [AnimationRootNode], implement this virtual method to return a child animation node by its [param name].
 			</description>
 		</method>
 		<method name="_get_child_nodes" qualifiers="virtual const">
 			<return type="Dictionary" />
 			<description>
-				When inheriting from [AnimationRootNode], implement this virtual method to return all children nodes in order as a [code]name: node[/code] dictionary.
+				When inheriting from [AnimationRootNode], implement this virtual method to return all children animation nodes in order as a [code]name: node[/code] dictionary.
 			</description>
 		</method>
 		<method name="_get_parameter_default_value" qualifiers="virtual const">
 			<return type="Variant" />
 			<param index="0" name="parameter" type="StringName" />
 			<description>
-				When inheriting from [AnimationRootNode], implement this virtual method to return the default value of a [param parameter]. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees.
+				When inheriting from [AnimationRootNode], implement this virtual method to return the default value of a [param parameter]. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees.
 			</description>
 		</method>
 		<method name="_get_parameter_list" qualifiers="virtual const">
 			<return type="Array" />
 			<description>
-				When inheriting from [AnimationRootNode], implement this virtual method to return a list of the properties on this node. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. Format is similar to [method Object.get_property_list].
+				When inheriting from [AnimationRootNode], implement this virtual method to return a list of the properties on this animation node. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. Format is similar to [method Object.get_property_list].
 			</description>
 		</method>
 		<method name="_has_filter" qualifiers="virtual const">
 			<return type="bool" />
 			<description>
-				When inheriting from [AnimationRootNode], implement this virtual method to return whether the blend tree editor should display filter editing on this node.
+				When inheriting from [AnimationRootNode], implement this virtual method to return whether the blend tree editor should display filter editing on this animation node.
 			</description>
 		</method>
 		<method name="_is_parameter_read_only" qualifiers="virtual const">
 			<return type="bool" />
 			<param index="0" name="parameter" type="StringName" />
 			<description>
-				When inheriting from [AnimationRootNode], implement this virtual method to return whether the [param parameter] is read-only. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees.
+				When inheriting from [AnimationRootNode], implement this virtual method to return whether the [param parameter] is read-only. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees.
 			</description>
 		</method>
 		<method name="_process" qualifiers="virtual const">
@@ -63,7 +63,7 @@
 			<param index="2" name="is_external_seeking" type="bool" />
 			<param index="3" name="test_only" type="bool" />
 			<description>
-				When inheriting from [AnimationRootNode], implement this virtual method to run some code when this node is processed. The [param time] parameter is a relative delta, unless [param seek] is [code]true[/code], in which case it is absolute.
+				When inheriting from [AnimationRootNode], implement this virtual method to run some code when this animation node is processed. The [param time] parameter is a relative delta, unless [param seek] is [code]true[/code], in which case it is absolute.
 				Here, call the [method blend_input], [method blend_node] or [method blend_animation] functions. You can also use [method get_parameter] and [method set_parameter] to modify local memory.
 				This function should return the time left for the current animation to finish (if unsure, pass the value from the main blend being called).
 			</description>
@@ -72,7 +72,7 @@
 			<return type="bool" />
 			<param index="0" name="name" type="String" />
 			<description>
-				Adds an input to the node. This is only useful for nodes created for use in an [AnimationNodeBlendTree]. If the addition fails, returns [code]false[/code].
+				Adds an input to the animation node. This is only useful for animation nodes created for use in an [AnimationNodeBlendTree]. If the addition fails, returns [code]false[/code].
 			</description>
 		</method>
 		<method name="blend_animation">
@@ -100,7 +100,7 @@
 			<param index="6" name="sync" type="bool" default="true" />
 			<param index="7" name="test_only" type="bool" default="false" />
 			<description>
-				Blend an input. This is only useful for nodes created for an [AnimationNodeBlendTree]. The [param time] parameter is a relative delta, unless [param seek] is [code]true[/code], in which case it is absolute. A filter mode may be optionally passed (see [enum FilterAction] for options).
+				Blend an input. This is only useful for animation nodes created for an [AnimationNodeBlendTree]. The [param time] parameter is a relative delta, unless [param seek] is [code]true[/code], in which case it is absolute. A filter mode may be optionally passed (see [enum FilterAction] for options).
 			</description>
 		</method>
 		<method name="blend_node">
@@ -115,7 +115,7 @@
 			<param index="7" name="sync" type="bool" default="true" />
 			<param index="8" name="test_only" type="bool" default="false" />
 			<description>
-				Blend another animation node (in case this node contains children animation nodes). This function is only useful if you inherit from [AnimationRootNode] instead, else editors will not display your node for addition.
+				Blend another animation node (in case this animation node contains children animation nodes). This function is only useful if you inherit from [AnimationRootNode] instead, else editors will not display your animation node for addition.
 			</description>
 		</method>
 		<method name="find_input" qualifiers="const">
@@ -128,7 +128,7 @@
 		<method name="get_input_count" qualifiers="const">
 			<return type="int" />
 			<description>
-				Amount of inputs in this node, only useful for nodes that go into [AnimationNodeBlendTree].
+				Amount of inputs in this animation node, only useful for animation nodes that go into [AnimationNodeBlendTree].
 			</description>
 		</method>
 		<method name="get_input_name" qualifiers="const">
@@ -142,7 +142,7 @@
 			<return type="Variant" />
 			<param index="0" name="name" type="StringName" />
 			<description>
-				Gets the value of a parameter. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees.
+				Gets the value of a parameter. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees.
 			</description>
 		</method>
 		<method name="is_path_filtered" qualifiers="const">
@@ -194,20 +194,20 @@
 			<param index="0" name="object_id" type="int" />
 			<param index="1" name="name" type="String" />
 			<description>
-				Emitted by nodes that inherit from this class and that have an internal tree when one of their nodes removes. The nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], and [AnimationNodeBlendTree].
+				Emitted by nodes that inherit from this class and that have an internal tree when one of their animation nodes removes. The animation nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], and [AnimationNodeBlendTree].
 			</description>
 		</signal>
 		<signal name="animation_node_renamed">
 			<param index="0" name="object_id" type="int" />
 			<param index="1" name="old_name" type="String" />
 			<param index="2" name="new_name" type="String" />
 			<description>
-				Emitted by nodes that inherit from this class and that have an internal tree when one of their node names changes. The nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], and [AnimationNodeBlendTree].
+				Emitted by nodes that inherit from this class and that have an internal tree when one of their animation node names changes. The animation nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], and [AnimationNodeBlendTree].
 			</description>
 		</signal>
 		<signal name="tree_changed">
 			<description>
-				Emitted by nodes that inherit from this class and that have an internal tree when one of their nodes changes. The nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], [AnimationNodeBlendTree] and [AnimationNodeTransition].
+				Emitted by nodes that inherit from this class and that have an internal tree when one of their animation nodes changes. The animation nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], [AnimationNodeBlendTree] and [AnimationNodeTransition].
 			</description>
 		</signal>
 	</signals>

doc/classes/AnimationNodeAdd2.xml

@@ -4,7 +4,9 @@
 		Blends two animations additively inside of an [AnimationNodeBlendTree].
 	</brief_description>
 	<description>
-		A resource to add to an [AnimationNodeBlendTree]. Blends two animations additively based on an amount value in the [code][0.0, 1.0][/code] range.
+		A resource to add to an [AnimationNodeBlendTree]. Blends two animations additively based on the amount value.
+		If the amount is greater than [code]1.0[/code], the animation connected to "in" port is blended with the amplified animation connected to "add" port.
+		If the amount is less than [code]0.0[/code], the animation connected to "in" port is blended with the inverted animation connected to "add" port.
 	</description>
 	<tutorials>
 		<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>

doc/classes/AnimationNodeAdd3.xml

@@ -4,11 +4,12 @@
 		Blends two of three animations additively inside of an [AnimationNodeBlendTree].
 	</brief_description>
 	<description>
-		A resource to add to an [AnimationNodeBlendTree]. Blends two animations together additively out of three based on a value in the [code][-1.0, 1.0][/code] range.
-		This node has three inputs:
+		A resource to add to an [AnimationNodeBlendTree]. Blends two animations out of three additively out of three based on the amounmt value.
+		This animation node has three inputs:
 		- The base animation to add to
-		- A -add animation to blend with when the blend amount is in the [code][-1.0, 0.0][/code] range.
-		- A +add animation to blend with when the blend amount is in the [code][0.0, 1.0][/code] range
+		- A "-add" animation to blend with when the blend amount is negative
+		- A "+add" animation to blend with when the blend amount is positive
+		If the absolute value of the amount is greater than [code]1.0[/code], the animation connected to "in" port is blended with the amplified animation connected to "-add"/"+add" port.
 	</description>
 	<tutorials>
 		<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>

doc/classes/AnimationNodeBlend2.xml

@@ -4,7 +4,8 @@
 		Blends two animations linearly inside of an [AnimationNodeBlendTree].
 	</brief_description>
 	<description>
-		A resource to add to an [AnimationNodeBlendTree]. Blends two animations linearly based on an amount value in the [code][0.0, 1.0][/code] range.
+		A resource to add to an [AnimationNodeBlendTree]. Blends two animations linearly based on the amount value.
+		In general, the blend value should be in the [code][0.0, 1.0][/code] range. Values outside of this range can blend amplified or inverted animations, however, [AnimationNodeAdd2] works better for this purpose.
 	</description>
 	<tutorials>
 		<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>

doc/classes/AnimationNodeBlend3.xml

@@ -4,11 +4,12 @@
 		Blends two of three animations linearly inside of an [AnimationNodeBlendTree].
 	</brief_description>
 	<description>
-		A resource to add to an [AnimationNodeBlendTree]. Blends two animations together linearly out of three based on a value in the [code][-1.0, 1.0][/code] range.
-		This node has three inputs:
-		- The base animation
-		- A -blend animation to blend with when the blend amount is in the [code][-1.0, 0.0][/code] range.
-		- A +blend animation to blend with when the blend amount is in the [code][0.0, 1.0][/code] range
+		A resource to add to an [AnimationNodeBlendTree]. Blends two animations out of three linearly out of three based on the amounmt value.
+		This animation node has three inputs:
+		- The base animation to blend with
+		- A "-blend" animation to blend with when the blend amount is negative value
+		- A "+blend" animation to blend with when the blend amount is positive value
+		In general, the blend value should be in the [code][-1.0, 1.0][/code] range. Values outside of this range can blend amplified animations, however, [AnimationNodeAdd3] works better for this purpose.
 	</description>
 	<tutorials>
 		<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>

doc/classes/AnimationNodeBlendSpace1D.xml

@@ -91,7 +91,7 @@
 			The interpolation between animations is linear.
 		</constant>
 		<constant name="BLEND_MODE_DISCRETE" value="1" enum="BlendMode">
-			The blend space plays the animation of the node the blending position is closest to. Useful for frame-by-frame 2D animations.
+			The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations.
 		</constant>
 		<constant name="BLEND_MODE_DISCRETE_CARRY" value="2" enum="BlendMode">
 			Similar to [constant BLEND_MODE_DISCRETE], but starts the new animation at the last animation's playback position.

doc/classes/AnimationNodeBlendSpace2D.xml

@@ -136,7 +136,7 @@
 			The interpolation between animations is linear.
 		</constant>
 		<constant name="BLEND_MODE_DISCRETE" value="1" enum="BlendMode">
-			The blend space plays the animation of the node the blending position is closest to. Useful for frame-by-frame 2D animations.
+			The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations.
 		</constant>
 		<constant name="BLEND_MODE_DISCRETE_CARRY" value="2" enum="BlendMode">
 			Similar to [constant BLEND_MODE_DISCRETE], but starts the new animation at the last animation's playback position.

doc/classes/AnimationNodeBlendTree.xml

@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AnimationNodeBlendTree" inherits="AnimationRootNode" version="4.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		A sub-tree of blend type [AnimationNode]s used for complex animations. Used by [AnimationTree].
+		A sub-tree of many type [AnimationNode]s used for complex animations. Used by [AnimationTree].
 	</brief_description>
 	<description>
-		This node may contain a sub-tree of any other blend type nodes, such as [AnimationNodeTransition], [AnimationNodeBlend2], [AnimationNodeBlend3], [AnimationNodeOneShot], etc. This is one of the most commonly used animation node roots.
+		This animation node may contain a sub-tree of any other type animation nodes, such as [AnimationNodeTransition], [AnimationNodeBlend2], [AnimationNodeBlend3], [AnimationNodeOneShot], etc. This is one of the most commonly used animation node roots.
 		An [AnimationNodeOutput] node named [code]output[/code] is created by default.
 	</description>
 	<tutorials>
@@ -17,7 +17,7 @@
 			<param index="1" name="node" type="AnimationNode" />
 			<param index="2" name="position" type="Vector2" default="Vector2(0, 0)" />
 			<description>
-				Adds an [AnimationNode] at the given [param position]. The [param name] is used to identify the created sub-node later.
+				Adds an [AnimationNode] at the given [param position]. The [param name] is used to identify the created sub animation node later.
 			</description>
 		</method>
 		<method name="connect_node">
@@ -34,57 +34,57 @@
 			<param index="0" name="input_node" type="StringName" />
 			<param index="1" name="input_index" type="int" />
 			<description>
-				Disconnects the node connected to the specified input.
+				Disconnects the animation node connected to the specified input.
 			</description>
 		</method>
 		<method name="get_node" qualifiers="const">
 			<return type="AnimationNode" />
 			<param index="0" name="name" type="StringName" />
 			<description>
-				Returns the sub-node with the specified [param name].
+				Returns the sub animation node with the specified [param name].
 			</description>
 		</method>
 		<method name="get_node_position" qualifiers="const">
 			<return type="Vector2" />
 			<param index="0" name="name" type="StringName" />
 			<description>
-				Returns the position of the sub-node with the specified [param name].
+				Returns the position of the sub animation node with the specified [param name].
 			</description>
 		</method>
 		<method name="has_node" qualifiers="const">
 			<return type="bool" />
 			<param index="0" name="name" type="StringName" />
 			<description>
-				Returns [code]true[/code] if a sub-node with specified [param name] exists.
+				Returns [code]true[/code] if a sub animation node with specified [param name] exists.
 			</description>
 		</method>
 		<method name="remove_node">
 			<return type="void" />
 			<param index="0" name="name" type="StringName" />
 			<description>
-				Removes a sub-node.
+				Removes a sub animation node.
 			</description>
 		</method>
 		<method name="rename_node">
 			<return type="void" />
 			<param index="0" name="name" type="StringName" />
 			<param index="1" name="new_name" type="StringName" />
 			<description>
-				Changes the name of a sub-node.
+				Changes the name of a sub animation node.
 			</description>
 		</method>
 		<method name="set_node_position">
 			<return type="void" />
 			<param index="0" name="name" type="StringName" />
 			<param index="1" name="position" type="Vector2" />
 			<description>
-				Modifies the position of a sub-node.
+				Modifies the position of a sub animation node.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="graph_offset" type="Vector2" setter="set_graph_offset" getter="get_graph_offset" default="Vector2(0, 0)">
-			The global offset of all sub-nodes.
+			The global offset of all sub animation nodes.
 		</member>
 	</members>
 	<signals>