Files
UmaViewer/implementation_plan.md
T

14 KiB
Raw Blame History

PMX 导出姿势与 IK 修复实施计划

已确认目标

  • PMX 导出前固定回到角色初始化姿势,并将左右上臂分别旋转 -38.5°、+38.5°,生成与历史 VMD 导出一致的 MMD 默认 A-pose。
  • 导出期间冻结 Animator、眼动和动态骨,保证顶点烘焙与骨骼位置来自同一参考姿势。
  • 无论导出成功或异常,都恢复角色 Transform、表情权重、Animator、眼动和物理状态。
  • 按 PMX 文件原始语义写入 IK 角度限制,使用未经尺寸缩放和坐标轴翻转的弧度,并逐轴规范化上下限。

实施范围

  1. 由角色导出状态快照辅助类冻结状态、应用固定 A-pose,并在结束后完整恢复。
  2. PMX 与 VMD 使用同一组 38.5° 手臂参考旋转。
  3. PMX Writer 对 IK 角度执行有限值校验和端点排序后,以原始弧度直接写入。
  4. PMX Reader 以无尺寸倍率、无坐标轴翻转方式读取 IK 弧度,并对异常文件重新排序。
  5. 骨架导出前校验 IK 索引及角度区间,拒绝 NaN、Infinity 和倒置区间。

验证标准

  • dotnet build umamusume.csproj -nologo 构建无错误。
  • PMX 导出路径不调用 Animator Rebind(),而是明确应用固定 MMD A-pose。
  • 膝 IK 写入 PMX 并回读后均为约 [-π, -0.0087];MMD Skin/Saba 转换到求解器后为约 [0.0087, π]。
  • 导出成功和异常路径都能恢复原动作、表情、眼动和物理状态。
  • 最终在 MMD Skin 中实机确认导入不崩溃、双臂姿势正确且腿 IK 弯曲方向正常。
  • 使用问题动作和正常动作分别导出,并在 Blender 中确认基础姿势不受预览动作影响。

执行状态

  • 完成导出状态冻结、MMD 默认 A-pose 应用及异常路径恢复。
  • 完成标准骨架、腿 IK 和 IK 原始弧度读写修复。
  • 完成项目构建、差异检查和膝 IK 二进制写入验证。
  • 在 MMD Skin 中实机确认导入、A-pose、膝盖弯曲方向及导出后状态恢复。
  • 使用问题动作和正常动作导出,并在 Blender 中确认两份 PMX 的基础姿势一致。

修复复盘和长期维护规则见 docs/pmx-export-standard-and-postmortem.md。


PMX/MMD 原生物理导出实施计划(网络资料修订版,待批准)

目标是生成符合 PMX 2.x 语义、可由 MMD 标准运行时直接消费的物理数据。MMDSkin 不负责自动补充阻尼追踪;此前“只导出骨骼链”的兼容方案作废,也不会原样恢复已经出现卷曲和拉扯的旧刚体实现。

已确认根因

Assets/Scripts/Exporters/ModelExporter.cs 当前在构建 PMX 模型时无条件写入空的 Rigidbodies 和 Joints 数组。因此导出文件虽然包含网格、骨骼和表情,却没有任何 PMX 动力学数据;预览中由 CySpring 驱动的头发、裙摆、耳朵和尾巴不会被带入导出结果。

截图中的 Blender 约束 mmd_additional_rotation、目标骨 _shadow_* 是 mmd_tools 对 PMX 付与旋转字段的还原。付与旋转只表达骨骼之间的旋转继承,不提供时间延迟、惯性、重力或回弹,不能替代刚体和 Joint。

实现目标与边界

  • 按 MMD 的三层语义导出:骨骼变形顺序、明确存在的付与旋转关系、刚体与六自由度弹簧 Joint。
  • 第一阶段只覆盖由 CySpringDataContainer.springParam 明确标识、拓扑可判定为单根串联链的头发、耳朵和尾巴。
  • 裙摆不是普通串联链:按 MMD 常用做法,需要纵向动态刚体链、同层横向 Joint 和薄盒体共同组成网格,因此独立放在第二阶段,不能套用头发胶囊链。
  • CySpring 只用于识别动态链及提供参数参考,不假定其参数与 MMD Bullet 一一等价;首版采用集中定义、可校准的保守 MMD 预设。
  • 第一阶段不导出复杂身体碰撞体和环境平面,不承诺逐帧复刻游戏内 CySpring、风场或裙摆专用求解结果。
  • 不为所有 Sp_* 父子骨自动添加付与旋转。只有存在明确 MMD 继承语义时才写入 AppendRotate,避免动画层级和物理层级产生双重旋转。

