# UnityVATTool

一套 Unity 编辑器工具集，用于把 **SkinnedMesh + 动画** 烘焙成 **VAT（顶点动画贴图）** 静态网格，并附带 **减面（Mesh Decimation）** 流程，最终输出一个仅靠 Shader 采样贴图来播放动画的低开销 Prefab，可在大规模同屏（小怪海、群体单位等）场景下显著降低 SkinnedMeshRenderer/Animator 的 CPU 消耗。

---

## 一、目录结构

```
Assets/
├── Plugins/
│   └── AnimMapBaker/                                  # 工具核心
│       ├── Scripts/
│       │   ├── AnimMapBaker.cs                        # 烘焙核心（采样动画 → 顶点位置写入 EXR）
│       │   ├── VATAnimationController.cs              # 运行时 VAT 动画控制器（驱动 Shader）
│       │   ├── VATClipDatabase.cs                     # 烘焙生成的 Clip 元数据（起止帧 / 时长）
│       │   └── Editor/
│       │       ├── AnimMapBakerWindow.cs              # 原始单文件烘焙窗口
│       │       ├── MeshDecimatorWindow.cs             # 步骤 1：减面工具（UnityMeshSimplifier）
│       │       └── SelectiveVATBakerWindow.cs         # 步骤 2：选择性烘焙窗口（减面 + 多 clip + VAT）
│       ├── Shaders/
│       │   ├── AnimMapShader.shader                   # 内置管线（BuiltIn）VAT Shader
│       │   └── AnimMapWithShadowShader.shader         # 带阴影版本
│       └── Documentation.pdf                          # 原始作者文档
└── Common/
    └── Scripts/Editor/                                # 上层批量入口（Tools/OctoberStudio/VAT/...）
        ├── MonsterVATBatchBaker.cs                    # 一键批量烘焙（按 Resources/Role/Monster 全量）
        ├── EnemyVATConverter.cs                       # Enemy 类型 prefab → VAT Variant
        ├── CharacterVATConverter.cs                   # Character 类型 prefab → VAT Variant
        ├── MonsterOrientationCheck.cs                 # FBX 朝向（站立/Z-up）一键体检
        ├── OrientationCalibrator.cs                   # 朝向 + 缩放 + 偏移交互式校准
        └── ImportMonsterPackageAndClean.cs            # 自动导入 unitypackage 并清理夹带文件
```

---

## 二、依赖

