---
name: playcraft-sprite-generation
description: 从概念图/示意图出发，通过 AI 文生图/图生图批量生成完整精灵图集（如 34 张麻将牌、54 张扑克牌、棋子集等），再智能切割为逐帧资产并组装精灵图。核心理念：信任现代生图模型（GPT-Image-2 等）的文字/符号精度，走「AI 直接生成 → 智能切割 → 组装」路径，不做分层合成。
compatibility: agent,opencode
triggers: 精灵图生成, sprite generation, 批量生成, 牌面生成, 完整套, tile set, card set, 从概念图, from concept, 全套素材, batch asset, mahjong set, poker set, chess set
---

## Skill Definition
tools:
  - bash
  - read
prompt_extension: |
  你是批量精灵图生成工程师。从一张概念图/示意图出发，利用 AI 生图模型批量生成完整游戏资产集，再通过智能切割提取逐帧资产，最终组装为生产级精灵图。
  不得向 /project/ 写入；所有中间产物与最终输出必须在会话 .../sessions/{id}/ta-workspace/ 下。
  核心原则：信任现代生图模型的符号/文字精度，优先让 AI 直接生成带正确内容的资产，不搞"底板+符号"分层合成。
  通过 bash 调用 playcraft CLI：tools generate-image、image sprite-split、image sprite-sheet、image remove-background、image resize 等。

## 我做什么

- 从一张概念图/示意图推导出完整资产集的生成计划（例：一张麻将牌 → 全部 34 种牌面）
- 利用 AI 生图模型（GPT-Image-2、Gemini 等）批量生成完整资产，保持风格一致性
- 智能切割 AI 生成的批量图（规则网格 / Vision 自动检测 / 未来 SAM 语义分割）
- 后处理（去背景、统一尺寸、质量检查）后组装为生产级精灵图 + JSON 帧坐标

## 何时用我

- 拿到一张概念图/示意图，需要生成**完整套**的同类元素（牌、棋子、图标集等）
- 元素上有**精确符号/文字/图案**（中文字符、数字、花色等），需要 AI 模型直接生成正确内容
- 需要保持全套元素**风格高度统一**
- 最终交付物是可用于游戏引擎的精灵图 + JSON 元数据

## 不用我的场景

- 已有完整精灵图只需换肤/风格变换 → 用 `playcraft-sprite-remix`
- 已有逐帧图片只需合并 → 用 `playcraft-sprite-sheet`
- 需要 3D 翻转动画 → 用 `playcraft-3d-flip-sprite`
- 单张图片生成（非批量套） → 用 `playcraft-image-generation`

---

## 核心流程

```
概念图/示意图
  ↓
Step 1: 分析 — 推导完整资产集清单
  ↓
Step 2: 选择生成策略 — 逐张 vs 批量拼板
  ↓
Step 3: AI 批量生成（图生图 + reference-image 保持风格）
  ↓
Step 4: 智能切割（grid / auto-detect / 未来 SAM）
  ↓
Step 5: 后处理（去背景、统一尺寸、质量校验）
  ↓
Step 6: 组装精灵图 + JSON 帧坐标
```

---

## Step 1: 分析概念图，推导完整资产清单

拿到概念图后，先明确**完整集合的定义**：

```bash
# 查看概念图
playcraft image info ta-workspace/concept.png
```

常见集合清单（TA 应根据项目 atom-plan / layout-spec 确定）：

| 游戏类型 | 集合 | 元素数 | 每元素特征 |
|----------|------|--------|-----------|
| 麻将 | 万条筒风箭 | 34 | 每张牌有独特中文字符/图案 |
| 扑克 | A-K × 4花色 + 大小王 | 54 | 数字+花色，大小王特殊 |
| 象棋 | 红黑各 16 子 | 32 | 中文棋子名，红黑双色 |
| UNO | 数字牌+功能牌+万能牌 | 108 | 数字+颜色+功能符号 |
| Match-3 元素 | 按主题 | 6-8 | 各不相同的图案 |
| 图标集 | UI 元素 | N | 各不相同的图标 |

输出：**资产清单表**（记录在 ta-workspace/asset-manifest.json）

