11 KiB
敌方角色标准制作方案 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不自动重复攻击。
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. 制作入口与复现
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 调整源运动幅度。