实例：从 GEIMG 图元数据集到 Live2D 式 Lua

# 实例：从 GEIMG 图元数据集到 Live2D 式 Lua

本文是知识库全部十二篇的合集。文中提到的 `attachments/` 脚本下载连接如下 
[【附件】attachments.zip](/media/attachment/2026/09/attachments.zip)

## 目录

1. 实例：从 GEIMG 图元数据集到 Live2D 式 Lua
2. 01 · 前置：从图集拆到可用的分层
3. 02 · 拟合：从 PNG 到图元集合
4. 03 · 数据格式：图元、导出、三套坐标系
5. 04 · 在游戏里重建：控件、层序、加载、性能
6. 05 · 动作与骨骼
7. 06 · 边缘与画质
8. 07 · API 速查与验证状态
9. 08 · 踩坑清单
10. 09 · 端到端 SOP 与检查表
11. 10 · 补间动画（Tween）：能省掉什么、不能省什么
12. 11 · 层级与骨骼：用「父容器」代替逐图元写入

---

## 实例：从 GEIMG 图元数据集到 Live2D 式 Lua

一套**可复现的流水线**：把一张 Live2D 风格的图集，变成游戏内用纯 Lua 驱动、能呼吸/眨眼/跟随视点/做动作的角色。

> **⚠️ 这里的 Lua 是「原神 · 千星奇域」的客户端脚本，不是通用 Lua**
>
> 本知识库 `04`~`11` 的代码全部跑在**千星沙箱的客户端脚本环境**里。写之前先认清三件事：
>
> 1. **环境是运行时给的**：全局只有 `script`（当前脚本实例）、`Enum`（枚举命名空间）、
>    `game`（客户端运行时表，点号调用）。控件是这个游戏的**客户端 UI 控件**
>    （图片 / 文本 / 光标检测区…），不是别的引擎的 UI。
> 2. **标准库被裁过**，照搬通用 Lua 的写法会直接报错：
>    - `io.*` —— **不可用**。所以图元数据必须内联在源码里（脚本里那一大块 `RAW` 就是这个原因）。
>    - `require` / `package` —— **不要指望**。产物是**一份自包含脚本**，不是一包文件。
>    - `coroutine.*`、`string.dump` —— **不可用**。
>    - `os.*` —— 只有 `os.time` / `os.date` / `os.clock` / `os.difftime`。
>    - `debug.*` —— 只有 `debug.traceback`。
>    - 反过来，标准库**补了** `math.isnan` / `math.isinf`。
> 3. **脚本要挂到客户端的「客户端控件容器」上**才生效，不是贴哪里都行（见 `04.2`）；
>    调试日志在客户端日志窗口的「客户端脚本」分类里看（见 `09`）。
>
> 接口以官方《客户端控件API文档》为准：
> <https://act.mihoyo.com/ys/ugc/tutorial/detail/mhtakr07vej4>
> —— 本知识库 `07` 里的字段名、签名、枚举都是照它核对过的。
>
> 数据集（`shapes.json` 与图元格式）本身是通用的，可以拿去做别的事；
> 但 `04`~`11` 讲的运行时**就是千星奇域这一个平台**，不要套到 Unity / 别的 Lua 宿主上。

> **先把定位说清楚**：这份知识库讲的是**我们跑过的一遍**，不是要求你照搬的教程。
> 里面是两层内容，读的时候分清：
>
> - **工具用法（要遵守）**：GEIMG 怎么用 —— `02` 的三个开关约定与参数口径、
>   `03` 的数据格式与坐标系、`07` 的 API 事实与"未验证"清单。
>   这部分是"这样才对 / 这样会报错"，与画风和实现选型无关。
> - **我们的实现（案例，可以不同）**：素材怎么拆、动画怎么写、UI 怎么搭 ——
>   `01` / `04` / `05` / `06` / `08` ~ `11`。这些**只是我们的一种做法**：
>   只要你的交付效果达标，随便换。每篇末尾都分了两栏，「规则 / 不变量」是判据，
>   「参考实现（可以不同）」是我们当时的选择。
>
> 想让图元数据集去干别的事（静态展示、别的动画方案、别的引擎/平台）也没问题 ——
> 工具只负责"把图拟合成图元"，下游是你的地盘；本知识库的运行时部分（`04`~`11`）
> 是拿"千星沙箱 + Lua"当**例子**写的，不是唯一出路。

写给两种读者：

- **人**：想搞懂每一步在干什么、为什么这么干、哪些坑已经踩过。
- **AI**：想照着做一遍、或改造其中一环。每个文件末尾都有「规则 / 不变量」小节，那是硬约束；
  标了 `⚠️ 未验证` 的地方不要当成事实往下推。
  **参数上没有被禁止的项**：看到"我们没调过/差异不大"时，那是我们的观测，
  你可以按 `02` 的 2.9 自己量一次再决定。

---

### 这条流水线长什么样

```
图集 PNG (1024×512)
   │  ① 拆分：在 PS 之类工具里**手工扣**成同尺寸分层（自动拆分效果不好，见 01）
   ▼
parts/part_NNNN_名字.png  ×26   （411×600，二值 alpha，已摆好位置）
   │  ② 拟合：逐部件调 GEIMG，用圆/椭圆/线逼近
   ▼
fit_10k/part_*/shapes.json    （space = source_image_pixels）
   │  ③ 边缘处理：剔溢出 / 缩回轮廓 / 轮廓改色        ← 直接在数据上做，不改原文件
   ▼
   │  ④ 构建：拼数据 + 生成部件表 + 骨骼参数 + 动画代码
   ▼
l2d_anim*.lua      （自包含：数据 + 实例化 + 动画）
l2d_theater*.lua   （同上 + UI：背景/按钮/文字/拖动条/快捷键）
l2d_preview*.html  （浏览器里预览同一套数据与公式，用于调参和验收）
```

**为什么用图元而不是直接贴图**：一张整身贴图动不了；拆成图元后每个图元是一个可独立变换的控件，
就能做形变。代价是控件数量大（本项目 9941 个），所以整条链路的性能约束都围绕"每帧写多少次属性"。

---

### 文件清单与阅读顺序

| 文件 | 讲什么 | 什么时候看 |
|---|---|---|
| 01-前置-拆分.md | 图集怎么拆、为什么必须二值 alpha、编号即层序 | 拿到新素材时 |
| 02-拟合-从PNG到图元.md | **三个开关怎么定**、GEIMG 各参数含义、预算怎么分、放大的必要性、同屏图元数、benchmark（含设备基准表） | 拟合前 |
| 03-数据格式-图元与导出.md | shapes.json 字段、Lua 紧凑行、三套坐标系 | 写解析代码时 |
| 04-在游戏里重建.md | 控件创建、层序、加载分帧、性能策略 | 第一次接进游戏时 |
| 05-动作与骨骼.md | 呼吸/眨眼/视点/骨骼位移场/跳跃 | 做动作时 |
| 06-边缘与画质.md | 硬边、白描边的根因与修法、量化验收 | 觉得"边不对"时 |
| 07-API速查与验证状态.md | 实测确认的 API 用法；**未验证项单列** | 每次写脚本前 |
| 08-踩坑清单.md | 12 个坑：现象→根因→修法→怎么发现的 | 出问题时先查这里 |
| 09-端到端SOP与检查表.md | 完整命令 + 交付前检查表 | 要跑一遍全流程时 |
| 10-补间动画-Tween.md | **补间能把空转负载打到 0**（视点跟随不行）；附实机探测脚本 | 想降负载时 |
| 11-层级与骨骼-父容器.md | **最强降负载手段**：图元挂父容器、只动容器（每帧 866/3286 → 几十次）；附探测脚本 | 要改架构时 |

---

### 先读这一段：两种要求，别混

这份知识库讲的是**一套跑通过的实现**，但**不要求你做得和我们一模一样**。
要求分两类：

#### ① 不变量（必须满足，违反了必然出错）

这些和风格无关，纯粹是对错：

- 跨坐标系必须显式转换（画布左下原点 ↔ 控件中心原点）
- 逐帧回调必须脚本自己打开
- 数据里**半径 ≠ 直径**、**弧度 ≠ 角度**、**0-based ≠ 1-based**，不能混
- 父子/层序关系必须明确（谁盖谁）
- 每帧写入量必须与图元数量级匹配，否则卡顿

#### ② 参考实现（我们的选择，**可以不同**）

**只要最终效果达标，随便换。** 例如：

| 我们这么做 | 你可以 |
|---|---|
| 26 个部件、编号 `0000`~`0026`、数字小的在上 | 任意部件数、任意命名与层序规则，**只要绘制顺序有明确定义** |
| 画布 411×600、缩放 1.05、偏移 584/135 | 任意展示尺寸；只要换算自洽（见 `03` 的公式） |
| 拟合预算 1700/1250/780… | 按你自己的边际收益曲线定 |
| 边缘阈值 0.12 / 2% / 半径 2 | 只要"外溢下降且内部不变差" |
| 骨骼锚点自动推、`bodyAmp=6`、`headKeep=0.25` | 任意幅度与曲线，只要满足验收表里的"脚钉住 / 梯度单调" |
| 跳跃参数 64/24/10/12/3.5 | 纯观感参数，按你的角色重调 |
| 具体 prefab ID、具体工具脚本 | 你自己的场景 ID 与工具链 |

**判断标准是下面这张表，不是"数字对不对得上"。**

---

### 验收表：要保证的就是这些效果

做完之后逐项量一遍。右列是本项目的实测值，**当参考量级看，不是及格线**。

| 要保证的效果 | 怎么量 | 参考量级（本项目） |
|---|---|---|
| **轮廓对得上** | 轮廓覆盖 / 轮廓不符像素 | 覆盖 > 98%、不符 < 2%（本 99.40% / 0.88%） |
| **边缘是硬的** | 半透明像素数 | 远低于软边（本硬边 ≈1136，源图 0） |
| **没有白描边** | 最外环「明显偏亮(>25)」像素 | 修完应大幅下降（本 1568 → 82） |
| **没伤到内部** | 内部 RMSE（离轮廓 >3px） | **不因边缘处理而变差**（本 22.40 → 22.23） |
| **位置正确** | 图元坐标范围 | 不超出半画布（本越界 0 个） |
| **脚钉住** | 脚部图元的水平位移 | ≈ 0（本 0.00px） |
| **越往上动越多** | 躯干/头位移梯度 | 单调递增、无台阶（本 0.66 → 17.29px） |
| **眨眼读得出** | 眼内容压缩数 + alpha 变化数 + 能否还原 | 三者都要有且能还原（本 681/681/681） |
| **动作互不干扰** | 逐动作位移量测 | 每个动作都有非零位移，互不抵消 |
| **不卡** | 每帧 API 写入次数 | 明显低于全量（本 596k/秒 → 197k/秒；**补间化呼吸后可到 ≈0**） |
| **不静默失败** | 日志 | 关键步骤都有日志（容器/UI/按键/铺完/层序） |

这些都能在**不进游戏**的情况下量（`attachments/l2d_verify_*.py`、`attachments/l2d_edge_probe.py`）。
真机只需确认那几件预览测不出来的事（见 `07` 的未验证表）。

---

### 五分钟速览（只记这几条也能跑通）

1. **先定三个开关**（`02` 的 2.0）：要保住图片的边缘形状就开**边缘感知**（与是否 PNG 无关；
   带透明通道的图 **必须**开）；**黑白交替底色**是用来拟合黑色/深色内容的，**建议常开**；
   像整体环境图这种不关心边缘形状的，两个都关掉、走标准拟合，**更省图元**。
2. **图元总数按"同一时间、同屏"算**，经验量级是同屏 **3000 以内** —— 这是**建议，不是规矩**，
   多少由你按用途和机器判断（`02` 的 2.8）；自己这台机器上跑一次 benchmark（2.9），
   比抄我们的耗时数字可靠。
3. **拆分层的 alpha 最好二值（0/255）** —— 非二值不是不能做，但"硬边"这一整套判断就不成立，
   而且后面（`06`）的白描边问题会更容易发生。
2. 每个部件的**绘制顺序要有明确定义**。我们用"文件名编号小的在上"。
3. 拟合产物 `shapes.json` 的坐标空间要**统一**（我们用 `source_image_pixels`）；
   放大拟合过的要除回去。
4. 一个图元 = **一个图片控件**：圆形贴图 + `ImageType.Stretch` + `imageColor` + 尺寸 + 旋转。
5. 控件位置用「**画布中心原点**」，`GetCursorUIPos` 用「**画布左下角原点**」，
   两者差半个画布——漏减就会整体窜到右上角（本项目实际踩过）。
6. **没有 `alpha` / `zIndex` 字段**：透明度改 `imageColor`，层序用 `SetSiblingIndex`。
7. 逐帧回调**默认是关的**，脚本必须自己 `script:EnableUpdate(true)`。
8. 图元上万时**别每帧全写**：降频 + 位移小于阈值不写 + 视点没变就跳过骨骼场。
   动作要用**连续位移场**，别给相邻部件不同权重（后者必然在边界撕开）。

---

### 生成的 Lua 必须以这段开头：ID 槽位（漏了就没有画面）

**这是硬要求。** 编辑器侧的 ID 既不在数据里、也不在 API 文档里，只能在编辑器里看到 ——
脚本里不留出可填的槽位，用户拿到脚本就无从下手。
（实机跑通的那份 `图元剧场_超拟合10k.lua` 开头就是这个结构；反过来，实测出现过别的 AI
读完本文生成的 Lua **整段省掉了 ID**、或把模板索引写成 `0`，结果进游戏什么都不显示。）

```lua
local CFG = {
  -- ── 编辑器侧 ID：这四个必须按自己场景的实际值填 ──
  containerName = "GEIMG_Canvas",   -- 客户端控件容器的名称（脚本通常也挂在它上面）
  imagePrefabId = 1073741850,       -- 图片控件模板索引ID（图元 / 背景 / 按钮底 / 轨道 / 滑块都用它）
  textPrefabId  = 1073741851,       -- 文本框控件模板索引ID（说明与参数文字）
  areaPrefabId  = 1073741849,       -- 光标检测区模板索引ID（按钮点击、拖动条拖动）

-- ── 资源 ID ──
  circleAssetId = 100002,           -- 图元用的圆形贴图资源ID（全项目共用这一张）

-- 其余参数（画布映射 / 分帧预算 / 动画幅度…）按本知识库各节给的值填
}
```

| 槽位 | 是什么 | 在编辑器哪里看 | 本项目实机跑通的值 |
|---|---|---|---|
| `containerName` | 客户端控件容器的名字 | 界面布局里那个容器节点 | `GEIMG_Canvas` |
| `imagePrefabId` | 图片控件**模板**索引 | 容器「画布设置 → 前往编辑」里那个图片控件 | `1073741850` |
| `textPrefabId` | 文本框控件**模板**索引 | 同上，文本框那个 | `1073741851` |
| `areaPrefabId` | 光标检测区**模板**索引 | 同上，光标检测区那个 | `1073741849` |
| `circleAssetId` | 圆形贴图**资源** ID | 贴图资源里那张白圆 | `100002` |

三条规矩：

1. **这段原样留在脚本顶部，五个值一个都不能省**，并且保留「编辑器侧填」这类提示。
   表里是**本项目实机跑通的值**，换场景要按编辑器里实际值改 —— 但**槽位不能删**。
2. 三个 prefab 都要先在编辑器里**另存为模板**才能被脚本实例化；
   挂载在主屏里的控件、以及模板的子节点，都不能实例化。
3. 用到音效或本地化时，同样在 `CFG` 里补 `audioId` / `textMapId` 槽位，
   别把 ID 写死在调用处。

> 相关：`04` 的 4.2 讲容器怎么找（找错了容器时 `InstantiateClientUIControl` 是**静默失败**的）；
> `09` 的交付检查表里有核对这五个 ID 的一项。

---

### 生成的 Lua 必须暴露这组对外函数（否则外部驱动不了它）

**这是硬要求，和上面的 ID 槽位同级。** 脚本自己会呼吸、眨眼、跟鼠标，但用户在关卡里、
在按钮上、在别的脚本里要能**驱动**它 —— 走的是 `script:Invoke("PlayAction", "shake")`
这条路（`07` 的按键示例就是这么调的）。实机跑通的那份脚本暴露了下面这些全局函数，
生成脚本时必须原样保留名字与语义：

| 全局函数 | 作用 | 要点 |
|---|---|---|
| `PlayAction(name)` | 播一次性动作 | 名见 `05.5` 的动作表；**未知名要 `print` 提示**并返回 false；`"jump"` 单独走骨骼轨迹，不乘通道正弦 |
| `SetPreset(name)` | 切预设 | 名见 `05.5` 的预设表；切换前**先清空全部通道**（见 `05.5` 那条坑） |
| `SetChannel(name, value)` | 直接设某个连续通道 | 未知名要报错，**并把可用通道列出来**（用户拼错时能自己发现） |
| `SetGaze(on)` | 视点跟随开关 | |
| `BlinkOnce()` | 立刻眨一次 | 按钮"眨一下"用 |
| `SetBlink(v)` | 手动眨眼 | `"hold"` 保持闭眼 / 数值指定闭合量 / `"open"` 恢复自动 / `"off"` 关掉自动 |
| `SetAnimate(on)` | 动画总开关 | 关的时候顺带停逐帧回调与跳跃序列；重开走 `startTick()`（别直接调 `EnableUpdate`，见 `04.5`） |
| `GetStatus()` | 运行状态快照 | 排查"到底在动没动"用；字段至少覆盖 `done` / `writesPerFrame` / `blinkCount` / `gazeX` / 动作数 / 当前通道值（见 `09` 的验收） |
| `OnEnable()` / `OnDisable()` | 生命周期回调 | 停用时**暂停跳跃序列**，启用时恢复；停用期间不要继续算 |

两条配套约定：

1. **未知名一律给提示**，别静默 `return` —— 用户写错 `SetPreset("wind ")` 的时候，
   日志里得能看见"没有这个预设"，否则他会以为脚本坏了。
2. 这些函数之外，脚本**不要再自作主张暴露别的全局名**（会和外部调用约定打架）；
   内部工具函数一律 `local`。

---

### 生成脚本的分节顺序（照这个结构写）

实机那份脚本的分节是固定的。用户后续要改（"拖动条改的是哪个值"），靠的就是这个顺序定位；
AI 生成时也照这个顺序写，别把功能摊平成一长串：

```
CFG          编辑器侧 ID + 画布映射 + 动画参数（见上一节「ID 槽位」）
RAW          图元紧凑行 "t|x|y|w|h|rot|rrggbbaa"（见 03.2）
PARTS / GN   部件表与分组（见 03.4）
ACT / CHANNELS / PRESET / BONE   动作表、通道清单、预设表、骨骼常量（见 05.5、11）
骨骼         柱面形变、躯干位移场、父容器层级（见 05.3、11）
运行时状态   pool / shapes / cursor / 计时 / 计数
建控件       decode / place / spawn / ensureRoot / 分帧铺（见 03.3、04.1~04.4）
动画         tickBlink / tickGaze / partMotion / updatePart（见 05）
生命周期     OnInit / OnStart / OnUpdate / OnDestroy（见 04.2、04.5、08 坑 2）
对外接口     PlayAction / SetPreset / SetChannel / …（上一节）
UI 层        背景 / 文字 / 按钮 / 拖动条 / 快捷键（见 04.7）
层序重排     背景 → 角色 → UI（见 04.3、04.7.5）
```

---

### 名词表

| 词 | 含义 |
|---|---|
| **图元 / shape** | 一个圆、椭圆或线段，用位置+尺寸+旋转+颜色描述一块色块 |
| **部件 / part** | 一个图层（如"前发""左腿"），由几十到上千个图元组成，部件内图元按顺序叠加 |
| **GEIMG / GEIMG 工具 / GE 图片工具** | 把 PNG 拟合成一堆图元的工具（基座是 LPGS 拟合算法）。**可执行文件不随本包发布**，脚本通过它的命令行调用 |
| **源图像素空间** | 手扣图层的坐标系：411×600，原点左上，Y 向下 |
| **画布空间** | 游戏 UI 坐标系：原点左下，Y 向上（尺寸由 `game.GetUICanvasSize()` 给） |
| **控件空间 / anchoredPosition** | 控件位置用的坐标系：原点在**容器中心**，Y 向上 |
| **骨骼位移场** | 位移 = (x,y) 的连续函数，替代"按部件给权重" |
| **硬边** | 边缘只有全不透明/全透明两种状态（与二值 alpha 对应） |

---

### 这些结论是从哪来的（可信度分级）

| 来源 | 能信到什么程度 |
|---|---|
| **实机运行** | 最高。踩坑清单里有一半是只有真机才发现的（忘开逐帧回调、容器就绪时序、回调签名） |
| **真 Lua 运行时实跑**（lupa + luaparser） | 高。运动/负载/按键这些数字都是这么量出来的；**但不含引擎真实开销**（用的是桩函数） |
| **可用实例的 API 类型定义**（EmmyLua stub） | 高。字段名、类型、签名、枚举以它为准 |
| **从官方 PDF 整理的接口表** | 中。**字段名/类型可信，解释列不可全信**（PDF 里的表格被裁过，有些说明是后补的） |
| **我们的推理与取舍** | 看标记：`【实测】`/`【约定】`/`【可调】`；标 `⚠️ 未验证` 的一律别当事实 |

**读的时候注意**：本项目早期还写过一份计划书（在实机验证之前），里面有几处结论后来被实测推翻
（例如当时不确定坐标系、API 名称写的是旧的 `EnableTick`）。
**如果看到和本知识库冲突的说法，以本知识库和 `07-API速查` 为准。**

---

### 本知识库的证据等级

每处结论都标了来源，看到这些标记请按对应可信度使用：

- **【实测】** 在真 Lua 运行时（lupa）里跑出来的数字，或真机反馈
- **【约定】** 我们定下的规则（例如"编号小的在上"）——**换一套同样可行，只要保持一致**
- **【可调】** 具体数值，按你的素材/手感调；判定看效果不看数字
- **⚠️ 未验证** 推论或文档说法，尚未在真机确认

---

## 01 · 前置：从图集拆到可用的分层

这一步的质量决定后面拟合、动画与边缘处理的上限，所以值得先花点时间定下来。

