# 素材库（assets）

> 本目录存放仓库 / 插件 / 文档使用的素材：固定气泡样式素材包、实验素材、模板与截图。
> 当前素材规范：[`docs/BUBBLE_SPEC.md`](../docs/BUBBLE_SPEC.md) **v3.2 固定气泡样式（内部制作版）**。

---

## 1. 目录结构

```
assets/
├── styles/             # M2 固定气泡样式正式素材包（每个样式一个目录）
│   └── <style-id>/     # manifest.json + background + accessories + preview
├── templates/
│   ├── style-package-example/   # v3 固定样式素材包示例（格式演示，不发布）
│   └── legacy/                  # v1 九宫格模板（仅留档）
├── recycle/            # 回收站：已废弃/暂不使用的素材，不随插件发布
│   └── bubbles/        # v1/v2 实验与用户定制测试图（2026-10-20 归档）
└── screenshots/        # 效果截图 / 模拟渲染图
```

> 固定样式正式素材放 `assets/styles/<style-id>/`；示例只放 `templates/`；废弃素材放 `recycle/`。

## 2. 固定样式素材包结构

每套样式一个目录：

```text
bubble-<id>/
├── manifest.json          # 必需：切片/内边距/文字色/尾巴色/挂件
├── background.svg         # 必需：九宫格背景
├── accessories/           # 可选：挂件单独拆分
│   └── tl-star@2x.svg
├── preview.png            # 必需：整体效果图（文档/验收，不运行时）
├── README.md              # 必需：来源、授权、制作记录
└── source/                # 可选：分层设计源文件，不发布
```

## 3. 新增素材要求

1. 按 `docs/BUBBLE_SPEC.md` **v3.2** 制作：逻辑气泡 **525×42**、源图按 @2x **1050×84** 导出、透明；有真实边框才加高；实际宽度由内容决定、最大约 525；
2. `manifest.json` 必须写清 `slice / borderWidth / borderImageWidth / padding / textColor / tailColor`；
3. 文字区默认 42px、上下 padding 相等；图案可以进入文字区，靠文字色/描边保证可读，不要为避图案加高气泡；
4. 装饰按部件决定固定/拉伸：脸/头/logo/尾尖固定；身体/轮廓/条纹/海水可随文字拉伸；不要一刀切拆挂件；
5. 有挂件时单独放 `accessories/`，在 manifest 里写 `anchor / width / height / offsetX / offsetY`；
6. 生成 `preview.png`（整体效果图），必须与实际组装一致；
7. 第三方素材必须注明来源与授权；**CC BY-NC-SA 等非商业素材不得直接进入 MIT 发布包**；
8. 新增后在 README / BUBBLE_SPEC 中引用；
9. 私有资料（`.agent/`、`AGENTS.md`）不属于素材库。

## 4. 现有素材

### 4.1 固定样式（正式）

| 路径 | 说明 | 来源 |
| --- | --- | --- |
| [`styles/bubble-clover-meadow/`](./styles/bubble-clover-meadow/) | 固定样式「幸运草坡」：已按 v3.2 重做（1050×84 / 42px），manifest + background + preview | 用户 Figma 原创 |
| [`styles/bubble-koi-rising/`](./styles/bubble-koi-rising/) | 固定样式「锦鲤跃潮」：已按 v3.2 重做（1050×84 / 42px），manifest + background + preview | 用户 Figma / 生成素材 |
| [`styles/bubble-ds-whale-girl/`](./styles/bubble-ds-whale-girl/) | 固定样式「DS鲸鱼娘·白瓷蓝」：带尾壳体 1050×108 + 右下外挂角色 38×40；已接入并随 v0.2.1 发布 | 用户 Figma / 生成素材 |
| [`templates/style-package-example/`](./templates/style-package-example/) | v3.2 素材包格式示例（逻辑 525×42，源图 1050×84 @2x）：manifest + background + 挂件 + preview；仅演示，不发布 | 本项目自绘 |
| [`templates/style-package-example/preview.png`](./templates/style-package-example/preview.png) | 整体效果图示例（背景 + 左上星标挂件） | 本项目自绘 |

### 4.2 实验/参考素材（暂不作为发布素材）

| 路径 | 说明 | 来源 |
| --- | --- | --- |
| [`recycle/bubbles/blank-background-720x240.svg`](./recycle/bubbles/blank-background-720x240.svg) | v2 实验：空白背景层（已归档） | 本项目自绘 |
| [`recycle/bubbles/deco-sample-*.svg`](./recycle/bubbles/) | v2 实验：示例装饰（已归档） | 本项目自绘 |
| `recycle/bubbles/bubble-*-720x240@2x.{svg,png}` | 用户定制/测试完整气泡（v1 九宫格设计，已归档） | 见各自 SOURCES.md |
| [`templates/bubble-layers-guide.svg`](./templates/bubble-layers-guide.svg) | v2 分层模型标注图（历史参考） | 本项目自绘 |
| [`templates/legacy/`](./templates/legacy/) | v1 九宫格模板/示意（已弃用，仅留档） | 本项目自绘 |
| [`screenshots/layered-model-test.png`](./screenshots/layered-model-test.png) | v2 分层模型模拟渲染（历史参考） | 本项目模拟 |
| [`screenshots/rose-deer-cover-comparison.png`](./screenshots/rose-deer-cover-comparison.png) | v2 整图背景保护对比（历史参考） | 本项目模拟 |

### 4.3 皮肤截图

| 路径 | 说明 |
| --- | --- |
| [`screenshots/qq-blue.png`](./screenshots/qq-blue.png) 等 | 5 套内置皮肤真机截图（README 预览） |

> M2 发布前，固定样式素材以 `assets/styles/` 为准；`assets/recycle/` 中的素材仅留档，不随插件发布。