用 Codex CLI 內建 image_gen（gpt-image-2）自動生成 pixel-art 角色 sprite 動畫與遊戲素材 — 逐格 PNG、橫向 sprite sheet、透明去背、動畫 GIF。
純文字描述即可從零生成角色（不需 reference 圖），也可附一張圖鎖定角色。完全走 CLI，不需啟動任何 server。
同時是一個 Claude Code skill（見 SKILL.md）：把整個 repo 放到 ~/.claude/skills/sprite-gen/，Claude 就會在你要求生 sprite 時自動使用。
# 1) 安裝（在你的專案根目錄）
git clone https://github.com/gpwork4u/sprite-gen.git .claude/skills/sprite-gen
( cd .claude/skills/sprite-gen && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt )
# 2) 跑內建範例（先 --dry-run 看 prompt，不花 token）
.claude/skills/sprite-gen/.venv/bin/python -m sprite_gen pack \
.claude/skills/sprite-gen/examples/pack.yaml --dry-run
# 3) 真跑，素材會落在當前目錄的 .sprites/
.claude/skills/sprite-gen/.venv/bin/python -m sprite_gen pack \
.claude/skills/sprite-gen/examples/pack.yaml用 Claude 更省事：裝好後直接說「生一隻騎士的 idle/walk/attack 動畫」，Claude 會自動寫好 spec 並呼叫此 skill。
需要先 codex login（圖像生成靠 Codex CLI 內建 image_gen）。完整選項見下方 用法。
裝成 skill 後，你不用寫 YAML，直接用一句話描述即可，Claude 會自動展開成完整 spec、dry-run 自查、再真跑，最後把去背 GIF 交給你：
| 你想要的 | 直接這樣說 |
|---|---|
| 一整套角色動畫 | 「生一隻森林精靈弓箭手的 idle / walk / attack 像素動畫」 |
| 指定畫風與比例 | 「做一個 Q 版騎士 sprite，藍色斗篷、chunky pixel outlines，要 idle、walk、run、jump」 |
| 用既有角色圖做動畫 | 「這張角色圖（附圖）幫我做成側視 walk + attack 動畫」 |
| 靜態道具 / 圖示 | 「生一組像素藥水圖示：紅補血、藍補魔、綠毒，要透明去背」 |
| 敵人 / 怪物 | 「生一隻史萊姆怪的 idle 跟 hurt 動畫，topdown 視角」 |
| 重切 / 重去背已生成的圖 | 「把這張 sprite sheet 重新切 6 格並去背」 |
Claude 會自動挑好 view（橫向捲軸用 side、立繪用 front、道具用 static_asset）、動作組合與格數；只在描述真的不足以判斷時才反問。想先看 prompt 不花 token，就加一句「先 dry-run 給我看」。
- Codex CLI
>=0.128（內建image_gen），且已codex login - Python 3.10+
- macOS / Linux
在你正在開發的專案根目錄執行，把 sprite-gen clone 進該專案的 .claude/skills/，Claude 在這個 repo 工作時就會自動有 sprite-gen skill：
# 在你的專案根目錄下
git clone https://github.com/gpwork4u/sprite-gen.git .claude/skills/sprite-gen
( cd .claude/skills/sprite-gen && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt )之後直接跟 Claude 說「生一隻 XX 角色的 walk/idle」即可；生成的素材會落在當前專案目錄的 .sprites/。
建議把
.claude/skills/sprite-gen/.venv/與.sprites/加進專案的.gitignore； 若不想連 skill 原始碼一起 commit 進你的 repo，把整個.claude/skills/sprite-gen/也 ignore 掉即可。
裝成全使用者通用（所有專案都可用）就改 clone 到 ~/.claude/skills/sprite-gen。
git clone https://github.com/gpwork4u/sprite-gen.git
cd sprite-gen
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt- 寫一份 pack spec（見
examples/pack.yaml）：
output_root: .sprites
defaults: { template: sidescroller_character, view: side, frames_per_image: 4, frame_size_px: 384, duration_ms: 120, qc_max_retries: 4 }
characters:
- id: knight
design:
- "young knight, short brown hair, steel plate over a blue tunic"
- "round wooden shield, short sword, chibi proportions, chunky pixel outlines"
actions:
- { action: idle, frames: 4 }
- { action: walk, frames: 6 }
- { action: attack, frames: 5, notes: "horizontal sword swing" }
assets:
- id: potions
name: potion
design: ["glass potion bottles, cork stopper, glossy highlight"]
variations: ["red health potion", "blue mana potion", "green poison vial"]- 先 dry-run 看 prompt（不花 token），再真跑：
.venv/bin/python -m sprite_gen pack examples/pack.yaml --dry-run # 只產 prompt
.venv/bin/python -m sprite_gen pack examples/pack.yaml # 真跑.sprites/
├── knight/
│ ├── idle/ final/{frames,transparent-frames,strip.png,animation.gif,transparent.gif,transparent-strip.png}
│ ├── walk/ …（>4 格會有 chunk-01 / chunk-02 子目錄）
│ └── attack/ …
└── potions/ final/…（一個 panel 一種變體，逐個透明去背）
每個動作都有：逐格 PNG（帶背景 + 去背）、橫向 sprite sheet、預覽 GIF。
- Sprite sheet → 切格：codex 一次生整條多 frame strip（避免逐張對不齊），Python 端切等格組 GIF。
- 文字一致性：無 reference 時，
design文字 + 嚴格 layout 約束（等寬 panel、固定 bbox、≤40% 填充）讓同一角色在每格保持一致。 - QC 自動重試：切格後檢查 clipping / 大小漂移，失敗帶錯誤訊息重生（預設最多 4 次）。
- 長動畫 chunk 串接：>4 格拆成多次 codex call，用前一段當 reference 維持連續。
- 去背：背景固定 chroma green
#00B140，corner-sample + edge BFS 清 halo（不依賴 ML）。 - 大小穩定：動畫共用單一縮放比例（身體大小固定、只有姿勢變化）；靜態素材逐格正規化（每個變體一致大小）。
python -m sprite_gen pack <spec>.yaml [--dry-run] [--output-root DIR] [--max-workers N]
python -m sprite_gen process <raw-sheet>.png --cols N -o out/ [--static] [--chroma-key]process 可重切 / 重去背已生成的 raw 圖而不重呼叫 codex。
| template | 用途 | 需要 reference 圖 |
|---|---|---|
sidescroller_character |
2D 橫向捲軸角色動畫（side/front/back/3-4/topdown） | 否（純文字即可） |
static_asset |
靜態素材／道具／圖示，一個 panel 一個變體 | 否 |
hd2d_anime_32frame |
保留 reference 構圖的 HD-2D anime strip | 是 |
- 圖像生成由 Codex CLI +
gpt-image-2完成
MIT — 見 LICENSE。