AIC-Project/docs/superpowers/specs/2026-07-27-unity-humanoid-animation-import-design.md

Unity Humanoid Animation Import Design

Goal

Automatically apply the project's shared humanoid animation import settings when FBX animation assets are imported under Assets/Game/Art/Actor/.

Scope

• Applies to .fbx assets inside Assets/Game/Art/Actor/.
• Excludes Assets/Game/Art/Actor/cityboy/cityboy_sk.fbx, because it provides the source avatar.
• Applies only when the FBX import has animation clips.
• Does not modify existing FBX, prefab, or controller assets directly.

Import Behavior

When an in-scope FBX with animation clips is imported:

• Set Rig Animation Type to Humanoid.
• Set Avatar to Copy From Other.
• Use Cityboy_sk Avatar from Assets/Game/Art/Actor/cityboy/cityboy_sk.fbx.
• For every imported animation clip:
  • Enable Root Transform Rotation Bake Into Pose.
  • Set Root Transform Rotation Based Upon to Original.
  • Enable Root Transform Position (Y) Bake Into Pose.

Error Handling

If the Cityboy avatar cannot be loaded, the importer logs a warning and leaves the asset unchanged. This avoids blocking Unity's asset import pipeline.

Testing

Editor tests cover the path filter, avatar exclusion, and clip-setting mutation logic without importing real FBX files.