Merge pull request godotengine#9161 from godotengine/classref/sync-29b3d9e

classref: Sync with current master branch (29b3d9e)

Author: mhilbrunner

classes/class_animationnode.rst

@@ -25,6 +25,16 @@ Base resource for :ref:`AnimationTree<class_AnimationTree>` nodes. In general, i
 
 Inherit this when creating animation nodes mainly for use in :ref:`AnimationNodeBlendTree<class_AnimationNodeBlendTree>`, otherwise :ref:`AnimationRootNode<class_AnimationRootNode>` should be used instead.
 
+You can access the time information as read-only parameter which is processed and stored in the previous frame for all nodes except :ref:`AnimationNodeOutput<class_AnimationNodeOutput>`.
+
+\ **Note:** If more than two inputs exist in the **AnimationNode**, which time information takes precedence depends on the type of **AnimationNode**.
+
+::
+
+    var current_length = $AnimationTree[parameters/AnimationNodeName/current_length]
+    var current_position = $AnimationTree[parameters/AnimationNodeName/current_position]
+    var current_delta = $AnimationTree[parameters/AnimationNodeName/current_delta]
+
 .. rst-class:: classref-introduction-group
 
 Tutorials
@@ -305,11 +315,13 @@ When inheriting from :ref:`AnimationRootNode<class_AnimationRootNode>`, implemen
 
 :ref:`float<class_float>` **_process**\ (\ time\: :ref:`float<class_float>`, seek\: :ref:`bool<class_bool>`, is_external_seeking\: :ref:`bool<class_bool>`, test_only\: :ref:`bool<class_bool>`\ ) |virtual| |const|
 
+**Deprecated:** Currently this is mostly useless as there is a lack of many APIs to extend AnimationNode by GDScript. It is planned that a more flexible API using structures will be provided in the future.
+
 When inheriting from :ref:`AnimationRootNode<class_AnimationRootNode>`, implement this virtual method to run some code when this animation node is processed. The ``time`` parameter is a relative delta, unless ``seek`` is ``true``, in which case it is absolute.
 
 Here, call the :ref:`blend_input<class_AnimationNode_method_blend_input>`, :ref:`blend_node<class_AnimationNode_method_blend_node>` or :ref:`blend_animation<class_AnimationNode_method_blend_animation>` functions. You can also use :ref:`get_parameter<class_AnimationNode_method_get_parameter>` and :ref:`set_parameter<class_AnimationNode_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).
+This function should return the delta.
 
 .. rst-class:: classref-item-separator
 

classes/class_animationnodeanimation.rst

@@ -40,11 +40,21 @@ Properties
 .. table::
    :widths: auto
 
-   +-------------------------------------------------------+-------------------------------------------------------------------+---------+
-   | :ref:`StringName<class_StringName>`                   | :ref:`animation<class_AnimationNodeAnimation_property_animation>` | ``&""`` |
-   +-------------------------------------------------------+-------------------------------------------------------------------+---------+
-   | :ref:`PlayMode<enum_AnimationNodeAnimation_PlayMode>` | :ref:`play_mode<class_AnimationNodeAnimation_property_play_mode>` | ``0``   |
-   +-------------------------------------------------------+-------------------------------------------------------------------+---------+
+   +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+
+   | :ref:`StringName<class_StringName>`                   | :ref:`animation<class_AnimationNodeAnimation_property_animation>`                     | ``&""``   |
+   +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+
+   | :ref:`LoopMode<enum_Animation_LoopMode>`              | :ref:`loop_mode<class_AnimationNodeAnimation_property_loop_mode>`                     |           |
+   +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+
+   | :ref:`PlayMode<enum_AnimationNodeAnimation_PlayMode>` | :ref:`play_mode<class_AnimationNodeAnimation_property_play_mode>`                     | ``0``     |
+   +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+
+   | :ref:`float<class_float>`                             | :ref:`start_offset<class_AnimationNodeAnimation_property_start_offset>`               |           |
+   +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+
+   | :ref:`bool<class_bool>`                               | :ref:`stretch_time_scale<class_AnimationNodeAnimation_property_stretch_time_scale>`   |           |
+   +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+
+   | :ref:`float<class_float>`                             | :ref:`timeline_length<class_AnimationNodeAnimation_property_timeline_length>`         |           |
+   +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+
+   | :ref:`bool<class_bool>`                               | :ref:`use_custom_timeline<class_AnimationNodeAnimation_property_use_custom_timeline>` | ``false`` |
+   +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+
 
 .. rst-class:: classref-section-separator
 
@@ -103,6 +113,23 @@ Animation to use as an output. It is one of the animations provided by :ref:`Ani
 
 ----
 
+.. _class_AnimationNodeAnimation_property_loop_mode:
+
+.. rst-class:: classref-property
+
+:ref:`LoopMode<enum_Animation_LoopMode>` **loop_mode**
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_loop_mode**\ (\ value\: :ref:`LoopMode<enum_Animation_LoopMode>`\ )
+- :ref:`LoopMode<enum_Animation_LoopMode>` **get_loop_mode**\ (\ )
+
+If :ref:`use_custom_timeline<class_AnimationNodeAnimation_property_use_custom_timeline>` is ``true``, override the loop settings of the original :ref:`Animation<class_Animation>` resource with the value.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_AnimationNodeAnimation_property_play_mode:
 
 .. rst-class:: classref-property