> **我们的选择：用 PS 之类的手工工具扣（不是唯一解）**
>
> 我们试过写自动拆分脚本（按连通域 + 软边生长），**效果不够好**，最后采用的分层是
> 在 PS 里手工扣出来的。原因是自动拆分解决不了"语义"问题，见 1.2。
> **手工扣 26 层大约半天到一天**，这笔时间在我们这个项目上是回本的。
> 但这是**我们的选择**：如果你的素材规整、或者你有别的分层办法（AI 辅助分层、
> 从画师那里直接拿图层、按绘制顺序反推……），只要满足 1.4 的四条约定，同样可行 ——
> 下面写手工扣的细节，是因为我们只完整验证过这一条路。

产物：一组**同尺寸、已摆好位置、alpha 二值**的 PNG（示例目录 `parts/`）。

---

### 1.1 输入长什么样

源头是 Live2D 风格的**图层图集**：一张大图里平铺着角色的各个零件（头发、脸、眼睛、衣服、腿……），
每个零件的 alpha 都是硬切的。

本例的输入是一张 **1024×512 的 RGBA 图集**（`atlas.png`），拆完得到 **411×600 的 26 层**。

---

### 1.2 拆分判据：什么算"一个零件"

有一条从实践里定出来的规则，**手工扣图时也要照它执行**：

> **任何不连续的都算独立零件 —— 两块内容之间有完全透明的通道，就是两个元件。**

手工扣的时候，这条规则具体化成三个判断：

| 情况 | 判断 |
|---|---|
| 两块之间有一条**全透明的通道**（哪怕只有 1px 宽） | **两个零件**，分别扣 |
| 两块只在**对角相接**（斜着蹭到一点） | 对角相接处是一个全透明角点 → **两个零件** |
| 两块粘在一起、没有透明通道 | 同一个零件，不要硬切 |

#### 为什么脚本自动拆不行

我们试过自动拆分：阈值摘"核心"像素 → 4 连通求连通域 → 软边按最近邻生长。
技术上跑得通，但**结果不能用**，原因有两条：

**① 抗锯齿的淡像素会"架桥"。**
直接对 `alpha > 0` 求连通域，两个本该分开的零件会被 alpha 1~8 的极淡像素连成一块 ——
看起来是一个零件。得先把阈值提到 32 才能把这些淡桥排除掉，而 32 这个值本身就得靠试。

**② 真正的障碍是语义，不是连通性。**
人画的时候是按"语义"分层的，而连通域只认"连不连"：

- **左眼白和左眼珠**在某处相接 → 自动拆成一块；但它们必须是两层（变换不同，见 `05`）
- **前发的一缕和旁边一缕**在发梢粘住 → 自动拆成一块；但它们在动画里要分别甩
- 反过来，**一处高光**可能被拆成独立小块，但它其实应该跟脸一起动

这类判断只有人能下。所以我们最后是：
> **自动拆分当"看一眼有哪些区域"的辅助；最终分层手工定**（26 层）。

---

### 1.3 PS 手工扣图的实操要点

**核心目标**：每个零件是一层，同尺寸画布，内容按原位置摆好，导出时 alpha 尽量干净。

#### 建立工作画布

1. 新建与目标展示尺寸一致的文件（本例 **411×600**），把图集里的角色拖进来当底图
2. **底图锁定 + 降低不透明度**（30% 左右）当参考，扣完删掉
3. 每个零件单独一层，**不要用图层组套娃**（导出时要逐层出 PNG）

#### 扣图手法

| 手法 | 说明 |
|---|---|
| **钢笔工具**（推荐） | 抠硬边线条最准、边缘最干净；转成选区后填充/加蒙版 |
| 魔棒 / 快速选择 | 快，但**务必关掉「消除锯齿」**，否则边缘会出现半透明像素 |
| 蒙版 + 画笔 | 适合头发丝这类不规则边缘，可以随时补/削 |

**关键：关掉所有抗锯齿/羽化**。图层 alpha 越接近二值，后面越省事
（`06-边缘与画质.md` 里"硬边"那一整节都建立在这个前提上）。

#### 层的顺序与命名

- 按"数字小的在上层"命名：`part_0000_xxx.png` 是最上面那层，编号越大越靠下
- **保险做法**：扣的时候按从下往上的顺序建层（先画身体、再衣服、再头发），
  这样图层顺序天然就是对的，命名时倒着编号即可
- 顺序错了不用重扣，改文件名就行

#### 导出

1. 隐藏底图，**逐层**导出 PNG（PS 的「导出为」或「快速导出为 PNG」）
2. 所有层必须**同尺寸**（就是画布尺寸），不要"裁到内容"
3. 导出前检查：每层都是 **RGBA + 透明背景**，不是白底

#### 导出后自检（一条命令）

> 配套脚本：`attachments/l2d_check_layers.py`
> （本项目实际用的就是"一层一层导出，然后跑一遍脚本确认尺寸/alpha/透明区颜色"）

```
① 所有层尺寸一致              ← 不一致下游坐标全乱
② 中间 alpha 像素数 = 0       ← 有中间值说明混进了抗锯齿
③ 透明区 RGB 记下来           ← 后面拟合放大时它会被卷进边缘（见 02）
④ 层数 + 编号连续性           ← 留意有没有缺号、重号
```

---

### 1.4 手扣层的四条约定 【约定】【可调】

这四条是**我们定下的规则**，整条流水线依赖它们。**换一套同样可行**，
只要满足右边"真正的要求"那一列。

| # | 我们的做法 | 真正的要求（不能省的） |
|---|---|---|
| ① | 所有层同尺寸（411×600），内容按位置摆好 | 每层的坐标基准**统一且明确**。可以是"同尺寸画布"，也可以是"各自裁紧 + 记录偏移"，只要下游能还原到同一个坐标系 |
| ② | alpha 严格二值（只有 0/255） | **知道自己的 alpha 是什么性质**。二值 → 后面按"硬边"处理；抗锯齿 → 按软边处理，并且要接受边缘会被拟合得更糊 |
| ③ | 文件名编号即层序：数字小的在上 | 绘制顺序**有明确定义且可程序化读取**。用文件名、用清单文件、用目录顺序都行，但**不能靠"碰巧"** |
| ④ | 命名 `part_NNNN_名字.png` | 有一个**稳定 ID** 能把"数据 / rig / 部件表"三边对上 |

下面按我们的做法展开，替换成你自己的规则时逐条对照即可。

#### ① 所有层同尺寸、且已摆好位置

```
411 × 600，每层都是整张画布大小，内容在自己该的位置上
```

**为什么选这个**：不需要每层记偏移量，合成就是"按顺序叠"。
代价是文件大（大部分是透明像素），但对这条流水线不影响（拟合只在 alpha>阈值处取样）。

**替代方案**：每层裁到内容外接框 + 记一个偏移量。省空间，但合成/拟合时都要把偏移加回去，
多一处容易出错的地方。两种都行，选一种并保持一致。

#### ② alpha 的性质（本项目是二值）

实测：26 个手扣层里**没有任何中间 alpha 值**。

**为什么值得关心**：
- 后面"硬边"那一整套讨论建立在这个前提上（源图本来就是硬边，拟合结果却是抗锯齿的，所以要往硬边拉）
- 如果素材是**抗锯齿**的：那么"往硬边拉"就不再是"还原"，而是"风格化"，两边不一致也没关系，
  但要知道自己在做哪一种
- 透明区的 RGB 记得看一眼 —— 本项目是**纯白 (255,255,255)**，这一点后来成了白描边问题的根因（`06`）

#### ③ 层序怎么定（本项目：编号小的在上）

```
part_0000_头发花装饰.png   ← 画在最后（最上面）
part_0001_前发.png
...
part_0026_后飘带.png       ← 画在最先（最下面）
```

本项目绘制顺序 = **编号从大到小**。编号是 `0000`~`0026`，其中 **`0005` 不存在**（人工删掉了一层），
一共 **26 个部件**。

**注意不要用编号范围循环**（`0..26` 会踩到不存在的 0005，也可能漏掉新增的编号）——
**遍历目录里的实际文件**。

#### ④ 命名与 ID

`NNNN` 是四位零填充编号，后面的中文/英文名只做人看的标注，**代码只用编号**。
名字里带中文和连字符都无所谓（`part_0008_R-睫毛和眼线.png`）。

替代做法：一个 `parts.json` 列出「ID → 文件 → 绘制顺序」。比文件名更容易扩展（比如一个部件多张图）。

---

### 1.5 拆完之后立刻要做的三件事

#### ① 配一张呼吸 rig（`attachments/l2d_rig.json` 是示例）

每个部件给四个参数，**这是"动作"的起点**，后面所有动画都从这里长出来：

| 字段 | 含义 |
|---|---|
| `w` | 呼吸幅度权重（软物给大：飘带 1.2、前发 1.65；硬物给小：腿 0.22） |
| `delay` | 相位延迟（秒）。**次级运动**的来源：发丝比身体慢半拍 |
| `rot` | 跟随呼吸的旋转幅度（度），绕 `pivot` |
| `pivot` | 该部件的旋转轴心（源图像素坐标）。发丝用发根、手臂用肩点 |
| `group` | 分组名，动画按组给权重（见 `05-动作与骨骼.md`） |

分组的实际取值：`head / bangs / hairBack / tailL / tailR / ribbon / body / armL / armR / legs`。

#### ② 确认合成结果

把 26 层按顺序叠起来，和原画对比。这一步能提前发现"层序错了""位置偏了"。

工具：`attachments/l2d_compose_layers.py`（按顺序叠层导出一张对照图，并统计每层露出多少）；
也可以看拼合台（`attachments/l2d_build_assembly.py` 生成的单文件 HTML，
能在浏览器里拖动每层、检查位置与遮挡关系）。

#### ③ 量一下"可见面积"

被上层完全盖住的层（本项目的 `part_0020_pantsi` 露出 0px）**不能删**：
角色一动它就会露出来。但拟合预算可以给到最低（留个底就行），因为平时看不见。

---

### 1.6 规则分成两栏

#### 必须满足（不满足就坏）

- 所有层的**坐标基准统一**，下游能还原到同一坐标系。
- 每个部件的**绘制顺序有明确定义且可程序化读取**（不能依赖文件系统的遍历顺序）。
- 一个**稳定 ID** 贯穿「数据 / rig / 部件表」，三边能对上。
- 重新拆图时**不要改变已有 ID 的含义**（改了就等于把所有下游数据作废）。

#### 参考实现（可以不同）

| 我们的做法 | 说明 |
|---|---|
| 26 个部件、编号 `0000`~`0026` | 部件数由画风决定；本项目人工按语义分，26 个够用 |
| 同尺寸 411×600 全幅画布 | 也可以裁紧 + 记偏移 |
| 数字小的在上 | 也可以数字大的在上、或用清单文件；**只要一致** |
| alpha 二值 | 抗锯齿素材也能做，只是"硬边"变成"风格化"而不是"还原" |
| `w` / `delay` / `rot` / `pivot` 这套 rig 字段 | 字段名随意，动作用得到就行 |

#### 做完立刻量一下（判好坏，不看数字）

| 要保证 | 怎么量 |
|---|---|
| 分层没拆错 | 按顺序合成后与原画对比，边缘无错位、无缺块 |
| 层序对 | 合成结果里该盖住的盖住了（脸不盖头发、眼睛在脸上面） |
| 坐标统一 | 任取一个部件，它的内容在原图坐标系里的位置能算出来且对得上 |
| 被遮住的部件没被删 | 列出"露出 0px"的部件，确认它们仍在数据集里 |

---

### 1.7 常见错误

| 现象 | 原因 |
|---|---|
| 拼起来角色缺一块 | 自动拆分把语义上分开的部分连成了连通域，或反过来把一个零件拆碎了 |
| 零件之间有条缝 | 拆分时只算了核心像素（alpha>32），把软边丢了 |
| 层序错乱（脸盖住头发之类） | 用了目录遍历顺序，或把"编号小在上"记反了 |
| 拟合出来边缘发虚一圈 | 素材 alpha 不是二值的（被某个工具重新导出过） |

---

## 02 · 拟合：从 PNG 到图元集合

把每个部件（PNG 图层）拟合成一堆圆/椭圆/线段。工具是 `GEIMG 工具`。可从左侧GE图片工具下载，1.3.0以上即可。
这一步的产物决定了后面"像不像"，也决定了控件数量（= 性能成本）。

---

### 2.0 先定三个开关（工具口径，与提示词同步）

数值参数（预算、放大倍数、阈值）怎么调是后话。这三个开关决定"图元花得值不值"，
先按**这次要的效果**定，再看图微调：

| 这次要的效果 | `fit mode` | `edge-aware`（边缘感知） | `alternate-bg`（黑白交替底色） |
|---|---|---|---|
| **要保住图片的边缘形状**（角色/图标/任何要抠到别的背景上的图，**不管是不是 PNG、有没有透明通道**） | 有透明通道 → `transparent`；**不透明但要让图元不鼓出画面/轮廓 → 也用 `transparent`**（实测：标准模式的圆形会越出原图边界，透明底模式不会） | **开** | **建议开** |
| **不关心边缘形状**（整体环境图、背景图、整幅都要的内容） | `standard` | 不开（同一片区域用更少图元就够，**图元性价比更高**） | 看内容里有没有黑色，见下 |

- **`edge-aware`（边缘感知）**：拦的是"图元跨出内容边界、鼓到轮廓外"。
  **只要这一次交付要保住边缘形状，就开它，与是否 PNG 无关**；
  本知识库的场景（lua + 带透明通道的 PNG）**是必须开的**。
  它的代价是候选尺寸被边界限制、同样图元数下内部可能更糊——所以"不要边缘形状"的图
  干脆别开，把预算全花在内容上。
  ⚠️ 未验证：它在 `standard` 模式下是否也起作用（`fit recommend` 说"标准拟合模式下它不适用"，
  但引擎实现里开了它会给画布加一圈内衬、否决贴边候选）。**要保边就用 `transparent` + 开它**，这条有实测。
- **`alternate-bg`（黑白交替底色）**：它专治**黑色/深色内容**。
  透明底模式下画布底是黑的，纯黑内容和底色没有差别、误差为 0，**一个图元都拟不出来**。
  所以**建议常开**，除非确认这张图里没有黑色部分。代价是它会周期性全量重放历史图元，
  大图/高 `max-dim` 下会明显变慢——**这是"量一量再决定"的开关，不是"永远别开"**，
  量法见 2.9。切换间隔：`alternate-interval` 默认 30（20~50 之间，越小越慢）。
  ⚠️ 已知边界：**内容接近纯黑（RGB 接近 0）时它只能救一半**——深色底那一拍仍然看不见
  （实测：297×140 近纯黑细条的透明图，透明底模式 0 个图元；开交替底色后能出图，但深底那一拍仍是 0）。
  这种情况最稳的是让内容不是纯黑（加描边/反相）。

> 这两个开关的口径与工具手册（`docs/GEIMG_AI上手提示词.md` 第三节）一致；
> 2.2 起的数值是**本项目这一次跑下来的取值**（一台机器、一批素材，当参考量级看），
> 换素材要按 2.3 的判断方法（预算按边际收益）和 2.9 的 benchmark（耗时自己量）重新定。

---

### 2.1 为什么是"图元"而不是直接贴图

一张整身贴图**动不了**——你没有像素级的变形能力。拟合成一群几何图元后：

- 每个图元 = 一个可独立设置位置/尺寸/旋转/颜色的控件
- 于是可以做**形变**（头转过去时五官按柱面分布位移，而不是整层平移）
- 代价：控件数量大（本项目 10030 个），所以整条链路都在跟"每帧写多少次属性"较劲

另一个好处：图元是**矢量描述**，放大不会糊（但会暴露图元是圆拼的，见 06）。

---

### 2.2 关键参数（本项目实际用的值）

命令行的调用方式见 `attachments/l2d_superfit.py` 与
`attachments/l2d_fit_batch.py`。参数含义：

| 参数 | 本项目取值 | 含义与经验 |
|---|---|---|
| `fit mode` | `transparent` | 有透明通道的图用这个模式（见 2.0） |
| `alpha-threshold` | `64` | **低于这个 alpha 当背景**（工具默认 128）。我们调低是为了让抗锯齿软边也算内容，零件交界处才不留缝；40~100 之间试 |
| `max-dim` | `600 × 放大倍数` | 拟合画布上限，放大 3 倍时写 1800。判据是"最细特征在拟合分辨率下留 2~3px"；工具的 `fit recommend` 会按边缘密度给 600/800/1000/1200，两者等价，按自己的素材定 |
| `candidates` | `64` | 每次尝试的候选图元数，越大越慢越准（工具默认 64） |
| `speed` | `5` | 引擎内部的速度档（工具默认 5） |
| `reserve-ratio` | `50` | 【可调】一半预算留给"精度阶段"（小图元）。我们观察到发丝分股更好；工具手册里另一组误差口径的对照认为差异在重复跑波动内。**这是取舍不是定论**：先按默认跑，嫌发丝糊再 30~50 之间试 |
| `edge-aware` | `on` | 要保边就开（见 2.0） |
| `alternate-bg` | `on`，间隔 `30` | 拟合**黑色/深色内容**用，建议常开（见 2.0） |
| `fit shapes N` | 见 2.3 / 2.8 | 总预算（图元数）。**同一时间、同屏**的总数建议 3000 以内，具体由你判断（见 2.8） |

#### ⚠️ 一个待复现的观察：edge-aware 与勾线

我们的记录里有两条互相冲突的信息，现在按"要保边就开"处理（见 2.0），但值得自己复现一次：

- 一部分日志（`manifest.json` / `session.json`，引擎实际写下的）记的是 `edge_aware: true`；
- 而汇总文件 `_summary.json` 里记的是 `false`，附注说：**开着时会否决所有跨内容边界的候选，
  而勾线恰在边界最外 1~2px，可能导致边缘画不出来**。

**遇到"勾线断了/边缘画不出来"时按这个假设排查**（关掉边缘感知对照跑一次），
常规情况仍按 2.0 开——不开的代价是图元溢出剪影。⚠️ 未验证。

---

### 2.3 预算怎么分：按边际收益，不平均分

我们这一轮观察到的规律：

> **小部件饱和得快：预算给过饱和点之后，再加基本只花时间。**

最夸张的一例（在我们的机器上）：`mouth` 给 120 个图元跑了 **1505 秒**，给 45 个只要 **3.7 秒**，
而**质量没有差别**。耗时的绝对值会随机器变化，但"过了拐点再给就没收益"这个形状是可复现的。

本项目的分配（10k 版，共 10030 图元）：

| 部件 | 预算 | 理由 |
|---|---|---|
| 前发 | 1700 | 成品里最大可见面积，到 v5 的 560 还在变好 |
| 衣服 | 1250 | 层叠 + 金边，420 之后仍在变好 |
| 头发花装饰 | 780 | 第二大可见面积，线条密集 |
| 腿（左右） | 780 / 700 | 到 260 仍在变好（宝石、V 形带） |
| 脸 | 480 | 大片平滑皮肤，实测 100/200/320 **无差别** → 给到下限即可 |
| 眼白 | 60 / 50 | 强边缘像素为 0（纯平滑渐变）→ 给最小底 |
| 嘴 | 60 | 45 即饱和 |
| 被完全盖住的裤子 | 40 | 平时露出 0px，但动画会露，不能给 0 |

**判断方法**：拿一个部件跑 3~4 个预算档，肉眼比"哪一档开始看不出差别"，取拐点。

---

### 2.4 细结构：放大拟合（×3）

**原因不是"更精细"，而是图元尺寸有绝对下限**：

```
圆的半径下限 ≈ max(2, …)      线段的 Ry 下限 = max(1, …)
```

在 411×600 上，这些下限**比勾线本身还宽** —— 1~2px 的线根本表达不出来，
拟合器只能用一个大得多的圆去近似，线就糊了。

做法：把部件图 **Lanczos 放大 3 倍** 再喂给引擎，导出后把坐标/半径**除回 3**。
这样 1~2px 的线在拟合分辨率下有 3~6px，能表达出来了。

哪些部件要放大（本项目）：**细线类全部 ×3**（眉毛、睫毛、眼线、五官、勾线、飘带、腿、手臂……），
大片平涂 ×1（眼白、脸、后布、后发、裤子——放大对它们只是白花时间）。

#### 要点：透明区会被卷进边缘（不管你怎么放大）

**根因与做法无关**：原图透明区的 RGB 是**纯白**，而 **PIL 的 `resize` 对 RGBA 四个通道
各自独立插值，不做预乘 alpha**。于是白色被卷进轮廓最外 1~3px 的半透明像素，
**拟合器照着这些偏亮像素取样，成品轮廓外侧就多出一圈浅色**。

这是本项目"边沿几个像素的白色描边"的根因（完整因果链见 `06-边缘与画质.md`）。

推荐做法（也是我们用的）：**放大前先把透明区的 RGB 染成邻居的颜色**
（`upscale_edge_aware()`，在 `attachments/l2d_fit_batch.py`）。

**反直觉的实测结论**：用"预乘 alpha → 插值 → 反预乘"**反而更糟** ——
Lanczos 的负瓣过冲会被 `1/alpha` 放大，最外圈 RGB 从 (248.6,244.7,242.1) 变成纯白 (255,255,255)。

**如果你不放大了**（例如图元尺寸够、线够粗）：这一步可以跳过。
但**透明区颜色仍然是"以后会出问题的地方"** —— 只要有任何一步做插值/缩放，
它就会卷进来。实在不想管，就在边缘处理阶段（`06`）收尾。

---

### 2.5 导出产物

每个部件一个数据集目录，关键文件：

```
<数据集>/part_0001_前发/
    shapes.json        ← 图元（下游只用这个）
    manifest.json      ← 引擎写下的实际配置 + 预处理信息（以它为准）
    preview.png        ← 用图元重绘的预览（RGBA，可叠加）
    preview_on_white.png
    shapes.csv
    lua/geimg_render.lua
```

**导出的坐标空间要统一，并在数据里写明**（我们用 `source_image_pixels`）：
放大拟合的要把 x/y/r/rx/ry 全除以倍数，并把 `space` 字段写成换算后的空间名。
本项目专门有 `rescale_dataset()` 做这件事
（它同时会把 `preview.png` 用换算后的图元**重绘**一遍——引擎给的原 preview 是放大空间的，
留着它就是"看着对、其实错位"）。

⚠️ 这是本项目踩过的坑：26 个部件里 6 个在源空间、20 个在放大空间，装配时必然对不上。

---

### 2.6 规则分成两栏

#### 必须满足（不满足就坏）

- **每个部件的坐标空间要统一，并且声明清楚。**
  我们统一到 `source_image_pixels`（源图像素）；换别的空间也行，
  但所有部件必须同一个，且下游知道怎么换算到屏幕。
