# 敌方角色标准制作方案 v1

2026-10-20。标准入口：`Tools/enemy_character_pipeline.py`；角色配置：`Config/Art/EnemyCharacters/{Name}.json`。岩团团为已落地的短腿双足样例。

## 交付与约定

每个敌人交付已验收静态模、同源骨架和蒙皮、Idle/Walk/Attack、Animator、Enemy视觉Prefab、验收场景、来源清单和验证报告。流程到可调用的视觉资产为止，战斗数值、寻路和伤害结算由玩法接入。

统一约定：Unity Y-up、米制、底面中心原点、局部-Z正面。外层逻辑根旋转identity、缩放1，关闭Root Motion；移动和转向由玩法驱动。网格、骨架和动画必须共用绑定空间，不能靠运行时反向旋转补救。

| 动作 | 标准行为 | 岩团团参数 |
| --- | --- | --- |
| Idle | 原地循环、轻呼吸、首尾连续 | 1.6秒 |
| Walk | 原地循环、交替迈步 | 1.1秒；步幅0.06m、抬脚0.018m |
| Attack | 蓄力→命中→恢复；只播放一次 | 1.0秒；0.25蓄力结束、0.45命中、0.90恢复完成（归一化） |

## 1. 静态模先验收

设计图→混元高模→减面/UV/烘焙→XPbr→静态Prefab。遵循 `GameResProductProc.md` 和 `CharacterUnitArtProc.md`，保留同角色高模。普通敌人以1500～2000三角面、每顶点最多4权重为起点，具体上限写配方；精英/首领显式配置预算与尺寸。

绑骨前先验尺寸、底面、正面、贴图与面数，后续不重做另一个形体替换已验收外观。最终绑定姿态与静态模的默认顶点误差≤2mm。P0可见敌人目标≤40个，仍须在战场做多实例性能验收；单角色通过不代表40实例性能已通过。

## 2. 同角色骨架与空间对齐

先尝试验收网格的TokenRig；过简低模导致关键关节缺失时，对**同角色高模**绑骨再转权重。骨数不能代替关节和动作质量验收。

项目静态FBX导入Blender后仍为Y-up顶点，TokenRig GLB为Blender Z-up。`bl_transfer_skin.py --low-up Y --align-bounds` 先转Y→Z，再以底面中心平移/等比缩放对齐，最后转权重，保留原UV与三角面。几何距离门槛：最大≤尺寸3%、RMS≤1%；不满足就停止检查来源或对齐，不能对另一角色强行蒙皮。

配方记录 `rigSource`，每个动作回执记录rig SHA256，导入前要求完全一致；新生成回执还校验FBX SHA256。Unity检查骨路径与父子关系，禁止按bone_N同名混用其它rig。Armature的+90°X可保留，不单独清零。

## 3. 解剖类型与动作生成

已实现并验证 `biped_short`（短腿双足、两侧短臂，岩团团12骨）、`avian_grounded`（地面鸟型，闪闪雀28骨）、`quadruped_turtle`（四足龟，泡泡龟26骨）及 `quadruped_heavy`（重型四足，岩甲犀29骨）。各自配方记录自身身体／前肢或四脚／脚尖／头颈与正面参考骨；骨数与bone编号只属于各自样例，不能跨角色套用。

其它短腿双足敌人需换成自己的骨名、尺寸和节奏并完整验收。其它四足、长腿人形、飞行或无脚敌人需要对应解剖适配器，当前入口拒绝未知profile；不能直接套双足步幅。标准人形可沿用Mixamo/Kimodo动作来源，仍需同源绑定和三动作验收。

非人动作在同一TokenRig上用UniMate生成。英文提示词写清体型与单一动作，Walk不混jump，Attack不只写move；显式指定左右正面骨，保留实际提交文本、任务号和哈希。三个动作顺序生成。

生成器在独立任务目录工作，成功后才替换当前FBX，最后提交回执；失败不得把旧FBX标成新产物。默认入口使用有效本地缓存，`--generate`才请求DGXA推理。

## 4. 编辑期收尾

源动作是制作中间件，最终.anim必须离线编辑保存，不能依赖运行时临时改骨骼。清单注明“生成源动作＋离线编辑”。