@@ -116,6 +143,80 @@ Animation to use as an output. It is one of the animations provided by :ref:`Ani
 
 Determines the playback direction of the animation.
 
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_AnimationNodeAnimation_property_start_offset:
+
+.. rst-class:: classref-property
+
+:ref:`float<class_float>` **start_offset**
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_start_offset**\ (\ value\: :ref:`float<class_float>`\ )
+- :ref:`float<class_float>` **get_start_offset**\ (\ )
+
+If :ref:`use_custom_timeline<class_AnimationNodeAnimation_property_use_custom_timeline>` is ``true``, offset the start position of the animation.
+
+This is useful for adjusting which foot steps first in 3D walking animations.
+
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_AnimationNodeAnimation_property_stretch_time_scale:
+
+.. rst-class:: classref-property
+
+:ref:`bool<class_bool>` **stretch_time_scale**
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_stretch_time_scale**\ (\ value\: :ref:`bool<class_bool>`\ )
+- :ref:`bool<class_bool>` **is_stretching_time_scale**\ (\ )
+
+If ``true``, scales the time so that the length specified in :ref:`timeline_length<class_AnimationNodeAnimation_property_timeline_length>` is one cycle.
+
+This is useful for matching the periods of walking and running animations.
+
+If ``false``, the original animation length is respected. If you set the loop to :ref:`loop_mode<class_AnimationNodeAnimation_property_loop_mode>`, the animation will loop in :ref:`timeline_length<class_AnimationNodeAnimation_property_timeline_length>`.
+
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_AnimationNodeAnimation_property_timeline_length:
+
+.. rst-class:: classref-property
+
+:ref:`float<class_float>` **timeline_length**
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_timeline_length**\ (\ value\: :ref:`float<class_float>`\ )
+- :ref:`float<class_float>` **get_timeline_length**\ (\ )
+
+If :ref:`use_custom_timeline<class_AnimationNodeAnimation_property_use_custom_timeline>` is ``true``, offset the start position of the animation.
+
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_AnimationNodeAnimation_property_use_custom_timeline:
+
+.. rst-class:: classref-property
+
+:ref:`bool<class_bool>` **use_custom_timeline** = ``false``
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_use_custom_timeline**\ (\ value\: :ref:`bool<class_bool>`\ )
+- :ref:`bool<class_bool>` **is_using_custom_timeline**\ (\ )
+
+If ``true``, :ref:`AnimationNode<class_AnimationNode>` provides an animation based on the :ref:`Animation<class_Animation>` resource with some parameters adjusted.
+
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
 .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`

classes/class_animationnodeoneshot.rst

@@ -96,6 +96,8 @@ Properties
    +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+
    | :ref:`float<class_float>`                         | :ref:`autorestart_random_delay<class_AnimationNodeOneShot_property_autorestart_random_delay>` | ``0.0``   |
    +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+
+   | :ref:`bool<class_bool>`                           | :ref:`break_loop_at_end<class_AnimationNodeOneShot_property_break_loop_at_end>`               | ``false`` |
+   +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+
    | :ref:`Curve<class_Curve>`                         | :ref:`fadein_curve<class_AnimationNodeOneShot_property_fadein_curve>`                         |           |
    +---------------------------------------------------+-----------------------------------------------------------------------------------------------+-----------+
    | :ref:`float<class_float>`                         | :ref:`fadein_time<class_AnimationNodeOneShot_property_fadein_time>`                           | ``0.0``   |
@@ -242,6 +244,23 @@ If :ref:`autorestart<class_AnimationNodeOneShot_property_autorestart>` is ``true
 
 ----
 
+.. _class_AnimationNodeOneShot_property_break_loop_at_end:
+
+.. rst-class:: classref-property
+
+:ref:`bool<class_bool>` **break_loop_at_end** = ``false``
+
+.. rst-class:: classref-property-setget
+
+- |void| **set_break_loop_at_end**\ (\ value\: :ref:`bool<class_bool>`\ )
+- :ref:`bool<class_bool>` **is_loop_broken_at_end**\ (\ )
+
+If ``true``, breaks the loop at the end of the loop cycle for transition, even if the animation is looping.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_AnimationNodeOneShot_property_fadein_curve:
 
 .. rst-class:: classref-property
@@ -272,6 +291,8 @@ Determines how cross-fading between animations is eased. If empty, the transitio
 
 The fade-in duration. For example, setting this to ``1.0`` for a 5 second length animation will produce a cross-fade that starts at 0 second and ends at 1 second during the animation.
 
+\ **Note:** **AnimationNodeOneShot** transitions the current state after the end of the fading. When :ref:`AnimationNodeOutput<class_AnimationNodeOutput>` is considered as the most upstream, so the :ref:`fadein_time<class_AnimationNodeOneShot_property_fadein_time>` is scaled depending on the downstream delta. For example, if this value is set to ``1.0`` and a :ref:`AnimationNodeTimeScale<class_AnimationNodeTimeScale>` with a value of ``2.0`` is chained downstream, the actual processing time will be 0.5 second.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -306,6 +327,8 @@ Determines how cross-fading between animations is eased. If empty, the transitio
 
 The fade-out duration. For example, setting this to ``1.0`` for a 5 second length animation will produce a cross-fade that starts at 4 second and ends at 5 second during the animation.
 
+\ **Note:** **AnimationNodeOneShot** transitions the current state after the end of the fading. When :ref:`AnimationNodeOutput<class_AnimationNodeOutput>` is considered as the most upstream, so the :ref:`fadeout_time<class_AnimationNodeOneShot_property_fadeout_time>` is scaled depending on the downstream delta. For example, if this value is set to ``1.0`` and an :ref:`AnimationNodeTimeScale<class_AnimationNodeTimeScale>` with a value of ``2.0`` is chained downstream, the actual processing time will be 0.5 second.
+
 .. rst-class:: classref-item-separator
 
 ----