Files
UmaViewer/implementation_plan.md
T

150 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 手工验证,再根据实际表现校准预设。裙摆必须等独立网格拓扑完成后再宣称支持。