```json
{
  "setName": "mahjong-tiles",
  "conceptRef": "ta-workspace/concept.png",
  "style": "ice crystal, frosted glass, blue-white cold theme",
  "totalCount": 34,
  "groups": [
    { "name": "wan", "items": ["一万","二万","三万","四万","五万","六万","七万","八万","九万"] },
    { "name": "tiao", "items": ["一条","二条","三条","四条","五条","六条","七条","八条","九条"] },
    { "name": "tong", "items": ["一筒","二筒","三筒","四筒","五筒","六筒","七筒","八筒","九筒"] },
    { "name": "feng", "items": ["东","南","西","北"] },
    { "name": "jian", "items": ["中","发","白"] }
  ]
}
```

---

## Step 2: 选择生成策略

### 策略 A：逐张生成（推荐，精度最高）

每个元素单独调用一次 `generate-image`，用概念图作为 `--reference-image` 锁定风格。

**优点**：每张有完整 prompt 描述符号，精度最高
**缺点**：API 调用次数多（N 次）
**适用**：元素数 < 50，每个元素有独特符号/文字

### 策略 B：批量拼板生成（省 API 调用）

让 AI 在一张大图中生成多个元素（如 "generate a 3×3 grid of mahjong tiles: 一万 through 九万"），然后切割。

**优点**：一次生成多个元素，风格自然一致
**缺点**：符号精度随密度下降；布局可能不够规则
**适用**：元素数多、符号相对简单（如 Match-3 的几何图案）

### 策略 C：分组生成（平衡方案）

按逻辑分组，每组生成一张拼板图。如麻将"万"字组 9 张一板、"条"组 9 张一板。

**优点**：组内风格 100% 一致，API 调用降到 4-5 次
**缺点**：需要切割步骤
**适用**：有自然分组的大集合（推荐麻将、扑克使用此策略）

### 策略选择决策

```
元素数量？
├── < 10 → 策略 A（逐张生成）
├── 10-50 且有自然分组 → 策略 C（分组生成）
├── 10-50 无分组 → 策略 A 或 B
└── > 50 → 策略 C（必须分组，否则太慢）
```

---

## Step 3: AI 批量生成

### 策略 A — 逐张生成

```bash
# 关键：使用同一模型 + 同一 reference-image，保证风格一致

# 先确认可用模型
playcraft tools list-image-models --json

# GPT-Image-2（符号精度最高，推荐用于带文字/符号的资产）
# 生成第一张（建立风格锚点）
playcraft tools generate-image \
  --prompt "mahjong tile, ice crystal frosted glass style, tile shows Chinese character 一万 (yi wan), game asset, white background, front view, single tile centered" \
  --reference-image ta-workspace/concept.png \
  --aspect-ratio 1:1 \
  --image-model iegg-litellm/gpt-image-2 \
  --output ta-workspace/tiles/wan_1.png

# 后续用第一张作为额外 reference，双重锁定风格
playcraft tools generate-image \
  --prompt "mahjong tile, ice crystal frosted glass style, tile shows Chinese character 二万 (er wan), game asset, white background, front view, single tile centered" \
  --reference-image ta-workspace/concept.png \
  --reference-image ta-workspace/tiles/wan_1.png \
  --aspect-ratio 1:1 \
  --image-model iegg-litellm/gpt-image-2 \
  --output ta-workspace/tiles/wan_2.png

# 循环生成剩余元素...（同一模型、同样的 reference 组合）
```

**风格锁定技巧**：

1. **双 reference**：概念图 + 前一张成品，双重约束风格
2. **同一模型**：全套元素必须用同一个 `--image-model`
3. **prompt 模板化**：只替换符号描述部分，其余措辞完全一致
4. **先验证后批量**：先生成 2-3 张检查风格，确认后再跑全套

### 策略 C — 分组生成（以麻将为例）

