humanoid-retargeting-import-workflow

name	humanoid-retargeting-import-workflow
description	Operational workflow for importing humanoid rigs and retargeted animation libraries using Godot integrated skeleton profile and bone map tooling.
tier	operational
godot_version	4.6+
doc_anchors	["godot-docs/tutorials/assets_pipeline/retargeting_3d_skeletons.rst","godot-docs/classes/class_skeleton3d.rst","godot-docs/classes/class_skeletonprofile.rst","godot-docs/classes/class_skeletonprofilehumanoid.rst","godot-docs/classes/class_bonemap.rst","godot-docs/classes/class_animationlibrary.rst"]
tags	["rigging","retargeting","animation-import"]
depends_on	["godot-skills/godot-foundations/foundation-asset-resource-pipeline/SKILL.md","godot-skills/godot-tertiary/transform-axis-winding-hardening/SKILL.md"]

Humanoid Retargeting Import Workflow

Use When

• Importing humanoid characters that must share animation libraries.
• Retargeted animations show distortion, drift, or axis mismatch.
• Standardized rig import validation is needed.

Outcomes

• Target skeletons map cleanly to profile/bone map requirements.
• Imported animation libraries play without severe rest/axis artifacts.
• Retargeting settings are repeatable and documented.

Required Rules

• Use SkeletonProfile and BoneMap alignment; do not assume name-only compatibility.
• Validate rest alignment and mapping warnings before bulk animation import.
• Apply high-impact rest-fix options incrementally with one-change reimport checks.
• Keep root-motion ownership explicit relative to movement authority.

Workflow

1. Select profile strategy (built-in humanoid or project-specific profile).
2. Configure and validate BoneMap for target skeleton.
3. Choose animation import mode (shared library vs scene-embedded) per reuse goals.
4. Apply retargeting import options iteratively and re-test acceptance checks.
5. Lock validated import settings and propagate through content pipeline.

Validation

• Idle, locomotion, and upper-body motion pass distortion/drift checks.
• Bone mapping warnings are resolved or explicitly waived with rationale.
• Retargeted library reuse across compatible characters works without manual patching.

Failure Modes

• Animation sharing relies only on bone names and breaks due to rest mismatch.
• Aggressive overwrite options are enabled blindly and damage rig behavior.
• Root motion and logical movement authority are mixed, causing drift/desync.

Local Doc Anchors

• godot-docs/tutorials/assets_pipeline/retargeting_3d_skeletons.rst
• godot-docs/classes/class_skeleton3d.rst
• godot-docs/classes/class_skeletonprofile.rst
• godot-docs/classes/class_skeletonprofilehumanoid.rst
• godot-docs/classes/class_bonemap.rst
• godot-docs/classes/class_animationlibrary.rst