| 依赖 | 版本 / 来源 | 必需性 |
|---|---|---|
| Unity | 2022 LTS 及以上（建议 2022.3+） | 必需 |
| [UnityMeshSimplifier (Whinarn)](https://github.com/Whinarn/UnityMeshSimplifier) | 任意稳定版 | **必需**（减面用） |
| 渲染管线 | BuiltIn / URP 均可，Shader 分别提供 | 必需 |

**安装 UnityMeshSimplifier**（任选其一）：

- 通过 UPM 直接拉 git：在 `Packages/manifest.json` 加：
  ```json
  "com.whinarn.unitymeshsimplifier": "https://github.com/Whinarn/UnityMeshSimplifier.git"
  ```
- 或本地克隆后 `file:` 引用：
  ```json
  "com.whinarn.unitymeshsimplifier": "file:../_thirdparty/UnityMeshSimplifier"
  ```

---

## 三、典型使用流程

### 方案 A：单只手动 —— 一步到位（推荐）

1. 菜单：`Tools/VAT Pipeline/1. Decimate SkinnedMesh`  
   - 选择带 `SkinnedMeshRenderer` 的 Prefab/场景对象
   - 设置 `Quality`（保留三角形比例，0.3 = 留 30%）
   - 可选保留边缘、表面曲率等
   - 输出：减面后的 `.asset` Mesh，并可选替换原 `sharedMesh`
2. 菜单：`Tools/VAT Pipeline/2. Bake Selected VAT`（`SelectiveVATBakerWindow`）  
   - 选择对象上的 `Animation` 组件
   - 勾选要烘焙的 `clip`（默认匹配 `Idle / Ready / Run / Die`）
   - 选择目标 Shader（BuiltIn / URP）
   - 输出：`*_VAT.prefab` + `*_VATClips.asset` + `*_VAT_Atlas.exr` + Material

### 方案 B：批量小怪 —— 一键烤全部

- 把美术 prefab（含 `Animation` + `SkinnedMeshRenderer`）整理到  
  `Assets/Resources/Role/Monster/*.prefab`
- 菜单：`Tools/OctoberStudio/VAT/Bake ALL Monsters in Resources`
- 产物默认输出到：`Assets/_VAT_Baking/Output/<name>/`

### 方案 C：从原始 FBX 批量烤（带 @Run.FBX 附加动画文件）

- 把美术 `<name>.FBX` 放在 `Assets/_External/Monsters/<name>/` 下
- 同目录放一份 `<name>@Run.FBX`（Legacy 动画）
- 菜单：`Tools/OctoberStudio/VAT/Bake Selected Monsters (Run-only)`

### 辅助工具

- `Tools/OctoberStudio/VAT/Orientation Calibrator`：交互式调整朝向/缩放/偏移并 apply 回 prefab
- `Tools/OctoberStudio/VAT/Monster Orientation Check`：批量体检 `_External/Monsters` 与 `_External/Bosses` 下所有 FBX 的站立朝向，输出报告

---

## 四、运行时使用

烘焙产物 `*_VAT.prefab` 内已挂好 `VATAnimationController`，通过它切换/播放 Clip：

```csharp
var ctrl = instance.GetComponent<VATAnimationController>();
ctrl.Play("Run");         // 按 Clip 名播放
ctrl.PlayByIndex(0);      // 或按索引
ctrl.SetSpeed(1.5f);
```

实际播放靠 Shader 在顶点阶段从 `_AnimMap` 采样 → 不再走 `SkinnedMeshRenderer` 蒙皮，CPU 几乎为零。

---

## 五、注意事项与坑点

1. **必须 Legacy 动画**：批量烤 FBX 那条流程要求 FBX 的 `animationType = 1 (Legacy)`，不是 Generic / Humanoid。Mecanim 流程请改用 `SelectiveVATBakerWindow` + 手动 prefab。
2. **顶点数 × 帧数 ≤ 单贴图限制**：贴图宽 = 顶点数，高 = 帧数总和。顶点过多请先减面。
3. **朝向**：源 FBX 若是 Z-up，会以 X=-90° 旋转烘入 Mesh 节点；如不符预期请用 `OrientationCalibrator`。
4. **URP 阴影**：`AnimMapShader` 默认无阴影投射，需要阴影请用 `AnimMapWithShadowShader`，并确认 Project Settings 中阴影距离/级联。
5. **采样精度**：动画位置编码为 EXR HALF，位移过大（>1000 单位）会出现可见抖动，模型请在烘焙前居中到原点附近。

---

## 六、菜单速查

| 菜单 | 入口脚本 | 功能 |
|---|---|---|
| `Tools/VAT Pipeline/1. Decimate SkinnedMesh` | `MeshDecimatorWindow` | 减面 |
| `Tools/VAT Pipeline/2. Bake Selected VAT` | `SelectiveVATBakerWindow` | 选择性 VAT 烘焙 |
| `Tools/OctoberStudio/VAT/Bake mon1001 (Test Sample)` | `MonsterVATBatchBaker` | 测试单只 |
| `Tools/OctoberStudio/VAT/Bake ALL Monsters in Resources` | `MonsterVATBatchBaker` | 批量 Resources 怪物 |
| `Tools/OctoberStudio/VAT/Bake Selected Monsters (Run-only)` | `MonsterVATBatchBaker` | 选中 FBX 烘焙 |
| `Tools/OctoberStudio/VAT/Import Monster Package Auto Clean` | `ImportMonsterPackageAndClean` | 导入并清理 monster.unitypackage |
| `Tools/OctoberStudio/VAT/Import Role Package Auto Clean` | `ImportMonsterPackageAndClean` | 导入并清理 role.unitypackage |
| `Tools/OctoberStudio/VAT/Orientation Calibrator` | `OrientationCalibrator` | 朝向校准 |
| `Tools/OctoberStudio/VAT/Monster Orientation Check` | `MonsterOrientationCheck` | 批量朝向体检 |

---

## 七、致谢

- VAT 烘焙核心来源：[chenjd / AnimMap-Baker](https://github.com/chenjd/AnimMap-Baker) 的思路与 Shader 框架
- 减面：[Whinarn / UnityMeshSimplifier](https://github.com/Whinarn/UnityMeshSimplifier)