```bash
# 万字组：9 张一板
playcraft tools generate-image \
  --prompt "3x3 grid of mahjong tiles, ice crystal frosted glass style. Top row left to right: 一万, 二万, 三万. Middle row: 四万, 五万, 六万. Bottom row: 七万, 八万, 九万. Each tile clearly shows its Chinese character. Game assets, white background, uniform size, evenly spaced grid" \
  --reference-image ta-workspace/concept.png \
  --aspect-ratio 1:1 \
  --image-model iegg-litellm/gpt-image-2 \
  --output ta-workspace/sheets/wan_grid.png

# 条子组
playcraft tools generate-image \
  --prompt "3x3 grid of mahjong tiles, ice crystal frosted glass style. Top row: 一条, 二条, 三条. Middle row: 四条, 五条, 六条. Bottom row: 七条, 八条, 九条. Each tile clearly shows its bamboo pattern. Game assets, white background, uniform size, evenly spaced grid" \
  --reference-image ta-workspace/concept.png \
  --reference-image ta-workspace/sheets/wan_grid.png \
  --aspect-ratio 1:1 \
  --image-model iegg-litellm/gpt-image-2 \
  --output ta-workspace/sheets/tiao_grid.png

# 筒子组、风箭组（2x2 即可）...类似
```

---

## Step 4: 智能切割

根据生成策略选择切割方式：

### 策略 A 的产物 — 逐张生成，无需切割

每张图已经是单独元素，跳到 Step 5。

### 策略 B/C 的产物 — 需要切割

```bash
# ── 方法 1：已知网格（最快、零 API 消耗）──
# 适用于 prompt 中明确指定了网格排列的生成结果
playcraft image sprite-split \
  --input ta-workspace/sheets/wan_grid.png \
  --output-dir ta-workspace/split/wan \
  --rows 3 --columns 3 \
  --frame-width 200 --frame-height 260 \
  --padding 10

# ── 方法 2：Vision 自动检测（需 token）──
# 适用于 AI 生成的网格不够规则、间距不均匀时
playcraft image sprite-split \
  --input ta-workspace/sheets/wan_grid.png \
  --output-dir ta-workspace/split/wan \
  --auto-detect \
  --hint "3x3 grid of mahjong tiles, uniform cells"

# 检查切割结果
ls ta-workspace/split/wan/
cat ta-workspace/split/wan/split-meta.json
```

**切割质量检查**：

```bash
# 逐张检查尺寸是否一致
for f in ta-workspace/split/wan/frame_r*.png; do
  playcraft image info "$f"
done
```

如果 auto-detect 结果不理想（帧偏移、尺寸不一），退回手动参数模式，
根据 `split-meta.json` 中报告的实际检测结果微调 `--rows --columns --frame-width --frame-height --padding`。

### 方法 3：SAM3 语义分割（不规则布局首选）

当 AI 生成的拼板图**不是规则网格**（元素散落、大小不一、间距不均），用 SAM3 语义分割精确提取每个对象。
SAM3 已集成到 CLI，通过 `playcraft image segment` 调用，冷启动约 15s，热启动约 5-10s。

```bash
# ── 从散乱拼板中提取所有麻将牌 ──
playcraft image segment \
  --input ta-workspace/sheets/wan_grid.png \
  --text "mahjong tile" \
  --threshold 0.2 \
  --output-dir ta-workspace/split/wan_sam

# 输出结构：
# ta-workspace/split/wan_sam/
#   prompt_0_mahjong_tile/
#     00_rgba.png   ← 已抠好透明背景，可直接用
#     00_mask.png
#     01_rgba.png
#     ...
#   segment-meta.json   ← 含每个实例的 bbox 坐标（可用于自动排序）

# ── 多类型同时提取（如带底板文字 + 图案的牌）──
playcraft image segment \
  --input ta-workspace/sheets/mixed_layout.png \
  --prompts '[{"text":"mahjong tile"},{"text":"game icon"}]' \
  --threshold 0.25 \
  --output-dir ta-workspace/split/mixed_sam
```

**SAM3 分割后的后处理**：

```bash
# SAM3 输出的 rgba.png 已是透明背景，直接统一尺寸即可（无需再跑 remove-background）
for f in ta-workspace/split/wan_sam/prompt_0_mahjong_tile/*_rgba.png; do
  base=$(basename "$f" _rgba.png)
  playcraft image resize \
    --input "$f" \
    --output "ta-workspace/final/wan_${base}.png" \
    --width 128 --height 168 \
    --fit contain
done
```

**三种切割方法对比**：

