# 物理

[文档目录](../../README.md) · [摇摆生成](SWING.md) · [模拟与烘焙](SIMULATION.md) · [MCP 使用与接口](../agent/MCP_AUTHORING.md)

物理让参数跟随头部、身体等输入产生惯性摆动。PSD2Live 使用 Cubism 的摆锤模型：一串从根部垂下的摆锤（Cubism Editor「摆锤设置」里编号 1、2、3… 的各行），输入推动根部或倾斜重力，摆锤按惯性摆动，指定摆锤的角度写入输出参数。导出时写入 `physics3.json` 和 `.cmo3`。

## 物理组从哪里来

模型的所有物理组都列在物理面板里，来源分五种：

| 来源 | 说明 | ID |
|------|------|----|
| 预设 | 按图层自动生成的前发、后发和果冻眼（图层里有对应部件才出现） | `PhysicsHairFront`、`PhysicsHairBack`、`PhysicsEyeJelly` |
| 骨骼 | 骨架第二节以后的尾巴、翅膀的跟随 | `PhysicsSkel_<骨骼 id>` |
| 摆动 | 每个摇摆的每个方向一根摆锤，见[摇摆生成](SWING.md) | `PhysicsSwing_<id>[_X\|_Y]` |
| 模拟 | 每个已烘焙的模拟一根拟合出的摆锤，每节驱动一个模态参数；上下运动另有一根以平移输入的摆锤，见[模拟与烘焙](SIMULATION.md) | `PhysicsSim_<id>`、`PhysicsSim_<id>_y` |
| 自定义 | 在面板或 MCP 中新建 | 默认 `PhysicsCustom<N>` |

生成的组也能直接编辑。编辑后它变成「已修改」，保存的是你的版本，来源（摇摆、骨骼）之后再变化也不会覆盖它；模拟的摆锤在重新烘焙或输出改名后按三方合并，只保留你改过的字段，其余跟随新的拟合结果（见[模拟与烘焙](SIMULATION.md)）；用「恢复生成值」回到生成的版本。每个组都能单独关闭，关闭的组不导出。自定义组如果驱动了某个生成组的输出参数，这个生成组会显示「被替代」，同样不导出。

同一个参数只能由一个生效的组驱动。组无效（参数不存在、没有输入或输出、某参数同时是输入和输出）时列表里标为「无效」，也不导出，编辑区显示原因。

## 物理面板

物理总开关和帧率在预览画布的左侧工具栏里，和待机动画、鼠标跟踪放在一起。帧率可选 30 / 60 / 90 / 120 / 无限制（默认 60），是工程唯一的帧率设置：预览按它出帧，参数面板和物理面板随预览逐帧刷新，物理按它计算，导出的 `physics3.json`（`Fps`）和 CMO3 也写入它。选「无限制」时预览跟随显示器刷新，导出不声明 `Fps`，运行时按各自的帧计算物理（CMO3 不写物理 FPS）。

面板上方显示物理是否运行、当前帧率和「生效 n / m」计数，以及预览的待机动画和鼠标跟踪开关。

待机动画和物理互相独立：待机动画停止、物理开启时，拖动参数滑块或用鼠标跟踪转头，预览里的物理照样摆动，静止后预览停止出帧；关闭物理则只显示编辑姿态。暂停时物理由与导出一致的引擎计算（见下文「预览与导出的一致性」），不会让暂停的动作继续播放。

参数面板与预览始终一致：待机动画播放时滑块随预览逐帧变化；停止时鼠标跟踪带动的角度和眼球参数也实时显示在参数面板里，物理面板的摆锤读取的也是同一份姿态。

专门调物理时可以新建「物理」工作区（标签栏的 + 菜单）：从左到右依次是预览画布、参数面板和物理面板，宽度约 2 : 1 : 1，其他面板隐藏，需要时从窗口菜单打开。

下面是物理组列表，按计算顺序排列并标出序号。每行可以勾选启用，标出来源和状态（已修改 / 无效 / 被替代）。标题栏的 ↑ / ↓ 调整所选组的计算顺序：Cubism 按顺序计算，后面的组在同一步里能读到前面组的输出，所以一个组以另一个组的输出为输入（链式物理）时，被读的组要排在前面。

「+ 新建」可以：

- 新建空白摆锤：默认输入头部与身体的晃动，一个长 10 的摆锤，还没有输出；
- 复制所选组为新组（输出参数会清空，避免与原组冲突）；
- 导入 physics3.json：文件中的每个组成为自定义组，按文件顺序排在现有组之后。ID 相同的组被替换（生成的组在恢复生成值前保持被替换），驱动相同输出的其他自定义组会被关闭，文件声明的 `Fps` 成为工程的计算 FPS。模型没有的参数会记在日志里，对应的组显示为无效；
- 为画布上选中的网格或弯曲变形器创建摆动（进入[摇摆编辑](SWING.md)）。

