diff --git a/tutorials/2d/2d_sprite_animation.rst b/tutorials/2d/2d_sprite_animation.rst index ee2853336ce6..377505f5dd72 100644 --- a/tutorials/2d/2d_sprite_animation.rst +++ b/tutorials/2d/2d_sprite_animation.rst @@ -143,7 +143,7 @@ You will now see your animation under the list of animations in the bottom panel .. image:: img/2d_animation_spritesheet_animation.png -Finally, check Playing on the AnimatedSprite2D in the inspector to see your frog jump! +Finally, check the play button on the SpriteFrames editor to see your frog jump! .. image:: img/2d_animation_play_spritesheet_animation.png diff --git a/tutorials/2d/img/2d_animation_add_from_spritesheet.png b/tutorials/2d/img/2d_animation_add_from_spritesheet.png index 561c6fc71d64..8b5876eaff18 100644 Binary files a/tutorials/2d/img/2d_animation_add_from_spritesheet.png and b/tutorials/2d/img/2d_animation_add_from_spritesheet.png differ diff --git a/tutorials/2d/img/2d_animation_play_spritesheet_animation.png b/tutorials/2d/img/2d_animation_play_spritesheet_animation.png index 2d1ca0ab6fb0..01bc789a0a8a 100644 Binary files a/tutorials/2d/img/2d_animation_play_spritesheet_animation.png and b/tutorials/2d/img/2d_animation_play_spritesheet_animation.png differ diff --git a/tutorials/2d/img/2d_animation_spriteframes.png b/tutorials/2d/img/2d_animation_spriteframes.png index f6731c711e60..a0b5cb8aed34 100644 Binary files a/tutorials/2d/img/2d_animation_spriteframes.png and b/tutorials/2d/img/2d_animation_spriteframes.png differ diff --git a/tutorials/2d/img/2d_animation_spriteframes_done.png b/tutorials/2d/img/2d_animation_spriteframes_done.png index cd1585905bb1..1641aa4306d5 100644 Binary files a/tutorials/2d/img/2d_animation_spriteframes_done.png and b/tutorials/2d/img/2d_animation_spriteframes_done.png differ diff --git a/tutorials/2d/img/2d_animation_spritesheet_animation.png b/tutorials/2d/img/2d_animation_spritesheet_animation.png index fae6904339d2..e4c2836fdc11 100644 Binary files a/tutorials/2d/img/2d_animation_spritesheet_animation.png and b/tutorials/2d/img/2d_animation_spritesheet_animation.png differ diff --git a/tutorials/2d/img/2d_animation_spritesheet_select_rows.png b/tutorials/2d/img/2d_animation_spritesheet_select_rows.png index d38ea63d7b75..4b7a3d63e544 100644 Binary files a/tutorials/2d/img/2d_animation_spritesheet_select_rows.png and b/tutorials/2d/img/2d_animation_spritesheet_select_rows.png differ diff --git a/tutorials/2d/img/2d_animation_spritesheet_selectframes.png b/tutorials/2d/img/2d_animation_spritesheet_selectframes.png index c8944b07dac2..06887629acbc 100644 Binary files a/tutorials/2d/img/2d_animation_spritesheet_selectframes.png and b/tutorials/2d/img/2d_animation_spritesheet_selectframes.png differ diff --git a/tutorials/animation/animation_track_types.rst b/tutorials/animation/animation_track_types.rst index 1c0ebc13fd11..d364160d4cc5 100644 --- a/tutorials/animation/animation_track_types.rst +++ b/tutorials/animation/animation_track_types.rst @@ -13,23 +13,36 @@ player node on top of the default property tracks. .. image:: img/track_types.png +Property Track +-------------- -3D Transform Track ------------------- +The most basic track type. See :ref:`doc_introduction_animation`. + +Position 3D / Rotation 3D / Scale 3D Track +------------------------------------------ -3D transform tracks control the location, rotation, and scale of a 3D object. +These 3D transform tracks control the location, rotation, and scale of a 3D object. They make it easier to animate a 3D object's transform compared to using regular property tracks. -.. image:: img/3D_transform_track.png +It is designed for animations imported from external 3D models and can reduce resource capacity through compression. + +Blend Shape Track +----------------- + +A blend shape track is optimized for animating blend shape in :ref:`MeshInstance `:. -Call Method tracks +It is designed for animations imported from external 3D models and can reduce resource capacity through compression. + +Call Method Track ------------------ -Call method tracks allow you to call a function at a precise time from within an +A call method track allow you to call a function at a precise time from within an animation. For example, you can call ``queue_free()`` to delete a node at the end of a death animation. +.. note:: The events placed on the call method track are not executed when the animation is previewed in the editor for safety. + To create such a track, click "Add Track -> Call Method Track." Then, a window opens and lets you select the node to associate with the track. To call one of the node's methods, right-click the timeline and select "Insert Key". A window @@ -50,24 +63,27 @@ Bezier Curve Track A bezier curve track is similar to a property track, except it allows you to animate a property's value using a bezier curve. +.. note:: Bezier curve track and property track cannot be blended in :ref:`AnimationPlayer ` and :ref:`AnimationTree `. + To create one, click "Add Track -> Bezier Curve Track". As with property tracks, you need to select a node and a property to animate. To open the bezier curve editor, click the curve icon to the right of the animation track. .. image:: img/bezier_curve_icon.png -In the editor, keys are represented by white diamonds and the transparent +In the editor, keys are represented by filled diamonds and the outlined diamonds connected to them by a line control curve's shape. .. image:: img/bezier_curves.png -In the bottom-right of the editor, you can select the manipulator mode: +In the right click panel of the editor, you can select the handle mode: -- Free allows you to orient a manipulator in any direction without affecting the +- Free: Allows you to orient a manipulator in any direction without affecting the other's position. -- Balanced makes it so manipulators rotate together, but the distance between +- Linear: Does not allow rotation of the manipulator and draws a linear graph. +- Balanced: Makes it so manipulators rotate together, but the distance between the key and a manipulator is not mirrored. -- Mirror makes the position of one manipulator perfectly mirror the other, +- Mirrored: Makes the position of one manipulator perfectly mirror the other, including their distance to the key. .. image:: img/manipulator_modes.png @@ -89,8 +105,9 @@ file in the track. To remove a sound from the animation, you can right-click it and select "Delete Key(s)" or click on it and press the :kbd:`Del` key. -.. note:: If you need to, you can create multiple audio tracks that trigger - playback on the same node. +The blend mode allows you to choose whether or not to adjust the audio volume when blending in the :ref:`AnimationTree `. + +.. image:: img/blend_mode.png Animation Playback Track ------------------------ diff --git a/tutorials/animation/animation_tree.rst b/tutorials/animation/animation_tree.rst index 01fa1ff4dadb..57243dd52319 100644 --- a/tutorials/animation/animation_tree.rst +++ b/tutorials/animation/animation_tree.rst @@ -93,33 +93,56 @@ This node will execute a sub-animation and return once it finishes. Blend times .. image:: img/animtree6b.gif -Seek -^^^^ +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]. + +.. tabs:: + .. code-tab:: gdscript 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 + + .. code-tab:: 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); + +TimeSeek +^^^^^^^^ 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 ``seek_position`` value to ``-1.0``. +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 ``seek_request`` value to ``-1.0``. .. tabs:: .. code-tab:: gdscript GDScript # Play child animation from the start. - anim_tree.set("parameters/Seek/seek_position", 0.0) + animation_tree.set("parameters/TimeSeek/seek_request", 0.0) # Alternative syntax (same result as above). - anim_tree["parameters/Seek/seek_position"] = 0.0 + animation_tree["parameters/TimeSeek/seek_request"] = 0.0 # Play child animation from 12 second timestamp. - anim_tree.set("parameters/Seek/seek_position", 12.0) + animation_tree.set("parameters/TimeSeek/seek_request", 12.0) # Alternative syntax (same result as above). - anim_tree["parameters/Seek/seek_position"] = 12.0 + animation_tree["parameters/TimeSeek/seek_request"] = 12.0 .. code-tab:: csharp // Play child animation from the start. - animTree.Set("parameters/Seek/seek_position", 0.0); + animationTree.Set("parameters/TimeSeek/seek_request", 0.0); // Play child animation from 12 second timestamp. - animTree.Set("parameters/Seek/seek_position", 12.0); + animationTree.Set("parameters/TimeSeek/seek_request", 12.0); TimeScale ^^^^^^^^^ @@ -130,6 +153,36 @@ Transition ^^^^^^^^^^ Very simple state machine (when you don't want to cope with a ``StateMachine`` node). Animations can be connected to the outputs 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. + +.. tabs:: + .. code-tab:: gdscript 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"] + + .. code-tab:: 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"); BlendSpace2D ^^^^^^^^^^^^ @@ -247,11 +300,27 @@ Afterwards, the actual motion can be retrieved via the :ref:`AnimationTree ` to control the character movement. @@ -260,7 +329,6 @@ character and animations (this node is disabled by default during the game). .. image:: img/animtree15.gif - Controlling from code --------------------- @@ -288,14 +356,13 @@ Which allows setting them or reading them: .. tabs:: .. code-tab:: gdscript GDScript - anim_tree.set("parameters/eye_blend/blend_amount", 1.0) + animation_tree.set("parameters/eye_blend/blend_amount", 1.0) # Simpler alternative form: - anim_tree["parameters/eye_blend/blend_amount"] = 1.0 + animation_tree["parameters/eye_blend/blend_amount"] = 1.0 .. code-tab:: csharp - animTree.Set("parameters/eye_blend/blend_amount", 1.0); - + animationTree.Set("parameters/eye_blend/blend_amount", 1.0); State machine travel -------------------- @@ -308,15 +375,14 @@ to the destination state. To use the travel ability, you should first retrieve the :ref:`AnimationNodeStateMachinePlayback ` object from the ``AnimationTree`` node (it is exported as a property). - .. tabs:: .. code-tab:: gdscript GDScript - var state_machine = anim_tree["parameters/playback"] + var state_machine = animation_tree["parameters/playback"] .. code-tab:: csharp - AnimationNodeStateMachinePlayback stateMachine = (AnimationNodeStateMachinePlayback)animTree.Get("parameters/playback"); + AnimationNodeStateMachinePlayback stateMachine = (AnimationNodeStateMachinePlayback)animationTree.Get("parameters/playback"); Once retrieved, it can be used by calling one of the many functions it offers: diff --git a/tutorials/animation/img/3D_transform_track.png b/tutorials/animation/img/3D_transform_track.png deleted file mode 100644 index 658ac7be3553..000000000000 Binary files a/tutorials/animation/img/3D_transform_track.png and /dev/null differ diff --git a/tutorials/animation/img/animation_animation_panel.png b/tutorials/animation/img/animation_animation_panel.png index 00d99896ae07..c8c5788a4edd 100644 Binary files a/tutorials/animation/img/animation_animation_panel.png and b/tutorials/animation/img/animation_animation_panel.png differ diff --git a/tutorials/animation/img/animation_animation_panel_overview.png b/tutorials/animation/img/animation_animation_panel_overview.png index ee5f4372a5ea..902d96eea150 100644 Binary files a/tutorials/animation/img/animation_animation_panel_overview.png and b/tutorials/animation/img/animation_animation_panel_overview.png differ diff --git a/tutorials/animation/img/animation_create_animationplayer.png b/tutorials/animation/img/animation_create_animationplayer.png index 7e330fd4dfb7..4beffc157f0d 100644 Binary files a/tutorials/animation/img/animation_create_animationplayer.png and b/tutorials/animation/img/animation_create_animationplayer.png differ diff --git a/tutorials/animation/img/animation_create_new_animation.png b/tutorials/animation/img/animation_create_new_animation.png index 3c38a1e88470..14bf39fb6f1c 100644 Binary files a/tutorials/animation/img/animation_create_new_animation.png and b/tutorials/animation/img/animation_create_new_animation.png differ diff --git a/tutorials/animation/img/animation_keyframe_editor_key.png b/tutorials/animation/img/animation_keyframe_editor_key.png index 1bcd9645d858..36d77d358211 100644 Binary files a/tutorials/animation/img/animation_keyframe_editor_key.png and b/tutorials/animation/img/animation_keyframe_editor_key.png differ diff --git a/tutorials/animation/img/animation_library.png b/tutorials/animation/img/animation_library.png new file mode 100644 index 000000000000..775c1fd9a9e3 Binary files /dev/null and b/tutorials/animation/img/animation_library.png differ diff --git a/tutorials/animation/img/animation_library_dialog.png b/tutorials/animation/img/animation_library_dialog.png new file mode 100644 index 000000000000..49a2bb05ccf5 Binary files /dev/null and b/tutorials/animation/img/animation_library_dialog.png differ diff --git a/tutorials/animation/img/animation_player_animation.png b/tutorials/animation/img/animation_player_animation.png index 31585aecc6f6..1040d2ffb019 100644 Binary files a/tutorials/animation/img/animation_player_animation.png and b/tutorials/animation/img/animation_player_animation.png differ diff --git a/tutorials/animation/img/animation_properties_keyframe.png b/tutorials/animation/img/animation_properties_keyframe.png index c8b7800449bb..3d6cc80b2e0e 100644 Binary files a/tutorials/animation/img/animation_properties_keyframe.png and b/tutorials/animation/img/animation_properties_keyframe.png differ diff --git a/tutorials/animation/img/animation_track.png b/tutorials/animation/img/animation_track.png index 58a1e1a68e20..7b24c58b5c9e 100644 Binary files a/tutorials/animation/img/animation_track.png and b/tutorials/animation/img/animation_track.png differ diff --git a/tutorials/animation/img/animation_track_interpolation.png b/tutorials/animation/img/animation_track_interpolation.png index a6a13b3a492d..14d20757453c 100644 Binary files a/tutorials/animation/img/animation_track_interpolation.png and b/tutorials/animation/img/animation_track_interpolation.png differ diff --git a/tutorials/animation/img/animation_track_loop_modes.png b/tutorials/animation/img/animation_track_loop_modes.png index f6476c0cf282..f3f294aa6cf7 100644 Binary files a/tutorials/animation/img/animation_track_loop_modes.png and b/tutorials/animation/img/animation_track_loop_modes.png differ diff --git a/tutorials/animation/img/animation_track_rate.png b/tutorials/animation/img/animation_track_rate.png index 7c8f96e95abf..4df33a8c9f48 100644 Binary files a/tutorials/animation/img/animation_track_rate.png and b/tutorials/animation/img/animation_track_rate.png differ diff --git a/tutorials/animation/img/animation_track_settings.png b/tutorials/animation/img/animation_track_settings.png index 7312c55f61e1..981720a1464c 100644 Binary files a/tutorials/animation/img/animation_track_settings.png and b/tutorials/animation/img/animation_track_settings.png differ diff --git a/tutorials/animation/img/animtree3.png b/tutorials/animation/img/animtree3.png index f81eb757d466..98f91640be1c 100644 Binary files a/tutorials/animation/img/animtree3.png and b/tutorials/animation/img/animtree3.png differ diff --git a/tutorials/animation/img/audio_track.png b/tutorials/animation/img/audio_track.png index 2494572ecc7b..014ebe2b7e97 100644 Binary files a/tutorials/animation/img/audio_track.png and b/tutorials/animation/img/audio_track.png differ diff --git a/tutorials/animation/img/bezier_curve_icon.png b/tutorials/animation/img/bezier_curve_icon.png index f12a06de1f06..c0cd623c4257 100644 Binary files a/tutorials/animation/img/bezier_curve_icon.png and b/tutorials/animation/img/bezier_curve_icon.png differ diff --git a/tutorials/animation/img/bezier_curves.png b/tutorials/animation/img/bezier_curves.png index 2a20315b2430..77c5d9002785 100644 Binary files a/tutorials/animation/img/bezier_curves.png and b/tutorials/animation/img/bezier_curves.png differ diff --git a/tutorials/animation/img/blend_mode.png b/tutorials/animation/img/blend_mode.png new file mode 100644 index 000000000000..e31aee195cab Binary files /dev/null and b/tutorials/animation/img/blend_mode.png differ diff --git a/tutorials/animation/img/manipulator_modes.png b/tutorials/animation/img/manipulator_modes.png index 843e44f98e7c..b1563b45c244 100644 Binary files a/tutorials/animation/img/manipulator_modes.png and b/tutorials/animation/img/manipulator_modes.png differ diff --git a/tutorials/animation/img/node_method_args.png b/tutorials/animation/img/node_method_args.png index 071db033dbc6..532305327836 100644 Binary files a/tutorials/animation/img/node_method_args.png and b/tutorials/animation/img/node_method_args.png differ diff --git a/tutorials/animation/img/node_methods.png b/tutorials/animation/img/node_methods.png index d7a8bb80fd7a..28308d9d82be 100644 Binary files a/tutorials/animation/img/node_methods.png and b/tutorials/animation/img/node_methods.png differ diff --git a/tutorials/animation/img/track_types.png b/tutorials/animation/img/track_types.png index b42c072c3ae0..e2bddf3a7e35 100644 Binary files a/tutorials/animation/img/track_types.png and b/tutorials/animation/img/track_types.png differ diff --git a/tutorials/animation/introduction.rst b/tutorials/animation/introduction.rst index e35a2a3f6ceb..da0e8a8a6785 100644 --- a/tutorials/animation/introduction.rst +++ b/tutorials/animation/introduction.rst @@ -128,6 +128,9 @@ The sprite holds an image texture. For this tutorial, select the Sprite2D node, click Texture in the Inspector, and then click Load. Select the default Godot icon for the sprite's texture. +Adding an animation +~~~~~~~~~~~~~~~~~~~ + Select the AnimationPlayer node and click the "Animation" button in the animation editor. From the list, select "New" (|Add Animation|) to add a new animation. Enter a name for the animation in the dialog box. @@ -137,6 +140,23 @@ animation. Enter a name for the animation in the dialog box. Add a new animation +Manage an animation libraries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For reusability, the animation is registered in a list in the animation library resource. If you add an animation to AnimationPlayer without specifying any particular settings, the animation will be registered in the [Global] animation library that AnimationPlayer has by default. + +.. figure:: img/animation_library.png + :alt: Manage animations + + Manage animations + +If there are multiple animation libraries and you try to add an animation, a dialog box will appear with options. + +.. figure:: img/animation_library_dialog.png + :alt: Add a new animation with library option + + Add a new animation with library option + Adding a track ~~~~~~~~~~~~~~ @@ -233,10 +253,6 @@ values. This can be: - **Continuous:** Update the property on each frame - **Discrete:** Only update the property on keyframes -- **Trigger:** Only update the property on keyframes or triggers. - Triggers are a type of keyframe used by the - ``current_animation`` property of a :ref:`class_AnimationPlayer`, - and Animation Playback tracks. - **Capture:** if the first keyframe's time is greater than ``0.0``, the current value of the property will be remembered and will be blended with the first animation key. For example, you @@ -259,6 +275,8 @@ keyframes. These interpolation modes are supported: the two keyframes - Cubic: Set the value based on a cubic function calculation between the two keyframes +- Linear Angle (Only appears in rotation property): Linear mode with shortest path rotation +- Cubic Angle (Only appears in rotation property): Cubic mode with shortest path rotation .. figure:: img/animation_track_interpolation.png :alt: Track interpolation @@ -347,3 +365,5 @@ When adding tracks on new animations, the editor will ask you to automatically create a RESET track when using the keyframe icon next to a property in the inspector. This does not apply on tracks created with Godot versions prior to 3.4, as the animation reset track feature was added in 3.4. + +.. note:: RESET tracks is also used as a reference value for blending. See also `For better blending <../tutorials/animation/animation_tree.html#for-better-blending>`__.