| 方法 | 适用场景 | 精度 | API 消耗 |
|------|---------|------|---------|
| 规则网格（`--rows --columns`） | prompt 中明确指定了 NxM 网格 | 高（前提是 AI 生成规则） | 零 |
| Vision 自动检测（`--auto-detect`） | 轻微不规则、大致网格排列 | 中 | 低（Vision API） |
| **SAM3 语义分割**（`image segment`） | **散乱布局、不规则间距、大小不一** | **最高** | 中（SAM3 API） |

**决策规则**：
- AI 生成时用了明确的网格 prompt → 先试规则网格；失败再用 `--auto-detect`
- 生成结果明显不规则 → 直接用 SAM3，一步到位
- SAM3 是抠图而非坐标切割，输出直接是带透明通道的 RGBA，省去 remove-background 步骤

---

## Step 5: 后处理

对每张切割/生成的资产做标准化处理：

```bash
# 1. 去背景（AI 生成图通常有白底/灰底）
playcraft image remove-background \
  --input ta-workspace/split/wan/frame_r0_c0.png \
  --output ta-workspace/clean/wan_1.png

# 复杂背景时用 AI 方法
playcraft image remove-background \
  --input ta-workspace/split/wan/frame_r0_c0.png \
  --output ta-workspace/clean/wan_1.png \
  --method ai

# 2. 统一尺寸（所有元素必须完全相同的 width × height）
playcraft image resize \
  --input ta-workspace/clean/wan_1.png \
  --output ta-workspace/final/wan_1.png \
  --width 128 --height 168 \
  --fit contain

# 3. 质量校验
playcraft image info ta-workspace/final/wan_1.png
# → 确认：dimensions 正确、文件大小合理
```

**批量脚本模式**（TA 可用 `Bash(node:*)` 写批量处理脚本）：

```bash
# 批量去背景 + 统一尺寸
for f in ta-workspace/split/wan/frame_r*.png; do
  base=$(basename "$f" .png)
  playcraft image remove-background --input "$f" --output "ta-workspace/clean/${base}.png"
  playcraft image resize --input "ta-workspace/clean/${base}.png" --output "ta-workspace/final/${base}.png" --width 128 --height 168 --fit contain
done
```

---

## Step 6: 组装精灵图

```bash
# 将所有最终帧合并为精灵图 + JSON 帧坐标
playcraft image sprite-sheet \
  --inputs ta-workspace/final/wan_1.png,ta-workspace/final/wan_2.png,ta-workspace/final/wan_3.png,ta-workspace/final/wan_4.png,ta-workspace/final/wan_5.png,ta-workspace/final/wan_6.png,ta-workspace/final/wan_7.png,ta-workspace/final/wan_8.png,ta-workspace/final/wan_9.png \
  --output ta-workspace/output/wan_sheet \
  --columns 3 \
  --cell-width 128 --cell-height 168 \
  --padding 2

# 结果：
# ta-workspace/output/wan_sheet.png  — 精灵图
# ta-workspace/output/wan_sheet.json — 帧坐标元数据

# 也可以把全部 34 张合成一张总图
playcraft image sprite-sheet \
  --inputs ta-workspace/final/wan_1.png,...,ta-workspace/final/jian_3.png \
  --output ta-workspace/output/mahjong_full \
  --columns 9 \
  --cell-width 128 --cell-height 168 \
  --padding 2
```

---

## Prompt 工程要点

### 符号精度技巧

现代生图模型（GPT-Image-2 等）中文字符精度已达 90%+，但仍需注意：

1. **明确标注拼音**：`Chinese character 一万 (yi wan)` 比纯写 `一万` 准确率更高
2. **单元素大图优先**：1:1 比例的单元素图比密集网格中的小元素精度高
3. **简单背景**：`white background` 或 `plain background` 减少干扰
4. **先验证再批量**：生成 2-3 张，人工确认符号正确后再跑全套

### 风格一致性技巧

1. **固定 prompt 模板**：只替换符号描述，其他措辞字字相同
2. **双 reference-image**：概念图 + 同批已确认的成品
3. **同一模型**：整套元素绝对不能中途换模型
4. **同一 aspect-ratio**：保持一致避免比例偏移

### Prompt 模板示例

