# 摇摆生成

[文档目录](../../README.md) · [物理](PHYSICS.md) · [MCP 使用与接口](../agent/MCP_AUTHORING.md)

摇摆生成对应 Cubism Editor 5.1 的「揺れの自動生成」：选中弯曲变形器，自动在 -1 / 0 / 1 上生成摆动的关键形。在此基础上它还做了这些事：

- 选中网格也可以，会自动给网格包一层贴合的弯曲变形器；
- 分**左右**和**上下**两种摇摆，两种可以同时开；
- 可以让尖端保持水平、底部平行摆动，用一个变形器模拟多束头发一起摆；
- 同时生成对应的**物理摆锤**；
- 设置随工程保存，随时可以重新打开调整。

## 打开方式

- 画布（对象模式）右键选中的网格或弯曲变形器 →「生成摇摆...」。多选时一起注册。
- 层级树里右键网格或弯曲变形器 →「生成摇摆...」。已经生成过摇摆的对象显示为「编辑摇摆...」。
- 物理面板 →「+ 新建」→「为选中对象创建摆动…」；物理组列表里摆动来源的组可以从「⋯」菜单「编辑摆动」打开。

打开后画布切到编辑模式，进入摇摆编辑。编辑时不会弹出遮挡画布的窗口：形状直接在画布上拖出来，左下角只有一个可以折叠的小面板。

- 多个目标共用同一组参数和摆锤。
- 编辑期间画布被锁定：点在手柄以外的地方不会选中或拖动其它对象，右键菜单也不弹出。
- 要追加目标，在层级树里选中其它网格，再点面板上的「注册选中对象」。
- 旋转变形器不能作为目标。

## 画布上的控件

画布上画的是摇摆矩形（宽为支点边、长为支点边中点到对边中点）的三个轮廓：静止形状（虚线）、+1 姿态（实线）、-1 姿态（淡色），并画出两个姿态的中心线。固定边会加粗显示。所有手柄都放在当前编辑方向的 +1 姿态上，拖到哪里，+1 姿态的那一部分就到哪里：

| 手柄 | 位置 | 拖动效果 |
| --- | --- | --- |
| 圆点 | 尖端 | 横向拖设幅度，拖到另一侧就是翻转；沿轴拖设上翘 / 下坠。伸缩弹跳时只沿轴方向起作用 |
| 菱形 | 中心线中点 | 设柔软度：中段跟着尖端走得越少，根部越挺 |
| 小方块 | 尖端两角 | 设尖端的放大 / 缩小；弯曲时也设底部平行程度（尖端边保持多水平） |
| 十字圆点 | 支点边中点 | 平移整个摇摆矩形，支点边中点跟随指针 |
| 空心圆 | 静止中心线越过尖端的延长处 | 绕支点中点旋转整个摇摆矩形（轴角），只看指针方向；接近 0° 时吸附回 0° |
| 空心方块 | 其余三条边的中点 | 点击后把这条边设为支点 |

所有修改都会实时显示在模型上。面板上的「预览摆动」让参数在 -1 和 1 之间来回摆动（多段时逐段错开，上下与左右错开）。「生成」/「应用」或 Enter 会写成一条历史记录；「取消」或 Esc 不留任何改动。

## 两种摇摆与支点

「摇摆方向」指尖端在屏幕上的运动方向；「支点」是固定不动的那条边（按格点的行列计算，第 0 行是上边）。两者的组合决定变形方式：

| 方向 | 支点 | 变形 | 典型用途 |
| --- | --- | --- | --- |
| 左右 | 上 / 下 | 弧形弯曲 | 发丝、飘带、尾巴 |
| 上下 | 左 / 右 | 弧形弯曲 | 横向伸出的饰物、侧边飘带 |
| 上下 | 上 / 下 | 伸缩弹跳 | 耳坠、蓬松发梢、胸 |
| 左右 | 左 / 右 | 伸缩弹跳 | 很少用 |