- Walk：校准初始根姿态、保留相对变化；锁水平根位移；选重复步态相位、平滑闭合；按解剖配方编辑步幅/抬脚；烘焙实际蒙皮贴地。
- Idle：以绑定姿态为循环参考，保留轻微生成变化并编辑呼吸幅度，首尾一致。
- Attack：以Idle参考开始/结束；编辑清楚的蓄力、命中与恢复；短冲在配方范围内，循环关闭。

这些编辑强度必须写配方，不能把岩团团数值作为所有敌人的统一值。

## 5. Animator与战斗接口

`Motion`（Int）：0=Idle，1=Walk。`Attack`（Trigger）：请求一次攻击。支持Idle/Walk进入Attack，结束根据Motion返回Idle/Walk；单次Trigger不自动重复攻击。

```csharp
animator.SetInteger("Motion", moving ? 1 : 0);
animator.SetTrigger("Attack");
```

Attack包含 `OnEnemyAttackImpact` 动画事件，时刻=`attackImpact * attackSeconds`。预览允许无接收器；玩法接入时由现有攻击事件或表现桥接处理，避免重复结算。美术事件不直接扣血，不替代服务器/战斗判定。

视觉Prefab输出 `Assets/Bundles/Characters/Enemy/{Name}/{Name}_Enemy.prefab`。新敌人源资产通常放 `Characters/Enemy/{Name}/`；岩团团复用已有 `Characters/Animal/RockBall/` 的模型、动画、XPbr，通过Variant交付Enemy目录，不复制贴图材质。转向时以局部-Z对准目标。

## 6. 验收门槛

| 检查 | 门槛 |
| --- | --- |
| 来源 | 三动作rig哈希一致；新生成FBX与回执哈希一致 |
| 绑定 | 静态形状、尺寸、底面、面数预算、XPbr通过 |
| 整段动作 | 每段121帧实际蒙皮；脚底偏差≤配方容差（样例3mm），倾角/高度合理 |
| Idle/Walk | 循环开启；首尾顶点差<1mm；呼吸/左右迈步可见 |
| Attack | 循环关闭；动作可读；恢复Idle；一个命中事件且时间正确 |
| 切换 | Idle↔Walk；二者均可进入Attack；单次触发一次；结束返回请求状态，过渡不明显穿地 |
| Play | 真实观察到三状态、逻辑根不漂移、方向不翻转 |
| 目视 | 静态/三动作/自动轮播并排，检查正面、贴图、穿模、脚滑与攻击可读性 |

不能用SkinnedMeshRenderer的保守剔除包围盒判断脚底。Edit验收通过骨骼矩阵和bindposes计算实际顶点；Play验收观察状态/骨骼/逻辑根，不为测试永久打开网格Read/Write。

## 7. 制作入口与复现

```powershell
python Tools/enemy_character_pipeline.py --recipe Config/Art/EnemyCharacters/RockBall.json --validate-recipe
python Tools/enemy_character_pipeline.py --recipe Config/Art/EnemyCharacters/RockBall.json --build-review --play-check
# 重新生成指定动作，再完整制作
python Tools/enemy_character_pipeline.py --recipe Config/Art/EnemyCharacters/RockBall.json --generate Idle Attack --build-review --play-check
```

复制配方后修改id、kind/assetRoot、静态/骨架来源、Enemy输出、尺寸/预算、全部骨名、动作来源与文本。先验配方，再生产和验收；配置合法不等于资产通过。

执行链：`SetupAnimalAnimator.Run`→`FinalizeAnimalWalk.RunFor`→`FinalizeEnemyMotions.Run`→`VerifyEnemyMotions.Run`→`BuildEnemyReview.Publish/Build/Capture`。验收场景Additive创建、隔离渲染层，保留其它场景未保存编辑。

输出 `Tools/output/enemy_characters/{Name}/production_manifest.json`、`verification.txt`、动作处理记录、原始回执；完成后登记Model/Animation/Picture，并将总验收manifest的requiredClips设为三动作。旧 `run_rockball_walk.ps1` 只作单Walk诊断，会缩减控制器，正式制作使用新入口。

