diff --git a/tutorials/animation/animation_tree.rst b/tutorials/animation/animation_tree.rst index 3aea4f668e5..01fa1ff4dad 100644 --- a/tutorials/animation/animation_tree.rst +++ b/tutorials/animation/animation_tree.rst @@ -188,6 +188,48 @@ Transitions also have a few properties. Click any transition and it will be disp * *Priority* is used together with the ``travel()`` function from code (more on this later). Lower priority transitions are preferred when travelling through the tree. * *Disabled* toggles disabling this transition (when disabled, it will not be used during travel or auto advance). +For better blending +------------------- + +In Godot 4.0+, in order for the blending results to be deterministic (reproducible and always consistent), +the blended property values must have a specific initial value. +For example, in the case of two animations to be blended, if one animation has a property track and the other does not, +the blended animation is calculated as if the latter animation had a property track with the initial value. + +When using Position/Rotation/Scale 3D tracks for Skeleton3D bones, the initial value is Bone Rest. +For other properties, the initial value is ``0`` and if the track is present in the ``RESET`` animation, +the value of its first keyframe is used instead. + +For example, the following AnimationPlayer has two animations, but one of them lacks a Property track for Position. + +.. image:: img/blending1.webp + +This means that the animation lacking that will treat those Positions as ``Vector2(0, 0)``. + +.. image:: img/blending2.webp + +This problem can be solved by adding a Property track for Position as an initial value to the ``RESET`` animation. + +.. image:: img/blending3.webp + +.. image:: img/blending4.webp + +.. note:: Be aware that the ``RESET`` animation exists to define the default pose when loading an object originally. + It is assumed to have only one frame and is not expected to be played back using the timeline. + +Also keep in mind that the Rotation 3D tracks and the Property tracks for 2D rotation +with Interpolation Type set to Linear Angle or Cubic Angle will prevent rotation of more than 180 degrees +from the initial value as blended animation. + +This can be useful for Skeleton3Ds to prevent the bones penetrating the body when blending animations. +Therefore, Skeleton3D's Bone Rest values should be as close to the midpoint of the movable range as possible. +**This means that for humanoid models, it is preferable to import them in a T-pose**. + +.. image:: img/blending5.webp + +You can see that the shortest rotation path from Bone Rests is prioritized rather than the shortest rotation path between animations. + +If you need to rotate Skeleton3D itself more than 180 degrees by blend animations for movement, you can use Root Motion. Root motion ----------- diff --git a/tutorials/animation/img/blending1.webp b/tutorials/animation/img/blending1.webp new file mode 100644 index 00000000000..28c3c802b34 Binary files /dev/null and b/tutorials/animation/img/blending1.webp differ diff --git a/tutorials/animation/img/blending2.webp b/tutorials/animation/img/blending2.webp new file mode 100644 index 00000000000..5c90f1f81e0 Binary files /dev/null and b/tutorials/animation/img/blending2.webp differ diff --git a/tutorials/animation/img/blending3.webp b/tutorials/animation/img/blending3.webp new file mode 100644 index 00000000000..c72206fbd54 Binary files /dev/null and b/tutorials/animation/img/blending3.webp differ diff --git a/tutorials/animation/img/blending4.webp b/tutorials/animation/img/blending4.webp new file mode 100644 index 00000000000..78b705bb4af Binary files /dev/null and b/tutorials/animation/img/blending4.webp differ diff --git a/tutorials/animation/img/blending5.webp b/tutorials/animation/img/blending5.webp new file mode 100644 index 00000000000..55bf97100ee Binary files /dev/null and b/tutorials/animation/img/blending5.webp differ diff --git a/tutorials/assets_pipeline/img/retargeting1.webp b/tutorials/assets_pipeline/img/retargeting1.webp new file mode 100644 index 00000000000..fb6c7a1ccfe Binary files /dev/null and b/tutorials/assets_pipeline/img/retargeting1.webp differ diff --git a/tutorials/assets_pipeline/img/retargeting2.webp b/tutorials/assets_pipeline/img/retargeting2.webp new file mode 100644 index 00000000000..09e323dc432 Binary files /dev/null and b/tutorials/assets_pipeline/img/retargeting2.webp differ diff --git a/tutorials/assets_pipeline/img/retargeting3.webp b/tutorials/assets_pipeline/img/retargeting3.webp new file mode 100644 index 00000000000..e36aaca3ef8 Binary files /dev/null and b/tutorials/assets_pipeline/img/retargeting3.webp differ diff --git a/tutorials/assets_pipeline/img/retargeting4.webp b/tutorials/assets_pipeline/img/retargeting4.webp new file mode 100644 index 00000000000..bbc97e2aadf Binary files /dev/null and b/tutorials/assets_pipeline/img/retargeting4.webp differ diff --git a/tutorials/assets_pipeline/index.rst b/tutorials/assets_pipeline/index.rst index c3122c0f779..e01da399398 100644 --- a/tutorials/assets_pipeline/index.rst +++ b/tutorials/assets_pipeline/index.rst @@ -10,5 +10,6 @@ Assets pipeline importing_audio_samples importing_translations importing_scenes + retargeting_3d_skeletons exporting_3d_scenes escn_exporter/index diff --git a/tutorials/assets_pipeline/retargeting_3d_skeletons.rst b/tutorials/assets_pipeline/retargeting_3d_skeletons.rst new file mode 100644 index 00000000000..59a19481ca0 --- /dev/null +++ b/tutorials/assets_pipeline/retargeting_3d_skeletons.rst @@ -0,0 +1,172 @@ +.. _doc_retargeting_3d_skeletons: + +Retargeting 3D Skeletons +======================== + +To share animations among multiple Skeletons +-------------------------------------------- + +Godot has Position/Rotation/Scale 3D tracks (which this document calls "Transform" tracks) +with Nodepaths to bones for Skeleton bone animation. This means you can't +share animations between multiple Skeletons just by using the same bone +names. + +Godot allows each bone to have a parent-child relationship and can have rotation +and scale as well as position, which means that bones that share a name can still +have different Transform values. + +The Skeleton stores the Transform values necessary for the default pose as Bone Rest. +If Bone Pose is equal to Bone Rest, it means that the Skeleton is in the default pose. + +.. note:: Godot 3.x and Godot 4.0+ have different Bone Pose behaviors. + In Godot 3.x, Bone Pose is relative to Bone Rest, but in Godot 4.0+, + it includes Bone Rest. See this `article `__. + +Skeletal models have different Bone Rests depending on the environment from +which they were exported. For example, the bones of a glTF model output from Blender +have "Edit Bone Orientation" as the Bone Rest rotation. However, there are skeletal +models without any Bone Rest rotations, such as the glTF model output from Maya. + +To share animations in Godot, it is necessary to match Bone Rests as well as Bone Names +to remove unwanted tracks in some cases. In Godot 4.0+, you can do that using the scene +importer. + +Options for Retargeting +----------------------- + +Bone Map +~~~~~~~~ + +When you select the Skeleton3D node in the advanced scene import menu, a menu will appear +on the right-hand side containing the "Retarget" section. The Retarget section has a single +property ``bone_map``. + +.. image:: img/retargeting1.webp + +With the Skeleton node selected, first set up a new :ref:`class_bonemap` and :ref:`class_skeletonprofile`. +Godot has a preset called :ref:`class_skeletonprofilehumanoid` for humanoid models. +This tutorial proceeds with the assumption that you are using :ref:`class_skeletonprofilehumanoid`. + +.. note:: If you need a profile for a model such as a beast or creature, you can export + a :ref:`class_skeletonprofile` from SkeletonEditor with some information converted from Skeleton. + +When you use :ref:`class_skeletonprofilehumanoid`, auto-mapping will be performed when the +:ref:`class_skeletonprofile` is set. If the auto-mapping does not work well, you can map bones manually. + +.. image:: img/retargeting2.webp + +Any missing, duplicate or incorrect parent-child relationship mappings will be indicated +by a magenta / red button (depending on the editor setting). It does not block the import process, +but it warns that animations may not be shared correctly. + +.. note:: The auto-mapping uses pattern matching for the bone names. So we recommend + to use common English names for bones. + +After you set up the ``bone_map``, several options are available in the sections below. + +.. image:: img/retargeting3.webp + +Remove Tracks +~~~~~~~~~~~~~ + +If you import resources as an :ref:`class_animationlibrary` that will be shared, we recommend to enable these options. +However, if you import resources as scenes, these should be disabled in some cases. +For example, if you import a character with animated accessories, +these options may cause the accessories to not animate. + +Except Bone Transform +^^^^^^^^^^^^^^^^^^^^^ + +Removes any tracks except the bone Transform track from the animations. + +Unimportant Positions +^^^^^^^^^^^^^^^^^^^^^ + +Removes Position tracks other than ``root_bone`` and ``scale_base_bone`` +defined in :ref:`class_skeletonprofile` from the animations. In :ref:`class_skeletonprofilehumanoid`, +this means that to remove Position tracks other than "Root" and "Hips". +Since Godot 4.0+, animations include Bone Rest in the Transform value. If you disable this option, +the animation may change the body shape unpredictably. + +Unmapped Bones +^^^^^^^^^^^^^^ + +Removes unmapped bone Transform tracks from the animations. + +Bone Renamer +~~~~~~~~~~~~ + +Rename Bones +^^^^^^^^^^^^ + +Rename the mapped bones. + +Unique Node +^^^^^^^^^^^ + +Makes Skeleton a unique node with the name specified in the ``skeleton_name``. +This allows the animation track paths to be unified independent of the scene hierarchy. + +Rest Fixer +~~~~~~~~~~ + +Reference poses defined in :ref:`class_skeletonprofilehumanoid` have the following rules: + +* The humanoid is T-pose +* The humanoid is facing +Z in the Right-Handed Y-UP Coordinate System +* The humanoid should not have a Transform as Node +* Directs the +Y axis from the parent joint to the child joint +* +X rotation bends the joint like a muscle contracting + +These rules are convenient definitions for blend animation and Inverse Kinematics (IK). +If your model does not match this definition, you need to fix it with these options. + +Apply Node Transform +^^^^^^^^^^^^^^^^^^^^ + +If the asset is not exported correctly for sharing, the imported Skeleton may have +a Transform as a Node. For example, a glTF exported from Blender with no "Apply Transform" +executed is one such case. It looks like the model matches the definition, +but the internal Transforms are different from the definition. +This option fixes such models by applying Transforms on import. + +.. note:: If the imported scene contains objects other than Skeletons, this option may have a negative effect. + +Normalize Position Tracks +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Position track is used mostly for model movement, but sharing the moving animation +between models with different heights may cause the appearance of slipping +due to the difference in stride length. This option normalizes the Position track values +based on the ``scale_base_bone`` height. The ``scale_base_bone`` height is stored +in the Skeleton as the ``motion_scale``, and the normalized Position track values is +multiplied by that value on playback. If this option is disabled, the Position tracks +is not normalized and the Skeleton's ``motion_scale`` is always imported as ``1.0``. + +With :ref:`class_skeletonprofilehumanoid`, ``scale_base_bone`` is "Hips", therefore the Hips' height is used as the ``motion_scale``. + +Overwrite Axis +^^^^^^^^^^^^^^ + +Unifies the models' Bone Rests by overwriting it to match the reference poses defined in the :ref:`class_skeletonprofile`. + +.. note:: This is the most important option for sharing animations in Godot 4.0+, + but be aware that this option can produce horrible results **if the original Bone Rest set externally is important**. + If you want to share animations with keeping the original Bone Rest, + consider to use the `Realtime Retarget Module `__. + +Fix Silhouette +^^^^^^^^^^^^^^ + +Attempts to make the model's silhouette match that of the reference poses defined in the :ref:`class_skeletonprofile`, +such as T-Pose. This cannot fix silhouettes which are too different, and it may not work for fixing bone roll. + +With :ref:`class_skeletonprofilehumanoid`, this option does not need to be enabled for T-pose models, +but should be enabled for A-pose models. However in that case, the fixed foot results +may be bad depending on the heel height of the model, so it may be necessary to add +the :ref:`class_skeletonprofile` bone names you do not want fixed in the ``filter`` array, as in the below example. + +.. image:: img/retargeting4.webp + +Also, for models with bent knees or feet, it may be necessary to adjust the ``scale_base_bone`` height. +For that, you can use ``base_height_adjustment`` option.