```
单元素模板：
"[STYLE_DESC] mahjong tile, tile shows [SYMBOL_CN] ([SYMBOL_PINYIN]),
 game asset, [BG_DESC], front view, single tile centered, [EXTRA]"

网格模板：
"[ROWS]x[COLS] grid of [STYLE_DESC] mahjong tiles.
 Row 1 left to right: [SYM1], [SYM2], [SYM3].
 Row 2: [SYM4], [SYM5], [SYM6].
 ...
 Each tile clearly shows its symbol. Game assets, white background,
 uniform size, evenly spaced grid, [EXTRA]"
```

---

## 完整示例：从概念图生成全套麻将牌

```bash
# === Step 1: 概念图已由 Designer 提供 ===
# ta-workspace/concept.png — 一张冰风格麻将牌示意图

# === Step 2: 选择策略 C（分组生成）===
# 34 牌 → 万(9) + 条(9) + 筒(9) + 风(4) + 箭(3) → 5 组

# === Step 3: 分组生成 ===

# 万字组（3×3 网格）
playcraft tools generate-image \
  --prompt "3x3 grid of mahjong tiles, ice crystal frosted glass style, blue-white cold translucent material. Top row left to right: 一万 (yi wan), 二万 (er wan), 三万 (san wan). Middle row: 四万 (si wan), 五万 (wu wan), 六万 (liu wan). Bottom row: 七万 (qi wan), 八万 (ba wan), 九万 (jiu wan). Each tile clearly shows red Chinese characters. Game assets, white background, uniform size, evenly spaced" \
  --reference-image ta-workspace/concept.png \
  --aspect-ratio 1:1 \
  --image-model iegg-litellm/gpt-image-2 \
  --output ta-workspace/sheets/wan_grid.png

# 条子组（同样模式，reference 加上万字组成品锁定风格）
playcraft tools generate-image \
  --prompt "3x3 grid of mahjong tiles, ice crystal frosted glass style, blue-white cold translucent material. Top row: 一条, 二条, 三条. Middle row: 四条, 五条, 六条. Bottom row: 七条, 八条, 九条. Each tile clearly shows bamboo stick patterns. Game assets, white background, uniform size, evenly spaced" \
  --reference-image ta-workspace/concept.png \
  --reference-image ta-workspace/sheets/wan_grid.png \
  --aspect-ratio 1:1 \
  --image-model iegg-litellm/gpt-image-2 \
  --output ta-workspace/sheets/tiao_grid.png

# 筒子组
playcraft tools generate-image \
  --prompt "3x3 grid of mahjong tiles, ice crystal frosted glass style, blue-white cold translucent material. Top row: 一筒, 二筒, 三筒. Middle row: 四筒, 五筒, 六筒. Bottom row: 七筒, 八筒, 九筒. Each tile clearly shows circular dot patterns. Game assets, white background, uniform size, evenly spaced" \
  --reference-image ta-workspace/concept.png \
  --reference-image ta-workspace/sheets/wan_grid.png \
  --aspect-ratio 1:1 \
  --image-model iegg-litellm/gpt-image-2 \
  --output ta-workspace/sheets/tong_grid.png

# 风牌组（2×2）
playcraft tools generate-image \
  --prompt "2x2 grid of mahjong tiles, ice crystal frosted glass style, blue-white cold translucent material. Top row: 东 (East wind), 南 (South wind). Bottom row: 西 (West wind), 北 (North wind). Each tile clearly shows its Chinese character. Game assets, white background, uniform size, evenly spaced" \
  --reference-image ta-workspace/concept.png \
  --reference-image ta-workspace/sheets/wan_grid.png \
  --aspect-ratio 1:1 \
  --image-model iegg-litellm/gpt-image-2 \
  --output ta-workspace/sheets/feng_grid.png

# 箭牌（1×3 or 3×1）
playcraft tools generate-image \
  --prompt "1 row of 3 mahjong tiles, ice crystal frosted glass style, blue-white cold translucent material. Left to right: 中 (red center, zhong), 发 (green prosperity, fa), 白 (white blank, bai). Each tile clearly shows its symbol. Game assets, white background, uniform size, evenly spaced" \
  --reference-image ta-workspace/concept.png \
  --reference-image ta-workspace/sheets/wan_grid.png \
  --aspect-ratio 3:1 \
  --image-model iegg-litellm/gpt-image-2 \
  --output ta-workspace/sheets/jian_grid.png

# === Step 4: 切割 ===

playcraft image sprite-split --input ta-workspace/sheets/wan_grid.png --output-dir ta-workspace/split/wan --auto-detect --hint "3x3 grid of mahjong tiles"
playcraft image sprite-split --input ta-workspace/sheets/tiao_grid.png --output-dir ta-workspace/split/tiao --auto-detect --hint "3x3 grid of mahjong tiles"
playcraft image sprite-split --input ta-workspace/sheets/tong_grid.png --output-dir ta-workspace/split/tong --auto-detect --hint "3x3 grid of mahjong tiles"
playcraft image sprite-split --input ta-workspace/sheets/feng_grid.png --output-dir ta-workspace/split/feng --auto-detect --hint "2x2 grid of mahjong tiles"
playcraft image sprite-split --input ta-workspace/sheets/jian_grid.png --output-dir ta-workspace/split/jian --auto-detect --hint "1x3 row of mahjong tiles"

# === Step 5: 后处理 ===

for group in wan tiao tong feng jian; do
  for f in ta-workspace/split/$group/frame_*.png; do
    base=$(basename "$f" .png)
    playcraft image remove-background --input "$f" --output "ta-workspace/clean/${group}_${base}.png"
    playcraft image resize --input "ta-workspace/clean/${group}_${base}.png" --output "ta-workspace/final/${group}_${base}.png" --width 128 --height 168 --fit contain
  done
done

# === Step 6: 质量检查 + 组装 ===

# 检查所有最终帧
for f in ta-workspace/final/*.png; do playcraft image info "$f"; done

# 组装全套精灵图（34 张, 9 列）
playcraft image sprite-sheet \
  --inputs $(ls ta-workspace/final/*.png | tr '\n' ',') \
  --output ta-workspace/output/mahjong_full \
  --columns 9 \
  --cell-width 128 --cell-height 168 \
  --padding 2

# 最终产出：
# ta-workspace/output/mahjong_full.png  — 全套精灵图
# ta-workspace/output/mahjong_full.json — 帧坐标
```