`--play-check`执行实际Play轮播，截图后自动退出Play。清单只有 `status=validated` 且qa两项均通过才表示完整交付；不带Play检查仅标 `edit_validated`。制作中标 `building`，不能将未完成结果视作通过。

## 岩团团样例

配方 `Config/Art/EnemyCharacters/RockBall.json`；视觉Prefab `Assets/Bundles/Characters/Enemy/RockBall/RockBall_Enemy.prefab`；场景 `Assets/Bundles/Scenes/Review/Enemy_RockBall_Review.unity`。横躺原因和单Walk历史保留在 `RockBall/WalkRiggingFix.md`，本方案是其三动作生产版本。

本次Idle/Attack在同一rig上重新生成；Walk沿用已验收源。三动作离线收尾后各121帧通过：Idle最大形变0.00635m，Walk左右步幅约0.06216/0.06124m，Attack最大形变0.13320m、最大根倾角14.098°；三段脚底误差均<0.6mm、首尾顶点差为0。控制器单次攻击与状态恢复、实际Play三状态轮播均已通过。3项配置/生成失败保护测试通过，完整一键生产命令已执行成功。
## 伙伴复用说明（2026-10-20）

同角色骨架、三动作离线处理与验收也供伙伴使用，统一入口为 `Tools/character_animation_pipeline.py`；原 `Tools/enemy_character_pipeline.py` 命令保持兼容。

伙伴配方使用 `usage: companion_visual`、`visualPrefab` 和独立 `reviewOriginX`，输出仍在对应角色的 `Characters/Animal/{Name}`，不创建敌方Variant。伙伴验收对象与相机使用含角色名的 `CompanionReview_{Name}` 前缀，避免与已加载的敌方验收对象重名；构建仍以Additive方式保留其他场景。

远程伙伴可选 `attackStyle: ranged_cast`，通过离线双臂抬起/前伸表现施法；`attackReach` 是小幅骨骼前伸，`attackLunge` 只控制模型内部的视觉位移。`attackEvent` 可配置，伙伴默认 `OnCompanionAttackImpact`，敌方沿用 `OnEnemyAttackImpact`。事件是视觉时机接口，接入实际火球与伤害前不表示玩法已完成。

新角色必须检查自身TokenRig后填写骨骼映射；禁止复用岩团团的bone编号。`boneMappingReady: false` 的草稿会被入口拒绝，不能当作完成资产。火喵正式配方为 `Config/Art/Companions/FireCat.json`，已完成1998 tris/1024 XPbr、自身22骨、Idle/Walk/施法Attack、伙伴视觉Prefab及Edit/Play验收；初始draft保留为禁止运行的制作记录。

火喵Walk的源动作在根骨之外还带有腿部坐姿偏移。此类来源使用 `walkBindCalibration: true`：每根骨骼以源首帧为参考，把相对运动应用到同rig的绑定姿态，并以 `walkSourceWeight` 控制幅度，然后再处理短步、贴地和循环。只纠正根骨不能保证腿部姿势正确；必须查看完整蒙皮的多个走路相位。旧岩团团配方默认沿用已验收处理方式。

DGXA显存不足时，可对指定动作加 `--generation-device cpu`（统一入口）或 `--device cpu`（generate_enemy_motions.py），只修改本次任务的独立采样配置；生成回执记录设备，不停止其他模型服务。火喵Attack首次CUDA运行因节点同时运行混元与音频服务而失败，保留失败日志并改用CPU重试。无需重新生成已经有效的Idle/Walk。

若自动骨架遗漏尾骨等附肢且权重错误跟随前臂，必须在最大动作幅度下检查蒙皮。配方可用 `skinOverrides` 以原静态模坐标/高度归一化的seed选取表面测地距离区域，在fullDistance到fadeDistance间渐变到指定已存在骨骼；该编辑只影响权重，不改变网格、UV或动作骨架。必须保留几何距离与受影响顶点范围报告，检查区域未误选头/躯干，完成绑定对照及动作峰值目视。火喵尾部175个顶点转到根骨后通过；目前没有独立尾骨的次级摆动。