### 摆锤画布

选中一个组后，编辑区顶部是它的摆锤。实线是实时摆动的摆锤；虚线是它的静止姿态，从实时的根部垂下，每个摆锤末端有一个圆环。画面左右镜像显示，所以向右牵动时根部向右移动。

| 操作 | 作用 |
|------|------|
| 在空白处左右拖动 | 像 Cubism Viewer 里横向拖动模型一样牵动模型（只取水平方向），松手后平滑回到原位；根部始终沿顶部横线移动 |
| 上下拖动圆环 | 这个摆锤的长度；单击选中这个摆锤（再次单击取消），下方滑块只调它 |
| 右侧的输出标签 | 标签与它读取的摆锤同高，连线指向该摆锤的实时位置，条形显示当前参数值。上下拖动时高亮离它最近的摆锤，松开即改为读取那个摆锤（即输出行的「摆锤数」） |
| 单击输出标签（或输出行前的色点） | 在摆锤上显示这个输出的范围扇形：这个摆锤相对上一个摆锤摆过扇形的角度时，参数从一端走到另一端。拖动扇形边缘的圆点调整范围（即倍率），扇形越窄摆动越明显 |

单击只做选择，拖动超过一小段距离才会修改，避免误改生成的组。悬停或拖动时左上角显示该项的含义和数值。

牵动时，指针位置是目标，模型按 Cubism 的 CubismTargetPoint 以受限的速度和加速度跟过去，再按 CubismLook 的系数换算成角度 X、身体 X 和眼球 X（组里的其他输入参数按拖动量占其半个范围）。实时摆锤播放预览时叠加在预览参数上（包括动作和视线跟随），暂停时叠加在参数面板的值上，所以直接拖参数滑块也能看到反应。右下角按钮让摆锤立即静止。

根部移动范围和重力倾斜范围（输入标准化）在「高级」里设置。

### 响应曲线

摆锤下方的曲线显示这个组对一次标准牵动的反应：向右拉满 1 秒后松开，每个输出一条曲线（按参数范围归一，虚线是参数端点），淡色曲线是牵动量本身。曲线下方列出每个输出的最大幅度和松开后多久静止。调整长度和动力学滑块时曲线随之更新，可以直接比较不同设置的过冲与收敛。

### 摆锤设置

「预置」一行对应 Cubism Editor 的摆锤预置：选一个预置后点「导入」，用它替换这个组的全部摆锤（摆锤变少时，读取被删摆锤的输出改读末端）。内置预置取自自动生成的前发、后发、果冻眼和一个三段摆锤；「⋯」里可以把当前摆锤「追加…」为自己的预置，或对自己的预置覆盖保存、重命名、删除。预置保存在本机，所有工程共用。

「编辑摆锤」一行选择下方滑块作用的对象：「全部」同时调整所有摆锤，数字只调整那一个（也可以在画布上单击圆环选择）。它只决定滑块改哪个摆锤，与输出的「摆锤数」无关。右侧按钮：

- ↑ / ↓：移动所选摆锤，读取它的输出跟着它走；
- +：在所选摆锤下方追加一个（复制所选摆锤的数值），未选中时加在末端；更深的输出跟着下移，仍读原来的摆锤；
- −：删除所选摆锤（未选中时删最后一个）。读取它的输出改读上一个，更深的输出跟着上移。

| 滑块 | Cubism Editor 名称 | 效果 |
|------|-------------|------|
| 总长 / 长度 | 长度 | 越长摆得越慢、幅度越大；选「全部」时按比例缩放所有摆锤 |
| 摇摆度 | 摇摆度（Mobility） | 越大越不容易停下来 |
| 反应速度 | 反应速度（Delay） | 越大对输入反应越快 |
| 收敛速度 | 收敛速度（Acceleration） | 越大重力越强，越快回到下垂 |

### 输入

每个输入是一个参数和它的影响方式：

- **类型**：**位置X** 把摆锤根部左右推动；**角度** 倾斜重力方向。
- **影响度**：0–100%，参数整个范围映射到输入标准化范围的比例。
- **⇄**：反转。

「+ 添加」列出可用参数，常用的头部、身体角度排在前面。

「预置」一行对应 Cubism Editor 的输入预置，一个预置包括全部输入和输入标准化。内置预置有头部与身体的晃动（±10°，与前发相同；±30°，与后发相同）、头部与身体的上下（与纵向摆动相同）和眼睛开闭（与果冻眼相同）；模型没有的参数和这个组自己的输出参数会被跳过。管理方式与摆锤预置相同。

### 输出

每个输出把某个摆锤的角度写入参数：