- **图元数组顺序 = 绘制顺序**（这是 GEIMG 输出的约定：下标 0 在最底层）。
  如果你的数据格式没有隐含顺序，就**额外记一份顺序**。
- **半径/直径、弧度/角度不能混**（见 `03`）。
- 放大拟合过的部件，**坐标必须除回同一个空间**——否则装配时必然错位。

#### 参考实现（可以不同）

| 我们的做法 | 可以这样 |
|---|---|
| 统一到 `source_image_pixels`，`space` 字段写明 | 用缩放后的空间、或归一化坐标（0~1），只要统一 + 能换算 |
| 细线部件 ×3 放大 | 加大 `max-dim` 让引擎内部提高分辨率；或接受细线表达不出来（画风允许就不必） |
| 预算 1700/1250/780… | 按你自己的边际收益曲线定（方法见 2.3） |
| `reserve-ratio = 50` | 30~60 之间试；越高越偏向小图元精度 |
| `alpha-threshold = 64` | 40~100 之间试；太高会让零件交界处留缝 |
| 边缘处理在构建脚本里做、不改 `shapes.json` | 直接改也行，但要留一份原始备份（否则没法回滚重调） |

#### 怎么判断拟合够用了

不要跟我们的数字比，问这三个问题：

| 要保证 | 怎么量 |
|---|---|
| 细线画得出来 | 把 `preview.png` 和原图叠起来看勾线/睫毛有没有断、有没有变粗成块 |
| 颜色没跑偏 | `preview` 与原图的颜色误差（RMSE 量级 20~40 属正常） |
| 预算没白花 | 同一个部件跑两档预算，**看不出差别**就说明早饱和了，往下调 |

---

### 2.7 常见错误

| 现象 | 原因 |
|---|---|
| 细线（勾线、睫毛）画不出来 | 没放大拟合，图元尺寸下限比线还宽 |
| 轮廓外一圈浅色 | 透明区是纯白 + 非预乘放大（见 2.4） |
| 装配错位 | 各部件坐标空间不一致（有的除了倍数、有的没除） |
| 五官糊成一团 | 预算给太少；或 `reserve-ratio` 太低，精度阶段没预算 |
| 小部件拟合跑了几十分钟还没提升 | 多半是预算给多了、早就饱和（见 2.3）；也可能是这台机器/这一版引擎在稀疏图上本来就慢——先按 2.9 量一次再下结论 |

---

### 2.8 图元总数：**同屏 3000 是经验上限，具体多少由你判断**

工具的图元数是全局预算（`fit shapes N`）。经验量级是**同一时间、同屏 3000 以内**，
但这是**建议、不是规矩**——最终多少由你按"这次交付的用途 + 用户的机器"判断：

- **按"同一时间、同屏"的总数算**，不按单张图算：三张各 2000 图元的图同屏出现就是 6000。
  这是这里唯一要守住的量级关系。
- **不关心边缘形状的图（整幅环境图/背景）可以明显低于 3000**：
  关掉 `edge-aware` 与 `alternate-bg` 走标准拟合，同一片区域用更少图元就够（见 2.0）。
- **要合成特写、要看清五官与发丝就减少其他部分数量比重**：本项目这一版是 10k 级别（10030 个图元、
  26 个部件），它对应的代价写在 `04` 与 `10`/`11`——每帧写入、首次创建成本、以及
  一整套"每帧别全写"的省法。**上万不是不能做，但要配这套省法并且有实测支撑。** 建议先把3000个图元作为上限，上万的图元只能说“能开”，但是使用体验极其糟糕。
- 如果必须使用大量图元来保证效果，**请务必减少同时刷新的图元数量**！

---

### 2.9 在**你的**机器上量一次（benchmark）

我们文档里所有耗时数字都来自**一台机器、一批素材**；换机器换素材就该自己量一次。
**一次 2~3 分钟就够**：

```bash
# ① 拿真正要用的那张图，设成最终打算用的参数
advanced set max-dim 1000            # 就用你打算用的值
fit mode transparent                 # 或 standard，按 2.0 的结论
advanced set edge-aware on

# ② 小预算试跑，量一个点
fit shapes 200
fit start --until full --timeout 120 --json    # 看 data.elapsed_ms 与 data.shape_count

# ③ 同一配置再跑一次，取两次里较大的耗时（重复跑波动能到 40%），然后线性外推：
#      预计秒数 ≈ 实测秒数 × (目标图元数 / 实测图元数) × 1.5
```

拿到"预计秒数"之后做两件事：**① 定图元数**（能等的秒数 ÷ 单图元秒数，再和 3000 取小）；
**② 定分段**（预计超过 ~90 秒就 `--timeout 60` + `fit resume` 一段一段跑，中断不丢成果）。

#### 设备基准表（待填）

同一张图、同一组参数，在不同设备上的耗时。**这是参考量级，不是门槛**：
你的机器比表里慢很正常；量完把自己的数字记下来一起看，就能分清是"这台机器就这样"
还是"参数选错了"。

| 设备 / CPU | 图（尺寸、透明占比） | 参数（mode / max-dim / edge-aware / alternate-bg / shapes） | 版本 | 耗时 | 备注 |
|---|---|---|---|---|---|
| 待填 | | | | | |

---

## 03 · 数据格式：图元、导出、三套坐标系

这一节是**写代码时的对照表**。三种图元、一个 JSON、一个紧凑文本行、三套坐标。

---

### 3.1 shapes.json（拟合的原始产物）

```json
{
  "format": "geimg-shapes",
  "format_version": 1,
  "space": "source_image_pixels",
  "count": 1700,
  "shapes": [
    {"t":"circle",  "x":110.193, "y":77.58,  "r":26.353,               "rgba":[212,211,188,252]},
    {"t":"ellipse", "x":132.98,  "y":148.663,"rx":21.347,"ry":21.347,"a":2.351687,"rgba":[210,217,197,252]}
  ]
}
```

| 字段 | 类型 | 含义 |
|---|---|---|
| `t` | `"circle"` / `"ellipse"` / `"line"` | 图元类型 |
| `x`, `y` | 源图像素 | **圆心**（不是左上角） |
| `r` | 源图像素 | 圆的半径（只有 `circle` 有） |
| `rx`, `ry` | 源图像素 | 半轴（`ellipse` / `line`） |
| `a` | **弧度** | 旋转角（`ellipse`/`line`）。**注意是弧度不是度** |
| `rgba` | 0~255 ×4 | 颜色 + 不透明度 |

**数组顺序就是绘制顺序**，下标 0 在最底层。

三个必须记住的细节：

1. **`a` 是弧度**。本项目在解析时踩过：以为是度数，算出来的包围盒完全不对。
2. **`r/rx/ry` 都是半径/半轴**，不是直径。导出成控件的尺寸时要 **×2**。
3. **`line` 也是椭圆**，只是 `ry` 很小（渲染成细长椭圆即可，不需要单独的线段路径）。

---

### 3.2 Lua 紧凑行（本项目导出用的格式）

```
"c|110.19|77.58|52.71|52.71|0.00|D4D3BCFC"
 t    x      y      w     h    rot    RRGGBBAA
```

| 位置 | 含义 |
|---|---|
| `t` | `c`=circle / `e`=ellipse / `l`=line（单字符，省体积） |
| `x`,`y` | 源图像素，圆心 |
| `w`,`h` | **直径 = 半径×2** |
| `rot` | 角度（**度**），且**已经取过负** |
| 颜色 | 大写十六进制 `RRGGBBAA` |

#### 为什么 rot 要取负

- 源图坐标系是 **Y 向下**（图像惯例）
- 画布坐标系是 **Y 向上**（游戏 UI 惯例）
- 同一个旋转，在 Y 翻转后方向相反 → 导出时取负，Lua 侧就不用再想这件事

对应代码：`rot = -math.degrees(s["a"])`。

**约定**：紧凑行一旦进了 Lua，里面的 `rot` 就是**最终值**，运行时不要再取负。

---

### 3.3 三套坐标系（最容易出错的地方）

| 名称 | 原点 | Y 方向 | 谁在用 |
|---|---|---|---|
| **源图像素空间** | 左上 | 向下 | `shapes.json`、图层 PNG、rig |
| **画布空间** | **左下** | 向上 | `game.GetCursorUIPos()`、`GetUICanvasSize()` |
| **控件空间** | **容器中心** | 向上 | `SetAnchoredPosition` / `anchoredPositionX/Y` |

#### 从源图像素到控件位置的完整换算

```lua
-- 常量（构建时算好写进 CFG）
scale      = min(1120 / 411, 630 / 600) = 1.050000   -- 目标展示尺寸 / 源图尺寸
offsetX    = 800 - 411 * scale / 2      = 584.225    -- 这里 800 = 画布宽/2
offsetY    = 450 - 600 * scale / 2      = 135.000
sourceHeight = 600

-- 每帧/每个图元
local function place(c, sx, sy)          -- sx,sy = 源图像素
  c:SetAnchoredPosition(
    CFG.offsetX + sx * CFG.scale - CX,                     -- CX = 实际画布宽/2
    CFG.offsetY + (CFG.sourceHeight - sy) * CFG.scale - CY -- CY = 实际画布高/2
  )
end
```

三个要点：

1. `(sourceHeight - sy)` 就是 **Y 翻转**。
2. **末尾减 `CX, CY`** 是把"画布左下原点"换成"容器中心原点"。**漏掉这一步，整个角色会窜到右上角**——
   本项目实际踩过：修复前 X 范围 620~950、Y 范围 155~740（全跑到半画布外），修复后 -180~150 / -297~293。
3. `CX, CY` 要**运行时取**，不要写死：

```lua
local w, h = CFG.canvasW or 1600, CFG.canvasH or 900
if game.GetUICanvasSize ~= nil then
  local gw, gh = game.GetUICanvasSize()
  if gw ~= nil and gw > 0 and gh ~= nil and gh > 0 then w, h = gw, gh end
end
CX, CY = w * 0.5, h * 0.5
```

⚠️ 未验证：`GetUICanvasSize` 在真机返回的是不是"设计分辨率"。本项目按 1600×900 硬编码做回退，
实机如果不同尺寸，只要它是同一个坐标系就仍然正确。

#### 光标坐标

`game.GetCursorUIPos()` 返回的是**画布左下原点**的坐标。做视点跟随时要：

```lua
local px, py = game.GetCursorUIPos()
local nx = (px - CX) / CX      -- 归一化到 [-1, 1]
local ny = (py - CY) / CY      -- 注意 ny > 0 = 光标在角色**上方**
```

**`ny > 0` 表示"上方"**（因为 Y 向上）。而源图 Y 向下，
所以让虹膜向上看时要 **取负**：`irisDy_offset = -ny * 幅度`。

本项目早期把上下做反过，就是漏了这一步。

---

### 3.4 部件表（构建时生成）

部件把连续的下标区间映射到一组动画参数：

```lua
local PARTS = {
  { n=26, f=1,    t=300,  px=160, py=300, w=1.2,  delay=0.26, rot=3.6,  g=6 },
  --  ↑编号  ↑首个图元 ↑末个图元 ↑旋转轴心        ↑呼吸权重 ↑延迟    ↑旋转  ↑组
  { n=9,  f=6358, t=6654, px=207, py=300, w=1.55, delay=0.04, rot=0,    g=1,
    role="iris", side="eyeL", geo={top=213.6, bot=263.3, lidCy=225.8, cy=238.45} },
}
local GN = {"head","bangs","hairBack","tailL","tailR","ribbon","body","armL","armR","legs"}
```

- `f`/`t` 是 **1-based 闭区间**，`f` 对应 RAW 数组里第一个图元。
- `g` 是组索引，**指向上面的 `GN` 表，1-based**。
  ⚠️ 构建脚本如果生成 0-based 索引，会整体错位一位（本项目踩过：头拿到 nil、腿继承了别人的权重）。
- `role`/`side`/`geo` 只给需要特殊处理的部件（眼、眉、嘴），见 `05`。

---

### 3.5 规则分成两栏

#### 必须满足（不满足就坏）

- 解析 `shapes.json` 时：**`a` 是弧度**、**`r` 是半径**（不是直径）、**数组顺序即绘制顺序**
  （这三条是 GEIMG 输出的既有约定，不是你我能选的）。
- **任何屏幕坐标计算，先确认现在是哪套坐标系**；跨坐标系**必须显式转换**。
- **同一份数据在整个链路里必须保持同一个坐标空间**（中途换空间就要到处改换算）。
- 场景里的容器中心**要运行时取**（`game.GetUICanvasSize()`），不要写死 ——
  写死了换分辨率就错位。
- 部件表的组索引要与代码里的组名表**同样的起始编号**（我们用 1-based；换 0-based 就处处 0-based）。
- 图元数据**内联在 Lua 里**（沙箱禁了 `io.*`）——这一条是被运行环境逼的，没得选。

#### 参考实现（可以不同）

| 我们的做法 | 可以这样 |
|---|---|
| 紧凑行 `t\|x\|y\|w\|h\|rot\|RRGGBBAA` | 任何格式；也可以直接嵌 JSON（更大、更慢，但更好读） |
| 导出时把角度取负、运行时不再翻 | 也可以存原始角度，运行时翻 —— **只要只翻一次** |
| 画布 1600×900、缩放 1.05、偏移 584/135 | 任意展示尺寸；按 3.3 的公式自己算 |
| 部件表用 `f`/`t` 区间 + `g` 组号 | 用数组引用、用名字查表都行 |
| 部件表里放 `role`/`side`/`geo` | 也可以另外放一张"特殊部件表"；`geo` 的字段名随你 |

#### 验收：怎么确认坐标这套没搞错

| 要保证 | 怎么量 |
|---|---|
| 整体不出画布 | 所有控件位置落在 ±半画布内（本项目越界 0 个） |
| 上下方向对 | 把光标移到画布**上方**，头/眼应向上（不是向下） |
| 尺寸对 | 抽一个图元，算它应占的屏幕像素数，和实际 `sizeDelta` 比 |
| 旋转方向对 | 让一个部件转 +10°，看它在屏幕上是不是你预期的方向 |
| 层序对 | 眼睛应该盖在脸上面、头发盖在脸的一部分上面 |

---

### 3.6 常见错误

| 现象 | 原因 |
|---|---|
| 整个角色窜到窗口右上角 | 忘了减半画布（画布空间 vs 控件空间） |
| 角色位置对但上下颠倒 | Y 翻转漏了 / 做了两次 |
| 图元尺寸是预期的一半 | 把半径当直径用了 |
| 椭圆方向不对 | `a` 当成了度数 |
| 层序整体错一位 | 组索引 0-based vs 1-based |

---

## 04 · 在游戏里重建：控件、层序、加载、性能

目标：把图元数据变成游戏里的角色。这一节只讲**怎么把控件建出来并驱动**，动作设计见 `05`。

---

### 4.1 一个图元 = 一个图片控件

> **重要**：这一节讲的是"平铺"结构（现在跑通的版本）。
> 更好的做法是把同一骨骼的图元挂到**父容器**下、只对容器做动画 ——
> 每帧写入能从 866/3286 次降到几十次，见 **`11-层级与骨骼-父容器.md`**。
> 下面这套仍然是基础（容器里装的还是这些控件），先看懂这里再看 11。

```lua
local c = game.InstantiateClientUIControl(CFG.imagePrefabId, root)
c:SetAnchorMin(0.5, 0.5)          -- 锚点收紧到中心，位置才好算
c:SetAnchorMax(0.5, 0.5)
c:SetPivot(0.5, 0.5)
place(c, d.x, d.y)                -- 见 03：源图像素 → 控件空间（含减半画布）
c:SetSizeDelta(d.w * CFG.scale, d.h * CFG.scale)
if d.rd ~= 0 then c:SetLocalRotation(0, 0, d.rd) end
c:SetImage(Enum.ImageSource.StaticReference, CFG.circleAssetId)  -- 固定圆贴图
c.imageType = Enum.ImageType.Stretch
c.imageColor = Color.FromRGBA(d.r, d.g, d.b, d.a)
c:SetVisible(true)
c:SetSiblingIndex(index - 1)      -- 层序：见 4.3
```

要点：

| 项 | 说明 |
|---|---|
| 圆贴图 | `circleAssetId = 100002`（固定可用的那张）。所有图元共用它，靠 `imageColor` 染色 |
| `ImageType.Stretch` | 必须设，否则圆贴图不跟着 `sizeDelta` 拉伸 |
| 透明度 | 基类**没有** `alpha`/`opacity` 字段，只能用 `imageColor` 的第四通道 |
| 旋转 | `SetLocalRotation(0, 0, 度)`，绕 pivot |
| 圆形 | 圆贴图按 `sizeDelta` 拉伸成椭圆，所以 `w ≠ h` 就是椭圆——**不需要不同的贴图** |

#### ⚠️ 边缘硬度取决于这张圆贴图

API 里图片控件有 `enableSoftEdge` / `softEdgeMode` / `softEdgeWidthX/Y` / `horizontalSoftRange` /
`verticalSoftRange`。本项目**没有设置**它们，实机观感取决于该 prefab 的默认值。

如果实机边缘比预期软（源图是硬边，预期是硬边），第一件事就是试 `c.enableSoftEdge = false`。
⚠️ 未验证：默认值是什么、改了会不会影响性能。

---

### 4.2 容器：先确认找得到，再往里塞

> **先把 ID 槽位留好** —— 见 `README` 的「生成的 Lua 必须以这段开头：ID 槽位（漏了就没有画面）」。
> `CFG.containerName` / `imagePrefabId` / `textPrefabId` / `areaPrefabId` / `circleAssetId`
> 这五个值缺一个就建不出东西，而且**失败是静默的**（返回 `nil`，不报错）。
> 本节下面讲容器为什么可能找不到。

```lua
local function ensureRoot()
  if root ~= nil and root.alive then return true end
  -- 优先用有文档保证的按名查找
  if CFG.containerName ~= nil and CFG.containerName ~= "" and game.FindClientUIRoot ~= nil then
    local r = game.FindClientUIRoot(CFG.containerName)
    if r ~= nil then root = r; return true end
  end
  -- 回退：从脚本宿主往上找同名祖先
  local node = script.object
  if node == nil then return false end
  local p, guard = node, 0
  while p ~= nil and p.name ~= CFG.containerName and guard < 32 do
    p = p.parent; guard = guard + 1          -- guard 防 parent 成环
  end
  if p == nil then return false end
  root = p
  return true
end
```

#### 血泪教训：容器可能晚于 `OnStart` 就绪

`InstantiateClientUIControl(prefab, nil)` 是**静默失败**（不报错，返回 nil）。
本项目最初的写法是在 `OnStart` 里直接建 UI：

```lua
-- ✗ 错：root 还是 nil
if UIBuild ~= nil then UIBuild() end
```

结果：UI 控件 0 个、按键监听 0 个（因为监听挂在控件上），而**日志里只说了一句"UI 未建"**。
正确写法：

```lua
-- OnStart：能建就建，不能建就留给 OnUpdate
uiBuilt = false
if ensureRoot() and UIBuild ~= nil then UIBuild(); uiBuilt = true end

-- OnUpdate：容器就绪后补建（只建一次）
if not uiBuilt and UIBuild ~= nil then UIBuild(); uiBuilt = true end
```

同类问题：**找不到容器就不要静默空转**。本项目做到"连续 60 帧找不到就停掉逐帧回调并打日志"，
否则在游戏里表现为"脚本没反应"，而错误只在 `ErrorLog.txt` 里。

---

### 4.3 层序：`SetSiblingIndex` 与"铺完再重排"

基类**没有 `zIndex`**，层序 = 同级索引。

```lua
c:SetSiblingIndex(index - 1)      -- 图元按数据顺序
```

两个坑：

1. **`SetSiblingIndex` 会返回 boolean 且"受父控件子控件数量限制"**——失败就是层序静默错乱。
   必须检查返回值并出声（本项目 `warnOnce`）。
2. 有 UI 层时，等**角色铺完之后**统一重排一次，顺序是「背景 → 角色 → UI」：

```lua
local z = 0
put(UI.bg)                 -- 背景最底
for i = 1, n do pool[i]:SetSiblingIndex(z); z = z + 1 end   -- 角色
put(UI.fg)                 -- UI 压在最上
```

---

### 4.4 加载：分帧铺（一帧建一万个会卡住那一帧）

```lua
if not done then
  local budget = CFG.budgetPerFrame        -- 本项目 40
  while cursor <= total and budget > 0 do
    local c = spawn(shapes[cursor], cursor)
    if c ~= nil then pool[cursor] = c end
    cursor = cursor + 1
    budget = budget - 1
  end
  if cursor > total then done = true; if UIReindex then UIReindex() end end
  return                                    -- 铺完之前不驱动动画
end
```

- 9941 个控件、每帧 40 个 → **约 249 帧铺完**
- 「铺完之前不驱动动画」很重要：否则会看到"部分图元在动"的残影
- 跳跃这类动作要判断 `done`：没铺完不受理（见 `05`）

---

### 4.5 逐帧回调：默认是关的，必须自己开

```lua
-- 官方在线版确认：接口就叫 EnableUpdate；EnableTick 在官方文档里不存在（旧 PDF 时代留下的写法）
local function startTick()
  if script.EnableUpdate ~= nil then script:EnableUpdate(true); return true
  elseif script.EnableTick ~= nil then script:EnableTick(true); return true end
  return false
end
```

**脚本的 update 开关默认关闭**：不显式打开，`OnUpdate` 一帧都不会被调用 ——
图元铺不出来、动画更不会动。本项目第一次上真机就是这个症状（用户反馈"忘记开 EnableUpdate 了"）。

同时保留 `EnableTick` 回退（老运行时 —— 官方文档里没有这个名字），并在 `OnDestroy` 里关掉。

---

### 4.6 性能：每帧写多少次属性（这一环的主要代价）

10030 个图元每帧全写 = **60 万次属性写入/秒**。指南里那句
"循环调用……会导致进关加载变久或卡死，且日志无法正常报告"说的就是这个量级。

#### 四道闸（按收益排序，都是可选手段）

目标只有一个：**每帧写入次数要明显低于"图元数 × 帧率"**。下面四条是我们用的办法，
也可以只用其中一两条、或用别的（比如把静态区域合并成一张贴图）。

| 手段 | 做法 | 实测效果 |
|---|---|---|
| ① **降频** | `updateStride = 2` → 30Hz 更新 | 图元 >4000 时默认打开，写入次数直接减半 |
| ② **视点 epsilon 闸门** | 鼠标没动 → 骨骼场贡献不变 → 相关部件整帧不写 | 空转时 3286 → **866** 次/帧 |
| ③ **逐图元写入缓存** | 与上次写下的位置差 < `posEps`(0.35 源像素) 就不调 API | 亚像素位移不计；腿那种小权重部件整段被冻住 |
| ④ **部件级跳过** | 部件总位移 < `skipBelow`(0.5px) 且无表情需求 → 整块跳过 | 省下小位移部件 |