对新角色先完成单Walk数值门禁（`VerifyEnemyMotions.Walk(recipePath)`）及多个相位目视，再交付完整三动作。数值门禁不能代替动作语义检查：施法必须能看出双爪前推，Idle不能大幅摇摆。最终配方支持 `idleSourceWeight` / `attackSourceWeight` 调整源运动幅度。


## 地面鸟型伙伴适配（2026-10-20）

闪闪雀配方 `Config/Art/Companions/SparkBird.json` 与制作记录 `SparkBird/ProductionBrief.md` 为 `avian_grounded` 已验收样例。它有自身28骨，不能复用短臂生物的骨名或把飞行作为Walk。该适配仅覆盖双足地面行走及挥翼施法；持续飞行、悬停与飞行切换需另建适配器。

`attackStyle=wing_cast` 与avian_grounded必须成对使用。通用rightArm／leftArm字段表示各自翼根，额外提供rightWingTip／leftWingTip；检查左右骨独立、翼根分居身体两侧。离线负X旋转把初始向外／向上的鸟翼向局部-Z扫出，两侧相反的Z旋转按wingSpreadDegrees展翼，attackReach可加小幅前伸。抬翼不能用身体前倾冒充；VerifyEnemyMotions扣除根骨转动后检查每侧翼尖相对身体前挥>1cm，并仍通过完整蒙皮／脚底／高度／循环／恢复／事件／控制器及Play门禁。

闪闪雀先完成单Walk再生成Idle／Attack，均同rig且CUDA成功；0.9秒Walk，1.4秒Idle，1.0秒Attack，0.45秒OnCompanionAttackImpact。双翼实际相对前挥约3.4／3.7cm，尾羽／冠羽无独立次级骨但峰值形状目视通过。伙伴Prefab、X=80独立场景、Edit／Play均已交付；5项流程保护测试和2个C#脚本编译通过。参数只属于该角色，复制到其它鸟型时须重查自身解剖和重新验收。

## 四足龟伙伴适配（2026-10-21）

泡泡龟 `Config/Art/Companions/BubbleTurtle.json` 为已验收quadruped_turtle／turtle_bubble样例，最终26骨、0.35m／2000tris；详情见BubbleTurtle/ProductionBrief.md。该适配覆盖水平四足龟和缩颈探头施法，其它四足仍需检查解剖与动作类型，不能直接套用。

前右／前左／后右／后左踝及脚尖全部独立映射，FinalizeAnimalWalk.RunQuadruped将源变化校准到绑定姿态，四拍20%摆动窗口保证每次一脚抬起，固定脚部朝向并烘焙实际蒙皮贴地。VerifyQuadrupedMotions每段121帧计算四只脚各自的实际网格步幅／抬脚／支撑，Walk至少三脚支撑，Idle／Attack四脚撑地。骨点移动不能代替实际网格移动；泡泡龟后左脚原步幅不足，经离线paw权重区域修正后四脚均达约3.4～3.5cm，门槛未放宽。

shellRegionMin／Max在Unity归一化空间选取壳区，扣除shellBone刚性变换后检查≤1mm形变；可见身体倾角使用壳体相对绑定姿态的世界up，不能用固定根骨掩盖身体倾斜。skinRegions在原静态FBX顶点／高度空间控制权重，两者Z方向转换必须明确；每个区域保留影响数和范围，保持几何／UV不变。

静态三分之四设计图可能生成斜向躯干。先离线统一高模和后续绑定源，再在Unity前／侧／背面确认；glTF相机约定不能代替游戏朝向检查，须计入FBX左右手转换。新增绑定门禁要求头及前脚位于后脚的-Z方向，泡泡龟最终采用原高模Blender Z +45°；17骨斜向／11骨反向均留诊断，正式动作只用26骨同一rig哈希。

标准入口自动选择四足Walk与专用验证器，Idle／Attack使用离线turtle_bubble收尾：四脚固定、缩颈→探头→恢复，0.6秒OnCompanionAttackImpact。三动作／壳刚性／接缝／控制器／实际Play均通过，6项Python保护测试和4个C#脚本编译通过；真实泡泡投射物／缓速／音效仍由技能系统接入。

## 重型四足伙伴适配（2026-10-21）

