# 🎨 自定义素材包（Custom Assets）

把文件放到本目录，**无需改任何代码**，桌宠启动时自动加载并覆盖内置素材。

## 可定制的内容

### 1. 像素图案与配色（`sprites.json`）

放一个 `sprites.json` 即可同时覆盖鲸鱼形象（网格）和配色（调色板）。格式与内置素材一致：

```json
{
  "canvas": { "width": 80, "height": 58 },
  "palette": {
    ".": "#00000000",   "b": "#546AF5",   "B": "#2E46D0",
    "w": "#FFFFFF",     "K": "#0F1B4D",   "P": "#FF9EBB",
    "R": "#8FB0FF",     "g": "#9AA3B8",   "G": "#6E7690",
    "q": "#F0F2F7",     "k": "#3A4154"
  },
  "sprites": {
    "default":   ["<第0行：80个字符>", "<第1行>", "...共58行..."],
    "working":   ["...", "...58行..."],
    "attention": ["...", "...58行..."],
    "done":      ["...", "...58行..."],
    "idle":      ["...", "...58行..."],
    "offline":   ["...", "...58行..."]
  }
}
```

- **只改配色**：`palette` 里的颜色值（如 `"b": "#546AF5"` → 换成你的主题色，全鲸鱼身体同步变色）
- **只改形象**：`sprites` 里每个状态是 58 行 × 80 字符的像素网格，每字符对应 `palette` 里的一个颜色（`.` 为透明）；6 个状态必须齐全
- **快速生成**：用官方像素化脚本把参考图转成 `sprites.json`（见下方"从参考图生成"）

> 提示：内置素材的完整 JSON 在 `pixel-src-hd/whale-sprites-hd.json`，可以复制一份在此基础上改。

### 2. 状态音效（`.m4a` / `.mp4`）

```
custom/attention.m4a   ← 覆盖"需要确认"音效
custom/done.m4a        ← 覆盖"任务完成"音效
```

AAC 编码、建议 1 秒内短音。缺失时自动回退到内置音效。

## 从参考图生成像素图案

1. 准备一张白底鲸鱼参考图（如 PNG/JPG）
2. 运行像素化脚本（生成 `sprites.json` 到 `custom/`）：

```bash
# 需要 Python3 + PIL
python3 scripts/ref_to_sprites.py <你的参考图路径>
```

3. 重启桌宠生效。生成脚本会做投票降采样 + 平滑 + 表情覆盖（6 状态），可调整脚本顶部参数微调。

---

*删除本目录下不需要的文件即可恢复内置素材。*