# 模拟与烘焙

[文档目录](../../README.md) · [物理](PHYSICS.md) · [摇摆生成](SWING.md) · [画布编辑](CANVAS_EDITOR.md) · [MCP 使用与接口](../agent/MCP_AUTHORING.md)

第一次操作可先看[模拟图文教程](SIMULATION_TUTORIAL.md)，按截图完成预设、固定点权重、重新烘焙与效果检查。

模拟在编辑器里对网格做真实的 2D 布料 / 头发模拟：顶点被固定点牵住，受重力和惯性驱动。Cubism 运行时不会做这种模拟，所以**模拟本身不导出**。要导出，须把它**烘焙**成 Cubism 能播放的内容：新参数上的网格关键形，由拟合出的摆锤驱动，另加若干参数上的精确修正。烘焙结果存进工程；重建模型时只写回结果，不会重新模拟。

## 基本流程

1. 在画布上选中裙子或头发的网格，在「模拟」面板（各工作区里位于「物理」标签之后，编辑工作区默认显示）点「新建」，选「布料」或「头发」。同一个物理体里的多张网格一起模拟。
2. 指定固定点。可以二选一或同时使用：
   - 在面板「顶点权重组」里点「固定点」一行的「绘制」，或切到画布的「模拟」模式，用权重笔刷绘制「固定点」权重组；
   - 在面板「胶水」里把与腰部相连的胶水设为「作为固定点」。
3. 打开工具条的预览开关切到「参考模拟」，在预览里转头、摇身体，调整材质直到效果自然。
4. 在选中物理体的「烘焙」节（编辑区第一节）点「烘焙」，或在面板顶部工具条点「烘焙全部」。烘焙需要数秒，在后台进行，期间可以继续编辑其他内容，完成后在当时的最新版本上作为单独一步撤销提交。工具条的「自动烘焙」开关默认关闭；打开后面板里的每次修改立即提交，随后在后台重新烘焙。烘焙后物理面板出现来源为「模拟」的摆锤组，参数面板出现 `ParamSim…` 参数，导出即包含它们。
5. 关闭预览开关切回「导出效果」，预览播放的就是导出模型的动作，与参考模拟对照。

### 面板布局

面板与物理面板采用同样的布局：