岩甲犀 `Config/Art/Companions/RockRhino.json` 为quadruped_heavy／braced_bash已验收样例：0.55m／2000tris／自身29骨。先离线统一高模朝向，再静态Unity三视图确认-Z；检查本角色胸背、头颈及四蹄映射，禁止套用龟的探头施法或其它角色bone编号。

重型四足复用RunQuadruped四拍步态；Attack独立编辑胸背前送、头颈短促推进和低头，四蹄撑地，逻辑根固定。配方必须给出armorRegion与hornRegion及各自≤2mm刚性预算（样例均1mm），对应chestBone／headBone；QA扣除各自刚性变换后检查实际顶点，另检查肩部前送和角区相对头枢轴降低，不能用根骨运动或纯转向冒充冲撞。区域坐标与蒙皮源空间的Z转换沿用明确登记原则。

岩甲犀先通过单Walk，再生成Idle／Attack。Attack源变化8%时后蹄离地4.08mm失败，调整为4%后降至1.77mm，通过原3mm门槛；头前送4.15cm、肩前送2.51cm、可见头转约11.21°，岩甲／头角区域刚性通过。四脚步幅约5.96～5.98cm、抬脚约1.47～1.60cm，至少三脚支撑；三段首尾与根XZ误差0，Edit／控制器／实际Play通过，0.6秒伙伴事件。详情见RockRhino/ProductionBrief.md。

入口run_script显式使用服务器timeout_ms=90000、CLI --timeout 120，覆盖现场Editor刷新后的调度延迟；不自动重试结果未知的写入。四足验证失败另存last_failure.txt后仍抛错，不能以旧失败文件或CLI外层成功替代当前verification与validated状态。7项Python流程保护测试覆盖重型分支错误配对、缺失刚性区域、共享头胸和四蹄映射；泡泡龟只读回归验收通过。


## P0 五类正式敌人（2026-10-21）

5 类敌人都按短腿双足 `biped_short`／`body_slam` 制作，共用一个已验证的解剖适配器，不需要新的四足或飞行适配器。设计、来源与验收结果见 `Doc/ResDesc_Model.md`「P0 五类正式敌人」；配方在 `Config/Art/EnemyCharacters/`。

| type | 敌人 | 配方 | 高度 | 骨数 | Walk／Idle／Attack |
| --- | --- | --- | --- | --- | --- |
| 0 | 小角怪 | Hornlet.json | 0.50m | 22 | 1.0／1.6／1.0s |
| 1 | 疾跑怪 | Dashlet.json | 0.50m | 22 | 0.8／1.4／0.9s |
| 2 | 硬壳怪 | Shellhorn.json | 0.50m | 28 | 1.2／1.8／1.0s |
| 3 | 角怪队长 | HornCaptain.json | 0.60m | 22 | 1.1／1.8／1.0s |
| 4 | 大角首领 | GreatHorn.json | 0.80m | 22 | 1.3／2.0／1.2s |

流程：设计草图（内网本地 Turbo）→ 用户选定 → 混元官网 50k → Blender 八向渲染确认正面 → `Tools/enemy_static_pipeline.py {Name} {height}`（烘焙、安装、静态 Prefab、四向检查）→ `Tools/rig_character_source.py --generate`（DGXA）→ 检查骨架填写配方 → `Tools/generate_enemy_motions.py`（DGXA）→ `character_animation_pipeline.py --build-review --play-check`。

本批次新增的注意事项：

- **DGXA 调用必须从 PowerShell 启动。** NVIDIA Sync 的 SSH 别名 `DGXA` 写在 `~/.ssh/config` 的 Windows 路径 Include 里，只有 Windows OpenSSH 能解析。Git Bash 下 ssh 解析失败，TokenRig 会静默回退本机 SkinTokens，得到单链退化骨架。`rig_character_source.py` 现在遇到回退会直接报错。DGXA 未连接时先运行 `Tools/dgx_ensure_ready.py`。
- **生图后释放显存。** 本地 Turbo 生图模型会占用 DGXA 约 43GB，导致 TokenRig 显存不足；3D 前调用 `POST /api/local-images/prepare-3d`。
- **DGXA 任务串行。** TokenRig 与 UniMate 并发时出现过 `No module named 'Animation'`，重试即可，应避免同时提交。
- **检查游离网格岛。** 混元高模可能把细尾尖等做成悬浮的独立网格，TokenRig 会丢弃，导致 `bl_transfer_skin` 报 bind geometry mismatch。先焊接 UV 接缝统计网格岛；有游离岛时用 `Tools/model_tools/bl_keep_main_island.py` 生成 `_main.glb`，烘焙和绑骨都用它。
- **验收后关闭验收场景。** 验收场景以 Additive 方式留在编辑器中，其相机 depth 很高，会盖住游戏 Play 画面。

