AIGame/Doc/Design/Character/RockBall/WalkRiggingFix.md

岩团团绑骨与 Walk 流程修正（2026-10-20）

此文保留单Walk诊断历史。后续已升级为敌方Idle/Walk/Attack三动作标准，正式制作入口和当前状态见 ../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重新生成源动作；不需要重新绑骨或重做静态模。

关键步骤：

# 项目静态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同名直接混用。