# Astra Yao 桌面宠物图集交付要求

当前修复方式和复查结果见 [atlas-review.md](atlas-review.md)。本文件是后续修图、换图时的契约，
不再使用旧版“只改 6 格即可”或“头部密度就是头身比”的判断。

## 交付规格

- `spritesheet.webp`：1536 × 2288 px，8 列 × 11 行，单格 192 × 208 px。
- 透明 RGBA，静态 lossless WebP，文件 ≤ 20 MiB。审计也可读取带透明度的 PNG，正式包仍交 WebP。
- 不加背景、投影、边框、文字或网格线；不裁切人物、头发、麦克风杖，不让内容越格。
- 格子索引从 0 开始。第 `(行 r, 列 c)` 格的像素范围为
  `x = 192*c … 192*(c+1)-1`、`y = 208*r … 208*(r+1)-1`。
- 脚掌接地参照第 0 行。脚底最后一排像素约在格内 `y=202`，
  对应 Pillow **右开区间包围盒 bottom=203**；不要混淆这两种记法。

## 统一角色与动作

1. 第 0 行是角色母版：同一套脸型、头宽、躯干长度、白裙、红黑外套、青绿长发和金色麦克风杖。
   不能每行重新设计一个比例相近的角色。
2. 对齐母版的头部、衣身和接地位置。格子几何中心是 `x=96`，但头发、道具会使人物不对称，
   **不能把整个透明包围盒的中心当作躯干中心**。
3. 待机、失败、等待、思考保持同一站姿族；跑步应有连续迈腿相位，不能混入跪坐或躺平。
   跳跃的预备、腾空和落地允许高度变化，不能为了通过脚本把每帧整体高度硬拉到一样。
4. 同一行不换视角、道具持手或长度。左右跑可整体镜像；不能只翻道具或临时换手。
5. 同一行首尾应能顺接。眼睛、手、头发的小变化应支持主要动作，不能用眨眼或比手势代替跑步。
6. 描边、像素颗粒、左上光源和配色跨行一致。生成图需要归一尺寸时，同一组源图用共同尺度，
   不对单帧做非等比拉伸，不用逐帧缩放掩盖身材变化。
7. 不足 8 帧只在末尾留全透明格，不在中间挖空，不复制同一张画凑帧数。
8. 持杖手固定为画面左侧那只（她的右手），另一只手才能做动作。挥手、托腮、比手势都必须是
   **画面右侧**的手；挥手帧不得在持杖手旁边再画出一只抬起的巴掌。
9. 插件会在运行时从待机切到其它行（挥手、跳跃、失败…），这些行必须与第 0 行共用同一套身体：
   裙摆轮廓、腿部站距、麦杖落点、人物在格内的水平位置都要能对上。挥手只改自由手和表情，不改身体比例。

## 行与帧数

| 行 | 动作 | 有内容的格数 | 要求 |
| --- | --- | --- | --- |
| 0 | idle | 6 或 7 | 轻微呼吸、眨眼；插件播放前 6 格 |
| 1 | runningRight | 8 | 向右跑步闭环；可逐格镜像第 2 行 |
| 2 | runningLeft | 8 | 向左跑步闭环 |
| 3 | waving | 4 | 同一站姿挥手 |
| 4 | jumping | 5 | 预备、起跳、腾空、回落、落地 |
| 5 | failed | 8 | 同一站姿叹气、低落；不跪、不躺 |
| 6 | waiting | 6 | 等待、细微目光或姿态变化 |
| 7 | running | 6 | 真正的跑步；可取第 2 行相位 `[0,1,3,4,5,7]` |
| 8 | review | 6 | 同一抬头托腮姿势、目光变化、眨眼；不反复点头 |
| 9 | look 000°–157.5° | 8 | 顺时针视线：向上，经右上、右侧，继续到右下 |
| 10 | look 180°–337.5° | 8 | 顺时针视线：向下，经左下、左侧，继续到左上 |

朝向采用屏幕坐标的完整 360° 光标方向：0° 向上、90° 向右、180° 向下、270° 向左，每格递增 22.5°。
这不是绕竖轴转一圈：耀嘉音应由头颈、肩部和少量上身自然带动视线；向下时低头并可轻微前倾，向左右时头发随转向遮挡或露出相应侧脸。下身、脚底、站姿和法杖落点保持稳定，不能整张精灵旋转或拼贴替换头部。16 格按顺序形成完整闭环；中性待机由第 0 行提供。
如果无法交付，允许两行同时全透明，但必须同时关闭消费者的光标跟随入口；不接受只留 8 个方向。
当前正式图集保留完整 16 格，插件光标跟随默认开启。

### 朝向两行的验收标准

16 格应能辨认出环绕注视，四个主方向和斜向过渡清楚，量化指标仅用于发现异常：

| 指标 | 现值 | 要求 |
| --- | --- | --- |
| 第 9、10 行中位占用高度 | 当前 198 / 198 px | 两行差异 ≤ 2%；每行共用一套等比尺度 |
| 16 格人脸区域像素离散度 `(max-min)/max` | 当前 73% | 有变化即可；须逐格目检方向，不能仅凭像素计数验收 |
| 16 格人物包围宽度离散度 | 当前 7% | 只作警示；由长发、头部转向和法杖共同影响 |
| 四个主方向 | 当前已填满 16 格 | 0° 向上、90° 向右、180° 向下、270° 向左；确认屏幕方向无反转 |

也就是说：视线应沿「上 → 右 → 下 → 左 → 回到上」顺时针连续变化，头颈和上身跟随自然，不能把向下误画成背面。
`python scripts/audit-atlas.py` 会输出方向两行占用高度、16 格面部像素变化和四个主方向的面部像素数；这些数值不能代替语义目检。

## 自动检查与目检

```powershell
python scripts/audit-atlas.py spritesheet.webp
npm run test:atlas
npm run build
npm run verify
npm test
```

审计输出 `OK`、退出码 0，**仅表示结构检查通过**：

- 实际文件格式、大小、静态图片、真实透明度和固定尺寸；
- 必须存在的连续帧数、末尾空格，以及朝向两行同时存在或同时省略；
- 站立行含道具的占用下沿在 `203 ± 2`，不再从可能本身偏移的第 0 行推定基线；
- 站立行占用高度相对行中位数偏差 ≤ 3%；跑步允许 ≤ 8% 的姿势变化；跳跃不做高度一致性检查；
- 无内容触碰格子边缘。躺平帧不再有豁免。

这些透明边界包含麦克风杖和头发，**不是人体身高、脚底位置或头身比测量**。
脚掌是否接地、角色比例、持手、动作语义、方向辨识度和循环首尾必须另外逐帧与动态目检。
不能把脚本 `OK` 当成画面已经全部合格。

## 重打包

`npm install` 安装开发依赖后，运行 `npm run build:atlas`。
它会从 `assets/atlas-source/normalized/` 和 `assets/atlas-source/look/` 重建全部 11 行，输出根目录的 `spritesheet.webp`；不从旧图集中保留部分动作行。
源图更换后必须重新检查 `scripts/pack-atlas.mjs` 的提取范围，不能沿用旧坐标盲切。完成后运行 `python scripts/audit-atlas.py spritesheet.webp`，再查看全量格子预览并逐帧验收。
提示词和未采用的生成跑步说明见 [atlas-generation-prompts.md](atlas-generation-prompts.md)。