- **弧形弯曲**：沿中心线弯曲时长度保持不变，所以尖端摆出去时会自然上抬，不会像单纯平移那样被拉长。
- **伸缩弹跳**：尖端沿支点方向伸长或缩短。伸长时变窄，压缩时变宽，保持体积感。
- **自动支点**：
  - 细长的对象取上边；
  - 横向的对象取离身体中线更近的一侧。

### 旋转与平移摇摆矩形

默认的摇摆矩形与变形器对齐。素材斜着垂下（侧发、斜挂的饰物）而变形器仍是正的矩形时，可以拖尖端外的空心圆，把整个摇摆矩形绕支点边中点旋转，范围 ±75°：

- 正值让尖端转向支点边的末端（上 / 下支点为右端，左 / 右支点为下端），镜像的父空间也跟着镜像。
- 矩形大小不变，只是转了方向；弯曲垂直于转后的轴，弧形保长、上翘、伸缩、平行都在转后的矩形里计算，画布上的轮廓、固定边、支点和尖端手柄也一起转。
- 固定的是矩形的支点边：它后面的部分不动，格点原来的边若有一端伸到支点边前面，会随靠近根部的弯曲轻微移动。
- 拖支点边中点的十字圆点可以平移整个矩形，例如把支点下移到发根实际所在的位置，上面的部分就保持不动；旋转绕平移后的中点进行。
- 平移量按矩形自身比例保存：沿轴以长度计、沿支点边以宽度计（各 ±1），所以目标变形器的各个关键形缩放、移动后仍落在素材的同一位置。
- 轴角和平移属于整个摇摆，两个方向共用；面板上显示当前数值，各自的「归零」恢复默认。点击其它边改支点时两者都归零。以前保存的摇摆按 0 打开。

### 组合左右与上下

面板上「摇摆方向」的两个选项可以同时勾选，两者作用在同一个变形器上。

- 两个方向各有自己的参数、形状设置和摆锤。
- 同一支点下两者必然是一个弯曲、一个伸缩：生成时先伸缩再弯曲，所以组合姿态是精确的，不是两者简单相加。
- 两个方向都开时，面板多出「编辑」一行，选择画布手柄对应哪个方向。

## 底部平行（多束头发）

头发没拆分时，左侧发、刘海和右侧发都在同一个变形器里。普通的弯曲会让每个横截面跟着中心线一起转，整块像一块板一样转动：尖端边倾斜，一侧上抬、另一侧下沉，看起来很怪。

「平行」设置控制横截面转多少：

- **0**：横截面跟着弯曲转，整块像一块板一样摆，适合单根的发丝、饰物。
- **1**：横截面保持水平，尖端边不倾斜。每一列像挂在固定边上各自的位置，和旁边的列并排平移，看起来就像多束头发一起摆。
- 中心线的弧线不受影响，所以幅度、上翘、柔软度的意义不变。
- 刘海这类靠近固定边的短束，本来就处在弯曲量小的位置，自然摆得少；不需要拆分，也不需要额外的变形器。

发丝和布料预设默认偏向平行（发丝左右 0.7），饰品预设为 0。在画布上拖尖端两角的小方块即可调整。

## 设置

面板里只放画布上没有对应位置的选项（摇摆方向、编辑方向、自动估计、分段、自动支点、物理），其余几项只读显示当前方向的数值。

| 设置 | 作用 |
| --- | --- |
| 摇摆幅度 | ±1 时尖端移动的距离，按支点到尖端的长度计（0.25 = 四分之一长度） |
| 上翘 / 下坠 | 弯曲时尖端额外抬起（正值）或下坠（负值） |
| 柔软度 | 0：整条均匀弯曲；1：根部保持挺直，主要是尖端在动 |
| 放大 / 缩小 | ±1 时靠近尖端的部分变宽或变窄 |
| 平行 | 0：整块像板一样转；1：尖端边保持水平，各列并排摆动 |
| 轴角 | 摇摆矩形绕支点中点旋转的角度（±75°），用于斜挂的素材 |
| 平移 | 摇摆矩形的支点边中点沿轴 / 沿支点边的偏移，按长度 / 宽度计 |
| 左右翻转 | 把 +1 和 -1 的方向对调 |
| 分段 | 每个方向 1–3 段，每段一个参数。第 k 段只弯曲它下面的部分，物理上共用一根多节摆锤，下面一段比上面一段晚一拍，形成甩鞭式的跟随 |
| 自动估计 | 发丝 / 饰品 / 布料，给出一组初始形状和摆锤参数；摆锤长度按目标的像素长度估算 |