战场接入：`BuildPrototype.ApplyFormalEnemies` 在 `PrototypeArena` 每个 `Enemies/EnemyN` 下嵌套 `Type0～4`，统一 1.2 单位高。`PrototypeFlow` 按 type 显示对应模型；`PrototypeBattle.Enemy` 新增仅供表现的 `Moving`／`Strikes`，移动时 Motion=1，每次出手触发一次 Attack，受击只做轻微缩放。`VerifyFormalEnemies.Assets`／`PlaySeeded`／`Cleanup` 为验收入口。

## 双足火焰施法伙伴适配（2026-10-21）

烈焰狮 `Config/Art/Companions/FlameLion.json` 为biped_short／flame_roar已验收样例：0.60m／2000tris／自身远程28骨。profile仍为双足；新attackStyle要求自身头颈／胸背／双臂与爪尖／双脚、鬃毛区域与≤2mm刚性预算，禁止套用火喵编号或按大头外观改成四足。

离线施法固定双脚与逻辑根，编辑头部前送／抬头、双爪前送／展开，开始与结束为Idle参考。QA对头鬃区实际网格扣除头骨刚性变换检查，对头部和双爪扣除胸背转动检查释放行为，并对两脚实际顶点测步幅／抬脚／支撑。不能只看脚骨或用身体前倾冒充施法。烈焰狮没有独立下颌或尾骨，本版无张嘴口型与独立尾摆；尾部58个源顶点跟随髋骨。

头鬃宽空间区域与尾部相邻时，bl_transfer_skin先执行skinRegions，再由精细skinOverrides测地距离覆盖，防止尾簇被头部或前臂带动。两种规则必须按自身网格检查，不能盲抄；此前已有伙伴未同时启用两种覆盖，其原单类行为不变。

烈焰狮先通过单Walk再补同rig Idle／Attack。25%Walk源变化导致左脚实际抬脚6.71mm失败，降至12%后11.91mm通过，未放宽门槛；两脚实际步幅48.66／67.37mm。Attack头前送16.24mm／抬头6.654°、双爪前送约6cm／外展约2cm，双脚支撑、鬃毛刚性及Edit／实际Play通过，0.6秒伙伴事件。详情见FlameLion/ProductionBrief.md。

本机TokenRig回退曾产出异常33骨长链，不可按生成回执直接当可用骨架。`rig_character_source.py --backend remote`要求远程回执且拒绝隐式本机回退；显存错误需保留诊断、验证GPU状态后重试，不停止其它服务。最终烈焰狮只接受DGXA28骨哈希。8项流程保护测试与火喵只读回归通过。

并排截图使用BuildEnemyReview.Capture隔离Prefab实例，在PreviewScene采样指定相位并异步等待渲染更新，避免已有Animator状态让Attack列显示旧Idle姿势；不改写或暂停真实验收场景。该方法已实际编译执行、峰值截图核对通过。

## 敌人攻击／受击表现衔接（2026-10-21）

五类正式敌人已接入8套攻击／命中特效与8条TangoFlux短音效，受击不再只有缩放。资产放在 `Assets/Bundles/Effects/EnemyCombat/` 和 `Assets/Bundles/Sound/SFX/EnemyCombat/`；完整方案见 [../Combat/EnemyCombatFx/Production.md](../Combat/EnemyCombatFx/Production.md)。继续制作敌人时需检查类型映射、攻击与目标命中位置、硬甲分类、音效开关及池回收；不能让动画事件扣血或把减速Pulse当成实际命中。现有规则即时结算与动画前摇的对齐属于下一阶段技能时序改造。