#### 实测负载（9941 个控件，`updateStride=2`）

| 状态 | 写入/帧 | 写入/秒 |
|---|---|---|
| 鼠标不动（只剩呼吸） | 866 | 52k |
| 鼠标移动（骨骼场 + 呼吸） | 3286 | 197k |
| **不做任何跳过的全量** | 9941 | 596k |

#### 还要说清楚的两件事

1. 这些优化压掉的是**每帧属性写入**。**进关卡时的首次创建成本仍然存在**
   （9941 个控件分帧创建，约 249 帧）。
2. 真机实际开销必须在真机上测。本项目上面的数字是**用桩函数跑出来的**（lupa），
   不含引擎的实际渲染与布局开销。

#### 想同时降静态成本

只能走"**烘一张整身贴图 + 条带位移**"：静止姿态用几个控件（贴图切片）表达，
动起来只挪条带。这条路需要"已导入的贴图资源 + RenderTexture API"，
本项目尚未验证这类资源是否可用。

---

### 4.7 UI 层：背景 / 文字 / 按钮 / 拖动条

目标产物是"剧场版"（`l2d_theater*.lua`）时，除了角色还要搭一层 UI。这一节的代码全部
照实机跑通的那份写；API 细节（字段名、枚举、方法签名）见 `07`。

#### 4.7.1 三个建控件的助手 + 固定六件套

所有 UI 控件（图、文字、命中区）都是 `game.InstantiateClientUIControl(CFG.xxxPrefabId, root)`
建出来的，然后**固定走这六步**：

```lua
local function uiImage(x, y, w, h, c)          -- 背景圆 / 面板底 / 按钮底 / 轨道 / 滑块都用它
  local ctl = game.InstantiateClientUIControl(CFG.imagePrefabId, root)
  if ctl == nil then return nil end
  ctl:SetAnchorMin(0.5, 0.5)      -- ① 锚点收紧到中心，位置才好算
  ctl:SetAnchorMax(0.5, 0.5)
  ctl:SetPivot(0.5, 0.5)          -- ② 轴心也收到中心
  ctl:SetAnchoredPosition(x, y)   -- ③ 位置（容器中心原点，见 03.3）
  ctl:SetSizeDelta(w, h)          -- ④ 尺寸
  ctl.imageType = Enum.ImageType.Stretch
  ctl.imageColor = c
  ctl:SetVisible(true)            -- ⑤ 显式可见（默认不可见）
  if ctl.SetSiblingIndex ~= nil then ctl:SetSiblingIndex(UI.z); UI.z = UI.z + 1 end  -- ⑥ 递增同级索引
  return ctl
end
```

`uiText(x, y, w, h, size, color, align, s)` 同理，只是用 `CFG.textPrefabId` 并写
`ctl.text` / `ctl.fontSize` / `ctl.fontColor`；
`uiArea(x, y, w, h)` 用 `CFG.areaPrefabId`，并且**必须**打开射线检测，否则收不到光标事件：

```lua
if ctl.raycastTarget ~= nil then ctl.raycastTarget = true end   -- 不打开收不到光标事件
```

> 三个 ID 里任何一个为 0 就直接放弃并**打印原因**，别静默什么都不建：
> `[GEIMG] UI 未建：CFG.imagePrefabId 还是 0（图片控件模板）`、
> `[GEIMG] 注意：CFG.textPrefabId 是 0，文字控件建不出来`、
> `[GEIMG] 注意：CFG.areaPrefabId 是 0，按钮点不动、拖动条拖不了`。

#### 4.7.2 光标事件：两个兜底

**① 枚举按名取、多名字兜底**（不同版本枚举名可能不一样，取不到就不注册）：

```lua
local function uiOn(area, ...)                 -- 用法：uiOn(area, "CursorClick", "Click")
  for _, name in ipairs({...}) do
    local et = Enum.CursorEventType and Enum.CursorEventType[name]
    if et ~= nil and area.AddCursorEventListener ~= nil then return et end
  end
  return nil
end
```

**② 回调签名兜底**：回调的参数顺序/数量文档没写死，做成签名无关 —— 遍历参数认出
`CursorEventData`（有 `GetUIPos`）就用它，有两个数字就用数字，都没有就退回
`game.GetCursorUIPos()` 轮询，并**打印实际走的是哪一路**。完整写法见 `08` 的坑 9。

> 前置条件别忘了：容器 `showCursor` 必须为真（见 `07.1`）。

#### 4.7.3 拖动条 = 轨道 + 滑块 + 值文字 + 加高的命中区

```lua
local function uiSlider(spec)
  uiImage(spec.x, spec.y, spec.w, 8, 0x39415AFF)                  -- 轨道
  local knob = uiImage(spec.x, spec.y, 22, 22, 0x5AA9FFFF)        -- 滑块
  local label = uiText(spec.x, spec.y + 26, spec.w, 24, 18, 0xE6E8EFFF,
                       spec.al or "left", spec.label .. "  " .. tostring(spec.val))
  local area = uiArea(spec.x, spec.y, spec.w + 24, 40)            -- 命中区加高，好点
  -- 拖动：绝对映射（见 07.4 ①）—— 只关心水平位置
  --   t = (toAnchor(ux, 0) - (spec.x - spec.w/2)) / spec.w
  --   apply(spec.min + t * (spec.max - spec.min))
end
```

`apply(v)` 里做三件事：夹到 `[min, max]`、把滑块移到 `x - w/2 + t*w`、把 `label.text`
刷成新值**并写回对应的参数** —— 写回用一张 setter 表，别在回调里写 if-else 长串：

```lua
local SLIDER_SETTER = {
  swing=…, yaw=…, pitch=…, swingY=…,        -- 视点参数（05.3）
  motion=…, breath=…, amp=…, speed=…, period=…,   -- 动画幅度与周期（05.1）
  bodyAmp=…, depthK=…, boneOn=…,            -- 骨骼（05.3 身体、11）
}
```

> **这些旋钮是给人现场调手感的**（实机那份有 12 个）。拖动条不是装饰：验收时"进游戏觉得
> 幅度不对"就靠它当场找手感，再把数值写回 `CFG`。

#### 4.7.4 按钮 = 底图 + 文字 + 命中区 + 一个命令串

按钮不用为每个功能写一个回调：命中区监听 `CursorClick`，把动作写成字符串交给一个派发器：

```lua
local area = uiArea(spec.x, spec.y, spec.w, spec.h)
local et = uiOn(area, "CursorClick", "Click")
if et ~= nil then area:AddCursorEventListener(et, function(...)
  local kind, arg = string.match(spec.cmd or "", "^(%a+):(.*)$")
  if     kind == "act"     then PlayAction(arg)
  elseif kind == "preset"  then SetPreset(arg)
  elseif kind == "gaze"    then SetGaze(arg ~= "0")
  elseif kind == "blink"   then SetBlink(arg)
  elseif kind == "animate" then SetAnimate(arg ~= "0")
  elseif kind == "cmd"     then BlinkOnce()
  elseif kind == "tog"     then SetAnimate(not CFG.animate)      -- 开关类
  end
end) end
```

好处：按钮表就是一张数据（`{x,y,w,h,label,cmd="preset:wind"}`），加按钮不用碰逻辑。

#### 4.7.5 层的顺序：背景 → 角色 → UI

UI 控件**必须压在角色之上**，而控件没有 `zIndex`，只能靠同级索引。角色铺完之后统一重排一次：

```lua
local function UIReindex()
  local z = 0
  local function put(list)
    for i = 1, #list do
      local c = list[i]
      if c ~= nil and c.alive and c.SetSiblingIndex ~= nil then c:SetSiblingIndex(z); z = z + 1 end
    end
  end
  put(UI.bg)                      -- 最底：背景
  -- 中间：角色（父骨骼模式下只放一个根，见 11）
  put(UI.fg)                      -- 最上：UI
  print("[GEIMG] 层序重排完成：背景 " .. #UI.bg .. " · 角色 " .. n .. " · UI " .. #UI.fg)
end
```

> 建 UI 控件时**先临时递增** `SetSiblingIndex`（4.7.1 第 ⑥ 步），保证 UI 内部自己的顺序；
> 角色铺完后再整体重排一次，把三层关系定下来。`SetSiblingIndex` 的返回值要检查（见 4.9）。

#### 4.7.6 屏幕功能表 + 快捷键映射

屏幕上那块功能表**从按键表生成**，别手写两遍（改一处就不会不同步）：

```lua
local KEYACTS = {   -- {按键序号, 屏幕键名, 功能说明, 执行}
  {1,  "1", "待机",     function() SetPreset("idle") end},
  {2,  "2", "摆动",     function() SetPreset("swayIdle") end},
  {3,  "3", "风吹",     function() SetPreset("wind") end},
  {4,  "4", "眯眼笑",   function() SetPreset("smile") end},
  {5,  "5", "说话",     function() SetPreset("talk") end},
  {6,  "6", "全停",     function() uiAllOff() end},          -- allOff + SetAnimate(false)
  {7,  "7", "摇头",     function() PlayAction("shake") end},
  {8,  "8", "点头",     function() PlayAction("nodOnce") end},
  {9,  "9", "惊讶",     function() PlayAction("surprise") end},
  {10, "0", "摆臂",     function() PlayAction("wave") end},
  {11, "U", "眨一下",   function() BlinkOnce() end},
  {12, "Z", "视点跟随", function() SetGaze(not CFG.gaze) end},
  {13, "Y", "保持闭眼", function() uiToggleHold() end},       -- SetBlink("hold"/"open")
  {14, "G", "动画开关", function() SetAnimate(not CFG.animate) end},
  {15, "H", "功能表",   function() uiToggleHelp() end},
  {"KeyboardJumpKeyDown", "空格", "跳跃", function() PlayAction("jump") end},
}
```

| 键 | 作用 |
|---|---|
| `1`~`6` | 预设：待机 / 摆动 / 风吹 / 眯眼笑 / 说话 / 全停 |
| `7`~`0` | 一次性动作：摇头 / 点头 / 惊讶 / 摆臂 |
| `U` / `Y` / `Z` / `G` / `H` | 眨一下 / 保持闭眼 / 视点跟随 / 动画开关 / 功能表 |
| 空格 | 跳跃（走 `PlayAction("jump")`） |

按键序号 → 枚举名的对应：`1`~`0` 是 `Enum.KeyboardKeyCode.CraftspersonKey1..10`、
`U/Z/Y/G/H` 是 `Key11..15`；事件用 `KeyboardKeyCode` 还是 `KeyboardKeyEventType`
见 `07` 的按键枚举。**键位与浏览器预览页（`图元动态预览*.html`）完全一致**，
照着预览调好的手感直接能搬到游戏里。

绑定要**多路兜底**（先容器根节点、再全屏命中区），日志写明绑在哪一路（见 `08` 坑 9）。

---

### 4.8 规则分成两栏

#### 必须满足（这几条是环境事实，违反了就坏）

- **每个图元一个控件**，用圆贴图 + `ImageType.Stretch` 拉伸来表达圆/椭圆与旋转。
- 透明度和层序**没有专门字段**：只能走 `imageColor` / `SetSiblingIndex`。
- **`script:EnableUpdate(true)` 必须自己调**（默认关闭，官方在线版确认）。`EnableTick` 回退可留可不留 —— 官方文档里没有这个名字。
- **建控件/建 UI 前确认容器已就绪**；`InstantiateClientUIControl(id, nil)` **静默失败**。
- **`SetSiblingIndex` 的返回值要检查**（失败 = 层序静默错乱）。
- 找不到容器**不要空转**：连续 N 帧失败就停掉回调并打日志。
- **每帧写入量要与图元数量级匹配**（9941 个控件每帧全写 = 596k 次/秒，在我们的机器上
  足以拖慢进关；你的机器可能更宽裕，但量级关系不会变）。

#### 参考实现（可以不同）

| 我们的做法 | 可以这样 |
|---|---|
| `budgetPerFrame = 40`（9941 个 → 约 249 帧铺完） | 按你的目标加载时长定：想 1 秒铺完就调大 |
| `updateStride = 2`（图元 > 4000 时自动开） | 1/2/3 都行；先试 2，卡再往上加 |
| `posEps = 0.35` 源像素 | 0.2~0.5 之间；越小越精确、写入越多 |
| `skipBelow = 0.5` 源像素 | 同上 |
| `gazeEps = 0.004` | 视点抖动容忍度；越大越省 |
| 圆贴图 `100002`、prefab ID `1073741850/51/49` | 你自己的资源 ID 与模板 ID（**换场景必须改**） |
| 容器名 `GEIMG_Canvas` | 任意，和场景里一致即可 |
| 铺完再重排层序「背景→角色→UI」 | 也可以一开始就插到正确位置（但要保证角色整体在 UI 之下） |

#### 验收：怎么确认"接进游戏"这件事做对了

| 要保证 | 怎么量 |
|---|---|
| 能显示 | 铺完后控件数 = 图元数；坐标不越界 |
| 会动 | 静置能看到呼吸；`frames` 在增长 |
| 层序对 | 背景在最后、UI 在最前、角色在中间 |
| 不卡 | 打印每帧写入次数，明显低于"图元数 × 帧率" |
| 不静默失败 | 日志里有：画布尺寸 / 容器中心 / 图元数 / 铺完 / 层序重排 / UI 控件数 / 按键绑定结果 |

---

### 4.9 常见错误

| 现象 | 原因 |
|---|---|
| 角色窜到窗口一角 | 忘了减半画布（`03` 有完整换算） |
| 一帧都不跑 / 什么都没显示 | 没调 `script:EnableUpdate(true)` |
| UI 一个都没建出来 | `root` 还没就绪就 `UIBuild()`；或 prefab ID 是 0 |
| 层序错乱 | `SetSiblingIndex` 失败没检查；或没做"背景→角色→UI"重排 |
| 进关卡死 / 加载很久 | 一次性建上万个控件；或每帧全量写属性 |
| 圆变成方形 | 忘了 `imageType = ImageType.Stretch` |

---

## 05 · 动作与骨骼

这一节是"怎么让它活起来"。核心结论先给：

> **相邻或重叠的部件，在同一位置的位移必须一致。**
> 最省事的满足方式是**连续位移场**：位移是 (x,y) 的连续函数，相邻图元拿到的值只差一点点，
> "部件边界"这个概念在算法里直接消失。
> 按部件给权重则必然在边界撕开——本项目实测腰部裂了 **4.2px**
> （身体转 1.6°、腿只转 0.48°，200px 力臂上就是 4px 的缝）。
>
> 这不是"必须照我们的公式写"，而是**必须满足这个条件**；手段可以换（见 5.6）。

---

### 5.1 呼吸：一切的基础

> 实现方式有两种：**逐图元写**（下面这种，现在跑通的版本）和
> **挂父容器只动容器**（每帧写入降到几十次，见 `11-层级与骨骼-父容器.md`）。
> 公式本身两种都用，只是"施加对象"不同：前者施加到每个图元，后者施加到部件容器。

```lua
local vB = math.sin(TAU * (t - (p.delay or 0)) / CFG.period)
dy  = dy - CFG.baseAmp * CFG.ampScale * p.w * vB   -- 源像素；负号 = 向上
rot = rot + (p.rot or 0) * vB
```

- `period` = 呼吸周期（本项目 3.6 秒）
- `w` / `delay` / `rot` 全部来自 `attachments/l2d_rig.json`（见 `01`）
- **`delay` 是"次级运动"的来源**：发丝比身体慢半拍，读起来就有生命感
- `baseAmp` 本项目压到 **1.2**（原 rig 给 3.6，实机放大 1.05 倍后头肩起伏到 15px，实测期望只有 ~3px）

---

### 5.2 眨眼：几何**从数据推**，不要手填

关键洞察：

> **虹膜和眼白要分成两个部件。** 原因很直接：它们在同一帧里的变换不一样
> （虹膜跟着视点滑动，眼白留在原地）。**变换不同的东西就得分开**，
> 否则只能一起动，读起来是「整个眼球在平移」而不是瞳孔在动。

角色划分（按部件编号，本项目）：

| role | 部件 | 做什么 |
|---|---|---|
| `iris` | 9（左）、11（右） | 随视点滑动 |
| `eye` | 10（左）、12（右） | 眼白，随眨眼**纵向压缩** |
| `lid` | 6、7（左）、8（右） | 睫毛/眼线，下移到闭合线 |
| `brow` | 2（左）、3（右） | 眉毛（可选跟随） |

几何从图元包围盒算，不手填：

```lua
eye.top   = (虹膜 ∪ 眼白) 的 y 最小值
eye.bot   = 同上的 y 最大值
eye.lidCy = (睫毛 ∪ 眼线) 的 y 中心
闭合线 ty = top + closeAt * (bot - top)        -- closeAt = 0.78（≈下眼睑位置）
```

三件事必须同时做，缺一个就看不出"闭上"：

1. **眼内容绕闭合线纵向压缩**：`ny = ty + (ny - ty) * sc`，`sc = 1 - maxClose * v`（maxClose 0.92）
2. **眼睑线下移到同一条闭合线**：两者落在一条线上才读得出闭眼
3. **眼内容随闭合淡出**：否则眼白压扁后留一条淡色带，像"厚嘴唇"

闭合剖面：**前 40% 时间闭合、后 60% 张开**（真人也是闭得快、睁得慢）：

```lua
if u < 0.4 then p = 0.5 - 0.5 * math.cos(math.pi * u / 0.4)
else p = 0.5 + 0.5 * math.cos(math.pi * (u - 0.4) / 0.6) end
```

#### 三个实测踩过的 bug

| bug | 症状 | 根因 |
|---|---|---|
| 眼白不眨眼 | 只有虹膜在动 | 生成器写的 role 是 `eye`，Lua 里判断的是 `sclera` —— 名字对不上 |
| 眨完眼眼睛没恢复 | 一直保持细长 | 只在 `nh ≠ s.h` 时写回尺寸，压缩后又恢复时恰好相等 → 没写 |
| 恢复睁眼后 alpha 不还原 | 眼睛一直是淡的 | 淡出/还原的标志位写进了**逐图元循环**，被第一个图元清掉了。必须按**部件**判定一次 |

#### 左右不同步

`skewMs`（本项目 12ms）给左右眼一点相位差，避免完全同步（同步会显得很假）。
另外有 `doubleChance`（0.16）概率连眨两下。

---

### 5.3 视点跟随：眼球 + 头 + 身体

分三层，**权重完全不同的性质**：

| 层 | 手段 | 说明 |
|---|---|---|
| **眼球** | 虹膜滑动 | 主动作。**受限**，见下 |
| **头** | 柱面形变（内部形变） | 头**不做整体平移**——平移是"滑动"，形变才是"转头" |
| **身体** | 躯干位移场 | 越往上越大，脚钉住 |

#### 眼球：API 没有 stencil 掩膜，只能限幅

`enableMask` 是**矩形区域遮罩**（`reverseMaskArea` 决定是否反转），**不是按图片 alpha 的模板**，
所以裁不出眼型。于是只剩两条路：

- **限幅**（本项目 Lua 采用）：量出"虹膜整块都在合法区内"的最大位移
- 掩膜裁剪（只有浏览器预览能做：Canvas 的 `destination-in` 可以按眼型裁）

限幅值是从原图 alpha 量出来的，**严重不对称**：

```
左眼 {左 5, 右 0, 上 3, 下 0}     右眼 {左 0, 右 0, 上 7, 下 0}   （源像素）
```

因为虹膜本来就在某几侧贴着边界。**代价**：实机里往右看、往下看时瞳孔不会动，
方向感主要由头/身体/发丝读出来。这是我们接受的取舍（硬拉过去会更露馅）；
如果以后找到了能做眼型掩膜的办法，这里可以改回完整跟随。

#### 头部：柱面形变（不是平移）

把头部想象成一根柱子，绕它转：

```lua
w  = s.x - HEAD.hx                    -- 离头部中线的水平距离
z  = sqrt(HEAD.rx² - w²)              -- 该处的"深度"
nx = nx + w * (cos(θ) - 1)            -- ① 压缩项：远端收窄，轮廓边缘几乎不动
       + (z / HEAD.rx) * swing * k     -- ② 摆幅项：正前方摆得最多
```

- **① 压缩项**让轮廓边缘几乎不动 → 不会和脖子/背景脱开
- **② 摆幅项**按深度 `z/R` 衰减 → 层的**前后关系**就出来了（视差）
- `k` 是**层间深度系数**：虹膜 1.30 > 五官 1.14 > 嘴 1.10 > 前发 1.05 > 脸 1.00 >
  后发 0.85 > 发尾 0.80。前景动得多、背景动得少，就是立体感的来源
- 头部圆柱的**中心与半径从数据推**（头部件组的并集 bbox），不手填

**两个必须解耦的参数**："头部半宽"（本项目 159px，含头发）和"前后深度"不是一回事。
用同一个半径会让摆幅直接爆掉——实测会到 35~50px。

#### 身体：躯干位移场（三段斜坡）

```
Δx = gx · bodyAmp · s(y) · (1 + depthK · d(x))
Δy = -gx · bodyAmp · depthK · tiltK · s(y) · d(x)
```

| 段 | y 范围 | s(y) | 含义 |
|---|---|---|---|
| ① | y ≥ yHip（髋线以下） | **0** | 腿脚**自动钉住**，不需要单独给腿权重 |
| ② | yHip → yNeck | 0 → 1 | 胸口转得最多，"身体在转"就读出来了 |
| ③ | yNeck → yTop | 1 → **headKeep**(0.25) | **脖子吸收掉大部分转角** |

第 ③ 段是关键：头自己已经有一整套柱面形变，再叠加满幅整体平移就变成"整颗头在横滑"——
正是用户否掉的那个效果。让脖子吸收掉，头就只保留形变。

本项目实测锚点（自动从数据推）：`yGround=594.5, yHip=380.3, yNeck=318.9, yTop=99.8,
cxTorso=214.5, rxTorso=98`。

参数：`bodyAmp=6`（胸口最大水平位移，源像素）、`depthK=0.25`（伪深度压缩）、`tiltK=0.10`（轻微歪斜）。

**实测振幅画像**（鼠标左右扫 3 秒，代表图元）：

| | 水平 | 竖直 |
|---|---|---|
| 脚 | **0.00px** | 0.00px |
| 躯干 | 0.66px | 2.12px |
| 头 | 17.29px | 3.87px |