参数不存在时会自动创建（范围 -1..1），命名为 `ParamSwing<id>`，两个方向都开时加 `_X`（左右）/ `_Y`（上下），多段时再加 `_1`、`_2`…。改变方向或段数时参数会按这个规则重新命名。如果选用已有的参数，关键放在它的最小值、默认值和最大值上。

以前保存的摇摆没有「平行」设置，打开时按 0 处理，保持原来的样子。

## 物理

勾选「为此摇摆生成物理摆锤」后，导出的 physics3.json 和 cmo3 里会多出摆锤物理组：

- 每个方向一个摆锤。只有一个方向时组名是 `PhysicsSwing_<id>`；两个方向时是 `PhysicsSwing_<id>_X` 和 `PhysicsSwing_<id>_Y`。
- **左右**：输入与前后发相同，头部和身体的角度 X（X 类型）、角度 Z（角度类型）。
- **上下**：输入头部和身体的角度 Y、以及小权重的角度 Z。
  - Cubism 的摆锤杆是刚性的，一根垂直挂着的摆对上下平移没有反应。
  - 所以这里把角度 Y 当作横向（X 类型）激励输入，再用摆的角度去驱动上下形态。
- **分段**：每段对应物理组里的一个摆锤，第 k 段参数由摆锤数为 k 的输出驱动。

摆锤也列在[物理面板](PHYSICS.md)里，可以在那里直接编辑（输入、输出、各摆锤的动力学等）。在物理面板里修改后，以物理面板的版本为准，摇摆面板中的摆锤数值不再生效，面板会提示；在物理面板中「恢复生成值」即回到按摇摆生成的摆锤。对同一输出参数新建的自定义组会替换掉对应的摆锤。删除摇摆或改变方向时，旧摆锤的修改一并清除。

## 生成器语义与烘焙

摇摆是一个「生成器」：每次重建模型时，都会按目标变形器当前的形态重新计算，然后在后面加上摇摆轴。所以：

- 目标原有的关键轴（例如角度 X）都会保留。每个原有关键形都会各自展开出摇摆的各个形态。
- 这些摇摆轴归摇摆所有，手动改这些轴上的关键形，重建后会被覆盖。
- 想手动微调时，在面板上点「烘焙为关键」：
  - 当前形态会写成普通关键形，之后可以自由编辑；
  - 摆锤保留，摇摆只剩物理部分。
- 「删除」会连同生成的轴和自动创建的参数一起移除。

## Agent

MCP 的 `swing` 工具提供 `put` / `delete` 两个分支：

- 只要一个方向时，直接在顶层写 `kind`、`segments`、`parameters` 和形状字段（`magnitude`、`lift`、`softness`、`zoom`、`parallel`、`flip`）。
- 组合两个方向时用 `motions: [{kind: "lateral", ...}, {kind: "vertical", ...}]`，每项带自己的字段、参数和 `physics`。
- 顶层的 `fulcrum` 选支点边，`tilt` 为摇摆矩形绕支点中点的旋转角（度，±75），`offset_along` / `offset_across` 为矩形的平移（按长度 / 宽度计，±1），两个方向共用。
- 省略 `physics` 时，按目标尺寸估算摆锤；`physics_enabled=false` 表示不生成摆锤。
- `delete` 的 `bake=true` 等同于「烘焙为关键」。

`inspect` 的 `scope=swings` 列出当前所有摇摆。