- **摆锤数**：输出读第几个摆锤的角度（相对上一个摆锤，摆锤 1 相对重力方向），即 Cubism Editor 输出设置的「摆锤数」、`physics3.json` 的 `VertexIndex`。与上面的「编辑摆锤」无关；在画布上把右侧标签拖到某个摆锤旁松开也能修改。多个摆锤分别接到不同参数上，就能做出甩鞭式的逐段跟随。
- **倍率**：每弧度摆角对应的参数值，结果会被限制在参数范围内；也可以在画布上拖扇形弧端调整。
- **⇄**：反转。

输出只有角度类型：Cubism 原生运行时不读取位置X 类型输出的倍率，这类输出恒为 0。读入的旧数据如有位置X 类型输出，会提示并可一键改为角度。

「+ 添加」里已被其他生效组驱动的参数显示为不可选，并注明由哪个组驱动。

每个输出行右侧的「最大输出力」对应 Cubism Editor 输出设置的同名列：从打开这个组起（或上次重置起），这个输出在当前倍率下达到的最大值占参数端点的百分比。牵动画布、播放预览或视线跟随时都会记录；超过 100% 显示为警告色，表示参数已被截断在端点。改倍率后百分比立即按新倍率换算，不需要重新牵动。

- 「按最大值调整倍率」：把每个输出的倍率调整到最大输出力恰好为 100%。还没有记录时，用响应曲线的标准牵动来测。
- 「重置输出最大值」：清空记录，重新开始测量。

### 高级

折叠在「高级」下的是画布和滑块已经覆盖、只在需要精确数值时才用的数据：

- 摆锤设置表：每个摆锤的长度、摇摆度、反应速度、收敛速度；
- 输出细节：倍率和影响度；
- 输入标准化：位置X 和角度输入的最小值 / 中心 / 最大值。

组名点击即可重命名；「⋯」菜单里有重命名、复制、编辑摆动（摆动来源）、恢复生成值和删除（自定义组）。

每次拖动、滑块拖动或数值输入会在松手后记一条历史，可以撤销。编辑保存在工程里，重建模型后按同样的组重新生成。

## 预览与导出的一致性

面板里的摆锤、响应曲线、内置渲染的软件预览和 MCP 的模拟使用同一个物理引擎，逐项对应 Cubism Native Framework 5-r.5 的 `CubismPhysics::Evaluate`：输入标准化、按 `Fps` 固定步长并在帧间插值输入、组之间通过参数缓存传递（后面的组能读到前面组同一步的输出）、节段更新与空气阻力、输出插值与权重混合，包括 SDK 本身的一些特殊行为。仓库中的 `PhysicsReferenceTest` 用官方 Framework 在导出模型上跑出的逐帧数据（`native/physics_reference`）校验：900 帧不规则帧间隔、链式组、反转、部分权重和位移输出，有无 `Fps` 两种情况下最大偏差约 1e-5。

导出的 `physics3.json` 声明工程的帧率（`Fps`，默认 60；「无限制」时不声明），CMO3 的物理 FPS 与之相同，摆动不随渲染帧率变化，从 CMO3 经 Cubism Editor 再导出也保持一致。组按列表顺序导出，也就是运行时的计算顺序。官方 SDK 预览可用时，预览直接由 SDK 读取导出的 `physics3.json`。

物理只写参数；摆动效果取决于输出参数的关键形。自定义组要先为输出参数做好端点形态，否则参数在动但模型不动。

## MCP

`physics` 工具有六种模式（完整字段见 [MCP 使用与接口](../agent/MCP_AUTHORING.md)）：

- `put`：按 ID 新建或修改，只写给出的字段。已有 ID（包括生成的组）以当前组为基础；`inputs` / `outputs` / `segments` 整体替换列表，`length` / `mobility` / `delay` / `acceleration` 作用于所有节段，`output_scale` 作用于所有输出，`segment_count` 改节段数，`enabled=false` 关闭任意组。
- `delete`：删除自定义组，或把已修改的生成组恢复成生成值。
- `simulate`：从静止开始把输入阶跃到给定值、保持 `hold` 秒再放回，返回每个输出在保持期间和松开后的峰值、最终值与稳定时间。
- `fit`：用响应曲线的标准牵动运行一个组，把每个输出的倍率调到峰值恰好达到参数端点的 `target`%（默认 100），与面板的「按最大值调整倍率」在没有实时记录时相同。
- `config`：`order` 设置计算顺序（列出的组排在前面），`fps` 设置工程帧率（0 为无限制）。
- `import`：导入 physics3.json（绝对路径），规则与面板相同，返回导入的组、被关闭的组和缺失参数。

`inspect scope=physics` 返回计算 FPS 和按计算顺序排列的全部组，每组带来源、是否生效、被谁替代和无效原因。

预置只在面板里使用；MCP 直接写入输入和摆锤的完整数值。