对照旧版"按部件权重"：6.96 / 8.59 / 21.6px —— 脚在动、脖子断层。

#### 手臂骨与发丝骨：用"离轴距离"当参数

```
extra = dynRot × armBend / hairWhip × t        t = 该图元离轴心的归一化距离 ∈ [0,1]
```

转角随距离增长 → 读成**肩→肘→手**、**发根→发梢**的分段，而不是整条刚性转。
`armBend=0.55`（末端多转 55%）、`hairWhip=0.85`。
`t` 是几何量，**加载时算一次**（放进每帧循环就是白烧 CPU）。

驱动量用 `dynRot`（**通道+视点**的转动，**不含呼吸**）——呼吸是整体慢起伏，不该当甩动的驱动。

---

### 5.4 跳跃：关键帧轨迹，不是正弦

跳跃的节奏（下蹲→蹬地→腾空→落地缓冲）不是正弦能表达的，所以单独一条关键帧轨迹：

```lua
-- 每行 = {秒, 下蹲系数, 摆臂系数, 发梢滞后系数}；三次平滑插值（smoothstep）
local JUMP_KEYS = {
  {0,     0,    0,     0},
  {0.22,  1,   -0.35,  0.2},     -- 下蹲到最深
  {0.32,  0,    0.8,   0.6},     -- 起跳
  {0.48,  0.25, 1,    -0.65},
  {0.60,  0.45, 0.8,  -1},       -- 最高点附近
  {0.84,  0,    0.3,   0.5},     -- 落地
  {0.96,  0.75,-0.2,   1},       -- 落地缓冲
  {1.12, -0.12, 0.1,  -0.3},
  {1.35,  0,    0,     0},
}
-- 腾空高度不在表里，是一条单独的抛物线（0.32s 起跳、0.84s 落地）
jump.height = 4 * CFG.jump.height * u * (1 - u)
```

每个图元预计算三个权重（几何量，加载时算一次）：

| 权重 | 含义 |
|---|---|
| `jHip` | 髋部以下渐弱 → 脚踝以下 ≈ 0，脚只跟根位移走 |
| `jKnee` | 膝部权重 → 下蹲时把小腿沿 x 向外撑开 |
| `jSide` | 相对中线的横向归一化，决定"往外撑"的方向 |

幅度（本项目，实机调出来的）：`height=64, crouch=24, knee=10, arm=12, hair=3.5`。
锚点：髋 392 → 膝 480 → 踝 560，中线 x=218（**源坐标 Y 向下**）。

#### 三个容易出错的点

1. **跳跃位移要放在"表情之后"施加**：根位移必须跟眼睛/睫毛/眉毛一起走，
   否则眨眼时眼球留在原地、脸飞上去。
2. **恢复帧要把写入阈值压到 0**：跳跃结束那一帧的位移小于 `posEps` 会被写入缓存吃掉，
   角色会**停在半空/半蹲**。
3. **不叠加**：上一次还没落地就不受理新的，否则腾空高度会累积。

绑定按键时注意：跳跃用的是**独立的** `KeyboardJumpKeyDown`（空格），不属于"奇匠按键"那一组。

---

### 5.5 动作系统：连续通道 + 一次性动作

两层叠加：

```lua
通道有效值 = 连续开关(CFG.ch[name]) × 强度 + Σ 正在播的一次性动作包络
```

- **连续通道**：`sway`(摆动) / `turn`(转头) / `nod`(点头) / `wind`(风吹) / `armR`(摆臂)，
  每个是一条正弦，按**组权重**分配
- **一次性动作**：`shake`(摇头) / `nodOnce`(点头) / `surprise`(惊讶) / `wave`(摆臂) / `jump`(跳跃)，
  各有 dur 秒的包络，`pulse(u,a,w)` 做"快起、保持、稍慢落"

#### 一个容易踩的写法

每帧重算通道值时，遍历固定的 `CHANNELS` 清单（而不是 `CFG.ch`）就不会踩这个坑：

```lua
local CHANNELS = { "sway","turn","nod","wind","armR","talk","eyeOpen","browRaise" }
```

**原因**：切预设时如果把 `CFG.ch` 换成空表，遍历等于什么都没做，
`chv` 里的旧值就挂在那儿了 —— 实测"说话 → 全停"之后说话通道还是 1。

#### 摆臂要按部件编号定向

`armR` 在我们的 rig 里只该动右臂（部件 24）：按组给权重会把左臂一起带上。

#### 动作表（实机跑通的那份，`dur` 与包络照抄即可）

`u` = 0~1 的动作进度；`pulse(u, 起, 宽)` 是"快起、保持、稍慢落"（见 5.5 开头）。

```lua
local ACT = {
  jump     = { dur=1.35, ch={} },   -- 专用骨骼轨迹（5.4），不乘连续通道正弦
  shake    = { dur=1.15, ch={ turn  = function(u) return 1.5*math.sin(TAU*2.4*u)*math.sin(math.pi*u) end } },
  nodOnce  = { dur=1.05, ch={ nod   = function(u) return 1.8*math.sin(TAU*2.0*u)*math.sin(math.pi*u) end } },
  surprise = { dur=1.6,  ch={ eyeOpen   = function(u) return  1.5*pulse(u,0.05,0.34) end,
                              browRaise = function(u) return  1.5*pulse(u,0.05,0.34) end,
                              nod       = function(u) return -1.6*pulse(u,0.05,0.34) end } },
  wave     = { dur=1.8,  ch={ armR = function(u) return math.sin(TAU*2.6*u)*math.sin(math.pi*u) end } },
}
```

**这些名字是对外契约**：外部用 `PlayAction("shake")` 调（见 README 的「对外函数」）。
名字可以换，但要和调用方（快捷键、按钮、别的脚本）一起换。

#### 预设表

```lua
local PRESET = {
  idle     = {},
  swayIdle = { sway = 1 },
  talk     = { nod  = 0.7 },      -- 嘴已改静态，这个预设在实机里只做轻微点头
  wind     = { wind = 1, sway = 0.8 },
  smile    = { eyeOpen = -1 },
  allOff   = { blink = 0, gaze = 0 },
}
```

`blink` / `gaze` 是**开关**不是通道：其它键写进 `CFG.ch[name]`，这两个要写进
`CFG.blink.auto` / `CFG.gaze`（`SetPreset` 里分开处理）。

> 预设名同样是契约：`SetPreset("wind")` 这样被外部调用；"全停"是
> `SetPreset("allOff")` **加上** `SetAnimate(false)`（关掉逐帧回调），实机就是这么做的。

---

### 5.6 规则分成两栏

#### 必须满足（不满足就坏）

这些是数学/物理层面的要求，换任何实现方式都绕不开：

- **相邻或重叠的部件，在同一位置的位移必须一致**（或差异小到看不见）。
  否则边界必然开缝 —— 实测裂缝能到 4.2px。
  满足它的手段不止一种：连续位移场（我们用的）、把相邻部件并成一组共用同一个变换、
  或保证接缝处被别的东西盖住。
- **每帧重算的通道必须覆盖全部通道**，不能只遍历"当前配置里出现过的"——
  否则切预设时会留下上一套的残值（实测"说话→全停"之后说话还是 1）。
- **眼/眉/嘴这类特殊部件，生成器与运行时的角色定义必须来自同一处**（同一份表、或同一套命名规则），
  否则名字对不上就会静默失效（实测"眼白不眨眼"就是这个）。
- **眨眼的淡出/还原标志按部件判定**，不能放进逐图元循环（会被第一个图元清掉）。
- **跳跃这类"回到原位"的动画，最后一帧必须精确写回**——
  写入缓存会把恢复帧的小位移吃掉，角色停在半空。

#### 参考实现（可以不同）

| 我们的做法 | 可以这样 |
|---|---|
| 连续位移场 `Δ = F(x,y)`（含三段斜坡） | 骨骼层级 + 蒙皮权重；或把相邻部件合并成一组 |
| 躯干斜坡：髋=0 → 脖=1 → 头顶=headKeep | 任意曲线，只要**脚≈0** 且**越往上越大**（见验收表） |
| 头**不做整体平移**，只做柱面形变 | 也可以给一点整体平移，只要**看起来是"转"不是"滑"** |
| 柱面公式 `w(cosθ-1) + (z/R)·swing·k` | 任何内部形变都行；`k` 的层间深度系数是我们的取值 |
| 手臂/发丝用"离轴距离"当弯曲参数 | 也可以分两段骨骼节点实现 |
| 虹膜**限幅**（Lua 没有眼型掩膜） | 若找到能做 stencil 的方法就用，效果更好 |
| 跳跃用关键帧 + 抛物线 | 正弦叠加也行；只要节奏读起来像跳跃 |
| 呼吸/通道/一次动作这套参数 | 幅度、周期、包络都按你的角色调 |

#### 验收：怎么确认"动作做对了"

| 要保证 | 怎么量 |
|---|---|
| 脚钉住 | 脚部图元水平位移 ≈ 0（本 0.00px） |
| 越往上动越多 | 躯干/头位移单调递增、无台阶（本 0.66 → 17.29px） |
| 无接缝 | 扫一遍位移场，相邻 2px 采样的差 < 0.5px；或肉眼放大看腰/脖子 |
| 头读成"转"不是"滑" | 看轮廓边缘与中心是否**不同步**（整块同速平移就是滑） |
| 眨眼读得出 | 眼内容压缩数 + alpha 变化数 + 能还原，三者都要有（本 681/681/681） |
| 动作互不干扰 | 逐动作量位移峰值，每个都非零、且不改变别的动作的数字 |
| 视点自然 | 眼球/头/身体/发丝四层动得不一样（分层才是立体感） |

---

### 5.7 常见错误

| 现象 | 原因 |
|---|---|
| 腰部/脖子撕开一条缝 | 相邻部件位移函数不同（用了按部件的权重） |
| 整颗头在横滑 | 头吃到了满幅躯干场平移，或头部有整体平移 |
| 脚在地上滑 | 躯干斜坡的 0 点没放在髋线，放在了脚底 |
| 眨眼后眼睛没恢复 | 尺寸只在 `nh ≠ s.h` 时写回；淡出标志写进了逐图元循环 |
| 眼白不眨眼 | role 名字和生成器不一致 |
| 切预设后旧通道还在生效 | 遍历了 `CFG.ch` 而不是固定通道清单 |
| 跳跃落地后停在半空 | 恢复帧没把写入阈值压到 0 |
| 跳跃时眨眼、眼球留在原地 | 跳跃位移施加在表情之前 |

---

## 06 · 边缘与画质

这一节讲"边看起来不对"时怎么办。核心结论：

> **硬边主要取决于贴图边缘，不取决于 alpha 滑杆。**
> **白描边是颜色问题，不是几何问题** —— 所以**不能按颜色（白色）删图元**。

---

### 6.1 硬边：源图是二值的，拟合结果不是

源图层 alpha 严格二值（0/255，见 `01`），而拟合出的图元带抗锯齿与半透明。
把重建结果拉回硬边，杠杆按效果排序：

| 手段 | 效果 |
|---|---|
| **① 贴图边缘（硬边二值贴图）** | 半透明像素 2000 → **690**，**主要杠杆** |
| ② 像素对齐（位置/尺寸取整） | 与源图的半像素错位消失 |
| ③ alpha 丢淡阈值 / 提纯阈值 / 增益 | 只改不透明度分布，**对边缘硬度影响 ±5%** |

**"硬边"的判据是半透明像素数 + 放大镜看，不是 RMSE。**
软边会人为降低 RMSE（半像素错位正好被糊掉），所以"软边 RMSE 更低"是度量假象，不是质量更好。

⚠️ 未验证：游戏里那张圆贴图（`circleAssetId`）本身的硬度。
图片控件有 `enableSoftEdge` 等字段，本项目没有设置——实机若偏软，先试 `enableSoftEdge = false`。

---

### 6.2 白描边：完整因果链

现象：轮廓**外侧**多出一圈 1~3px 的浅色描边，在深色背景上特别明显。

#### 因果链（每一环都有实测数据）

```
① 手扣图层的透明区 RGB 是**纯白 (255,255,255)**          ← 26 个部件实测 100% 如此
        ↓
② 细结构部件为了表达勾线，先用 Lanczos 放大 3 倍           ← 见 02
        ↓
③ PIL 的 resize 对 RGBA 四通道**各自独立**插值，不做预乘 alpha
   → 白色被卷进轮廓最外 1~3px 的半透明像素
        ↓
④ 拟合器照着这些**偏亮**像素取样 → 轮廓最外一圈被拟成浅色
        ↓
⑤ 用户看到"边沿几个像素的白色描边"
```

#### 关键判据：几何外溢只有 0.68%

实测：10030 个图元里，只有 **90 个（0.90%）** 落在轮廓外，外溢的 alpha 质量只占
重建总质量的 **0.68%**。

**所以这不是"图元画到外面去了"，而是"轮廓最外那圈颜色偏亮"。**
——这一步决定了修法：要修颜色，而不是删图元。

#### 反例：为什么不能按"白色"删图元

花朵、衣服金边、瞳孔高光本来就有大片近白像素。按颜色删会直接把它们切掉。
**判据只能用空间（在不在原图内容里），不能用颜色。**

---

### 6.3 我们的修法：三步都在**数据**上做

> 下面这三步是**我们这套**的做法，不是唯一解。要求只有两条：
> ① 判据用空间不用颜色；② 改完内部误差不能变差。具体阈值和步骤随你（见 6.8）。

处理顺序有讲究：**先剔溢出 → 再缩边界 → 最后改色**
（缩边界改了尺寸，颜色取样必须排在它后面，否则取样范围是过时的）。

| 步骤 | 判据 | 用哪个掩膜 | 本项目规模 |
|---|---|---|---|
| ① **剔溢出** | 图元面积落在内容内的比例 < 0.12 → 删 | **本部件自己的** alpha | 90 个 |
| ② **缩回轮廓** | 跨出轮廓 → 绕自身中心缩小到"外面 ≤2%" | **整身并集** alpha | 633 个 |
| ③ **轮廓改色** | 贴着轮廓的图元按原图真值**往暗里**修 | 本部件自己的 alpha | 3841 个 |

#### 为什么 ② 是必须的（也是最反直觉的一步）

**真正画出浅色描边的，是一半在里、一半在外的图元。**
轮廓是硬切的，而圆/椭圆是拼接的，边缘总有图元鼓出去 1~3px。删是删不掉的
（它们在轮廓内有内容），只能**缩**。

#### 为什么 ② 必须用整身并集，不能用本层 alpha

"超出本层、但被上层盖住"是**正常**的（每层都画满整张画布）。
按本层缩会白掉内容：

| 掩膜选择 | 被动到的图元数 | 五官/睫毛 |
|---|---|---|
| 按本层 alpha | 2883 个 | 被误动 |
| **按整身并集** | **633 个** | **一个都不动** |

#### 为什么 ③ 只往暗里修

白边污染**只会让图元比真值更亮**。逐通道只下调、不上调，
这样即使真值和拟合值本来就有偏差，也不会把已经对的地方改坏。

---

### 6.4 实测效果

| 指标 | 修前 | 修后 |
|---|---|---|
| 最外 1px 环「明显偏亮(>25)」像素 | 1568 | **82**（降 95%） |
| 轮廓外溢出质量 | 745 | **333**（降 55%） |
| 内部 RMSE（离轮廓 >3px） | 22.40 | **22.23**（没伤里面） |

验收图：把源图/未修/修复三种并排，**在外缘放大 6 倍**看 —— 白描边只有 1~3px，不放大看不出来。

---

### 6.5 更根本的修法（在上游）

上面三步都是**在拟合输出上打补丁**。根因在第 ③ 步（放大卷边），所以更彻底的做法是：

> **放大部件图前，先把透明区的 RGB 染成邻居的颜色。**

`upscale_edge_aware()`（`attachments/l2d_fit_batch.py`）就是这么做的。
它对拟合是**中性**的：拟合只看 alpha ≥ 阈值的像素，而那些像素的颜色一个都没改，
改的只是透明区里"本来就不该被采样"的 RGB。

**⚠️ 反直觉的实测结论：用"预乘 alpha"反而更糟。**

| 放大方式 | 最外圈（alpha<128）RGB 均值 |
|---|---|
| 直接 Lanczos | (248.6, 244.7, 242.1) |
| 预乘 → 插值 → 反预乘 | **(255.0, 255.0, 254.9)** ← 更白 |
| **先填色 → 插值** | 接近内容色 |

原因：Lanczos 的负瓣过冲会被 `1/alpha` 放大，边缘反而更白。

---

### 6.6 显示层的遮罩：能做，但不该依赖

浏览器预览里可以按原图二值 alpha 把最终合成 `destination-in` 裁一遍，轮廓外溢出质量能到 **0**。

**但 Lua 侧做不到**（没有 stencil 掩膜），所以：

- **不要**用"显示层遮罩"当最终方案 —— 预览里干净、进游戏又脏了
- 遮罩只能当**诊断工具**（判断白描边是不是本来就在原图轮廓内）
- 本项目最终把预览里的遮罩也**去掉了**：数据干净了就不需要它，
  留着反而让预览和实机不一致

---

### 6.7 验收指标怎么读

| 指标 | 含义 | 健康的量级 |
|---|---|---|
| **半透明像素数** | 边缘硬度 | 源图 0；本项目硬边 ≈ 1136 |
| **轮廓覆盖** | 源图不透明处、重建也覆盖的比例 | > 99% |
| **轮廓不符像素** | 两者轮廓不一致的像素 | < 1% |
| **颜色 RMSE** | 整体颜色误差 | 20~30（硬边比软边略高是正常的） |
| **环带带符号亮度** | 边缘偏亮/偏暗的**系统性偏差** | \|值\| < 3 |
| **环带「明显偏亮(>25)」像素数** | **白描边的直接度量** | 越低越好 |

⚠️ 注意：**比较颜色时必须先把预乘 alpha 还原**（`rgb / alpha`）。
本项目在诊断脚本里踩过：`rasterize` 返回的是预乘色，直接比较会把轮廓像素算得偏暗，
把结论带反（"重建偏暗"），浪费了一轮排查。

---

### 6.8 规则分成两栏

#### 必须满足（不满足就会误伤）

- **"要不要删/缩某个图元"的判据只能用空间（在不在内容里），不能只用颜色。**
  花朵、衣服金边、瞳孔高光本来就有大片近白像素 —— 按颜色删一定误伤。
- **缩边界时，判据要用"角色可见轮廓"，不能用"本层自己的 alpha"。**
  因为本层内容会被上层盖住，按本层缩会把被盖住的部分也削掉
  （本项目：按本层缩会动 2883 个图元，按整身并集只动 633 个，且五官一个不动）。
  如果你的分层是"每层只保留自己的内容"，两者等价，那用哪个都行。
- **边缘修正的副作用必须可量化，且内部误差不能变差。**
  本项目每次改完都复测"内部 RMSE"，防止修边界顺手把里面改坏。
- **做像素比较前先把预乘 alpha 还原**（`rgb / alpha`），否则结论会反
  （本项目就因此把"重建偏亮"误判成"偏暗"，白查一轮）。

#### 参考实现（可以不同）

| 我们的做法 | 可以这样 |
|---|---|
| 三步：剔溢出 → 缩边界 → 改色 | 只做其中一两步；或换别的收尾方式 |
| 阈值 0.12（剔）/ 2%（缩）/ 半径 2px（改色） | 按你的素材调；判据是"外溢下降 + 内部不变差" |
| 缩边界时绕图元中心等比缩小 | 也可以只缩长轴、或改用"裁掉越界的那部分"（如果格式支持） |
| 改色只往暗里修 | 取决于污染方向：确认你的污染让它变亮还是变暗，只往那个方向修 |
| 在构建时内存里做、不改 `shapes.json` | 直接改也行，但**留一份原始备份** |
| 放大前先把透明区染成邻居颜色 | 任何能阻止透明区颜色卷进边缘的办法都行 |
| 不用预乘 alpha 做放大 | **这条是实测教训**，不是风格选择：预乘会让边缘更白（见 6.5） |
| 显示层不加遮罩 | 遮罩只能当诊断工具；加了会让预览和实机不一致 |

#### 验收：怎么确认边缘这套做对了

| 要保证 | 怎么量 | 参考量级 |
|---|---|---|
| 白描边消掉了 | 最外环「明显偏亮(>25)」像素 | 本项目 1568 → **82** |
| 外溢少了 | 轮廓外 alpha 质量 | 745 → **333**（几何外溢本来就只占 0.68%） |
| 没伤内部 | 内部 RMSE（离轮廓 >3px） | 22.40 → **22.23**（**必须不变差**） |
| 边缘是硬的 | 半透明像素数 | 远低于软边（本硬边 ≈1136，源图 0） |
| 轮廓对得上 | 轮廓覆盖 / 不符像素 | 覆盖 > 98% / 不符 < 2% |
| 修的地方对 | 放大 6 倍看外缘 | 白边明显变淡，且没有出现新缺口 |

**校验方法**：把「源图 / 未修 / 修复」三张并排、**外缘放大 6 倍**看 ——
白描边只有 1~3px，不放大根本看不出来（`attachments/l2d_edge_probe.py` 就是干这个的）。

---

## 07 · API 速查与验证状态

**写脚本前先看这一页。**

> **这一节和其他章节性质不同**：这里是**环境事实**，不是我们的选择。
> API 就是这个样子，绕不开 —— 所以这一节里的"必须/不能"是真的必须。
> 但请注意**分成三段看**：已确认可用 / 未验证 / 明确不存在。**不要把"未验证"当事实用。**

> **这是「原神 · 千星奇域」客户端脚本的 API**，不是通用 Lua 的 API。
> 运行时只有 `script` / `Enum` / `game` 三个全局，标准库被裁过（`io.*`、`coroutine.*`、
> `string.dump` 不可用，`os.*` 与 `debug.*` 只留了几个），详见 `README` 开头的环境说明。
> 官方文档：<https://act.mihoyo.com/ys/ugc/tutorial/detail/mhtakr07vej4>

