150 lines
14 KiB
Markdown
150 lines
14 KiB
Markdown
# 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 中确认基础姿势不受预览动作影响。
|
||
|
||
## 执行状态
|
||
|
||
- [x] 完成导出状态冻结、MMD 默认 A-pose 应用及异常路径恢复。
|
||
- [x] 完成标准骨架、腿 IK 和 IK 原始弧度读写修复。
|
||
- [x] 完成项目构建、差异检查和膝 IK 二进制写入验证。
|
||
- [x] 在 MMD Skin 中实机确认导入、A-pose、膝盖弯曲方向及导出后状态恢复。
|
||
- [x] 使用问题动作和正常动作导出,并在 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:物理教程](https://w.atwiki.jp/mmdphysics/pages/14.html):确认 `Type 0 → Joint → Type 1` 的基础链、同组禁碰撞、刚体重叠导致持续反弹,以及质量、阻尼、弹簧的调整关系。
|
||
- [MMD 模型物理设置 Wiki:刚体与 Joint 构成元素](https://w.atwiki.jp/mmdphysics/pages/16.html):确认三种刚体模式、形状用途、Joint 两端必须关联有效刚体,以及 `Type 2` 的额外骨骼位置校正风险。
|
||
- [MMD 模型物理设置 Wiki:高级调整](https://w.atwiki.jp/mmdphysics/pages/15.html):确认头发末端应减小质量并提高阻尼;裙摆需要薄盒刚体、纵向链和同层横向 Joint,且同组自碰撞通常应关闭。
|
||
- [MMD 物理设置 Joint 教程](https://tsuki-gummd.hatenablog.com/entry/2022/08/15/210000):确认裙摆纵向 Joint 控制弯曲、横向 Joint 控制横向伸展,参数需要随列数、段数和部位变化。
|
||
- [MMD 刚体设置教程](https://tsuki-gummd.hatenablog.com/entry/2024/02/01/211802):确认服装摩擦通常设为零、长链质量与阻尼要分段变化,碰撞体过多会增加失稳风险。
|
||
- [PMX 2.0/2.1 格式说明](https://gist.github.com/felixjones/f8a06bd48f9da9a4539f):确认刚体字段、碰撞组字节与 16 位掩码、弧度旋转,以及 PMX 2.0 Spring 6DOF Joint 的字段顺序。
|
||
- mmd_tools 的 PMX 导入/导出实现用于交叉核对坐标轴、盒体尺寸和 Joint 上下限转换;PmxTailor 未找到公开源码,不作为规范依据。
|
||
|
||
## 待确认
|
||
|
||
批准后先实施第一阶段线性链,以“符合 MMD 原生物理、MMDSkin 可解析、摆动能够稳定收敛”为目标。第一版参数只要求形成可靠基线;每轮构建和静态回读通过后,由用户在 MMDSkin 手工验证,再根据实际表现校准预设。裙摆必须等独立网格拓扑完成后再宣称支持。
|