132 lines
5.1 KiB
Markdown
132 lines
5.1 KiB
Markdown
# Unity Humanoid Animation Import Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Add a Unity editor import hook that applies the shared Cityboy humanoid avatar and root transform clip settings to Actor animation FBX imports.
|
|
|
|
**Architecture:** Create a small pure-policy helper plus an `AssetPostprocessor` wrapper in the existing editor assembly. EditMode tests exercise the helper so behavior can be verified without importing binary FBX assets.
|
|
|
|
**Tech Stack:** Unity Editor C#, `UnityEditor.ModelImporter`, `UnityEditor.ModelImporterClipAnimation`, NUnit EditMode tests.
|
|
|
|
## Global Constraints
|
|
|
|
- Scope is `Assets/Game/Art/Actor/`.
|
|
- Exclude `Assets/Game/Art/Actor/cityboy/cityboy_sk.fbx`.
|
|
- Only mutate imports that have one or more animation clips.
|
|
- Use `Assets/Game/Art/Actor/cityboy/cityboy_sk.fbx` as the source avatar asset path.
|
|
- Do not touch existing FBX, prefab, or controller asset files.
|
|
|
|
---
|
|
|
|
### Task 1: Import Policy Tests And Helper
|
|
|
|
**Files:**
|
|
- Create: `Client/Assets/Script/Editor/HumanoidAnimationFbxImportSettings.cs`
|
|
- Create: `Client/Assets/Script/Tests/EditMode/HumanoidAnimationFbxImportSettingsTests.cs`
|
|
- Modify: `Client/Assets/Script/Tests/EditMode/XWorld.Link.EditModeTests.asmdef`
|
|
|
|
**Interfaces:**
|
|
- Produces: `HumanoidAnimationFbxImportSettings.ShouldProcessAsset(string assetPath, bool hasAnimationClips) : bool`
|
|
- Produces: `HumanoidAnimationFbxImportSettings.ApplyClipSettings(ModelImporterClipAnimation clip) : ModelImporterClipAnimation`
|
|
- Produces: `HumanoidAnimationFbxImportSettings.CityboyAvatarPath : string`
|
|
|
|
- [ ] **Step 1: Write failing EditMode tests**
|
|
|
|
```csharp
|
|
using NUnit.Framework;
|
|
using UnityEditor;
|
|
|
|
public sealed class HumanoidAnimationFbxImportSettingsTests
|
|
{
|
|
[Test]
|
|
public void ShouldProcessActorAnimationFbx()
|
|
{
|
|
Assert.That(
|
|
HumanoidAnimationFbxImportSettings.ShouldProcessAsset(
|
|
"Assets/Game/Art/Actor/Controller/Class/Caster/Standing Walk Forward.fbx",
|
|
true),
|
|
Is.True);
|
|
}
|
|
|
|
[Test]
|
|
public void ShouldNotProcessCityboySourceAvatar()
|
|
{
|
|
Assert.That(
|
|
HumanoidAnimationFbxImportSettings.ShouldProcessAsset(
|
|
HumanoidAnimationFbxImportSettings.CityboyAvatarPath,
|
|
true),
|
|
Is.False);
|
|
}
|
|
|
|
[Test]
|
|
public void ShouldNotProcessActorFbxWithoutAnimationClips()
|
|
{
|
|
Assert.That(
|
|
HumanoidAnimationFbxImportSettings.ShouldProcessAsset(
|
|
"Assets/Game/Art/Actor/captain/captain.fbx",
|
|
false),
|
|
Is.False);
|
|
}
|
|
|
|
[Test]
|
|
public void ApplyClipSettingsUsesOriginalRotationAndBakesRotationAndY()
|
|
{
|
|
var clip = new ModelImporterClipAnimation
|
|
{
|
|
lockRootRotation = false,
|
|
keepOriginalOrientation = false,
|
|
lockRootHeightY = false
|
|
};
|
|
|
|
ModelImporterClipAnimation updated = HumanoidAnimationFbxImportSettings.ApplyClipSettings(clip);
|
|
|
|
Assert.That(updated.lockRootRotation, Is.True);
|
|
Assert.That(updated.keepOriginalOrientation, Is.True);
|
|
Assert.That(updated.lockRootHeightY, Is.True);
|
|
}
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Run test to verify it fails**
|
|
|
|
Run: Unity EditMode tests for `HumanoidAnimationFbxImportSettingsTests`.
|
|
|
|
Expected: compile/test failure because `HumanoidAnimationFbxImportSettings` does not exist.
|
|
|
|
- [ ] **Step 3: Implement minimal helper**
|
|
|
|
Create `HumanoidAnimationFbxImportSettings` with the constants and pure helper methods used by the tests.
|
|
|
|
- [ ] **Step 4: Run test to verify it passes**
|
|
|
|
Run: Unity EditMode tests for `HumanoidAnimationFbxImportSettingsTests`.
|
|
|
|
Expected: all tests in the fixture pass.
|
|
|
|
### Task 2: AssetPostprocessor Integration
|
|
|
|
**Files:**
|
|
- Modify: `Client/Assets/Script/Editor/HumanoidAnimationFbxImportSettings.cs`
|
|
- Test: `Client/Assets/Script/Tests/EditMode/HumanoidAnimationFbxImportSettingsTests.cs`
|
|
|
|
**Interfaces:**
|
|
- Consumes: `HumanoidAnimationFbxImportSettings.ShouldProcessAsset(string assetPath, bool hasAnimationClips) : bool`
|
|
- Consumes: `HumanoidAnimationFbxImportSettings.ApplyClipSettings(ModelImporterClipAnimation clip) : ModelImporterClipAnimation`
|
|
- Produces: `HumanoidAnimationFbxPostprocessor : AssetPostprocessor`
|
|
|
|
- [ ] **Step 1: Add AssetPostprocessor implementation**
|
|
|
|
Use `OnPreprocessModel` to get the `ModelImporter`, check scope and clip count, load the Cityboy avatar, set humanoid/copy-from-other settings, and update `clipAnimations`.
|
|
|
|
- [ ] **Step 2: Run editor compilation/tests**
|
|
|
|
Run Unity EditMode tests.
|
|
|
|
Expected: editor code compiles and the helper tests still pass.
|
|
|
|
- [ ] **Step 3: Inspect git diff**
|
|
|
|
Run: `git diff -- Client/Assets/Script/Editor/HumanoidAnimationFbxImportSettings.cs Client/Assets/Script/Tests/EditMode/HumanoidAnimationFbxImportSettingsTests.cs Client/Assets/Script/Tests/EditMode/XWorld.Link.EditModeTests.asmdef`
|
|
|
|
Expected: only the new importer helper/postprocessor and test assembly reference changes are present.
|