119 lines
11 KiB
Markdown
119 lines
11 KiB
Markdown
# 敌方角色标准制作方案 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骨。配方显式记录root/chest/左右臂/脚根/脚尖/正面参考骨；12骨和bone_8等名称只属于样例。
|
||
|
||
其它短腿双足敌人需换成自己的骨名、尺寸和节奏并完整验收。四足、长腿人形、飞行或无脚敌人需要对应解剖适配器，当前入口拒绝未知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` 调整源运动幅度。
|
||
|