# 桌仔卡带制作规范 v1.0

> 只要符合这个规范，任何人做的角色都能在桌仔里加载运行。
> 用什么工具做都行——AE、Spine、Procreate、甚至逐帧手绘PNG。
> 最后输出为一个zip包，就是"桌仔卡带"。

---

## 一、卡带文件夹结构

```
角色名/                     ← 文件夹名 = 卡带ID（英文小写+下划线）
├── manifest.json           ← 必填，角色信息+动作清单
├── preview.png/webp        ← 必填，卡片封面预览图（正方形或3:4，200×200以上）
└── assets/
    ├── idle.webm           ← 必填，待机呼吸/待着不动
    ├── walk.webm           ← 必填，走路/移动
    ├── happy.webm          ← 必填，开心/被表扬
    ├── think.webm          ← 必填，工作/思考/打字
    ├── click_response.webm ← 必填，被点击时的反应
    ├── greeting.webm       ← 推荐，打招呼
    ├── angry.webm          ← 推荐，生气/失败
    ├── sleep.webm          ← 推荐，睡觉/打盹
    └── xxx.webm            ← 自定义动作，随意加
```

---

## 二、manifest.json 格式

```json
{
  "manifest_version": "2.0",
  "id": "scout_corgi",
  "name": "侦探柯基",
  "version": "1.0.0",
  "author": "你的名字",
  "license": "MIT",
  "source_url": "",
  "description": "一句话描述角色性格，不超过50字",
  "tags": ["柯基", "侦探", "动物"],
  "category": "character",
  "size": {"width": 192, "height": 208},
  "anchor": {"x": 96, "y": 200},
  "default_action": "idle",
  "actions": [
    {"id": "idle", "file": "assets/idle.webm", "description": "平静呼吸", "loop": true},
    {"id": "walk", "file": "assets/walk.webm", "description": "跑动巡逻", "loop": true},
    {"id": "happy", "file": "assets/happy.webm", "description": "开心蹦跳", "loop": true},
    {"id": "think", "file": "assets/think.webm", "description": "认真思考", "loop": true},
    {"id": "click_response", "file": "assets/click_response.webm", "description": "被点击的反应", "loop": true}
  ]
}
```

### 字段说明

| 字段 | 必填 | 说明 |
|------|------|------|
| id | ✅ | 英文标识，小写+下划线，全局唯一 |
| name | ✅ | 中文角色名，不超过6字 |
| author | ✅ | 作者名/昵称 |
| description | ✅ | 一句话介绍，出现在市场卡片上 |
| tags | ✅ | 3-6个标签，方便搜索 |
| size | ✅ | 动画画布像素尺寸 width×height |
| anchor | ✅ | 锚点坐标（脚底中心点），通常 x=width/2, y=height |
| default_action | ✅ | 启动时播放的动作，通常是 idle |
| actions | ✅ | 动作列表，至少包含5个必选动作 |
| license | 推荐 | MIT / CC BY / CC BY-NC / 自定义 |
| source_url | 推荐 | 来源链接或作者主页 |
| preview | 可选 | 封面图文件名，默认preview.png |

### 5个必选动作

| 动作ID | 用途 |
|--------|------|
| idle | 待机——平时站着/坐着呼吸发呆 |
| walk | 移动——桌仔在桌面移动时播放 |
| happy | 开心——被表扬/任务完成/你逗它时 |
| think | 思考——帮你干活/分析问题时 |
| click_response | 点击反应——你点击它时 |

---

## 三、WebM动画技术要求

### 编码参数（直接抄这条命令）

```bash
ffmpeg -framerate 10 -i "frames/%03d.png" \
  -c:v libvpx-vp9 \
  -pix_fmt yuva420p \
  -auto-alt-ref 0 \
  -an \
  -b:v 0 -crf 30 \
  -row-mt 1 \
  output.webm
```

**参数说明：**
- **-pix_fmt yuva420p**：必须！这个带alpha透明通道
- **-auto-alt-ref 0**：必须！VP9 alpha通道的关键参数，缺了背景不透明
- **-framerate 10**：建议10fps，Q版动画足够流畅，文件更小
- **-crf 30**：质量参数，20-35之间，30是推荐平衡点
- **-an**：无音频（桌宠动画不需要声音）
- **-row-mt 1**：加速编码，多核并行

### 素材准备
- 每一帧是一张**透明背景PNG**
- 文件命名 frame_001.png, frame_002.png, ... 顺序排列
- 帧尺寸统一（比如全部192×208）
- 角色脚底对齐画布底边（锚点附近）
- 建议帧数：idle/think 4-8帧循环，walk 6-8帧，happy/angry 4-6帧

### 验证透明通道
编码完成后验证：
```bash
ffprobe -v error -select_streams v:0 -show_entries stream_tags=alpha_mode -of csv=p=0 output.webm
# 输出 1 表示alpha通道正常
```

---

## 四、推荐制作工具

| 工具 | 适合人群 | 优势 |
|------|---------|------|
| Adobe Animate/AE | 有动画基础 | 专业骨骼动画，导出PNG序列 |
| Spine 2D | 游戏动画师 | 骨骼动画省帧，文件小 |
| Procreate Dreams | iPad用户 | 手绘逐帧友好 |
| Piskel/Aseprite | 像素风爱好者 | 免费轻量，直接导出PNG/GIF |
| Live2D | 日漫风格 | 专业二次元，但学习曲线陡 |
| CapCut/剪映 | 完全新手 | 可以把GIF导出为帧再转webm |

**最懒路线**：找到透明GIF/APNG素材 → 拆帧为PNG → 跑ffmpeg命令 → 写manifest.json → 打包zip。

---

## 五、版权红线

- ✅ MIT / Apache / CC0 协议的开源资源：可自由移植、修改、分发
- ✅ CC BY 协议：必须标注原作者
- ⚠️ CC BY-NC 协议：只能非商用，不能在付费卡带中使用
- ❌ 商业IP（迪士尼/三丽鸥/原神/宝可梦等）：严禁制作分发
- ❌ 真人形象/明星肖像：严禁
- ❌ 其他商业桌宠/游戏的付费素材：严禁盗用

卡带提交到市场时需勾选协议确认，违规卡带将被下架。

---

## 六、发布到卡带市场

1. 把整个角色文件夹压缩为zip（zip根目录就是manifest.json，不要套一层文件夹）
2. 到 [deskling.cards](https://deskling.cards)（即将上线）上传
3. 填写标题/简介/标签/预览图
4. 选择定价：免费 / 付费（定价1-9.9元）
5. 提交审核（审核周期24小时内，主要查版权+格式合规）
6. 上架后获得独立链接，可以分享到社交平台

### 当前提交方式（市场上线前）
加入QQ群【桌仔卡带创作者群】，直接在群文件里发zip，官方定期整理入库。

---

## 七、官方示例卡带

仓库地址：https://github.com/Deskling/cartridges

- **jingyu_niang（鲸鱼娘）**——54个丰富动作，旗舰角色
- **scout_corgi（侦探柯基）**——9动作，MIT开源移植
- **taotao（淘淘）**——9动作，阳光程序员小哥
- **xiaoman（小满）**——9动作，中华田园犬
- **basketball_chicken（篮球鸡）**——9动作，运动风小鸡

可直接下载参考manifest.json写法和webm编码格式。