---

## 生图模型选择指南

| 模型 | 符号/文字精度 | 风格一致性 | reference-image | 推荐场景 |
|------|-------------|-----------|-----------------|---------|
| `iegg-litellm/gpt-image-2` | **极高** (中文 90%+) | 极高 | ✅ | 带文字/符号的资产（麻将、扑克、棋子） |
| `google/gemini-3.1-flash-image-preview` | 中 | 高 | ✅ 原生支持 | 图案类资产（Match-3 元素、图标） |
| `google/gemini-2.5-flash-preview-05-20` | 中 | 高 | ✅ | 同上 |
| `google/imagen-3.0-generate-002` | 低 | 高 | ❌ 纯文生图 | 无文字的背景/纹理 |

**关键原则**：带精确文字/符号的资产 → 优先 GPT-Image-2；纯图案 → Gemini 系列即可。

---

## 与现有 Skill 的关系

| Skill | 定位 | 本 Skill 的区别 |
|-------|------|----------------|
| `playcraft-image-generation` | 单张 AI 生图 | 本 Skill 覆盖「从概念到全套」的批量生成策略 |
| `playcraft-sprite-sheet` | 多张图合并为 sheet | 本 Skill 的 Step 6 调用它 |
| `playcraft-sprite-remix` | 已有 sheet 的换肤/重绘 | 本 Skill 是「从零生成」，不是改已有的 |
| `playcraft-image-processing` | 单张后处理 | 本 Skill 的 Step 5 调用它 |
| `playcraft-3d-flip-sprite` | 3D GLB 渲染精灵图 | 互补：3D 翻转动画走那边，平面批量走这边 |

---

## 注意事项

1. **先验证再批量**：前 2-3 张生成后人工确认符号正确、风格满意，再批量跑
2. **同一模型贯穿全套**：中途换模型会打破风格一致性
3. **保留 raw 产物**：`ta-workspace/sheets/` 和 `ta-workspace/split/` 保留原始中间产物，方便重切
4. **符号出错时的降级方案**：若 AI 对某个符号始终画错，该元素退回逐张生成（策略 A），其余继续批量
5. **API 限流**：批量生成时注意 provider 的 rate limit，按需在调用间加 sleep
6. **总资产预算**：可玩广告全部素材通常 ≤ 2-3 MB，精灵图分辨率不宜过高