Add prototype gameplay loop with character/battlefield assets and server game APIs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-20 18:50:00 +08:00
parent 79369e4473
commit 6c64210331
833 changed files with 998079 additions and 1042 deletions
@@ -0,0 +1,85 @@
+# 角色与单位美术制作 / 验收流程
+
+本流程把「设计图 → 混元 → 减面烘焙 → 入库 Prefab → 验收场景」固定成可重复步骤。验收只在编辑器专用场景里做，不进开战运行时。
+
+配套清单：`character_unit_review_manifest.json`  
+Pipeline：`AIClient/AgentScripts/BuildCharacterReview.cs`、`SetupCharacter.cs`
+
+## 目录约定
+
+| 用途 | 路径 |
+| --- | --- |
+| 设计原稿 | `Doc/Design/Character/{英文名称}/`（不进 Bundles） |
+| 高模 / 烘焙中间件 | `Tools/output/{name}_3d/`、`Tools/output/{name}_game/` |
+| 游戏资源 | `AIClient/Assets/Bundles/Characters/{Kind}/{英文名称}/` |
+| 验收场景 | `Assets/Bundles/Scenes/Review/CharacterUnitReview.unity` |
+| 验收报告 | `Tools/output/character_review/CharacterUnitReview/review_report.json` |
+
+`Kind` 建议：
+
+- `Human`：人形（T Pose，目标身高约 1.8m）
+- `Animal`：非人生物 / 宠物正式模型（站姿或四足，目标身高按物种登记）
+- 后续武器/道具走 `GameResProductProc` 独立物件节，可先在本验收场景并排放下对比尺度
+
+网格约定与附录 B 一致：Y-up、原点在底面中点、局部 **-Z 为正面**。
+
+## 制作步骤（单件）
+
+1. **设计图**：纯白底、全身入画。人物用 T Pose、比例 `2:3`；非人用可辨识站姿，比例按体型选 `2:3` 或 `1:1`。
+2. **混元图生 3D**：`Tools/hunyuan_3d_generate.py --faces 50k`。
+3. **减面烘焙**：`Tools/model_tools/model_lowpoly_bake.py --tris <目标> --size 1024`。人物约 3000；非人/宠物默认 800～2000，在 manifest 的 `maxTriangles` 写死验收上限。
+4. **入库**：`python Tools/install_character_bundles.py -a {Name} --kind {Kind} -b Tools/output/..._xpbr`
+5. **Prefab**：  
+   `unity command --project-path D:/UD/AI/AIGame/AIClient run_script --file AgentScripts/SetupCharacter.cs --entry SetupCharacter.Run --args '["Animal","LmCat",0.42]'`
+6. **登记**到 `Doc/ResDesc_Model.md` / `Doc/ResDesc_Picture.md`。
+7. **验收**：把该件追加进 `character_unit_review_manifest.json` 的 `subjects`，再执行下方 Pipeline。
+
+## 验收场景（专用）
+
+场景里固定包含：
+
+- 地面与刻度（身高参考柱 0.5 / 1.0 / 1.8m）
+- 每个 subject 脚下的 **-Z 正面箭头**
+- 方向光 + 验收相机
+- 按 `spacing` 横向排列的 Prefab 实例
+
+### Pipeline 入口
+
+```powershell
+# 校验 manifest 与 Prefab 是否齐全
+unity command --project-path D:/UD/AI/AIGame/AIClient run_script --file AgentScripts/BuildCharacterReview.cs --entry BuildCharacterReview.ValidateOnly
+
+# 生成 / 覆盖验收场景，并写报告
+unity command --project-path D:/UD/AI/AIGame/AIClient run_script --file AgentScripts/BuildCharacterReview.cs --entry BuildCharacterReview.Build
+
+# 打开场景并框住全体
+unity command --project-path D:/UD/AI/AIGame/AIClient run_script --file AgentScripts/BuildCharacterReview.cs --entry BuildCharacterReview.OpenReview
+
+# 自动量身高、面数、XPbr、底面贴地
+unity command --project-path D:/UD/AI/AIGame/AIClient run_script --file AgentScripts/BuildCharacterReview.cs --entry BuildCharacterReview.ValidateReview
+
+# 截 Scene View 留档
+unity command --project-path D:/UD/AI/AIGame/AIClient run_script --file AgentScripts/BuildCharacterReview.cs --entry BuildCharacterReview.CaptureReview
+```
+
+### 验收门槛
+
+- Prefab 可加载，材质为 `Test/XPbr`（manifest 可对旧件关闭 `requireXpbr`）
+- 包围盒底面 `min.y` 接近 0（±0.05）
+- 身高在 `expectedHeight ± heightTolerance`
+- 三角面数 ≤ `maxTriangles`
+- 人工目视：局部 -Z 朝向相机前的箭头、无悬浮、无穿模、贴图无品红缺贴图
+
+通过后，才允许把该 Prefab 接到开战/营地替换简模。
+
+非人绑骨/三动作见 `GameResProductProc` 二.3.B：先验收静态模，再 `--mesh` 已验收 FBX 跑 TokenRig+UniMate → `install_animal_rigged` → `SetupAnimalAnimator`（挂回 XPbr）。`{Name}_Rigged` 并排验收（`requireAnimator` + `requireXpbr`），勿覆盖静态 Prefab。
+
+带 `Motion` 参数的单位会挂 `CharacterReviewAnimCycle`，在 Scene 视图自动轮播 Idle→Walk→Attack（约 2.8s/段，名称旁显示当前动作）。
+
+诊断新骨架时可先设 `requiredClips: ["Walk"]` 验证单动作；正式敌方必须恢复三动作检查。RockBall现已在同一12骨上补齐Idle/Walk/Attack，正式流程见 [EnemyCharacterProduction.md](EnemyCharacterProduction.md)。单Walk历史见 [RockBall/WalkRiggingFix.md](RockBall/WalkRiggingFix.md)。
+
+## 与开战的关系
+
+敌方角色制作采用 [EnemyCharacterProduction.md](EnemyCharacterProduction.md)：同角色骨架、空间对齐、三动作来源哈希、离线收尾、Enemy视觉Prefab与整段验收。岩团团已从单Walk阶段升级到Idle/Walk/Attack；总验收按三动作检查。
+
+本场景**不**被 `PrototypeFlow` 加载。开战仍用 `PrototypeArena` 简模，直到某宠物正式模型验收通过并单独做替换任务。
@@ -0,0 +1,118 @@
+# 敌方角色标准制作方案 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` 调整源运动幅度。
+
@@ -0,0 +1,56 @@
+# 火喵 FireCat · T1制作记录
+
+2026-10-20。伙伴清单ID=1，继岩团团之后制作。火元素、远程输出，普通攻击为火焰弹，技能“灼热火球”；不改变玩法数值。
+
+## 本次范围
+
+T1设计图→混元高模→约1800三角面低模/1024 XPbr→同角色TokenRig→Idle/Walk/Attack→伙伴视觉Prefab与专用验收。T2另作进化形态，不混入本次T1。
+
+## 造型与动作
+
+参考现有火喵原型的橙色主体、奶油色口鼻/肚皮/爪子、青色领圈和弯尾，统一为岩团团的精致卡通3D材质与大眼比例。短腿双足、双臂稍离躯干，双脚可见；三角耳、额头火焰纹、尾尖实体火焰绒簇。无武器、无独立漂浮火焰，便于蒙皮及低模烘焙。
+
+Idle轻呼吸与尾部小幅变化；Walk交替短步；Attack为蓄力后双爪前推的远程施法动作，保持脚下站位。实际火球/命中效果与玩法发射逻辑另行接入，不将近身冲撞动作直接复用为施法。
+
+目标身高0.55m（含耳），Y-up、底面中心、局部-Z正面。静态形状验收后再绑定动画；所有动作使用火喵自己的同一rig。伙伴资产在Characters/Animal/FireCat，不创建敌方角色Variant。
+
+## 设计图
+
+`firecat.png`：内置imagegen参考岩团团风格和火喵原型生成，1086×1448。四角RGB最小253，纯白背景门槛通过。原图留在Doc，不放入Bundles。
+
+生成提示词与输入记录见 `design_prompt.txt`。参考图仅提供风格/原型身份，不覆盖原始参考文件。
+
+## 状态
+
+- 设计图：已生成并检查。
+- 高模、低模、绑定、三动作、伙伴视觉Prefab与Unity Edit/Play验收：已完成。用户已明确授权设计图提交腾讯混元3D、同角色模型发送DGXA（192.168.132.46）绑骨及三动作。
+- 正式配方：`Config/Art/Companions/FireCat.json`。初始 `FireCat.draft.json` 保留为不可运行的制作记录；正式配方包含自身22骨映射和最终动作/权重参数。
+- 入口：`python Tools/character_animation_pipeline.py --recipe Config/Art/Companions/FireCat.json --build-review --play-check`。默认使用同源缓存，不重新发起推理。4项Python流程测试通过。
+
+## 最终资产
+
+混元50k档高模50186 tris→Blender低模1998 tris、1006源顶点、1024 XPbr base/mix。静态与动画伙伴身高0.55m，Y-up、底面中心、局部-Z正面；动画外层根为单位缩放，Root Motion关闭。
+
+- 目录：`AIClient/Assets/Bundles/Characters/Animal/FireCat/`
+- 静态：`FireCat.prefab`；同源蒙皮：`FireCat_Rigged.prefab`；伙伴视觉：`FireCat_Companion.prefab`
+- 动作：`Clips/{Idle,Walk,Attack}.anim`；Controller：`FireCat_Animator.controller`
+- 验收：`AIClient/Assets/Bundles/Scenes/Review/Companion_FireCat_Review.unity`，静态/Idle/Walk/Attack/自动轮播并排，Additive构建，未保存或关闭其它场景。
+- 来源与报告：`Tools/output/companions/FireCat/{production_manifest.json,verification.txt,play_verification.txt,walk_verification.txt}`。
+
+## 绑定与动作处理
+
+TokenRig同角色高模生成22骨，rig SHA256为 `62a5097099beccbbefd40a97ac7d744c086dcf3f39411fab81ba5ac37db03bea`，三个源动作回执完全一致。自身映射：root=bone_0，chest=bone_3，左右臂=bone_7/11，脚根=bone_16/20，脚尖=bone_17/21。均按实际位置和层级检查，不复用岩团团的12骨编号。
+
+Walk源首帧根倾斜约69.5°且腿部呈坐姿。只修根骨仍会坐着走，因此开启全骨骼首帧相对绑定姿态校准、保留35%源运动，再离线编辑短步、贴地和循环。最终1.1秒循环，左右有效步幅约0.0625/0.0455m，最大根倾角4.35°。
+
+Idle源运动降至8%后形成轻呼吸/小幅摆动，1.6秒循环。Attack保留12%源运动，双爪75°抬起并小幅前伸，蓄力→施法→恢复，共1.1秒；0.55秒触发 `OnCompanionAttackImpact`，不循环，结束恢复请求的Idle或Walk。Controller使用 `Motion` Int（0/1）和 `Attack` Trigger。
+
+TokenRig未生成独立尾骨，原自动权重让部分尾部跟随前臂，施法时被拉扁。配方skinOverrides使用低模表面测地距离选择尾部、渐变绑定到bone_0；修正175个顶点权重，保留几何/UV/骨架与三动作来源，限制4权重并归一化。尾巴随躯干自然运动，目前没有独立尾骨摆动。绑定姿态相对静态模最大顶点差约0.000030m。
+
+Attack首次CUDA推理因其它混元/音频服务占用DGXA内存而失败，保留日志；改用独立任务CPU配置生成成功，未停止其他服务。该回执明确device=cpu。
+
+## 验收结论
+
+三个动作各121帧实际蒙皮通过；最终最大脚底误差约0.15mm，循环及Attack恢复端点顶点差为0。最大根倾角Idle约1.85°、Walk约4.35°、Attack约11.31°。控制器切换、一次Trigger只攻击一次、恢复请求状态通过；实际Play观察到三个状态，逻辑根位置固定。正侧背与施法峰值目视通过。
+
+本次完成T1视觉资源；火球特效、实际发射/伤害和开战/营地正式替换属于玩法接入，尚未接入。T2进化形态另作资产。
@@ -0,0 +1,5 @@
+Method: built-in imagegen, style-transfer, opaque white background.
+Style reference: Doc/Design/Character/RockBall/rockball.png
+Identity reference: AIClient/Assets/Bundles/UI/Texture/Prototype/proto_pet_1.png
+
+Create FireCat (火喵), the next companion, a friendly small fire-element ranged-damage cat. Match the approved RockBall reference's polished stylized 3D mobile creature rendering, expressive glossy eyes, soft toy-like volume and grounded material detail; do not copy stone, moss or blue crystal. Preserve the FireCat prototype's warm orange body, cream muzzle/belly/paws, simple turquoise collar, upright bipedal cat and curved tail, replacing blocky geometry with rounded finished anatomy. One full-body T1 character centered on pure white #FFFFFF, no text, labels, props or scenery. Near-front view with a slight three-quarter turn, face/both arms/both feet clearly visible, eye-level camera. Rounded cat head, triangular soft ears, golden inner ears, huge amber-brown eyes with catchlights, dark feline nose and confident friendly smile. Short arms slightly away from torso for rigging, separate stubby legs and cream paws on invisible ground. One orange tail curves beside/behind the body; compact sculpted orange-red/yellow flame-shaped tuft at its tip, continuous solid geometry, no floating flame/particles. Modest flame-shaped forehead marking. Plain turquoise collar, no bell/equipment/armor. Clean simple volumes suitable for1500-2000 triangle model. Soft studio light, stylized fur without wispy strands, white corners and full silhouette.
@@ -0,0 +1,50 @@
+# 岩团团绑骨与 Walk 流程修正（2026-10-20）
+
+此文保留单Walk诊断历史。后续已升级为敌方Idle/Walk/Attack三动作标准，正式制作入口和当前状态见 [../EnemyCharacterProduction.md](../EnemyCharacterProduction.md)；旧单Walk脚本仅用于诊断。
+
+已跑通单个 Walk：`RockBall_Rigged.prefab` 使用同角色高模的12骨骨架，默认循环播放1.1秒走路。专用并排场景：`Assets/Bundles/Scenes/Review/RockBallWalkReview.unity`。原静态模型、UV、XPbr贴图保持原样。
+
+## 原因与证据
+
+1. **权重转移前缺少坐标对齐。** `bl_decimate.export_fbx_source_yup` 保存的是项目Y-up顶点；Blender重新导入后仍为Y-up，静态低模高度位于Y=0..1.0069。TokenRig GLB进入Blender后则为Z-up。旧 `bl_transfer_skin.py` 的“keep both as imported”把这两者直接蒙皮；所以绑定姿态就已横躺，不能仅凭根骨up判断网格站直。
+2. **骨架来源不匹配。** 旧资产使用 `3cead72a` 的19骨代理，形体及原点与验收低模不同。当前使用同一混元高模生成的 `high_rig/rigged.glb` 12骨骨架；对齐后低模至高模表面RMS=0.002229、最大0.005794（原始高度约1）。
+3. **旧Walk实际上提交了Jump。** `high_rig/pipeline.log` 写明：用户提示“原地走路弹跳…”被后端转成 `an animal jumps forward`。英文walk又会被上游改写成dog；新适配器保留明确的双足英文提示，指定左右脚骨 `bone_8/bone_10`。
+4. **新生成动作仍需制作收尾。** 原始UniMate Walk带约34.46°初始根骨偏移，脚部平移不足4mm、首尾顶点差约3.7cm。`FinalizeAnimalWalk` 在编辑期烘焙绑定参考根姿态、原地XZ、实际蒙皮贴地、周期残差闭合，并为短腿骨架编辑交替步幅。最终步幅0.06m、抬脚0.018m、周期1.1s。它是“UniMate源动作＋离线编辑”的样例，不把生成原件当作可直接交付的成品。
+
+Armature在Unity中的+90°X是这组FBX的坐标表示；骨架与动作一致时可以保留。不要单独清零Armature或给Prefab套反向90°旋转，这会破坏绑定矩阵或让动画重新覆盖。
+
+## 可复现入口
+
+在仓库根目录运行 `powershell -File Tools/run_rockball_walk.ps1`：使用已缓存的同角色骨架与新Walk，重做转权重、Pipeline导入、Prefab、Walk离线烘焙、验证。`-Generate` 会调用DGXA重新生成源动作；不需要重新绑骨或重做静态模。
+
+关键步骤：
+
+```powershell
+# 项目静态FBX → 同角色高模骨架空间；输出在Tools，不手改Unity资产
+& D:/Tools/Blender/blender-5.0.0-windows-x64/blender.exe -b --factory-startup --python Tools/model_tools/bl_transfer_skin.py -- Tools/output/rockball_dgx/high_rig/rigged.glb AIClient/Assets/Bundles/Characters/Animal/RockBall/RockBall.fbx Tools/output/rockball_dgx/walk_verified/RockBall_Rigged.fbx --low-up Y --align-bounds
+
+# Pipeline导入Rigged FBX与walk_verified/motion/animated.fbx后，按顺序执行
+unity command --project-path D:/UD/AI/AIGame/AIClient run_script --file AgentScripts/SetupAnimalAnimator.cs --entry SetupAnimalAnimator.SetupRockBallWalk
+unity command --project-path D:/UD/AI/AIGame/AIClient run_script --file AgentScripts/FinalizeAnimalWalk.cs --entry FinalizeAnimalWalk.Run
+unity command --project-path D:/UD/AI/AIGame/AIClient run_script --file AgentScripts/VerifyAnimalWalk.cs --entry VerifyAnimalWalk.Run
+```
+
+重新执行Setup会从原始FBX提取Walk，因此必须接着执行Finalize。`FinalizeAnimalWalk.Run` 参数依次为步幅米数、抬脚米数、循环秒数。当前12骨没有长腿的完整髋/膝链，走路采用短脚迈步，不作为通用长腿人形重定向模板。
+
+## 验证结果
+
+| 检查 | 结果 |
+| --- | --- |
+| 绑定几何 | 0.55000m高、底面Y=0；对静态模最大顶点误差0.000031m |
+| 资源 | 1500三角面、12骨、最多4权重、原XPbr材质 |
+| 整段61帧采样 | 根骨最大倾角0.27°；脚底Y约-0.00016..0.00050m |
+| 左右脚前后步幅 | 0.06212m / 0.06124m |
+| 关节运动 | 最大32.94° |
+| 循环接缝 | 首尾蒙皮顶点差0 |
+| Animator | 实际控制器连续6秒，保持Walk并完成约5.45圈 |
+| Play Mode | 专用场景实际播放约16圈后Live校验通过，脚底Y=0；随后退出Play，保留Edit预览 |
+| 总角色验收 | CaoCao、LmGirl、LmCat、RockBall、RockBall_Rigged均通过 |
+
+报告：`Tools/output/rockball_walk_audit/{processing,verification}.txt`；截图：`Assets/Screenshots/rockball_walk_{review,play}.png`。验收计算实际蒙皮顶点，不能把SkinnedMeshRenderer的保守剔除包围盒当作脚底位置。错误19骨代理的几何匹配检查已验证会拒绝（RMS=0.04218，最大=0.13996）；完整本地缓存复现脚本已执行通过。
+
+当前仅Walk接入控制器。旧19骨Idle/Attack留作历史资源，不接入12骨；后续必须在同一12骨rig上生成并单独验收，不能按bone_N同名直接混用。
@@ -0,0 +1,95 @@
+{
+  "schemaVersion": 1,
+  "sceneId": "CharacterUnitReview",
+  "outputScene": "Assets/Bundles/Scenes/Review/CharacterUnitReview.unity",
+  "reportPath": "Tools/output/character_review/CharacterUnitReview/review_report.json",
+  "label": "角色与单位美术验收",
+  "spacing": 3.0,
+  "groundSize": 24.0,
+  "cameraPosition": { "x": 6.0, "y": 1.4, "z": -6.5 },
+  "cameraTarget": { "x": 6.0, "y": 0.85, "z": 0.0 },
+  "fieldOfView": 35,
+  "subjects": [
+    {
+      "id": "CaoCao",
+      "kind": "Human",
+      "prefab": "Assets/Bundles/Characters/Human/CaoCao/CaoCao.prefab",
+      "expectedHeight": 1.8,
+      "heightTolerance": 0.15,
+      "maxTriangles": 3500,
+      "requireXpbr": true,
+      "notes": "人物样例：Y-up、底面原点、局部 -Z 正面"
+    },
+    {
+      "id": "LmGirl",
+      "kind": "Human",
+      "prefab": "Assets/Bundles/Characters/Human/LmGirl/LmGirl.prefab",
+      "expectedHeight": 1.65,
+      "heightTolerance": 0.15,
+      "maxTriangles": 3500,
+      "requireXpbr": true,
+      "notes": "人物样例"
+    },
+    {
+      "id": "LmCat",
+      "kind": "Animal",
+      "prefab": "Assets/Bundles/Characters/Animal/LmCat/LmCat.prefab",
+      "expectedHeight": 0.42,
+      "heightTolerance": 0.12,
+      "maxTriangles": 3500,
+      "requireXpbr": true,
+      "notes": "非人样例：可作宠物正式模型目录模板 Characters/Animal/{Name}"
+    },
+    {
+      "id": "RockBall",
+      "kind": "Animal",
+      "prefab": "Assets/Bundles/Characters/Animal/RockBall/RockBall.prefab",
+      "expectedHeight": 0.55,
+      "heightTolerance": 0.12,
+      "maxTriangles": 2000,
+      "requireXpbr": true,
+      "notes": "岩团团正式静态宠模：混元50k→烘焙1500 tris；已通过。开战/营地替换另开任务"
+    },
+    {
+      "id": "RockBall_Rigged",
+      "kind": "Animal",
+      "prefab": "Assets/Bundles/Characters/Animal/RockBall/RockBall_Rigged.prefab",
+      "expectedHeight": 0.55,
+      "heightTolerance": 0.15,
+      "maxTriangles": 2500,
+      "requireXpbr": true,
+      "requireAnimator": true,
+      "requiredClips": ["Idle", "Walk", "Attack"],
+      "notes": "敌方制作标准样例：同角色12骨→空间对齐→低模转权重→Idle/Walk/Attack→离线收尾；Enemy视觉Variant见Characters/Enemy/RockBall。Motion=0/1，Attack使用Trigger。"
+    },
+    {
+      "id": "FireCat",
+      "kind": "Animal",
+      "prefab": "Assets/Bundles/Characters/Animal/FireCat/FireCat.prefab",
+      "expectedHeight": 0.55,
+      "heightTolerance": 0.01,
+      "maxTriangles": 2000,
+      "requireXpbr": true,
+      "notes": "火喵T1伙伴静态模：混元50k→1998 tris/1024 XPbr，隔离正侧背面与尺寸贴地验收通过。"
+    },
+    {
+      "id": "FireCat_Companion",
+      "kind": "Animal",
+      "prefab": "Assets/Bundles/Characters/Animal/FireCat/FireCat_Companion.prefab",
+      "expectedHeight": 0.55,
+      "heightTolerance": 0.01,
+      "maxTriangles": 2000,
+      "requireXpbr": true,
+      "requireAnimator": true,
+      "requiredClips": ["Idle", "Walk", "Attack"],
+      "notes": "火喵T1伙伴视觉：同角色22骨，Walk全骨骼首帧校准，尾部权重修正；Idle/Walk循环，Attack单次双爪施法，0.55秒出手事件。专用Companion_FireCat_Review场景Edit/Play均通过。"
+    }
+  ],
+  "workflow": {
+    "designDir": "Doc/Design/Character/{Name}/",
+    "bakeOutput": "Tools/output/{name}_game/",
+    "bundleDir": "AIClient/Assets/Bundles/Characters/{Kind}/{Name}/",
+    "setupEntry": "SetupCharacter.Run",
+    "reviewEntry": "BuildCharacterReview.Build"
+  }
+}