最高可信来源：**官方在线版《客户端控件API文档》**（2026-09-23 抓取）—— 未被裁切的官方原文，
字段/方法/**参数名**与「说明」文字都可直接引用。
在线全文已存档在 `团队内部的接口文档`。
其次：`（团队提供的 API 类型定义 stub）`（别人提供的可运行实例的 EmmyLua stub）——
它的价值在**实测数字**（枚举序号、控件 ID 等），这部分官方文档不给。
再次：真机反馈。

> **已作废**：`Lua 客户端 UI 脚本 API.pdf` 及其转录件的**解释文字**。
> 那份 PDF 的光栅表在 x=1480 处被硬切，说明列大量残缺、部分整列丢在画外，
> 且转录时出现过把半句补成完整句的情况。**下面凡是引用过它的地方都已在 2026-09-23 校订。**

---

### 7.1 已确认可用 【实测】

#### 脚本生命周期

```lua
function OnInit()  end
function OnStart() end
function OnUpdate(dt) end
function OnDestroy() end

--- 控制当前脚本的 update 启用状态；false 关闭，true 重新启用
function Script:EnableUpdate(enabled) end
```

- **逐帧回调默认关闭**，必须自己 `script:EnableUpdate(true)`，否则 `OnUpdate` 一帧都不跑。
- ⚠️ **`EnableTick` 这个写法在官方在线文档里根本不存在** —— 官方只有 `EnableUpdate`。
  2026-09-23 用官方全文查过：「Tick」在文档里只出现在 `EnableUpdate` 的说明文字
  「控制当前脚本的 Tick 更新」当中。保留回退无害，但**新代码一律写 `EnableUpdate`**。

#### game 命名空间

```lua
--- 获取 UI 画布尺寸（用于取容器中心；不要写死 1600×900）
game.GetUICanvasSize()                       --> w, h

--- ⚠️ 返回「画布左下角原点」坐标；控件位置用「画布中心原点」，两者差半画布
game.GetCursorUIPos()                        --> x, y

--- 实例化 UI 控件；parent 为 nil 时**静默失败**（返回 nil）
--- ⚠️ 官方参数名是 controlPrefabIndex（控件模板索引），旧转录件写的 uiPrefabId 不是官方名
game.InstantiateClientUIControl(controlPrefabIndex, parent)  --> ClientUIBaseControl

--- 按名查找 UI 根
game.FindClientUIRoot(nodeName)              --> ClientUIBaseControl

game.DestroyClientUIControl(control)
game.PrintClientUITree()
```

#### ClientUIBaseControl（基类）

```lua
-- 可读写、可 Tween
anchoredPositionX/Y      sizeDeltaX/Y      pivotX/Y
localScaleX/Y/Z          localRotationX/Y/Z
alive                    visible / active

c:SetAnchoredPosition(x, y)
c:SetSizeDelta(w, h)
c:SetPivot(0.5, 0.5)          -- 注意字段叫 pivotX/pivotY，方法是 SetPivot
c:SetLocalRotation(0, 0, deg)
c:SetAnchorMin(0.5, 0.5)
c:SetAnchorMax(0.5, 0.5)
c:SetVisible(true)
c:SetSiblingIndex(i)          --> boolean（**会失败**，必须检查）

--- 按键事件：回调返回 boolean，true 表示**消费**该事件
c:AddKeyEventListener(eventType, callback)
c:RemoveKeyEventListener(eventType, callback)
c:RemoveKeyEventListeners(eventType)
c:RemoveAllKeyEventListeners()
```

- **基类没有 `alpha` / `opacity` / `zIndex` 字段**：透明度走图片控件的 `imageColor`，
  层序走 `SetSiblingIndex`。
- **`active` 与 `visible` 不是一回事**（官方原文）：
  `active` 为 `true` 时控件可见**且挂载脚本逻辑运行**；为 `false` 时控件不可见**且脚本逻辑停止运行**，
  **而且默认值就是 `false`**。`visible` 只管可见性，不停脚本。
  所以 `SetActive(false)` 了再去动那个控件上的脚本是无效的 —— 这是本项目「隐藏面板」时的经典坑。
- 基类字段里**没有 `enable`**：控件侧是 `active`，`enabled` 是**脚本**（`Script`）上的字段。
- `Script` 的只读字段是 `alive` / `scriptMappingId` / `object` / `path`；
  **没有 `id`、没有 `prefabId`**（旧转录件写错，2026-09-23 已按官方订正）。

#### ClientUIImageControl

```lua
imageSource        -- 只读
imageId            -- 只读
imageType          -- Enum.ImageType.Basic(0) / Stretch(1)
imageColor         -- ColorValue，可读写、可 Tween
enableMask         -- 是否启用遮罩（**矩形区域**，不是图片 alpha 模板）
reverseMaskArea    -- 是否反转遮罩区域
enableSoftEdge     -- 是否启用边缘羽化
softEdgeMode       -- Enum.ImageMaskSoftEdgeMode.Percentage(0) / Pixel(1)
softEdgeWidthX/Y, horizontalSoftRange, verticalSoftRange
c:SetImage(Enum.ImageSource.StaticReference, circleAssetId)
```

⚠️ 注意：**没有 `maskArea` 这个字段**，只有 `reverseMaskArea`。
⚠️ 参考系说明见 `beyond_api.lua` 头部，字段注释里对掩膜的解释来自文档，不可全信。

#### ClientUITextBoxControl

```lua
text, fontSize, fontColor, bgColor
enableOutline, outlineColor
horizontalAlignment    -- Enum.TextHorizontalAlignment.Left(0)/Middle(1)/Right(2)
verticalAlignment      -- Enum.TextVerticalAlignment.Top(0)/Middle(1)/Bottom(2)
adaptiveFontSize, minimumFontSize
```

⚠️ 未验证：`text` 里的换行符（`\n`）是否被渲染成多行。本项目按"是"来用，实机要确认一次。

#### 枚举

```lua
Enum.ImageSource.StaticReference = 0
Enum.ImageType = { Basic = 0, Stretch = 1 }
Enum.TextHorizontalAlignment = { Left=0, Middle=1, Right=2 }
Enum.TextVerticalAlignment   = { Top=0,  Middle=1, Bottom=2 }
Enum.CursorEventType = {
  CursorDown=0, CursorUp=1, CursorEnter=2, CursorExit=3,
  CursorDrag=4, CursorBeginDrag=5, CursorEndDrag=6, CursorClick=7 }
```

#### 按键枚举

`Enum.KeyboardKeyCode`（**键鼠按键，官方在线文档确认共 59 项**；下表序号为 1-based）：
`CraftspersonKey1..10` = 数字 **1 2 3 4 5 6 7 8 9 0**；
`CraftspersonKey11..22` = **U Z Y G H I O P J K L V**；
`23..28` = F5~F10；`29` = 反引号；`30..35` = **- = [ , . /**；
`36..39` = **↑ ↓ ← →**；`40..43` = 右Ctrl / 右Shift / Backspace / CapsLock。
移动/交互键，**枚举值（0-based）**与默认物理键：
`MoveForwardKey=43`(W) / `MoveBackwardKey=44`(S) / `MoveLeftKey=45`(A) / `MoveRightKey=46`(D) /
`SwitchToWalkOrRunKey=47`(左Ctrl) / `SprintKey=48`(鼠标右键) / `JumpKey=49`(**Space**) /
`DropKey=50`(X) / `OpenShortcutWheelKey=51`(Tab) / `InteractKey=52`(F) / `NormalAttackKey=53`(鼠标左键) /
`CharacterSkill1Key=54`(E) / `CharacterSkill2Key=55`(Q) / `CharacterSkill3Key=56`(R) / `CharacterSkill4Key=57`(T) /
`None=58`。

> 物理键列来自官方在线文档；**数字序号官方不给**，是按官方表格顺序推的 0-based 值，
> 与原有实测值（`JumpKey=49` / `InteractKey=52` / `NormalAttackKey=53`）逐条吻合，可放心用。
> 手柄侧 `Enum.ControllerKeyCode` 共 **25** 项（奇匠 1~14 / `SprintKey`=RB / `JumpKey`=A /
> `InteractKey`=X / `NormalAttackKey`=B / 技能 1~4 = RT、Y、十字键上、十字键右 /
> `MenuConfirmKey`、`MenuBackKey`（由手柄导航配置决定）/ `None`）。

`Enum.KeyEventType`（**事件**，与上面不是同一张表；官方确认共 **164** 项）：
官方表格顺序固定为四段，可据此算编号 ——

| 区段 | 内容 | 0-based 编号 | 项数 |
|---|---|---|---|
| ① | 键鼠**按下**：奇匠按键 1~43，再 15 个具名键 | 0~57 | 58 |
| ② | 键鼠**抬起**：同 ① 的顺序，`Down` 换成 `Up` | 58~115 | 58 |
| ③ | 手柄**按下**：奇匠按键 1~14，再 10 个具名键 | 116~139 | 24 |
| ④ | 手柄**抬起**：同 ③ 的顺序 | 140~163 | 24 |

- 键鼠具名键在段内顺序与 `KeyboardKeyCode` 相同（`MoveForwardKey` → … → `CharacterSkill4Key`），
  **但没有 `None`**；手柄具名键为 `SprintKey` `JumpKey` `InteractKey` `NormalAttackKey`
  `CharacterSkill1Key`…`CharacterSkill4Key` `MenuConfirmKey` `MenuBackKey`。
- 已实测对上的值：`KeyboardCraftspersonKey1Down = 0`、`KeyboardCraftspersonKey43Down = 42`、
  `KeyboardJumpKeyDown = 49`、`KeyboardInteractKeyDown = 52`、`KeyboardCraftspersonKey1Up = 58`、
  `ControllerSprintKeyDown = 130`、`ControllerMenuBackKeyUp = 163`（**末项**）。
- **164 行完整清单（含每项默认物理键）见 `团队内部的接口文档` 的 26.(3)。**

**用法**：

```lua
local et = Enum.KeyEventType["KeyboardCraftspersonKey" .. 3 .. "Down"]   -- 数字键 3
local et2 = Enum.KeyEventType["KeyboardJumpKeyDown"]                     -- 空格
ctl:AddKeyEventListener(et, function(...) PlayAction("nodOnce"); return true end)
```

**三点提醒**：
1. 返回 `true` = **消费该事件**。绑空格时如果这一关的空格本来就是"角色跳跃"，
   可能把这个键吃掉。不确定就先不绑。
2. **回调返回 `boolean`** —— 这条官方在线文档已写明（旧 PDF 里被裁掉了）。
   本项目仍做签名无关 + 多路兜底（见 `08` 的坑 9），不必改。
3. **穿透语义（官方原文）**：「同一个容器中，如果交互按键事件被 lua 回调响应，并标记为已处理，
   容器内的其他按键不会也响应此次按键事件」。所以按键挂在**容器根节点**上做多路兜底是安全的，
   不会把同一次按键重复派发给容器里的每个子控件 —— 但反过来说，**谁先响应谁就吃掉了这次事件**。

#### 层级 / 父容器（降负载的关键）

```lua
--- parent 是**读写**字段
control.parent = otherControl          -- 运行期搬家（是否生效待实机确认）

--- 创建时直接指定父级
game.InstantiateClientUIControl(controlPrefabIndex, parent)   --> ClientUIBaseControl

--- 子控件查询
c:GetChildren()        --> ClientUIBaseControl[]
c:GetChild(name)       --> ClientUIBaseControl
c:FindChild(path)      --> ClientUIBaseControl
```

- 控件类型里有专门的 **`ClientUIContainerControl`（容器节点，"用于组织子控件"）**，
  但它**没有** `children` / `childCount` 字段，只能走基类的 `GetChildren()`。
- 官方规范写明：**「父子层级中的位移、缩放、显隐、Alpha、镜像与裁剪效果由运行时 UI 层级共同决定；
  使用组合布局时应验证实际显示结果」** ⟶ 父控件变换会作用到子控件（"骨骼"的机制）。
  注意它列的是**位移/缩放/显隐/Alpha/镜像/裁剪**，**没提旋转** —— 而摆臂/甩发全靠旋转，必须实机确认。
- ⚠️ 未验证：单个父容器的**子控件数量上限**（规范里"受控件的子控件数"后半句被裁掉了）、
  → 见 `11-层级与骨骼-父容器.md` 与附件 `l2d_hier_probe.lua`。
- ⚠️ 仍未验证：单个父容器的**子控件数量上限**、父 alpha 是否真的传递到子控件（官方只写「由运行时
  UI 层级共同决定」，并让「验证实际显示结果」）。
- **已由官方在线版解答的两条**（2026-09-23）：
  ① **子控件坐标相对父** —— 官方原文「存在父层级时，获取 / 设置与**父层级中心的相对偏移**」，
  无父层级时才是以画布左下为原点。这正是"骨骼"机制成立的基础。
  ② 模板索引字段名是 **`prefabIndex`**（不是 `prefabId`），挂在 `ClientUIBaseControl` 上。
- 另外：**服务器侧必须有「客户端控件容器」**，控件与脚本都依赖它（隐藏/关闭会导致其中控件不显示）。

#### 光标事件的前置条件：`showCursor` ★ 与拖动条 / 点击热区直接相关

**官方原文**（`ClientUIContainerControl` 的 `showCursor` 字段说明）：

> 是否显示常驻光标；**CursorEvent 相关方法都需设置该参数为真后才可正常使用**

- 所以 **容器 `showCursor = false` 时，`AddCursorEventListener` 一系可能根本不触发**。
  这不是"光标看不看得见"的纯视觉开关，而是光标事件链路的**前置开关**。
- 本项目做拖动条（见 7.4）/ 点击热区时，**先确认所在容器 `showCursor` 为真**，
  否则很容易误判成"事件绑定写错了"，白查半天。
- `raycastTarget`（"可被光标射线检测"）在光标检测区域 / 预设按钮 / 网格视窗上也要为真才会被命中。
- `showCursor` / `isolateNavigation` / `disableKeyEventPassthrough` / `disableCursorEventPassthrough`
  都挂在 **`ClientUIContainerControl`（容器节点）** 上，**不在基类上** —— 拿基类引用是取不到的。

> ⚠️ 未验证：`showCursor` 置真后画面上是否会**多出一个常驻光标图标**（字面意思如此）。
> 若项目里不希望出现额外光标，需实机确认视觉影响。

#### 颜色

```lua
Color.FromRGB(r, g, b)
Color.FromRGBA(r, g, b, a)     -- 0~255
Color.ToRGBA(colorValue)       --> r, g, b, a
```

#### 补间动画（Tween）

签名与全部方法已确认，**所有我们要用的控件字段都标了 Tweenable**；
**但 `tweenDataTable` 的格式在所有材料里都缺失** —— 官方在线版同样只写
「传入对象的 tweenable 字段名为键，目标值为值组成的 table」，**没有给示例**，
所以只能实机探测 —— 详见 **`10-补间动画-Tween.md`** 与附件 `l2d_tween_probe.lua`。

`Enum.EaseType` **共 31 项**已确认（`Linear` → `InOutBounce`，官方表格到此为止），
按顺序映射 0~30；本项目常用的 `InOutSine` 在序号 3（0-based）。

```lua
game.Tween(object, tweenDataTable, duration)  --> Tween          -- ⚠️ 表格式未确认
game.TweenSequence()                          --> TweenSequence
t:SetEase(Enum.EaseType.InOutSine)  t:SetRelative(true)  t:SetLoops(-1)  t:Kill(false)
t:SetOnComplete(fn)
q:Append(t)  q:Join(t)  q:Insert(time, t)  q:AppendInterval(sec)  q:AppendCallback(fn)
```

Tweenable 字段（能补间的）：`anchoredPositionX/Y`、`sizeDeltaX/Y`、`localRotationX/Y/Z`、
`localScaleX/Y/Z`、`anchorMin/MaxX/Y`、`pivotX/Y`、`imageColor`、`softEdgeWidthX/Y`、`fillAmount`。

#### 其它

`print(...)` / `printerr(...)` / `typeof(v)` / `math.isnan/isinf` / `debug.traceback`
—— 沙箱**禁了 `io.*`**，读不了外部文件，所以图元数据必须内联在源码里。

---

### 7.2 未验证 / 需要实机确认的

| 项 | 现状 | 怎么确认 |
|---|---|---|
| `enableSoftEdge` 默认值 | 本项目没设置，实机边缘硬度未知 | 实机看边缘；偏软就设 `false` |
| `enableMask` 的精确语义 | 文档说是"是否启用遮罩"，实际是矩形区域 | 需要一个能跑的场景试 |
| 按键会不会被游戏界面占用 | 数字键/字母键可能已被奇匠模式占用 | 绑上后实机按一下 |
| 键事件该挂在哪个控件上 | 本项目挂在容器根节点（多路兜底） | 看日志"快捷键绑在「…」：成功 N/M 个" |
| 文本框 `\n` 换行 | 按"支持"来用 | 实机看文字面板 |
| `GetUICanvasSize` 返回什么 | 按 1600×900 做回退 | 打印一次即可 |
| 光标事件回调签名 | 官方在线版已写明**回调接收 `CursorEventData`**（旧 PDF 被裁掉了）；本项目仍做成签名无关 | 日志里会打印"光标坐标来源：…" |
| 容器 `showCursor` 的真实作用 | 官方写明 CursorEvent 方法**都要它为真**才可用 | 实机：置真后光标事件是否才触发、画面是否多出常驻光标 |
| `tweenDataTable` 的格式 | 官方也只给了文字描述，无示例 | 见 `10-补间动画-Tween.md` |
| 父 alpha 是否传递到子控件 | 官方只写"由运行时 UI 层级共同决定"，并让验证实际结果 | 见 `11-层级与骨骼-父容器.md` |
| 容器子控件数量上限 | 官方未给 | 逐步加子控件试 |
| 贴图资源 / RenderTexture | 没有 | 决定能否走"烘一张贴图 + 条带位移"路线 |
| 控件模板索引取值 | 值是别人实机跑通的（`1073741850/51/49`），**换场景要改**。官方参数名 `controlPrefabIndex`、字段 `prefabIndex` | 编辑器里核对 |

---

### 7.3 明确不存在 / 已改名

| 写法 | 结论 |
|---|---|
| `EnableTick` | **官方文档里不存在**（"Tick"只出现在 `EnableUpdate` 的说明文字中）。用 `EnableUpdate` |
| `Script` 的 `id` / `prefabId` | **不存在**。`Script` 只有 `alive` / `scriptMappingId` / `object` / `path` / `enabled` |
| 基类的 `prefabId` | **不存在**，正确的字段名是 `prefabIndex`（控件模板索引） |
| 基类的 `enable` | **不存在**。控件侧是 `active`；`enabled` 是 **`Script`** 上的字段 |
| `GetScript(scriptPrefabId)` | 参数名是 **`scriptMappingId`** |
| `GetPivot()` 的"轴心"叫法 | 官方原文只有「中心」二字（截图裁切曾让人补出错误说法） |
| `maskArea` | **不存在**，只有 `reverseMaskArea` |
| 基类的 `alpha` / `opacity` | **不存在**，用 `imageColor` |
| 基类的 `zIndex` | **不存在**，用 `SetSiblingIndex` |
| 现成的滑块控件 | **不存在**，要自己用"图片控件 + 光标检测区"拼（见下） |

---

### 7.4 拖动条怎么自己搭（没有现成 slider）

可用拼装件：**图片控件**（外观）+ **光标检测区**（命中与拖动）。

三种做法：

| 做法 | 说明 |
|---|---|
| **① 绝对映射（推荐）** | 拖动事件里取 `CursorEventData:GetUIPos()`，换算到控件空间后**直接映射**成轨道比例。滑块永远跟手，不会累积漂移，滑出轨道也不丢 |
| ② 相对增量 | 用 `GetUIPosDelta()` 累加。写法最短，但会漂（取整 + 丢帧），滑快了跟不上 |
| ③ 轮询 | 按住时每帧 `game.GetCursorUIPos()`。省掉拖动事件，但仍需要"按下/抬起"事件 |

三者都依赖同一个事实：**光标坐标是画布左下原点，控件位置是容器中心原点**，相差半个画布。

**还有一条前置条件别忘**：所在容器的 `showCursor` 必须为 `true`，否则 CursorEvent 一系不工作
（见 7.1「光标事件的前置条件」）。搭之前先把这个开关打开，再排查别的。

```lua
local function toAnchor(ux, uy)      -- 光标坐标 → 控件坐标
  return ux - CX, uy - CY
end
-- 拖动回调里
local ax = toAnchor(ux, 0)
local t  = (ax - (spec.x - spec.w / 2)) / spec.w      -- 轨道上的比例 0~1
apply(lo + t * (hi - lo))
```

**命中区不要铺满全屏**：会跟按钮/拖动条抢光标事件。本项目兜底的"按键接收区"故意做成
角落里的 300×60。

---

## 08 · 踩坑清单

按"**出问题时先查这里**"的用法组织。每条：现象 → 根因 → 修法 → 怎么发现的。

> **现象和根因是客观的**（换了实现方式也可能踩到）；**"修法"是我们当时的解法**，
> 可以换成别的，只要解决同一个根因。有些坑还写了"教训"，那部分比具体解法更值得记。

---

### 坑 1 · 整个角色窜到窗口右上角

- **现象**：图元都建出来了，但全挤在画面右上角，看不出形状。
- **根因**：`game.GetCursorUIPos()` / 画布空间用的是**左下原点**，
  而控件 `SetAnchoredPosition` 用的是**容器中心原点**，两者相差半个画布。
  直接把画布坐标喂给 `anchoredPosition` 就整体偏了 (+W/2, +H/2)。
- **修法**：位置计算末尾减去 `CX, CY`（`CX/CY` 运行时用 `game.GetUICanvasSize()` 取）。
- **量化**：修复前 X∈[620, 950]、Y∈[155, 740]（全在半画布外），
  修复后 X∈[-180, 150]、Y∈[-297, 293]。**用数值验证，比看图可靠。**
- **发现**：用户反馈"全都在窗口是右上角点能看出形状"。

---

### 坑 2 · 脚本一帧都不跑

- **现象**：脚本加载了、没报错，但什么都没发生。
- **根因**：脚本的逐帧回调**默认关闭**，不显式打开 `OnUpdate` 一次都不会被调用。
- **修法**：`OnStart` 里 `script:EnableUpdate(true)`（官方在线文档确认只有这个名字；`EnableTick` 只作老运行时回退）。
- **发现**：用户反馈"问题还是在忘记开 EnableUpdate 了"。**这条只能靠真机发现。**

---

### 坑 3 · UI 一个都建不出来、快捷键一起失效

- **现象**：日志只有一句"UI 未建"；按钮、文字、拖动条、快捷键全都没有。
- **根因**：`OnStart` 里容器还没解析出来（`root == nil`）就调 `UIBuild()`，
  而 `InstantiateClientUIControl(prefab, nil)` 是**静默失败**（返回 nil，不报错）。
  按键监听是挂在控件上的，控件没建出来 → 监听 0 个。
- **修法**：先 `ensureRoot()` 确认容器；失败就留给 `OnUpdate` 每帧重试到就绪。
- **量化**：修复前 UI 控件 **0** 个 / 按键 **0** 个 → 修复后 **92** / **16**。
- **发现**：别人拿去做实机测试时发现。**我原来的测试桩没抓到，因为桩里的
  `InstantiateClientUIControl` 没校验父节点，把 nil 吞了** ——
  桩比真实 API 宽松，就会漏掉这类 bug。

---

### 坑 4 · 腰部撕开一条缝（4.2px）

- **现象**：身体转的时候，腰/脖子处出现错位裂缝。
- **根因**：给**相邻部件不同的变换权重**（身体转 1.6°、腿只转 0.48°，
  200px 力臂上就是 4px 的位移差）。
- **修法**：改用**连续位移场** `Δ = F(x,y)`。相邻图元拿到的位移只差一点点，
  部件边界这个概念在算法里直接消失。
- **发现**：视觉检查 + 数值复核（算法改后相邻 2px 采样的最大跳变 0.0535px，
  旧方案是 0~4.2px 的台阶）。

---

### 坑 5 · 脚在地上滑 / 大腿跟着身体平移 7px

- **现象**：视点跟随时脚会动，或大腿整体平移。
- **根因**：躯干斜坡的"0 点"放在了**脚底**，于是脚底以上全都在动（大腿平移 7px）。
- **修法**：斜坡起点放在**髋线**（腿部件组的 y 上沿）。髋线以下 `s(y)=0`，
  腿脚**自动**钉住，不需要在算法里特判腿。
- **量化**：修前脚水平 6.96px，修后 **0.00px**。

---

### 坑 6 · 整颗头在横滑（像"漂浮木偶"）

- **现象**：鼠标一动，头整体平移，很假。
- **根因**：两处叠加——① 头部有整体平移（`GAZE.dx = 7px`）；
  ② 躯干场在脖子以上仍保持满幅，头又吃了一遍。
- **修法**：① 头部**不做整体平移**（方向感只由柱面形变提供）；
  ② 躯干斜坡加**第三段**：脖子 → 头顶从 1 衰减到 `headKeep`(0.25)，**让脖子吸收掉大部分转角**。
- **量化**：头水平位移 21.55px → 17.29px，且是"形变 + 小幅跟随"而不是纯滑动。

---

### 坑 7 · 眼白不眨眼 / 眨眼后眼睛没恢复

- **现象**：眨眼时只有虹膜在动；或眨完之后眼睛一直是细长的、alpha 也没还原。
- **根因**（三个独立 bug）：
  1. 生成器写的 role 是 `eye`，Lua 里判断的是 `sclera` —— 名字不一致
  2. 尺寸只在 `nh ≠ s.h` 时写回，压缩后又恢复时恰好相等 → 该写的时候没写
  3. 淡出/还原的标志位写进了**逐图元循环**，被第一个图元清掉了
- **修法**：名字逐字对齐；**带 role 的部件每帧都写尺寸**；淡出判定按**部件**做一次。
- **量化**：现在 681 个控件压缩、681 个 alpha 降、681 个 alpha 还原。
- **发现**：真 Lua 运行时（lupa）实跑才发现的 —— 光看代码看不出来。

---

### 坑 8 · 切预设之后旧通道还在生效

- **现象**："说话 → 全停"之后，说话通道的值还是 1。
- **根因**：每帧重算通道值时**遍历了 `CFG.ch`**，而切预设时把 `CFG.ch` 换成了空表 ——
  遍历等于什么都没做，`chv` 里的旧值就挂在那儿。
- **修法**：遍历**固定的 `CHANNELS` 清单**，没写到的通道一律归零。

---

### 坑 9 · 拖动条/按钮在实机不跟手

- **现象**：预览里好好的，进游戏拖不动或跳变。
- **根因**：光标事件回调的签名文档**没写死**，可能传 `(cursorEventData)`、
  `(control, data)`、`(x, y)` 甚至什么都不传。
- **修法**：做成**签名无关**——遍历参数，认出 `CursorEventData`（有 `GetUIPos`）就用它，
  有两个数字就用数字，都没有就退回 `game.GetCursorUIPos()` 轮询。
  并在日志里打印**实际用的是哪条路径**。
- **同类**：按键监听挂在哪个控件上能收到也不确定 → **多路兜底**（先试容器根节点，
  再试角落命中区），日志写明绑在哪一路。

---

### 坑 10 · 找不到容器却静默空转

- **现象**：进游戏"脚本没反应"，什么日志都没有。
- **根因**：找不到容器时每帧空转，而错误只落在 `ErrorLog.txt` 里。
- **修法**：连续 60 帧找不到容器就**停掉逐帧回调**并打印原因，
  绝不做"每帧空转又什么都不显示"的哑巴脚本。

---

### 坑 11 · 层序静默错乱

- **现象**：偶尔有图元被盖住/浮到不该在的层。
- **根因**：`SetSiblingIndex` **会返回 boolean 且"受父控件子控件数量限制"**，
  失败时返回 false，但很多人不检查返回值。
- **修法**：检查返回值为 false 就 `warnOnce` 出声；层序不依赖目录/遍历顺序；
  有 UI 时角色铺完统一按「背景 → 角色 → UI」重排。

---

### 坑 12 · 白描边（最绕的一个）

- **现象**：轮廓外侧一圈 1~3px 的浅色描边，深色背景上特别明显。
- **排查过程（走过一次弯路）**：
  1. 先量几何：外溢只有 0.68%（10030 个里 90 个）→ **否掉"图元画到外面了"**
  2. 再量颜色：环带偏亮，但结论一度是"重建偏暗" —— **因为我拿预乘 alpha 的颜色直接比了**
  3. 反预乘后重测：**1px 环 57.8% 的像素偏亮、均值 +6.45** → 确认是颜色问题
  4. 追根因：原图透明区是纯白 + Lanczos 放大不做预乘 → 白色卷进边缘 → 拟合器照着取样
- **修法**：数据级三步（剔溢出 / 缩回轮廓 / 轮廓改色），**不按颜色删图元**。
  上游再加一步"放大前把透明区染成邻居颜色"。
- **量化**：最外环"明显偏亮(>25)"像素 1568 → **82**；内部 RMSE 22.40 → 22.23（没伤里面）。
- **教训**：
  - **颜色比较前先反预乘**（否则结论会反）
  - **不能按颜色删图元**：花朵、衣服金边、瞳孔高光本来就有大片近白像素
  - 显示层遮罩只能当诊断，**Lua 侧没有 stencil 掩膜**，别依赖它

---

### 坑 13 · 跳跃落地后停在半空

- **现象**：跳跃动画结束，角色停在空中或保持半蹲。
- **根因**：写入缓存（位移小于阈值就不调 API）把**恢复那一帧的小位移吃掉了**。
- **修法**：恢复帧把阈值压到 **0**，强制精确写回原位。
- **同类**：跳跃位移必须施加在**表情之后**，否则眨眼时眼球留在原地、脸飞上去。

---

### 坑 14 · 逐动作排查时"动作在播但什么都没动"

- **现象**：`GetStatus()` 显示有动作在播，但角色没反应。
- **根因**：一个动作可以"在播却什么都不动"（通道被开关挡住、或被新加的骨骼分支提前 return）。
  只检查"在播"是不够的。
- **修法**：写**逐动作位移量测**（每个动作单独跑一遍，量代表图元的位移峰值，与基线比）。
  本项目用它证明"加了跳跃之后其它 13 个动作没被改坏"。

---

### 元教训（比单个坑更值钱）

1. **桩比真实 API 宽松，就会漏掉 bug**（坑 3）。测试桩要尽量"严格"：
   该失败的失败、该校验的校验。
2. **能量化的就别靠眼睛**（坑 1、4、7、12）。位移范围、写入次数、环带亮度——
   数字能定位到具体哪一环错了。
3. **坐标/单位/参考系**是这类项目最大的 bug 来源（坑 1、5、6、7）：
   弧度 vs 度、半径 vs 直径、0-based vs 1-based、左下原点 vs 中心原点。
   **每写一段涉及坐标的代码，先问自己现在是哪套。**
4. **静默失败最贵**（坑 3、10、11）。凡是"返回值可能是 nil/false"的 API 调用，
   都要检查并出声。
5. **只有真机才知道的事**（坑 2、3、9）：忘开逐帧回调、容器就绪时序、回调签名。
   预览再像也不能替代一次真机跑。

---

## 09 · 端到端 SOP 与检查表

把整条链路串成可执行的步骤。命令以本项目为例（Windows + Git Bash）。

> **这一节是"我们跑过一遍的命令 + 检查点"**，不是唯一流程。
> 脚本名、目录名、参数都可以换；**要保住的是每个阶段的"检查点"** ——
> 那些才是保证最终效果的东西。数值一律当**参考量级**看，不要当及格线。
>
> **只用工具本体（不跑我们的 Python 封装）也能做完整条流水线**：
> 拟合与导出都在 `GE_IMG_Tool.exe` 的命令台上完成，等价命令序列是
> `fit recommend --json` → `advanced set …`（含 2.0 的三个开关）→ `fit shapes N` →
> `fit start --until full --ack-high-res`（长跑用 `--timeout 60` + `fit resume` 分段）→
> `inspect`（看图）→ `next` → `export dataset --out <目录>`。
> 细节见工具手册 `docs/GEIMG_AI上手提示词.md`；本节下面的 `attachments/*.py`
> 是我们为了批量跑 26 个部件、以及做边缘处理/构建/验证而写的封装。

**Python 路径**：下面命令里统一用 `$PY` 占位。本机当时没把 python 加进 PATH，
所以用的是解释器的绝对路径；你自己按环境改（`py -3`、`python3` 都行）。
```bash
PY="py -3"          # 按自己的环境改，例如 PY="/usr/bin/python3"
```

目录约定（相对知识库根目录）：
```
parts/                手扣的 26 层 PNG（源）
fit_10k/              超拟合图元数据集（10030 图元）
attachments/          本包附带的脚本
l2d_anim*.lua         交付物：自包含动画
l2d_theater*.lua      交付物：动画 + UI + 快捷键
l2d_preview*.html     调参与验收用的浏览器预览
```

---

### 阶段 0 · 准备（一次性）

```bash
# 1) 确认手扣层符合约定（同尺寸 / 二值 alpha / 编号即层序）
$PY attachments/l2d_check_layers.py parts/
```

**检查点**：所有部件同尺寸、`中间alpha=0`、透明区 RGB 是**纯白**（记住这个颜色，`06` 要用）。

```bash
# 2) 校正呼吸 rig（每个部件 w / delay / rot / pivot / group）
$PY attachments/l2d_rig_breath.py          # 或手工编辑 attachments/l2d_rig.json
```

---

### 阶段 1 · 拟合

```bash
# 单部件试参数（先小预算跑通，看质量拐点）
$PY attachments/l2d_superfit.py --parts "parts" --out "parts/_试跑" --only 0001 --workers 1

# 全量（26 部件并行 6 进程；10k 版耗时约 20 分钟量级）
$PY attachments/l2d_superfit.py --parts "parts" --out "fit_10k" --workers 6
```

**检查点**：
- `_summary.json` 里的 `total_shapes` 与预期一致
- 每个 `part_*/shapes.json` 的 `space` 必须是 `source_image_pixels`
- 抽 2~3 个部件把 `preview.png` 和原图叠一下，确认不错位

⚠️ `_summary.json` 里的 `edge_aware` 与 `manifest.json` 可能不一致（见 `02` 的 2.2）——
常规按"要保边就开"处理（见 `02` 的 2.0）；如果发现勾线断了/边缘画不出来，
再按那节的假设关掉对照跑一次，自己复现确认。

---

### 阶段 2 · 边缘处理（数据级）

```bash
# 出报告：剔了多少溢出、缩了多少边界、改色多少、外溢质量前后对比
$PY attachments/l2d_edge_clean.py --out "edge_report_10k.json"