影响范围

  1. Assets/Scripts/Exporters/PMXPhysicsExporter.cs(新增) 收集 CySpring 骨骼链,按 PMX 语义建立刚体、Joint、碰撞过滤和参数校验;坐标与角度换算集中在此处。
  2. Assets/Scripts/Exporters/ModelExporter.cs 在骨骼索引建立完成后调用物理导出器,替换当前的空数组赋值。
  3. Assets/Scripts/Exporters/PMXBoneExporter.cs 为参与物理的骨骼设置符合 MMD 更新顺序的 PostPhysics 与 TransformLevel;保留已经加入的标准 両目 控制骨。
  4. Assets/Scripts/Exporters/UnityPMXRuntimeLoader/LibMMD/Writer/PMXWriter.cs 保留刚体碰撞组单字节修复,并严格区分空间坐标、尺寸和弧度字段的写入规则。
  5. Assets/Scripts/Exporters/UnityPMXRuntimeLoader/LibMMD/Reader/PMXReader.cs 对称修正 Joint 角度字段读取,保证 PMX 往返后数值与单位一致。
  6. Assets/Scripts/Exporters/PMXPhysicsExporterTests.cs(新增) 覆盖链提取、骨骼缺失、非法浮点、索引关联、刚体类型、碰撞掩码、坐标方向和弧度区间。

参数映射方案

CySpring 数据 PMX 导出策略
springParam 的根/子骨骼 识别连续动态链,只接受已存在于 PMX 骨骼索引中的节点
骨骼位置与子骨方向 计算胶囊中心、长度及朝向;末端缺少子骨时使用可验证的链段回退规则
collisionRadius 作为半径参考并进行有限值和骨长比例钳制,不直接无界写入
_stiffnessForce 仅作为预设档位参考,转换后的旋转弹簧系数集中定义并可调
_dragForce 仅作为阻尼档位参考,分别映射到平移阻尼和旋转阻尼并限制范围
_gravity 不直接写入刚体;PMX 没有逐刚体重力字段,只参与预设选择或记录诊断
_isLimit 作为是否启用保守旋转限制的参考;首版不猜测不存在的逐轴 CySpring 限制
collisionNameList 第一阶段只用于诊断;第二阶段加入身体碰撞体后再映射跨组碰撞关系

刚体与关节生成规则

  1. 根据 PMXBoneExporter.Result.BoneIndexes 解析 CySpring 骨骼名并拆分连续链;缺失节点在日志中聚合报告,不能跨过缺失节点强行连接 Joint。
  2. 每条链根部使用关联链根父骨的 Type 0 / 骨骼跟随 支撑刚体,后续链段使用 Type 1 / 物理演算 动态刚体。若父骨已有可复用支撑体则不重复生成,防止初始重叠。Type 2 首版禁用,因为它会在 Bullet 求解后额外校正骨骼位置,位移限制不当时容易放大振动。
  3. 相邻刚体使用 PMX 2.0 Joint 类型 0(Spring 6DOF)连接,Joint 位置放在对应骨骼节点。固定以父级或锚刚体为 A、子动态刚体为 B,作为稳定的写入约定;不假定 A/B 顺序本身提供阻尼语义。
  4. 线性链的形状按链段几何选择:有明确长度且适合覆盖细长骨段时使用胶囊,短链段或近球形末端使用球体。胶囊中心位于链段中点,轴由父骨指向子骨;不能稳定定向时回退为球体并记录诊断。
  5. 刚体在初始姿势下必须没有会产生排斥的非预期重叠。动态链使用专用碰撞组并关闭组内自碰撞,避免同链及不同发束互相挤压;第一阶段没有身体碰撞体,因此也不伪造跨组碰撞关系。
  6. 平移限制默认锁定在 Joint 原点;旋转限制依据链段局部轴开放,不使用统一的三个轴对称小角度。教程表明限制过紧同样会产生边界振动,因此首版采用可校准的中等活动范围,并由阻尼和旋转弹簧负责收敛。
  7. 质量从根部向末端递减,末端平移和旋转阻尼逐步增大,以降低长链末端不断累积的运动能量。反弹力和摩擦力默认设为 0。具体数值集中在命名预设中,并在 MMDSkin 样本测试后校准,不把教程示例值直接硬编码为规范值。
  8. 动态刚体关联的骨骼标记为物理后变形;锚骨及普通动画骨保持物理前变形。实际 TransformLevel 依据父子依赖单调设置,避免物理结果被后续动画覆盖。

裙摆独立拓扑

  1. 只有在 CySpring 数据和骨骼父子关系能稳定识别出“列 × 段”的裙摆网格时才生成裙摆物理;无法判定时跳过并报告,不猜测相邻列。
  2. 每列由腰部 Type 0 支撑体连接若干 Type 1 动态体,刚体使用沿布片切向排列的薄盒体,不使用统一胶囊。
  3. 同列上下段用纵向 Joint 控制布料弯曲;同一高度的相邻列用横向 Joint 闭环连接,防止各列像独立帘条一样散开。环的首尾也必须连接。
  4. 横向 Joint 允许少量平移和旋转,不能像线性链一样全部锁零;允许量必须按裙摆半径、列数和段数归一化,避免模型尺寸变化后参数失效。
  5. 裙摆刚体同组禁碰撞,并依赖横向 Joint 保持整体形状。腿部 Type 0 碰撞体及裙摆到腿部的碰撞掩码放在身体碰撞阶段实现。

