update

Author: TokageItLab

tutorials/assets_pipeline/retargeting_3d_skeletons.rst

@@ -6,13 +6,14 @@ Retargeting 3D Skeletons
 To share animations among multiple Skeletons
 --------------------------------------------
 
-Godot has Position/Rotation/Scale 3D tracks (hereafter called Transform tracks)
-with Nodepaths to bones for Skeleton bone animation. If you think that you can
-share animations between multiple Skeletons as long as the bone names are the
-same, that is not correct.
+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 can have different Transform values.
+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.
@@ -23,33 +24,34 @@ If Bone Pose is equal to Bone Rest, it means that the Skeleton is in the default
 
 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
+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,
-moreover to remove unwanted tracks in some cases. In Godot 4.0+, you can do that using
-the scene importer.
+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 on the scene importer, you can find the Retarget
-section on the inspector.
+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 in the importer, first set up a new BoneMap and SkeletonProfile.
-Godot has a preset called SkeletonProfileHumanoid for humanoid models.
-This tutorial will proceed with the assumption that you will use SkeletonProfileHumanoid.
+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 SkeletonProfile from SkeletonEditor with some information converted from Skeleton.
+          a :ref:`class_skeletonprofile` from SkeletonEditor with some information converted from Skeleton.
 
-When you use SkeletonProfileHumanoid, the auto-mapping will be performed when the
-SkeletonProfile is set. If the auto-mapping does not work well, you can map bones manually.
+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
 
@@ -60,14 +62,14 @@ 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 BoneMap, several options are available in the sections below.
+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 AnimationLibrary that will be shared, we recommend to enable these options.
+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.
@@ -81,8 +83,8 @@ Unimportant Positions
 ^^^^^^^^^^^^^^^^^^^^^
 
 Removes Position tracks other than ``root_bone`` and ``scale_base_bone``
-defined in SkeletonProfile from the animations. In SkeletonProfileHumanoid,
-this means that to remove Position tracks other than Root and Hips.
+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.
 
@@ -102,13 +104,13 @@ Rename the mapped bones.
 Unique Node
 ^^^^^^^^^^^
 
-Makes Skeleton a unique node with the name specified in the Skeleton Name.
+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 SkeletonProfileHumanoid have the following rules:
+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
@@ -123,30 +125,30 @@ 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
+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 importer.
+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 bad effect.
+.. 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,
-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``.
+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 SkeletonProfileHumanoid, ``scale_base_bone`` is Hips, therefore the Hips' height is used as the Motion Scale.
+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 Rest by overwriting it to match the Reference Pose defined in the SkeletonProfile.
+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**.
@@ -156,15 +158,15 @@ Unifies the models' Bone Rest by overwriting it to match the Reference Pose defi
 Fix Silhouette
 ^^^^^^^^^^^^^^
 
-Attempts to make the model's silhouette match that of the reference pose defined in the SkeletonProfile,
+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 SkeletonProfileHumanoid, this option does not need to be enabled for T-pose models,
+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 SkeletonProfile bone names you do not want fixed in the Filter array, as in the below example.
+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.
+For that, you can use ``base_height_adjustment`` option.