# 出诊断对照图（源图/未修/修复，外缘放大 6 倍）
$PY attachments/l2d_edge_probe.py --out "edge_diagnosis.png"
```

**检查点**（本项目基线，异常时对比）：
- 剔溢出 ≈ 90 个、缩回轮廓 ≈ 633 个、轮廓改色 ≈ 3800 个
- 最外 1px 环「明显偏亮(>25)」像素 < 200
- 内部 RMSE（离轮廓 >3px）**不应变差**

这两步都**只在内存里做，不改 `shapes.json`**。

---

### 阶段 3 · 生成交付物

```bash
# 超拟合版（10k）：Lua + 剧场版
$PY attachments/l2d_build_anim.py --preset superfit

# 普通版（3518）：同样两条产物
$PY attachments/l2d_build_anim.py --preset normal

# 浏览器预览（两个版本各一份）
$PY attachments/l2d_build_showcase.py --source "../fit_10k" --out "l2d_preview_10k.html"
$PY attachments/l2d_build_showcase.py                                 --out "l2d_preview.html"
```

**构建脚本会自动做的事**：读 rig → 读图元 → 边缘处理 → 推骨骼锚点（脚底/髋线/脖子/头顶/躯干宽度）
→ 推眨眼几何 → 量虹膜安全范围 → 按图元数决定 `updateStride` → 填 CFG → 写出。

**检查点**（构建输出里会打印）：
```
部件 26 个，图元 9941 个（源：_超拟合_10k），默认 updateStride=2
骨骼锚点：脚底 y=594.5 脖子 y=318.9 躯干 x=214.5±98.0
边缘处理：剔溢出 90 个 / 缩回轮廓 633 个 / 轮廓改色 3841 个
虹膜安全范围：{ eyeL = {l=5, r=0, u=3, d=0}, eyeR = {l=0, r=0, u=7, d=0} }
```

---

### 阶段 4 · 自动验证（不进游戏就能查的）

```bash
# ① 运动与负载：14 项（语法/加载/铺图元/坐标/呼吸/眨眼/视点/动作/闭眼还原/负载/静态模式…）
$PY attachments/l2d_verify_anim.py      --lua l2d_anim_10k.lua
$PY attachments/l2d_verify_anim.py      --lua l2d_theater_10k.lua    # 剧场版会多报 UI/按键数量

# ② 逐动作位移量测：证明每个动作真的在动，且互不影响
$PY attachments/l2d_verify_actions.py       --lua l2d_anim_10k.lua

# ③ 剧场 UI 与快捷键：把 prefab ID 填成假值跑 UI 路径
$PY attachments/l2d_verify_theater_keys.py  --lua l2d_theater_10k.lua
```

**检查点**（本项目基线）：

| 项 | 期望 |
|---|---|
| 语法 / 加载 | 全部通过 |
| 铺图元 | 9941 / 9941，约 249 帧 |
| 位置范围 | 不超出半画布（0 个越界） |
| 闭眼 | 681 个控件压缩 + 681 个 alpha 降 + 681 个还原 |
| 骨骼场 | 脚 0.00px < 躯干 < 头，梯度单调 |
| 负载 | 空转 ≈866 次/帧、移动 ≈3286 次/帧（`updateStride=2`） |
| 按键 | 16/16 注册成功、回调全返回 true |
| 跳跃 | 整身位移 56~59px，与历史数字一致 |

⚠️ **这些验证用的是桩函数**，不含引擎真实开销。桩要尽量严格（见 `08` 元教训 1）。

---

### 阶段 5 · 浏览器验收

```bash
# 起个静态服务（本项目用 8743 端口）
$PY -m http.server 8743
# 打开 http://127.0.0.1:8743/l2d_preview_10k.html
```

**人眼检查项**：
- [ ] 切到「原 PNG」「叠影对照」「差异」三个视图，看轮廓是否对齐
- [ ] 放大镜（M）看边缘：硬边 vs 原图二值边，有没有白描边
- [ ] 鼠标在画布上移动：虹膜 / 头 / 身体 / 发丝是否分层运动，脚是否钉住
- [ ] 数字键 1~0：预设与动作是否生效，屏幕左上角是否显示状态
- [ ] H 键：功能表是否完整（含"游戏里空格=跳跃"的说明）
- [ ] 跳跃（游戏版空格）：起跳高度、下蹲、摆臂、落地缓冲
- [ ] 缩放窗口：布局是否错乱、面板是否溢出

---

### 阶段 6 · 真机

1. 把 `l2d_theater_*.lua` 放进编辑器/场景
2. **核对三个 prefab ID**（换场景必须改）：
   `imagePrefabId` / `textPrefabId` / `areaPrefabId`
3. 运行，看日志：
   ```
   [GEIMG] 画布 WxH，容器中心 (…, …)
   [GEIMG] 头部柱面：中心 (…) 半径 (…)
   [GEIMG] 骨骼：躯干场 脚底 y=… 脖子 y=…
   [GEIMG] 图元 9941 个，部件 26 个，动画 开
   [GEIMG] EnableUpdate(true) —— 已打开逐帧回调
   [GEIMG] 快捷键绑在「…」：成功 16 / 16 个
   [GEIMG] UI 建好：背景圆 7 个，共 92 个控件
   [GEIMG] 图元铺完：9941 个
   [GEIMG] 层序重排完成：背景 7 · 角色 9941 · UI …
   ```
4. **真机专属检查项**（预览测不出来）：
   - [ ] 角色位置是否正确（坐标参考系）
   - [ ] 边缘硬度是否和预览一致（否则试 `enableSoftEdge = false`）
   - [ ] 按键是否被游戏界面占用（尤其**空格**）
   - [ ] 拖动条是否跟手（日志会打印光标坐标来源）
   - [ ] 进关卡顿不卡；每帧写入次数（`GetStatus().writesPerFrame`）
   - [ ] 文本框的 `\n` 是否换行

---

### 日志契约（生成的脚本必须打印这些行）

上面阶段 5/6 的验收是**照着日志逐条对的**，所以这一节的日志行属于硬要求：
生成脚本时照抄这些文案（前缀统一 `[GEIMG]`，方便在客户端日志里筛），
别改成自己的说法，否则验收表里一半的项目没法核。

| 时机 | 日志行（`…` 是变量） |
|---|---|
| 画布与容器就绪 | `[GEIMG] 画布 1600x900，容器中心 (800, 450)` |
| 头部柱面参数 | `[GEIMG] 头部柱面：中心 (…, …) 半径 (…, …)` |
| 骨骼就绪 | `[GEIMG] 骨骼：躯干场 脚底 y=… 脖子 y=…（N 个部件完全冻结）` |
| 开始铺 | `[GEIMG] 图元 N 个，部件 M 个，动画 开/关` |
| 逐帧回调打开 | `[GEIMG] EnableUpdate(true) —— 已打开逐帧回调` |
| 首帧耗时偏高 | `[GEIMG] 首帧动画耗时 … ms（N 个控件）—— 偏高就把 CFG.updateStride 调到 2…` |
| UI 建好 | `[GEIMG] UI 建好：背景圆 7 个，共 N 个控件` |
| 按键绑定 | `[GEIMG] 快捷键绑在「容器名」：成功 16 / 16 个（奇匠按键 1~0 与 U/Z/G/H）` |
| 图元铺完 | `[GEIMG] 图元铺完：N 个` |
| 层序重排 | `[GEIMG] 层序重排完成：背景 7 · 角色 N · UI M` |
| 动作/预设被调用 | `[GEIMG] 动作：shake` / `[GEIMG] 预设：wind` |
| 调用到不存在的名字 | `[GEIMG] 没有这个动作：…` / `没有这个预设：…` / `没有这个通道：…（可用：…）` |
| 光标坐标走哪一路 | `[GEIMG] 光标坐标来源：CursorEventData:GetUIPos()` / `…事件回调直接给的两个数` / `…game.GetCursorUIPos() 轮询` |
| 关掉动画 | `[GEIMG] 动画关闭 → EnableUpdate(false)，静态不再逐帧回调` |
| 失败路径（别静默） | `[GEIMG] UI 未建：CFG.imagePrefabId 还是 0（图片控件模板）` / `注意：CFG.textPrefabId 是 0…` / `注意：CFG.areaPrefabId 是 0…` / `快捷键：所有候选控件都注册失败 —— 只能点按钮` / `找不到名为 … 的容器…` |

> 这张表是**照着实机跑通的那份脚本整理的**，上表出现过的行都是它实际会打的。
> 自己再补充可以，但上面这些不要省 —— 尤其"失败路径"那几行：
> 它们把"静默不工作"变成了"日志里直接说原因"，这是这套脚本能在真机上排查的前提（见 `08` 坑 3、坑 10）。

---

### 交付检查表（复制走用）

```
[ ] 手扣层：同尺寸 / 二值 alpha / 编号即层序
[ ] shapes.json：space = source_image_pixels，无错位
[ ] 边缘处理报告：外溢质量下降、内部 RMSE 不变差
[ ] 构建输出：骨骼锚点 / 虹膜安全范围 / updateStride 都有打印
[ ] **脚本顶部留有 ID 槽位**：`containerName` / `imagePrefabId` / `textPrefabId` /
    `areaPrefabId` / `circleAssetId` 五个值都在，且标注了「编辑器侧填」
    （见 README「生成的 Lua 必须以这段开头」）
[ ] **对外函数都在**：`PlayAction` / `SetPreset` / `SetChannel` / `SetGaze` /
    `BlinkOnce` / `SetBlink` / `SetAnimate` / `GetStatus`（见 README「对外函数」）
[ ] **日志行按契约打印**：`[GEIMG]` 那几行（含失败路径）都在（见「日志契约」）
[ ] verify_lua_anim：14 项通过，负载数字在预期区间
[ ] verify_actions：每个动作都有非零位移，互不影响
[ ] verify_theater_keys：16/16 按键注册成功
[ ] 浏览器验收：轮廓/边缘/视点/眨眼/动作/快捷键
[ ] 真机：坐标对、边缘对、按键没被占、拖动条跟手、不卡
[ ] 文档：prefab ID、未验证项、已知取舍都写清楚
```

---

### 换一个新角色要改什么

| 要改的 | 在哪 | 说明 |
|---|---|---|
| 手扣层 | `parts/<新目录>/` | 必须满足 `01` 的四条约定 |
| 呼吸 rig | `attachments/l2d_rig.json` | 部件编号 → w/delay/rot/pivot/group **要重新配** |
| 拟合预算 | `attachments/l2d_superfit.py` 的 `PLAN` | 按新角色的边际收益重定 |
| 骨骼锚点 | **自动**（从数据推） | 脚底/髋线/脖子/头顶/躯干宽度 |
| 跳跃锚点 | `attachments/l2d_build_anim.py` 的 `JUMP_RIG` | **手工调的观感参数**，换角色要重调 |
| 动作幅度 | `CFG.jump` / `BONE` / `GAZE` | 视角色尺寸等比缩放 |
| prefab ID | `build_lua_anim.py` 的 CFG | 换场景要按编辑器实际值改 |
| 容器名 | `CFG.containerName` | 场景里的 UI 容器名 |

**不需要改的**：图元解析、坐标换算、控件创建、层序重排、眨眼几何推导、
虹膜安全范围、负载策略、边缘处理——这些全部从数据推。

---

### 常用命令速查

```bash
PY="py -3"

