---
name: playcraft-sprite-sheet
description: 可玩广告流程步骤 7（可选）。将多张图片合并为精灵图（sprite sheet），输出 PNG 及 JSON 帧坐标元数据。通过 `playcraft image sprite-sheet` 命令在沙箱本地执行，无需 backend。
compatibility: agent,opencode
---

## Skill Definition
tools:
  - bash
  - read
prompt_extension: |
  你是精灵图合成师。不得向 /project/ 写入；所有输出必须在会话 .../sessions/{id}/ta-workspace/ 下。
  通过 bash 工具运行 `playcraft image sprite-sheet` CLI 命令将多张图合并为 PNG + JSON 元数据，全程本地执行，无需往返 backend。
  若需交付到素材库，先按 docs/agent/remixable-prefab-spec.md 整理 staging，再通过 bash 运行 `playcraft tools publish-prefab` CLI 命令。

## 我做什么

- 将多张图片合并为精灵图（sprite sheet）
- 输出：精灵图 PNG + JSON 元数据（每帧的 x, y, w, h 及文件名索引）
- 可与 playcraft-image-generation、playcraft-image-processing 串联使用

## 何时用我

当变体需要：
- 角色动画（idle、walk、jump 等多帧）
- 序列帧动画
- 多张小图合并为图集（减少 draw call）

## 命令用法

```bash
playcraft image sprite-sheet \
  --inputs <图1>,<图2>,<图3>,... \
  --output <ta-workspace内的基路径>   # 自动生成 .png 和 .json
  [--columns <列数>]                  # 默认按平方根自动计算
  [--padding <帧间距像素>]             # 默认 0
  [--cell-width <宽>]                 # 默认用第一张图的宽
  [--cell-height <高>]                # 默认用第一张图的高
```

### 输出文件

- `<output>.png` — 精灵图 PNG
- `<output>.json` — 帧坐标数据，格式如下：
  ```json
  {
    "frames": {
      "hero_idle_0.png": { "x": 0, "y": 0, "w": 64, "h": 64 },
      "hero_idle_1.png": { "x": 64, "y": 0, "w": 64, "h": 64 }
    },
    "meta": { "image": "hero.png", "size": { "w": 256, "h": 64 }, "scale": 1 }
  }
  ```

## 工作流

1. **准备帧图片**：从 /project 只读读取参考图，或引用 ta-workspace 内已生成/处理的帧图
2. **（可选）统一尺寸**：用 `playcraft image resize` 确保所有帧尺寸一致
3. **合并精灵图**：
   ```bash
   playcraft image sprite-sheet \
     --inputs ta-workspace/frame_0.png,ta-workspace/frame_1.png,ta-workspace/frame_2.png \
     --output ta-workspace/hero-sheet \
     --columns 4 \
     --cell-width 64 --cell-height 64
   # 生成：ta-workspace/hero-sheet.png 和 ta-workspace/hero-sheet.json
   ```
4. **（可选）交付到素材库**：
   ```bash
   playcraft tools publish-prefab \
     --remix-project-id <ID> --template <名> --variant <名> --prefab <名> \
     --staging-root <staging路径>
   ```

## 与步骤 5、6 融合

完整流程示例：

```bash
# 步骤 5：AI 生成帧
playcraft tools generate-image --prompt "hero idle frame 1, pixel art, transparent background" --output ta-workspace/f0.png
playcraft tools generate-image --prompt "hero idle frame 2, pixel art, transparent background" --output ta-workspace/f1.png

# 步骤 6：统一尺寸
playcraft image resize --input ta-workspace/f0.png --output ta-workspace/f0_64.png --width 64 --height 64 --fit contain
playcraft image resize --input ta-workspace/f1.png --output ta-workspace/f1_64.png --width 64 --height 64 --fit contain

# 步骤 7：合并精灵图
playcraft image sprite-sheet \
  --inputs ta-workspace/f0_64.png,ta-workspace/f1_64.png \
  --output ta-workspace/hero-idle \
  --cell-width 64 --cell-height 64
```

## 游戏引擎兼容

JSON 格式设计兼容常见引擎（Phaser、PlayCanvas 的 sprite 格式），key 为文件名，value 含 x/y/w/h 坐标。