- **工具条**：一行内依次是「新建」（布料 / 头发）、「烘焙全部」、「自动烘焙」开关，以及预览开关（关闭为「导出效果」，打开为「参考模拟」，标签显示当前所处的一种），下一行是烘焙状态；右侧是全部展开与全部折叠（物理体列表和编辑区各节），参考模拟时最右多一个重置按钮，让实时模拟回到静止。「新建」以所选网格创建物理体，名称为 `sim` 加第一张网格去掉 `ArtMesh` 前缀的名字（如 `ArtMeshBottomwear` → `simBottomwear`，重名时加序号）。「烘焙全部」依次烘焙所有未烘焙或已过期的启用物理体，后面的物理体在前面的烘焙结果上烘焙，全部完成后作为一步撤销提交；都已是最新时再点会全部重新烘焙。烘焙进行中可以继续编辑，也可以再烘焙其他物理体（排入队列，下一轮烘焙）；某个物理体的设置在烘焙期间被改动时，它的结果不会按旧设置提交，而是重新烘焙；烘焙期间被删除的物理体则丢弃结果。「自动烘焙」是本机的界面偏好，不随工程保存，默认关闭。按钮右侧显示状态数量：有待烘焙时黄色显示「1/2 个待烘焙」，否则显示「2/2 个已烘焙」。烘焙时按钮换成取消（取消后不提交任何结果），状态处显示当前物理体、序号和进度；个别物理体烘焙失败时保留它的旧烘焙并在列表下方提示，其余照常提交。
- **列表**：可折叠的「物理体」文件夹。每行左侧的勾选框启用 / 停用物理体，右侧是烘焙状态和类型：已烘焙只显示绿点，需要注意的状态才写出文字（黄色已过期即导出仍用旧结果、红色未烘焙即不会导出、灰色已停用）。右键菜单可烘焙、清除烘焙或删除。
- **编辑区**：标题行是名称和类型（切换会套用该类型的材质预设），然后依次为「烘焙」「材质」「输入」「输出」「胶水」「顶点权重组」。烘焙节先显示在没见过的动作上的视觉检查（摆幅之比、滞后、回落、抖动，看得出差别时以警告色显示），其次是 R² 与误差（有顶到极值或更抖时另行警告），然后是「烘焙 / 重新烘焙」「清除烘焙」、模态数、上下参数、关键点和夸张；模态写法、参与训练的动作、精确姿态和各模态的摆幅收在「高级」里。「对比」节（默认折叠）用来把烘焙结果和参考模拟放在一起看，见[导出效果与参考模拟](#导出效果与参考模拟)。材质节顶部可选命名预设，材质改动后节标题出现「恢复该类型的预设」按钮。输入节逐行列出参数名和 ID，模型中已不存在的参数以警告色标为「不存在」；烘焙后每个输入下面显示它带动物体多远，被剔除的以警告色标为「已剔除」并带「保留」勾选框；再下面一行是它的训练范围；输入与默认不同时节标题出现「恢复默认输入」按钮，没有输入时警告无法烘焙。输出节在烘焙后列出生成的模态参数和摆锤（名称与 ID），点名称可重命名，清空或改回默认名即恢复按物理体命名；每个模态参数下面可改 ID、范围和增益。

## 顶点权重组

权重组是每张网格上的逐顶点 0–1 权重，只存在于本软件，不写入 `.moc3` / `.cmo3`。每张网格每个种类一个组，按种类区分，不需要命名。它们在「模拟」模式下用权重笔刷或权重渐变绘制（见[画布编辑](CANVAS_EDITOR.md)）：左侧工具栏在权重工具下方列出各个种类（`1`–`5` 也可切换），点选即切换要画的组；权重笔刷同样可选圆形、直线、矩形笔尖；拓扑编辑后按顶点来源插值保留。

| 种类 | 作用 |
| --- | --- |
| 固定点（`1`） | 被 Rig 牵住的顶点，权重表示固定得多牢 |
| 刚度（`2`） | 逐顶点缩放拉伸和弯曲刚度，用于根部硬、下摆软 |
| 保形（`3`） | 逐顶点缩放向原画形状的回弹 |
| 质量（`4`） | 逐顶点缩放质量 |
| 阻尼（`5`） | 逐顶点缩放阻尼 |

面板「顶点权重组」列出目标网格是否已绘制各个种类的组。每行的「绘制」选中第一张目标网格、把画布切到「模拟」模式并打开该种类的权重笔刷。风等力场尚未实现，面板和权重笔刷不提供「受风」组；MCP 的 `vertex_group_update` / `vertex_group_paint` 仍接受 `wind`，只在 `simulation_simulate` 传入 `wind` 时起作用。MCP 仍可用命名组并在物理体的 `groups` 中按名字指定；同一种类有多个组时，未指定则用第一个，也就是界面画的那个。

## 胶水

胶水不会自动成为固定点，每个与模拟网格相连的胶水在面板里单独选择：

| 角色 | 作用 |
| --- | --- |
| 不参与（默认） | 模拟不理会它，只在运行时焊接 |
| 作为固定点 | 模拟一侧的胶水顶点跟随另一张网格的实际变形，例如裙子与腰部 |
| 双向约束 | 两侧都在模拟中时保持接缝相连，例如分开的前后片 |

## 材质

| 项 | 含义 |
| --- | --- |
| 质量 | 相对密度。每个顶点的质量按它分到的网格面积（周围三角形面积的三分之一）计算，所以加密或重新剖分网格只增加形变细节，不会让布料变重、变软 |
| 拉伸 | 抵抗变长的程度；布料和头发应接近 1 |
| 弯曲 | 能弯得多急：相邻三角形转过的角度差。只管弯曲，不管收缩 |
| 面积 | 每个三角形保持面积的程度。正面看，布料在纵深折叠时会缩短、堆叠，低值允许轻薄布料这样收缩，高值让厚重部件保形。无论设多少，三角形都不会翻转或压成零面积 |
| 纹理方向 | 横向比顺纹理方向软多少。纹理方向自动取「离开固定点的方向」（沿网格量的路径长度增加的方向），没有固定点时取竖直向下。高值时发束顺长不伸长，但可以左右分开、顺长折叠 |
| 阻尼 | 运动衰减的快慢（每秒） |
| 保形 | 向原画形状回弹的弹簧；0 为纯物理。按单位质量计，网格疏密不改变回弹快慢 |
| 余量 | 剧烈甩动时顶点离固定点的距离最多超出静止路径多少 |

默认值：布料 面积 0.3、纹理方向 0.3；头发 面积 0.5、纹理方向 0.7。袖子、裤子、腿部穿戴的预设为面积 0.5，领饰 0.4。

「预设」下拉框把一种命名材质的数值填入上表各项，之后可以继续调整；工程只保存数值，数值与某个预设一致时下拉框显示它的名称，否则显示「自定义」。

| 类型 | 预设 | 特点 |
| --- | --- | --- |
| 布料 | 棉布（默认） | 上表默认值 |
| 布料 | 丝绸 | 轻、软，褶皱细，摆动拖得长、停得慢 |
| 布料 | 雪纺 | 最轻最软，比丝绸更快被空气阻尼停住 |
| 布料 | 羊毛 | 重而软，起摆晚、停得快 |
| 布料 | 牛仔布 | 重而硬，褶皱宽且保形 |
| 布料 | 皮革 | 最硬，整体摆动，几乎不堆叠，回弹到原画形状 |
| 布料 | 弹力布 | 可拉伸并弹回，适合束带、袜子 |
| 头发 | 头发（默认） | 上表默认值 |
| 头发 | 细软发 | 轻，易弯、易分开，摆得久 |
| 头发 | 粗硬发 | 较重，整束摆动并保形 |
| 头发 | 刘海 | 贴在额头上而非下垂，回弹更强、阻尼更大，随头部移动、发梢轻微滞后；前发预设使用 |

模拟开始前会先标定，使原画形状就是静止时的平衡位置，所以打开模拟后静止的模型不会下垂。

求解器为二维 XPBD（每帧 16 个子步）。Rig 把某处拉长时（例如转头时的视差），该处的静止长度随之变长，不与 Rig 的造型对抗；Rig 把某处缩短时视为转向纵深，由柔软的压缩承担。

## 烘焙

「输入」是晃动物体的参数，按列表原样使用，没有隐含的默认值。新建物理体（面板、MCP 未给 `inputs`、模型预设）时写入默认输入：头部和身体角度（模型中存在的 `ParamAngleX`、`ParamAngleZ`、`ParamBodyAngleX`、`ParamBodyAngleZ`），以及点头、身体上下和前后倾（存在的 `ParamAngleY`、`ParamBodyAngleY`、`ParamBodyLean`）。布料类型的上下输入只取 `ParamBodyAngleY`：衣服挂在身体上，点头不带动它；前后倾主要让它停在另一个姿态，上下摆锤表达不了静态偏移，会被拟合成几乎没有回复力、靠极大输出倍率放大的摆锤。重新套用服装预设时，仍是旧版通用默认输入的物理体改为布料默认输入。列表为空表示没有输入，烘焙会报错。旧工程中没有记录输入的物理体（当时表示使用默认）打开后显示为上述完整默认列表，模型里没有的参数在下次修改该物理体时移除；默认输入与当时的「空」视为相同，已有烘焙不会因此过期。

烘焙先从 Rig 读出每个输入怎样带动物体：在训练范围内让任何顶点移动不到 1px 的输入不参与烘焙（面板标为「已剔除」，勾选「保留」或 MCP `force_inputs` 可强制保留），让物体上下移动多于左右移动的输入归入上下参数（见下文），其余归入左右的模态。所以默认输入里与该部件无关的参数（例如裙子上的头部转动）不会再被拟合进摆锤，用户动这些参数时物体也不会莫名晃动。

每个输入可以设置训练范围（下限到上限，参数单位）：烘焙只在这个范围内驱动它，默认是参数的整个范围；范围总是包含默认值，超出参数范围的部分会截断。模态参数按训练中最剧烈的运动定标（见步骤 4），所以范围越窄，在范围内摆得越充分，超出范围后也越早顶到极值。例如 `ParamBodyAngleX` 平时只在 ±5 内活动，训练范围设为 ±5 后，常规动作也能用满模态参数。训练范围变化后烘焙过期；输入被移除时它的训练范围和保留设置一起移除。

「参与训练的动作」（「高级」里，MCP `training_clips`）让烘焙在设计好的激励之外，再学习模型自己的动作（用户动作或内置的 Idle、Nod、Shake 等），每个按 ×0.05–×1 计权，适合主要靠少数固定动作驱动、不用面捕的模型。每个动作只计入它带动得最多的那一组参数。编辑这些动作后需要重新烘焙（动作内容不计入过期判断）。

「输出」是烘焙写出的模态参数和摆锤。名称默认按物理体命名（参数为「<名称>」「<名称> 2」「<名称> Y」等，摆锤与物理体同名）；重命名保存在物理体上，重建时套用，不需要重新烘焙，ID 不变。每个模态参数还可以单独设置写出时的 ID、范围和增益，同样不需要重新烘焙：ID 默认是生成的 `ParamSim<id>_<k>`，可改成别的 ID 来沿用为该 ID 制作的动作和物理，但不能与模型中其他参数或本物理体的输入重名；范围为 ±1…±100，默认 ±30，关键点和摆锤的输出倍率随之缩放，运动不变；增益为 ×0…×3，默认取夸张系数，0 即静止。烘焙结果本身始终按生成的 ID 和 ±30 保存，这些设置在重建时套用。在物理面板里重命名「模拟」来源的摆锤也写到这里，摆锤仍由烘焙驱动。

### 设置

| 项 | 含义 |
| --- | --- |
| 模态数（1–3，默认 2） | 生成几个参数，每个由拟合摆锤的一个顶点驱动。第一个模态是整体摆动；之后的模态是下面再挂的一节或一根独立摆锤，只补上面的模态表现不了的部分：物体滞后时的弯曲、堆叠与压缩。只有 1 个模态时形状只能随摆角整体移动，缺少布料的压缩感，所以默认 2 个；长发束、飘带可用 3 个 |
| 上下参数（自动 / 开 / 关） | 上下方向的输入是否单独烘焙成 `ParamSim<id>_Y`（见下文）。「自动」只在它们让物体移动 2px 以上时生成；「开」总是生成；「关」时上下输入不参与烘焙，只有上下输入时会报错 |
| 关键点（3 / 5 / 7 / 9） | 每个模态参数和每个精确姿态参数上的关键点数，均匀分布。越多越能贴合弧线，增加的是关键形而不是参数 |
| 夸张（×1–×2，默认 ×1.3） | 模态摆动比模拟大多少。写回关键形时生效，改了立即起作用，不需要重新烘焙，也不会让参数顶到极值。二次元风格通常比真实略大更好看 |
| 精确姿态 | 在自己的轴上烘焙成精确修正的参数（最多四个）；默认不烘焙 |
| 模态写成 | 「自动」（默认）、「融合变形」或「关键形轴」。两种写法播放效果相同。关键形轴所有 Cubism 版本都能读，但每个模态会把网格的关键形数量乘以它的关键点数；融合变形（Cubism 4.2+）的关键形叠加在原有关键形上。「自动」只在某张目标网格的关键形会超过 64 个时用融合变形；目标版本不支持时一律写成关键形轴 |

融合变形省下的是关键形，不是参数：例如一张网格原本有 9 个关键形，2 个模态、各 5 个关键点，写成关键形轴是 9 × 5 × 5 = 225 个，写成融合变形是 9 个加 8 个融合形。

### 步骤

1. **精确姿态**：把 Rig 摆到每个精确姿态参数的各个关键点，让物体静止下来，把与 Rig 的差写成该参数轴上的修正关键形。没有指定精确姿态参数时跳过这一步。
2. **逐个输入驱动**：参与烘焙的每个输入单独驱动，其他输入停在默认值：一段在 0.15 秒内转到训练范围上端、停住直到物体静止（最长 1.6 秒）、回到默认、再转到下端、回来；一段从 0.25 Hz 到 3 Hz 的对数扫频，3 Hz 附近幅度逐渐减小。每一段都从静止开始，在各自的物体副本上并行模拟，左右与上下两组共用这些模拟。每帧记录物体与 Rig（加上精确姿态修正）之差，换算到各网格自己的关键形坐标。每组另有一段让本组输入一起被拖动、摇晃、闲置摇摆的动作只用来检验。各段按运动量均衡计权（最多相差 100 倍），带动物体少的输入也要被拟合正确，不会被大幅甩动压过。
   以前所有输入在同一段动作里各自随机运动，拟合分不清是哪个输入带动了物体：`tml` 后发上 `ParamBodyAngleX` 把发根移动约 70px，摆锤却只给它 1% 的影响度，跟随鼠标拖动时导出的摆幅只有模拟的约两成。逐个驱动后每个输入都得到让物体按它的方式运动的影响度。
3. **摆锤**：拟合一根 Cubism 摆锤 `PhysicsSim_<id>`，节数等于模态数，逐个模态拟合：先只拟合第一个模态的那一节，再逐个拟合后面的模态，每个模态只拟合上面各模态读不出来的剩余运动，并在这部分剩余运动自己的主方向里拟合（而不是整体运动的主方向），最后所有节和影响度一起微调一轮；读出始终按模态顺序逐个求。后面的模态有两类候选：在摆锤下面再挂一节（摆锤的顶点只受上面的顶点影响，所以加一节不会改变上面的模态，从 4 个起点搜索），或者用一根独立的单节摆锤 `PhysicsSim_<id>_<k>`，有自己的输入、摆长和反应速度（压缩对加速度的反应可能比摆动更快更硬）。哪种在检验动作上更好就用哪种，参数数量不变。一起拟合时，相邻顶点的摆角几乎同步，两个模态的形会变得很大并相互抵消，在训练以外的动作上就会失真。评分看整体效果而不只是误差：跟随模拟的程度，输入停下后甩出和回摆的程度（单独再计一次），以及每一段动作里是否比模拟更抖。各输入的类型（X 平移或角度）和初始影响度由小幅叠加的最小二乘估出（输入不超过 6 个时逐一比较所有类型组合，取剩余误差最小的），之后 Nelder–Mead 同时搜索各节的摆长、反应速度、摇摆度、收敛速度和各输入的影响度；每个候选都用与导出一致的计算、按真实幅度把全部训练动作播放一遍再评分。几个候选里，在检验动作上得分最好的胜出。
4. **模态参数**：摆锤第 k 个顶点的角度写入 -30…30 的参数 `ParamSim<id>_<k>`。输出倍率按摆锤在全部训练动作和检验动作中的最大摆角再留 10% 余量来定，所以参数不会顶到 ±30：参数停在极值时头发会停住，看起来就是卡顿。参数范围取 ±30 而不是 ±1，是因为关键形轴会把离关键点 0.001 以内的值吸附到关键点上（Cubism 运行时也如此），在 ±1 的范围里，大物体每次摆过静止位置都会被这一下吸附顿一下。
5. **关键形**：逐个模态按最小二乘求解：每个模态的关键形拟合前面各模态解释后剩下的形状，每帧的形状等于各参数在摆锤播放值处的关键形插值之和。关键形被约束在一条平滑的曲线上，相邻关键点处不拐急弯，静止关键点处直线穿过，否则参数扫过关键点时速度突变，也是一种顿挫。之后在检验动作上做两项调整，只在跟随更好且不更抖时采用：各模态的关键形扣除其他模态后再各解一轮（更接近一起求解，又不相互抵消）；后面的模态试 ×0.25、×0.5、×0.75 的增益，防止它在小幅动作里添乱。几乎不动的参数不生成。

**上下方向单独烘焙**：Cubism 的摆锤沿重力下垂，只输出角度，根部竖直上下移动时角度不变，所以上下运动无论怎样设置输入都驱动不了它。做法与画师的 `裙y`、`长发y` 物理组相同：让物体上下移动多于左右移动的输入（通常是点头、身体上下和前后倾）与其他输入分开，单独跑一遍步骤 3–5：拟合一根单节摆锤 `PhysicsSim_<id>_y`，驱动一个模态参数 `ParamSim<id>_Y`（名称为“<模拟名> Y”），关键形是物体上下滞后和回弹的形状。两组参数的关键形在网格上相加。上下运动不到 2px 时不生成这个参数（上下参数设为「开」时总是生成，设为「关」时不生成且上下输入不参与烘焙）。只有上下输入时，所有模态都按这种方式拟合。`tml` 裙子：下蹲 / 起身时模拟中的残差最大 47px，原来烘焙后只剩一个静态倾斜；分开烘焙后检验动作的 R² 从 0.37 升到 0.61。

R² 不是看起来对不对的唯一标准：摆幅偏小、相位稍偏时，最小二乘会把关键形整体缩小来换更低的误差，导出的动作就显得没有生气。所以烘焙完成后面板先显示每组在检验动作上的视觉检查：

| 指标 | 含义 | 警告 |
| --- | --- | --- |
| 摆幅 | 尖端（运动最大的十分之一顶点）沿模拟主方向的摆动，导出与模拟之比 | 不在 ×0.75–×1.3 内 |
| 滞后 | 导出比模拟晚多少毫秒（互相关峰） | 超过 80 ms |
| 回落 | 输入停下后回到静止所需时间，导出与模拟之比 | 不在 ×0.6–×1.6 内 |
| 抖动 | 三阶差分能量之比的平方根 | 超过 ×1.5 |

方向相反时同样警告。MCP 还返回方向一致度、回摆次数之差、顶到极值和卡住的帧占比、发丝缩短程度和静止时的偏差。之后一行是 R² 和 95% 的帧与模拟的最大偏差；有帧顶到极值或急动度超过模拟 1.5 倍时另起一行警告。各模态参数的摆幅在「高级」里。MCP `simulation_bake` 返回全部指标和每个输入的读取结果（`inputs`）。

烘焙后的摆锤组和普通生成组一样，可以在物理面板里查看、修改或关闭。物理面板里的修改是对生成摆锤的覆盖；重新烘焙或修改输出的 ID、范围后，覆盖按三方合并带到新摆锤上：只保留你改过的字段（输出倍率按与原值的比例保留），其余取新拟合的值，输出随参数改名，改完与新摆锤相同的覆盖会被移除。清除烘焙、删除物理体或新的烘焙不再生成某根摆锤时，它的覆盖、停用状态和顺序一起移除。

### 效果与耗时

模型预设生成的物理体（2 模态、5 关键点，夸张 ×1），在烘焙时没有出现过的 13–15 段动作上逐帧对比参考模拟与导出模型（Cubism 摆锤 + 关键形）：类面捕的鼠标跟随、头身左右歪、内置 Idle / Nod / Shake、每个输入的阶跃、转头、拖动和摇晃。只统计模拟里尖端移动 10px 以上的动作（括号中为段数）：其余动作只由被剔除的输入驱动，模拟里只有物体起步时的轻微晃动，计入会把每项指标拉向 0。「方向对」是摆动方向一致（余弦 ≥ 0.9）的动作数，摆幅取各动作导出与模拟之比偏离 1 的中位数换算回的倍数，R² 为各动作均值（低于 -1 的按 -1 计），静止偏差是输入停住 1 秒以上时导出与模拟的距离（95% 分位）。前一列是原来按动作库训练的结果，后一列是逐个输入驱动。

| 部件 | 方向对 | 平均 R² | 摆幅 | 静止偏差 | 烘焙耗时 |
| --- | --- | --- | --- | --- | --- |
| tml 后发 | 5 → 7 / 11 | -0.03 → 0.48 | ×0.43 → ×0.72 | 10.5 → 10.3 px | 20.3¹ → 5.7 秒 |
| tml 后发（顶部 10% 固定） | 6 → 6 / 10 | 0.14 → 0.54 | ×0.32 → ×0.75 | 12.2 → 9.7 px | 7.6 → 6.5 秒 |
| tml 前发（刘海） | 8 → 8 / 13 | 0.11 → 0.51 | ×0.34 → ×0.83 | 6.2 → 5.1 px | 3.5 → 2.5 秒 |
| tml 裙子 | 3 → 3 / 5 | 0.35 → 0.30 | ×0.84 → ×0.84 | 3.2 → 3.2 px | 3.9 → 1.5 秒 |
| ds 后发 | 4 → 8 / 11 | 0.21 → 0.46 | ×0.14 → ×0.66 | 7.0 → 5.8 px | 7.3 → 5.1 秒 |
| ds 后发（顶部 10% 固定） | 4 → 8 / 10 | 0.25 → 0.56 | ×0.18 → ×0.71 | 5.9 → 5.9 px | 5.4 → 4.0 秒 |
| ds 前发（刘海） | 5 → 8 / 11 | 0.23 → 0.54 | ×0.25 → ×0.69 | 3.3 → 2.0 px | 4.1 → 2.4 秒 |
| ds 上衣 | 2 → 3 / 4 | 0.49 → 0.34 | ×0.77 → ×0.72 | 2.7 → 3.4 px | 6.5 → 3.8 秒 |
| ds 裙子 | 4 → 4 / 4 | 0.52 → 0.34 | ×0.74 → ×0.61 | 2.2 → 3.7 px | 3.9 → 1.0 秒 |

¹ 同一进程的第一次烘焙，含 JVM 预热；之后的烘焙都已预热。

- 头发改进最大，贴近实际使用的动作尤其明显：tml 后发跟随鼠标时摆幅从模拟的 0.19 倍到 1.04 倍、R² 从 -0.15 到 0.92，Shake 动作的 R² 从 0.07 到 0.83，`ParamBodyAngleX` 阶跃从完全不动到 R² 0.86。
- 布料逐个输入驱动后烘焙快 2–4 倍，但 R² 不如原来（裙子、上衣 0.3 左右，原来 0.35–0.5）。上下参数仍弱（`ParamBodyAngleY` 阶跃 R² 0.17–0.30，摆幅 0.2–0.8 倍）：模拟中身体向上和向下运动时裙摆都向同一侧甩出，回摆也只在一侧，而摆锤的输出对输入正负对称，拟合只能折中。
- 后发对身体左右歪（`ParamBodyAngleZ`）的摆动周期（约 1.3 秒）与转头（约 0.9 秒）不同，形状也不同，2 个模态时分不到它（ds 后发导出几乎不动，tml 后发摆幅 0.59 倍、R² 0.11）；改为 3 个模态也没有改善。
- 头部转动等几乎不带动布料的输入（模拟只动 2px 左右）直接剔除，用户转头时裙子不会莫名晃动。

耗时在 32 线程的台式机上测得；模拟与拟合在多核上并行，核数少时会更慢。上表由开发工具 `SimBakeSuite` 生成，输出每段动作的全部视觉指标和尖端轨迹图，用法见[开发工具](DEVELOPMENT.md#开发工具)。

### 过期

烘焙记录了它所依据的设置、目标网格、权重组、相关胶水和求解器版本（求解器改变后，旧工程的烘焙显示为过期）。它们变化后，面板提示烘焙已过期。打开工具条的自动烘焙时，面板里的修改提交后会在后台重新烘焙（作为单独一步撤销），并从上次的摆锤出发搜索，比从头烘焙快；应用模型预设同样先提交，再在后台烘焙它生成的物理体；MCP `simulation_put` 按物理体自己的 `auto_bake`（默认开启）决定；在别处做的修改（网格、权重）仍会显示过期。过期的烘焙仍会导出，点「重新烘焙」更新；「清除烘焙」会移除它的参数、关键形和摆锤。自动烘焙失败或被取消时保留旧的烘焙并提示原因。目标网格被重建（顶点数变化）时，该网格的烘焙结果跳过并在面板中提示。

### 导出效果与参考模拟

面板顶部和画布「模拟」模式的工具条可以切换预览内容：

- **导出效果**：预览播放烘焙结果，即由拟合的 Cubism 摆锤驱动的参数和关键形，与导出的模型动作一致。未烘焙的物体在这里不动，画布左下角提示「有未烘焙的模拟」。
- **参考模拟**：画布显示编辑器自己的物理模拟，只用来对照，不会导出。画布左下角以警告色标明「参考模拟 · 不会导出」，此时该物理体自己的 `ParamSim…` 参数保持静止，不会叠加两次。

物理体编辑区的「对比」节把两者放在一起看：

- **显示**（参考模拟打开时可用）：第一张预览画布上参考模拟的显示方式——「参考」（代替导出结果，同上）、「导出」（只显示导出结果）、「叠影」（导出结果上叠加半透明的参考模拟，只画被模拟的图层）。每张画布单独记住，随工作区保存。
- **并排**：打开参考模拟，并确保有两张预览画布，第一张显示导出、第二张显示参考，两者跟随同一个姿势同时播放。
- **播放**：从下拉框选一个动作（内置 Idle、Nod、Shake，有骨骼时加骨骼动作，以及用户动作），参考模拟和导出的摆锤一起回到静止后播放它，便于逐段对照。
- **检验**：在后台用所选动作分别驱动参考模拟和导出模型（增益 ×1），给出与烘焙节相同的视觉检查；MCP 对应 `simulation_compare`。

## 模型预设

「模型预设」面板（原「模型设置」）的「物理与模拟」组把常见部件一步做成模拟并烘焙，结果是普通的权重组和物理体，之后仍可在「模拟」面板里调整。面板里的「形变与口型」「动作」「物理与模拟」三组都是与参数面板文件夹相同样式的可折叠行，右侧显示摘要。「动作」组只决定模型有没有「基础动作」和「骨骼动作」两组，单个动作在动画面板中启用和调整。「物理与模拟」每项一行：前发、后发各有一个下拉框，在「模拟 / 经典摆动 / 关闭」间切换；服装与果冻眼是复选框，勾选即应用预设，取消即移除，服装的逐网格宽松度列表显示在服装行下方。控件旁的灰字说明当前内容（已模拟的服装部位、原画中没有该部件，悬停显示全文），未烘焙或模拟体已删除时以警告色提示。顶部工具栏的「仅选中（n）」让勾选只作用于选中的图层（取消勾选总是整体移除），右侧为「自动 Pin 物理权重」。烘焙进度与取消在底部状态栏，失败原因显示在组内底部。每次勾选都是一步撤销，MCP 对应 `model_apply_preset` 工具。

「开始」页（工作区标签栏最左侧，或「文件 → 开始页」）的「从 PSD 生成」在导入 PSD **之前**汇总同样的预设：属性面板顶部的「最小 / 默认 / 完整」分别对应只保留绑定（无动作、物理与模拟、嘴部描边）、两组动作 + 头发经典摆动 + 服装模拟 + 果冻眼、在默认基础上模拟前后发并开启五官位移；下方可逐项调整，选择会被记住。之后无论从开始页、「文件」菜单、最近文件还是拖放导入 PSD，生成后都会把改动过的预设作为一步撤销写入，再依次生成头发与服装模拟（每个模拟各占一步），并切到编辑工作区。服装默认开启，原画中识别到服装时会生成并烘焙服装模拟。已打开由 PSD 生成的模型时，「生成」按钮菜单里的「应用到当前模型」把同样的预设套到它上面。按网格拆分图层不再随导入弹出，改用「模型 → 按网格拆分图层…」扫描全部图层后批量确认。

| 预设 | 做什么 |
| --- | --- |
| 前发 / 后发 | 该类头发的全部网格合成一个头发物理体（`preset_front_hair` / `preset_back_hair`），每束发（网格的每个连通块）从自身顶端固定、向发梢放开，只写固定点组；前发用「刘海」材质，后发用默认头发材质；同时移除该类头发的旧摆动（`ParamHairFront/Back` 参数、`DeformHair*Physics` 变形器与摆锤），网格（含拆分出的部件）改挂到跟随变形器，原画位置不变。改选「经典摆动」或「关闭」时删除该物理体并恢复旧摆动（「关闭」同时停用旧摆动） |
| 服装 | 读取上衣、下装、领饰、手部（袖子）和腿部穿戴图层，只在原画看起来宽松的地方模拟，贴身部分跟随绑定。下装先判定裙子或裤子：名称优先（裙、skirt、スカート / 裤、pants、ズボン 等），否则看 Alpha 轮廓，从裆部持续到下摆的中缝间隙判为裤子。躯干与下装逐行比较轮廓与身体：身体轮廓从肩线（下装从腰线）开始，向下只能缓慢变宽，超出部分记为宽松（褶边、蝴蝶结、喇叭下摆、外套开襟）；上衣在腰线以下（腰线取下装腰线，或伸进上衣下方的腿部穿戴顶端）、裙子在臀部以下且比臀部宽时、领饰在结以下视为自由悬垂，直筒裤和铅笔裙保持贴身。袖子与腿部穿戴随肢体弯曲，改用形态学开运算：比肢体粗细一半的圆盘还细的部分（袖口 / 袜口褶边、飘带）才算宽松，泡泡袖、翻边袖口随肢体。肤色区域始终贴身，手指张开也不会被模拟。宽松度按到贴身区域的图层内距离渐增，生成固定点（1 − 宽松度）、质量与受风（随宽松度增加，肢体受风较小）。宽松顶点不足的网格不建物理体，并从原先所在的服装预设物理体中移出。物理体按部位分为 `preset_top`、`preset_skirt`、`preset_trousers`、`preset_neckwear`、`preset_sleeves`、`preset_legwear`，裤子、袖子与腿部穿戴较硬。服装行下方逐网格列出部位和宽松比例条，贴身的合为一行，下装悬停可看判定依据。取消勾选删除全部服装预设物理体 |
| 果冻眼 | 开关眼睛的果冻摆锤 |
| 「自动 Pin 物理权重」（工具栏） | 按部件类型重新计算选中图层或所有已模拟网格的上述权重组，并重新烘焙用到它们的物理体，不新建物理体 |

预设写入的组名为 `preset_pin`、`preset_mass`、`preset_wind`；物理体已在 `groups` 中指定了自己的组时，原地刷新那个组。再次应用同一预设会更新原有物理体，不会叠加。已属于用户自建物理体的网格会被拒绝。受风组目前只在 MCP `simulation_simulate` 传入风时起作用（见上文）。

## MCP

模拟按操作拆成几个工具，参数放在 `{"request": {...}}` 中，都按 `id` 指定物理体，并带 `project_id`、`state` 和 `request_id`；它们返回后台任务句柄，用 `job_wait` / `job_get` 取结果：

- `simulation_put`：按 `id` 新建或局部修改物理体，字段包括 `targets`、`material`、`material_preset`（上表预设名：`cotton`、`silk`、`chiffon`、`wool`、`denim`、`leather`、`elastic`、`hair`、`fine_hair`、`thick_hair`、`bangs`，同时给出的 `material` 字段覆盖其数值）、`groups`、`glue_roles`、`inputs`、`modes`、`keys`、`exaggeration`、`static_inputs`、`blend_shapes`（`true` / `false` / `null` 为自动）、`auto_bake`、`output_names`（按参数或摆锤 ID 指定名称，整体替换）、`input_ranges`（按输入参数给出 `[min, max]` 训练范围，整体替换）、`vertical`（`true` / `false` / `null` 为自动）、`outputs`（按生成的模态参数 ID 给出 `{id, range, gain}`，整体替换，不需要重新烘焙）、`force_inputs`（即使几乎不带动物体也保留的输入）、`training_clips`（参与训练的动作，`{动作: 0.05–1}`，整体替换）；新建时未给 `inputs` 写入默认输入，给空数组即没有输入；`auto_bake` 开启（默认）时在同一步内重新烘焙，并返回 `bake` 摘要或 `bake_error`；
- `simulation_simulate`：只读试算（面板里没有对应按钮），每个输入保持 `hold` 秒再松开、观察 `release` 秒，可选 `wind`，返回峰值、静止漂移、拉伸和设置提示；
- `simulation_bake`：烘焙（数秒），返回各模态参数与摆幅、关键点数、摆锤 ID 与节数、独立摆锤的 ID（`own_pendulums`，有时）、每个输入的读取结果（`inputs`：带动物体的距离、是否只平移旋转、所属组或已剔除）、每组在检验动作上的视觉检查（`visual`）、烘焙方法（`method`），以及在检验动作上的 `fit_r2`、`error_p95_px`、`parameter_peak`（模态参数最多用到范围的比例）、`clipped_frames`（顶到极值的帧占比）与 `jerk_ratio`（急动度与模拟之比）；
- `simulation_compare`：只读后台任务，用 `motions` 中的动作（用户动作 ID 或内置名称，最多 8 个）分别驱动参考模拟和导出模型，返回每个动作的视觉检查；
- `simulation_clear_bake`：清除烘焙；
- `simulation_delete`：删除物理体。

参考模拟预览对应试听会话，不进入文档和历史：`simulation_preview` 以 `mode=start` 和 `simulation_id` 开始（`restart` / `stop` 带 `session_id`），`simulation_preview_step` 按 `dt` 秒（最多 0.1）推进 1–240 步，`simulation_preview_get` 读取当前帧，`simulation_preview_render` 渲染当前帧。

`vertex_group_update` 按规则（`fill`、`outline`、`gradient`、`glue`、`region`）生成权重组，`delete=true` 删除，不传逐顶点数组；`vertex_group_paint` 用与画布相同的笔刷、渐变和反转修改权重。`workspace_inspect` 的 `scope=simulations` 列出物理体、胶水键和烘焙摘要（含 `bake_stale`），`scope=vertex_groups` 列出权重组。

## 当前范围

- 已实现：布料与头发（XPBD 求解，按面积分配质量，三角形面积与防翻转，基于旋转的弯曲，自动纹理方向与各向异性，固定点、胶水角色、长程约束）、顶点权重组、参考模拟预览、烘焙为参数 + 关键形（融合变形或关键形轴，可自动选择）+ 摆锤并导出、自动烘焙、夸张系数；模型预设（头发模拟替换旧摆动、按宽松度模拟上衣 / 裙子 / 裤子 / 领饰 / 袖子 / 腿部穿戴、自动 Pin 物理权重）。
- 实测：上表 tml 后发的对比数据。模型预设在 tml 上的烘焙（检验动作 R² / 95% 误差，旧求解器上测得，需在新材质模型下重测）：后发 0.69 / 229 px，与手动固定顶部 10% 相同；前发 0.25 / 185 px，换任何固定范围都在 0.2–0.3。前发的问题在材质而不在固定范围：贴额头横扫的刘海不像后发那样由发束长度承担重力，默认头发材质的弱回弹把它变成约 0.75 Hz 的软弹簧，左右摇头（1.2 Hz）时偏离骨架 74 px（骨架带动 33 px），点头时 47 px。改用「刘海」材质后（新材质模型，tml / ds）：摇头 41 / 30 px，点头 12 / 10 px，转头停住后残留 10 / 6 px，烘焙 R² 0.18 → 0.27 / 0.21 → 0.49，95% 误差 216 → 85 / 112 → 57 px；裙子的数据是在已移除的碰撞功能下测得的，需重新实测。头发加质量 / 受风组会把后发的 R² 从 0.69 降到 0.56，所以头发预设不写这两组。
- 障碍物：模拟体可带障碍物（`obstacles`）——跟随另一网格的圆或胶囊，粒子被挡在外面，参与参考模拟与烘焙，并导出到播放实时模拟的运行时目标（p2lrt、网页）。目前只能经 MCP `simulation_put` 编写，画布上还没有编辑入口。较早的网格碰撞体（按边距）实测不可靠，已移除；旧工程中的这类碰撞体和碰撞权重组在加载时忽略。
- 尚未实现：风等力场导出、刚体与软体、烘焙为普通关键（去掉生成器）。
- 宽松度热力图人工检查（tml、ds 与一份 Q 版素材）：tml 只有裙子下半部宽松；ds 的围裙、腰后蝴蝶结与裙摆宽松，泡泡袖、袖口和袜口贴身；Q 版敞开外套腰线以下宽松，直筒裤贴身。
- 尚待实测：示例模型上的裙子与头发导出后在官方运行时中的视觉效果；模型预设生成的头发与服装模拟的自然度。