坐标与单位规则

  • PMX 位置、刚体尺寸和 Joint 平移量使用与现有顶点/骨骼一致的 Unity 到 MMD 坐标变换及模型倍率。
  • 刚体欧拉旋转、Joint 旋转限制和旋转弹簧的轴分量不应用模型尺寸倍率。
  • PMX 文件中的旋转和旋转限制统一写为弧度;Reader 回读后必须保持弧度语义,不在底层工具函数中混入 Rad2Deg 或空间倍率。
  • PMX 刚体尺寸是按形状解释的 vec3;球体、盒体、胶囊必须分别构造,不能把同一个三轴值无差别写给所有形状。盒体在 mmd_tools 中还存在 Y/Z 轴交换,往返测试必须覆盖这一点。
  • 胶囊方向先由变换后的 MMD 空间链段向量计算,再生成 PMX 欧拉角,避免先算 Unity 欧拉角后简单翻轴造成方向错误。
  • 每个旋转轴的下限必须小于等于上限;NaN、Infinity、非法长度和无效索引不得写入文件。

验证标准

  • 导出无 CySpring 链的模型时,刚体/Joint 数量保持为零且不报错。
  • 二进制级检查刚体碰撞组为单字节,Joint 类型为 0,所有索引有效,所有旋转字段均为有限弧度值。
  • 使用本项目 PMX Reader 回读导出文件,刚体数量、Joint 数量、关联索引、位置、尺寸和旋转限制与写入前一致。
  • Blender mmd_tools 能加载并显示正确朝向的球体/胶囊、有效的相邻 Joint;动态骨的“物理后”状态符合预期。
  • 每个 Joint 的 A/B 索引均有效,且不能连接两个 Type 0 刚体;初始姿势下动态刚体之间没有非预期重叠。
  • MMDSkin 能完整解析模型,不进入因 PMX 数据错位导致的失败状态;标准 両目 控制骨继续可识别。
  • 在 MMDSkin 中以静止、走路和大幅转身动作手工确认:链条有延迟摆动并能收敛,不持续卷曲、不异常拉长、不飞散。
  • 第一阶段至少手工验收一份短发、一份长发和一份尾巴模型;裙摆在独立拓扑完成后另行验收。
  • 导出后 Unity 预览里的 CySpring、Animator、表情和姿势仍恢复到导出前状态。
  • 执行 dotnet build umamusume.csproj -nologo 与 git diff --check。

分阶段交付

第一阶段完成头发、耳朵、尾巴的稳定支撑刚体、动态链刚体、相邻 Joint、组内禁碰撞和物理后变形顺序,不导出裙摆和身体碰撞体。

第二阶段实现可可靠识别的裙摆“列 × 段”网格、薄盒刚体、纵向 Joint 和闭环横向 Joint,先验证裙摆自身能保持连续结构。

第三阶段在读取并核对 CySpring 碰撞数据后,导出身体球体/胶囊 Type 0 碰撞体与分组掩码,重点验证头发-身体、尾巴-身体和裙摆-腿部。

第四阶段依据 MMDSkin 手工样本调整集中预设中的刚度、阻尼、质量、旋转限制和碰撞规则;不把单个角色的校准值散落写死到链生成逻辑中。

网络资料结论

  • MMD 模型物理设置 Wiki:物理教程:确认 Type 0 → Joint → Type 1 的基础链、同组禁碰撞、刚体重叠导致持续反弹,以及质量、阻尼、弹簧的调整关系。
  • MMD 模型物理设置 Wiki:刚体与 Joint 构成元素:确认三种刚体模式、形状用途、Joint 两端必须关联有效刚体,以及 Type 2 的额外骨骼位置校正风险。
  • MMD 模型物理设置 Wiki:高级调整:确认头发末端应减小质量并提高阻尼;裙摆需要薄盒刚体、纵向链和同层横向 Joint,且同组自碰撞通常应关闭。
  • MMD 物理设置 Joint 教程:确认裙摆纵向 Joint 控制弯曲、横向 Joint 控制横向伸展,参数需要随列数、段数和部位变化。
  • MMD 刚体设置教程:确认服装摩擦通常设为零、长链质量与阻尼要分段变化,碰撞体过多会增加失稳风险。
  • PMX 2.0/2.1 格式说明:确认刚体字段、碰撞组字节与 16 位掩码、弧度旋转,以及 PMX 2.0 Spring 6DOF Joint 的字段顺序。
  • mmd_tools 的 PMX 导入/导出实现用于交叉核对坐标轴、盒体尺寸和 Joint 上下限转换;PmxTailor 未找到公开源码,不作为规范依据。

待确认

批准后先实施第一阶段线性链,以“符合 MMD 原生物理、MMDSkin 可解析、摆动能够稳定收敛”为目标。第一版参数只要求形成可靠基线;每轮构建和静态回读通过后,由用户在 MMDSkin 手工验证,再根据实际表现校准预设。裙摆必须等独立网格拓扑完成后再宣称支持。