# 训练/检查
$PY attachments/l2d_edge_clean.py --out 报告.json          # 边缘处理报告
$PY attachments/l2d_edge_probe.py                          # 白描边诊断图
$PY attachments/l2d_verify_anim.py --lua <文件>         # 14 项运动+负载
$PY attachments/l2d_verify_actions.py  --lua <文件>         # 逐动作位移
$PY attachments/l2d_verify_theater_keys.py --lua <文件>     # UI + 快捷键

# 生成
$PY attachments/l2d_build_anim.py --preset superfit    # Lua + 剧场
$PY attachments/l2d_build_showcase.py --source <图元目录> --out <html>

# 预览
$PY -m http.server 8743
```

---

## 10 · 补间动画（Tween）：能省掉什么、不能省什么

**结论先说**：目标软件**有**完整的一套补间 API（DOTween 风格），所有我们要用的控件字段都标了 Tweenable。
它能**砍掉整个空转负载**（呼吸那部分），但**砍不掉视点跟随那部分**。
前提是一个尚未确认的点：`tweenDataTable` 的格式——这是唯一的卡点，用附带的探测脚本一次问清。

---

### 10.1 API 有什么（已确认）

```lua
--- 为对象的 Tweenable 字段创建补间动画
game.Tween(object, tweenDataTable, duration)   --> Tween
game.TweenSequence()                           --> TweenSequence
```

**Tween 方法**：`SetEase(EaseType)`、`SetRelative(bool)`、`Play/Pause/Resume/Restart/Complete()`、
`Kill(complete)`、`SetOnComplete(fn)`、`SetOnStepComplete(fn)`、`SetLoops(times)`
（文档写"**负数表示无限循环**"）。

**TweenSequence 方法**：`Append(tween)`、`Join(tween)`、`Insert(time, tween)`、
`AppendInterval(sec)`、`AppendCallback(fn)`、`InsertCallback(time, fn)`、
`Play/Pause/Resume/Restart/Complete/Kill/SetOnComplete/SetOnStepComplete/SetLoops`。

**EaseType** 有 31 种（`Linear`、`InSine/OutSine/InOutSine`、`InQuad`…`InBounce`）。

#### 哪些字段能补间（这是关键）

| 控件 | 字段 | 我们拿它做什么 |
|---|---|---|
| `ClientUIBaseControl` | `anchoredPositionX/Y` | 呼吸位移、骨骼位移 |
| | `sizeDeltaX/Y` | 眨眼压缩、变粗细 |
| | `localRotationX/Y/Z` | 呼吸旋转、摆臂、甩发 |
| | `localScaleX/Y/Z` | （备选实现手段） |
| `ClientUIImageControl` | `imageColor` | 眨眼淡出、整体透明度 |
| | `softEdgeWidthX/Y`、`fillAmount` 等 | （用不到） |

**也就是说：我们逐帧写的每一个字段，都在 Tweenable 名单里。**

---

### 10.2 唯一卡点：`tweenDataTable` 的格式

签名是确认的（PDF 与转录件一致），但**这张"创建"表的内容拿不到**：

| 材料 | 情况 |
|---|---|
| API PDF | 文字层里"创建"只有**标题**（表格是位图）；而 Tween 那一页在 `api_pages` 抽取时**恰好缺失**（p11 不在） |
| 现有转录件 `Lua_API_关键接口速查.md` | 只有签名，没有表结构 |
| 使用指南 docx | **完全没提** Tween（正文约 145 段，含 Tween/补间 0 处） |
| 工具自带文档 | 只有字段级的 `Tweenable` 标记，没有用法示例 |
| 工作区内所有 .lua | 没有任何调用 `game.Tween` 的样例 |

所以只能实机问 —— 用 **`attachments/l2d_tween_probe.lua`**（附带的探测脚本）：
它按 6 个阶段依次问清 A 格式 / B 循环 / C 序列往返 / D 控件数组 / E Kill 语义 / F **谁在驱动**，
每段打一行结论，最后给汇总。把日志发回来就能确定实现方式。

**最可能的候选**（脚本会逐个试）：

| 候选 | 说明 |
|---|---|
| ① `{x=…, y=…}` | 用简写字段名 |
| ② `{anchoredPositionX=…, anchoredPositionY=…}` | **最可能**：直接照 Tweenable 字段名 |
| ③ `{anchoredPosition={x, y}}` | 用复合字段 |
| ④ `{ {field="anchoredPositionX", to=…} }` | 数组 + field/to |
| ⑤ `{anchoredPositionX={to=…}}` | 字段名 → 目标对象 |

---

### 10.3 能省掉什么：负载账

先看现在的负载（9941 个控件，`updateStride=2` = 30Hz）：

| 状态 | 写入/帧 | 写入/秒 | 由什么构成 |
|---|---|---|---|
| **鼠标不动**（游戏里绝大多数时间） | 866 | **52k** | 几乎全是**呼吸** |
| 鼠标移动 | 3286 | 197k | 呼吸 + 骨骼场 + 头部形变 |
| 不做任何跳过 | 9941 | 596k | 全量 |

#### 补间能砍掉的

**呼吸**是纯周期运动，跟交互无关 —— 正好是补间最擅长的：

```lua
-- 每个部件一个"出去→回来"的两段序列，无限循环
local q = game.TweenSequence()
q:Append(game.Tween(part0, {anchoredPositionY = y + amp}, T/2):SetEase(Enum.EaseType.InOutSine))
q:Append(game.Tween(part0, {anchoredPositionY = y      }, T/2):SetEase(Enum.EaseType.InOutSine))
q:SetLoops(-1):Play()
```

- 26 个部件 → **26 个序列 / 52 个补间**，**创建一次，之后引擎自己跑**
- 由此空转写入从 **866 次/帧（52k/秒）→ 0**
- 顺带省掉脚本侧的呼吸运算（每帧 9941 个图元 × 约 20 次浮点）

> ⚠️ 注意 API 里**没有 yoyo 参数**（`SetLoops(times)` 只有一个参数）。
> 要"出去再回来"就得用**两段序列**（上面那样）。探测脚本的 B 段会确认
> `SetLoops(-1, LoopType)` 这种第二参数到底收不收。

#### 补间砍不掉的：视点跟随

视点跟随的三个分量（虹膜滑动 / 头部柱面形变 / 躯干位移场）都是**逐图元**的，
目标值随光标位置变化。用补间要付的代价是：**每次光标变化都要新建 N 个补间**（N ≈ 9941）。

- 光标每帧都在动的话：9941 × 30 = 30 万次补间创建/秒，还带对象分配 ——
  **不会比现在的 19.7 万次属性写入便宜**，很可能更贵。
- 光标不动的时候：现在是 **0 写入**（已有 epsilon 闸门），补间也没有额外收益。

**所以视点跟随保持现在的逐帧写法**（`gazeEps` 闸门 + `posEps` 写入缓存 + stride 降频）。

#### 净效果

| | 现在 | 补间化呼吸之后 |
|---|---|---|
| 空转（鼠标不动） | 52k 写入/秒 | **≈0**（只有眨眼那几十帧） |
| 交互（鼠标移动） | 197k 写入/秒 | 197k 写入/秒（不变） |

**为什么这仍是大改善**：游戏里角色绝大多数时间处于"鼠标不动"的空转状态，
而进关卡顿/耗电也正是被这种**持续**负载拖出来的。把持续负载打到 0，
只在玩家真的在动鼠标时才花销，是这轮优化的真正价值。

#### 额外红利（待 D 段确认）

如果 `game.Tween` 的 `object` 接受**一组控件**，那连"26 个部件"都能并成 1 个补间。
探测脚本的 D 段会问清楚。

---

### 10.4 眨眼：可选，收益小

眨眼的形状是"快速压缩 → 保持 → 慢速张开"，用序列能表达：

```
Append(压缩 0.06s, InQuad) → Append(张开 0.09s, OutQuad) → [随机间隔] → 循环
```

- 眼内容 335 个控件 × 2 个字段 → 用**一个** tween 同时补位置和尺寸（如果格式支持多字段）
- 但**随机间隔**没法纯靠序列表达：要么固定节奏、要么预先烘一段"含 N 次随机眨眼"的长序列
  再循环（每轮略重复，间隔若烘成 30~60 秒基本看不出来）、要么保留逐帧回调、用完成回调续排
- **建议**：先不动。

理由：眨眼只在眨眼那几帧写入（约占 1.5% 时间），**平均成本很低**；
而它依赖随机数与状态机，改成补间反而更绕。等呼吸改完、空转确实打到 0 之后再评估。

---

### 10.5 如果探测结果是"脚本泵驱动"（❌）

那意味着补间只是**引擎提供的便利写法**，推进仍依赖脚本的逐帧回调 —— 收益就只剩
"省掉自己写插值代码"，**省不掉调用**。这种情况下：

- 空转负载不会变成 0，最多是每帧写 26 个部件的补间目标（比现在写近万个图元省得多，
  但比 0 差）
- 这时更值得走的是另一条路：**把静止姿态烘成一张整身贴图 + 条带位移**
  （见 `04-在游戏里重建.md` 的"想同时降静态成本"一节），但要先确认贴图资源与
  RenderTexture 类能力是否存在

所以 F 段的答案决定了后续路线，**这是最该先问的一件事**。

---

### 10.6 落地顺序（等探测结果回来再做）

1. **先探测**：跑 `l2d_tween_probe.lua`，拿到日志
2. 若 A 段命中 + F 段是"引擎驱动"：
   - 加一个 `ktween(obj, data, dur)` **包装器**：按 A 段结论拼 data、并缓存命中格式；
     格式不认时**自动回退**到现有的逐帧写法（和按键/光标事件一样做多兼容）
   - 呼吸改走补间（`CFG.breathViaTween = "auto"`）；开启后 `partMotion` 里不再叠加呼吸项
   - 验收：空转 `writes/frame` 应降到个位数；呼吸幅度与原来一致（逐帧对照 `GetStatus`）
3. 若 A 命中但 F 是"脚本泵"：改成"每帧只写 26 个部件的补间目标"，
   并重新量负载，再决定是否继续
4. 若 A 全不命中：把候选格式再扩几种（形如 `{property=…, value=…}`、
   `{"anchoredPositionX", value}` 位置参数等），或去找**未裁切的官方文档**

---

### 10.7 规则 / 不变量

- 我们把补间用在**"与交互无关"的运动**上（呼吸、待机摆动、风吹这类周期动作）；
  交互驱动的动作也可以改补间，代价见 10.3。
- **与交互相关的逐图元形变（视点跟随）** 我们保持逐帧写法 —— 补间化会更贵（10.3 有账）。
- 需要"出去再回来"时用**两段序列**（API 里没有 yoyo 参数，除非 B 段证明收第二参数）。
- 销毁控件前**要 Kill 自己的补间**（探测脚本 E 段会确认 Kill 是否真的能停住）。
- 格式不确定时**不要硬编码**：用包装器 + 回退，先跑探测再落地。
- ⚠️ 未验证：`tweenDataTable` 格式、是否引擎驱动、`imageColor` 补间的实际表现、
  以及补间在 `PauseLevelTime(true)` 下会不会跟着暂停。

---

## 11 · 层级与骨骼：用「父容器」代替逐图元写入

**这是目前我们量到降负载幅度最大的一条路（比补间更彻底）。**

一句话：**同一骨骼的图元挂在一个父容器下，只对父容器做动画** ——
那么每帧要写的就不是近万个图元，而是几十个容器。

---

### 11.1 为什么成立（API 依据）

| 依据 | 出处 |
|---|---|
| `ClientUIBaseControl.parent` 是**读写**字段 | 基类字段表 |
| `game.InstantiateClientUIControl(controlPrefabIndex, parent)` **创建时就能指定父级** | game 函数表 |
| API 里有专门的 **`ClientUIContainerControl`（容器节点，"用于组织子控件"）** | 控件类型表 |
| 官方规范原文：**「父子层级中的位移、缩放、显隐、Alpha、镜像与裁剪效果由运行时 UI 层级共同决定」** | PDF 文字层（未裁切的正文） |
| 子控件查询：`GetChildren()` / `GetChild(name)` / `FindChild(path)` | 基类方法表 |

也就是说：父控件的变换会**作用到子控件**，这正是"骨骼"的机制。我们不需要引擎给我们一套骨骼系统，
**用控件层级就能搭出来**。

---

### 11.2 架构：容器即骨骼

```
root（GEIMG_Canvas 容器）
 ├─ 部件容器 × 26           ← 每帧主要写这些
 │   ├─ 图元控件（该部件的全部图元，一次性创建、之后不再动）
 │   └─ 子骨骼容器（可选，用来做弯曲/甩动）
 │       └─ 图元控件
 └─ UI 层（背景/按钮/文字）
```

**映射关系**（把现有的动作系统平移过来）：

| 现有做法 | 层级化之后 |
|---|---|
| 每个图元的 `anchoredPosition` 逐帧写 | **图元不再写**；写它所属的容器 |
| 呼吸 = 每个部件算 dy/rot 再逐图元施加 | 部件容器直接 `anchoredPositionY` / `localRotationZ` |
| 摆臂 = 手臂部件的图元绕肩旋转 | 手臂容器**放在肩点**上，转容器即可 |
| 甩发 = 按"离轴距离"逐图元加转角 | 头发拆成 **发根 / 发中 / 发梢 三个子容器**，各自转一点 → 天然的鞭状 |
| 眨眼 = 335 个眼图元的 `sizeDelta` + alpha | **眼容器** `localScaleY` 压一下（1 次写入）+ 眼睑容器下移（1 次） |
| 跳跃 = 逐图元算 jHip/jKnee 权重 | 躯干/大腿/小腿各一个容器转一点（≈6 次写入）；根容器一条位移 |
| 视点：虹膜滑动 | 虹膜容器 1 次位移 |
| 视点：头/躯干形变 | 见 11.4（这一项**保留逐图元**，但只在鼠标真的在动时才算） |

**一次动作的开销从"图元数"变成"骨骼数"**：26 个部件 + 约 30 个子骨骼 ≈ **60 个容器**。

---

### 11.3 负载账（用真实图元分布算）

本项目 10030 个图元的分布：

| 组 | 图元数 | 占比 |
|---|---|---|
| bangs（前发） | 2740 | 27% |
| head（脸+五官） | 2020 | 20% |
| body（衣服/围巾/后布/裤） | 1750 | 17% |
| legs（腿） | 1480 | 14% |
| armL / armR | 890 | 9% |
| tailL / tailR / ribbon / hairBack | 1150 | 12% |
| **头部件组合计** | **5610** | **55%** |

对照现在的实测负载（9941 个控件，`updateStride=2` = 30Hz）：

| 状态 | 现在 | 层级化之后（预估） | 降幅 |
|---|---|---|---|
| 空转（鼠标不动） | 866 写入/帧（52k/秒） | **26~52 写入/帧** | **≈95%** |
| 鼠标移动 | 3286 写入/帧（197k/秒） | 120~240 写入/帧 | **≈93%** |
| 首次创建成本 | 9941 个控件 | **不变**（还是 9941 个控件，只是多了 60 个父容器） | — |

**注意最后一行**：层级化降的是**每帧写入**，不是**控件数量**。
9941 个图元控件照样要建、要占布局开销。想同时降静态成本仍然要看
"烘一张整身贴图 + 条带位移"那条路（见 `04`）。

---

### 11.4 会失去什么：逐图元形变，以及怎么补

层级化的代价很明确：**父容器内的图元只能一起做刚性变换**，做不了"同一部件内每个图元不一样的位移"。
我们目前有三处依赖这个：

| 逐图元形变 | 为什么需要 | 层级化之后怎么办 |
|---|---|---|
| **头部柱面绕**：`Δx = w(cosθ−1) + (z/R)·swing·k` | 让"转头"读起来是转、且轮廓边缘不滑动 | **保留逐图元**，但只作用于**脸+五官那 2020 个**，且只在鼠标真的在动时算（`gazeEps` 闸门已经做到：不动时 0 写入） |
| **躯干位移场**：`Δx = gx·bodyAmp·s(y)·(1+depthK·d(x))` | 髋线以下钉住、越往上越大、无接缝 | 用 **3~4 个子容器**（髋 / 腰 / 胸 / 颈）各转一点近似，误差比"按部件给权重"小得多（因为容器是**嵌套**的，位移天然连续） |
| **手臂弯 / 发丝甩 / 跳跃权重** | 分段感、跟随过冲 | **子骨骼容器**：发根→发中→发梢、上臂→前臂；跳跃用髋/大腿/小腿 |

**关键认识**：嵌套容器给出的是**层级链式变换**，它在数学上天然连续 ——
所以之前那条"相邻部件位移必须一致，否则撕开"的硬约束**自动满足**，
比我们的位移场更好（不会有条带量化、也不需要在算法里消缝）。

#### 剩下的"真正交互"部分

视点跟随里，**头的柱面形变**是唯一必须逐图元的部分。改进思路：
1. 用**头容器**承载整体转向（1~2 次写入）
2. 柱面形变只在鼠标移动时叠加（现有闸门已保证静止时为 0）
3. 若还是嫌贵：把柱面形变降级为"只对**脸部**（不含五官）做"，或只对头部做**两段子骨骼**近似

---

### 11.5 坐标要改：子控件相对父容器

这是迁移时**最容易踩**的一处：控件 `SetAnchoredPosition` 是**相对父控件**的。

现在所有图元都是 root 的子控件，位置 = 源图像素 → 画布空间 → 减半画布。
层级化之后：

```
容器放在部件轴心（pivot）：place(container, pivotX, pivotY)
图元的 anchoredPosition = 它在容器坐标系里的位置
                       = 画布空间位置 - 容器位置
```

我们现有的 `place()` 只要改成"相对容器"，并且**容器自己用部件轴心摆放** ——
旋转也就自然绕轴心了（不需要再自己算绕轴心的位移）。

**副作用**：容器的 pivot/anchors 要设成 (0.5, 0.5)，子控件的锚点也设 (0.5, 0.5)，
这样 `anchoredPosition` 的语义就是"相对容器中心的偏移"，和现在的算法最接近。

---

### 11.6 还没确认的点（附件里有探测脚本）

文档里**没有**（或只落在被裁切的表里）的，必须实机问：

| 未知项 | 为什么要紧 | 探测脚本对应段 |
|---|---|---|
| 一个父容器**能挂多少子控件** | 规范里"受控件的子控件数"后半句被裁掉了。前发有 **1700** 个图元，若上限比它小，就必须再分层 | **C 段**（滴灌式加到 3000，报出上限） |
| 子控件坐标是**相对父**还是绝对 | 决定 11.5 的换算怎么写 | **B 段**（视觉问答） |
| 父容器的**旋转**会不会传给子控件 | 规范只列了位移/缩放/显隐/Alpha/镜像/裁剪，**没提旋转**；而"摆臂/甩发"全靠旋转 | **D 段**（视觉问答） |
| 父 `SetVisible(false)` 是否藏掉子控件 | 决定"整块隐藏"能不能 1 次写入 | **E 段** |
| 父控件的 `imageColor` alpha 是否乘到子控件 | 决定眨眼淡出能不能 1 次写入（否则还要逐图元写 alpha） | **F 段** |
| 运行期改 `child.parent` 能否搬家 | 能的话可以先铺平再重组，迁移风险大降 | **G 段** |
| 容器模板的模板索引 | `InstantiateClientUIControl` 的第一个参数 `controlPrefabIndex`；需要编辑器里"容器节点"模板的索引 | **A 段**（没填就用图片模板兜底） |

探测脚本：**`attachments/l2d_hier_probe.lua`**（本项目内是 `attachments/l2d_hier_probe.lua`）。
A/C 会直接打印结论，B/D/E/F/G 是视觉问答，脚本会打印一份清单让你逐条回答。

---

### 11.7 迁移方案（探测通过后）

分三步走，**每步都能单独验收**：

1. **只加一层容器，不改变换逻辑**
   构建脚本把每个部件的图元挂到该部件的容器下（容器放在轴心，图元坐标减去轴心）。
   动作逻辑先把"逐图元写入"换成"写容器"，但**保留**逐图元路径做对照。
   验收：画面与之前**逐像素一致**（除了柱面形变/躯干场这类内部形变先按容器近似）。
2. **补子骨骼**
   头发→发根/发中/发梢，手臂→上臂/前臂，腿→大腿/小腿，躯干→髋/腰/胸。
   把"按离轴距离加转角"换成"逐级容器给不同转角"。
   验收：甩发/摆臂的观感与 `05` 里的参数曲线对齐；无接缝（层级天然连续）。
3. **把逐图元路径收缩到只剩"头部柱面形变"**
   并给它加闸门：鼠标不动 → 一次都不算。
   验收：空转 `writes/frame` 降到 **< 100**；移动时的峰值明显低于现在。

**回退**：第 1 步就保留 `CFG.hierarchy = "flat" | "container"` 开关，
出问题就切回平铺（现在的实现），不会把已经跑通的版本弄坏。

---

### 11.8 规则 / 不变量

- **同一骨骼的图元要挂在同一个父容器下**：混着挂（一部分挂容器、一部分挂 root）
  会出现两套坐标系，容易错。
- **容器放在部件的旋转轴心上**，图元坐标改成"相对容器"，旋转交给容器。
- **相邻容器别给不同的"位置权重"** —— 用**嵌套**（父→子）表达层级，变换天然连续；
  同级容器之间只允许"整体位移一致"的差异（否则就是 `05` 里那道缝）。
- 容器也要参与**层序**：容器之间的先后由容器在 root 下的同级索引决定，
  容器内部的顺序由子控件在容器内的索引决定 —— 两者都要显式设置。
- 我们把逐图元路径收缩到**只剩头部柱面形变**，并且只在"鼠标真的在动"时才走
  （要保留别的逐图元效果也可以，代价就是那些图元每帧都要写）。
- 迁移时留一个开关（`CFG.hierarchy = "flat" | "container"`），出问题能切回平铺。
- ⚠️ 未验证：子控件数量上限、旋转是否传递、父 alpha 是否传递、容器模板 ID、
  以及容器是否会影响 `SetSiblingIndex` 的语义。