aldegad/sprite-gen · 上手攻略

  • 仓库：aldegad/sprite-gen
  • 链接：https://github.com/aldegad/sprite-gen
  • 分类：工具 · 游戏美术生成
  • 作者：Tom
  • 更新：2026-08-09

这是什么

sprite-gen 是一个面向游戏美术的 AI 驱动精灵图（sprite atlas）生成 pipeline，以 Codex/Claude Skill 形式运行。给一张角色基础图，它驱动 AI 图像模型逐动作状态（idle、jump、attack…）生成一行帧图，依次完成去背景、连通分量提取、帧切割、帧级别校正，最后打包出一张含真实 alpha 通道的透明精灵图集（sprite-sheet-alpha.png）和一个机器可读的运行时 manifest（manifest.json.frame_layout）。内置可选的 Web curation 界面，可在打包前人工筛选、调整、预览动画。

核心设计理念：生成给你 90%，人工 curation 补完最后 10%——pipeline 做重复劳动，人保持审美判断。

快速安装

环境要求：Python 3.10+（CI 在 3.10–3.14 上验证），支持 macOS / Linux。

# 1. 创建虚拟环境并安装依赖（Pillow、NumPy）
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. 准备一个角色运行目录
python3 scripts/prepare_sprite_run.py \
  --out-dir ./runs/howl \
  --character-id howl \
  --base-image ./base-source.png

# 3. 用 AI 引擎生成各状态行图（示例用 Codex）
python3 scripts/generate_sprite_image.py \
  --provider codex \
  --prompt-file ./runs/howl/prompts/idle.txt \
  --out ./runs/howl/raw/idle.png \
  --ref ./runs/howl/base-source.png \
  --ref ./runs/howl/references/layout-guides/idle.png

# 4. 提取帧
python3 scripts/extract_sprite_row_frames.py --run-dir ./runs/howl

# 5. （可选）打开 curation webview 人工筛选
python3 scripts/serve_curation.py --run-dir ./runs/howl --lang en

# 6. 打包运行时精灵图集
python3 scripts/compose_sprite_atlas.py --run-dir ./runs/howl

输出在 --out-dir 下：sprite-sheet-alpha.png（透明精灵图集）+ manifest.json.frame_layout（帧矩形坐标、fps、循环标记，供游戏引擎直接消费）。

核心用法

完整 pipeline 概览

sprite-request.json
  → layout guides + prompts    (prepare_sprite_run.py)
  → AI 生成每状态一行图        (generate_sprite_image.py，AI 模型调用)
  → chroma 去背景              (extract_sprite_row_frames.py)
  → 连通分量 → 透明帧
  → 可选：webview curation   (serve_curation.py，非破坏性)
  → 精灵图集 + manifest.json   (compose_sprite_atlas.py)

帧去背细节（chroma alpha）

工具自动根据背景色走两条路： - magenta / green key：AI 生成时默认使用的背景色，走软 alpha 分离（soft-alpha unmix），保留发丝级抗锯齿； - white / matte：走 corner flood-fill，适用于截图、图标等。

# 手动指定去背策略
python3 -m sprite_gen.cli cutout icon.png --key auto
# auto 根据四角颜色自动判断；可选 --key white|magenta|green

Pixel-unfake（像素艺术专用网格对齐）

AI 生成的"像素风"往往在格子内漂移，--fit pixel_unfake 用 Backbone Lattice 机制全局测量一个基准网格，让整条动画的所有切割都锚定在同一网格上，保证 walk cycle 里每帧的像素块大小一致：

# 在 sprite-request.json 中声明 pixel_unfake
# fit.pixel_unfake = true
# fit.logical_height = 64
# fit.palette_size = 24

⚠️ 走动类动画（walk/run）标记为 experimental，需要 motion QA 实际通过才能认为可用。

色彩变体（recolor）

同一张精灵图集，无需重新生成，即可烘焙多套配色方案：

# 提取当前不透明色到调色板草稿
python3 -m sprite_gen.cli recolor-palette \
  --base ./runs/howl/sprite-sheet-alpha.png \
  --out palette.draft.json

# 手动编辑 palette.draft.json 为 recolor.spec.json，然后烘焙
python3 -m sprite_gen.cli recolor \
  --run-dir ./runs/howl \
  --spec recolor.spec.json

# 在 curation webview 中 blink-compare 并采纳
python3 -m sprite_gen.cli curation --run-dir ./runs/howl

几何形状和 alpha 通道从不移动，variant sheets 的基础 manifest 描述所有变体。

呼吸动画（breathe）

单帧 + 烘焙 squash & stretch，无需重新生成：

"breathe": { "depth": 0.05, "breaths": 3 }

引擎测量剪影（颈部瓶颈、双眼对称、躯干 vs 附肢宽度），对翅膀和手臂做推压变形，像素边缘保持像素级对齐。

精灵图集解包与重建

已有精灵图集但想重新 curation：

# 从精灵图集重建 curation 可用目录
python3 scripts/unpack_atlas_run.py --atlas ./sprite-sheet-alpha.png

# 从 manifest 精确还原（exact rectangles）
python3 scripts/unpack_atlas_run.py --manifest manifest.json.frame_layout

# 从松散 PNG 文件夹导入
python3 scripts/unpack_atlas_run.py --pngs-dir ./furniture/

典型适用场景

  • 独立游戏开发：快速用 AI 生成角色动画序列，配合 curation 保证帧质量，跳过传统逐帧外包流程。
  • VTuber / 数字人资产：一套角色基础图生成 idle / 说话 / 开心等多状态，输出直接可用于实时引擎。
  • AI 美术工作室：提供一致的 sprite 生成 pipeline + 人工审查节点，批量生产角色变体和色彩方案。
  • 像素艺术资产维护：用 pixel-unfake 把 AI 生成的"伪像素风"还原为真正的网格对齐像素图。

坑与注意

  1. 走动类动画（walk/run）仍是 experimental：标签里没有隐瞒，但需要人工 motion QA 实际通过才算可用——不要默认认为走动动画能直接交付。

  2. 生成步骤依赖外部 AI 模型：pipeline 本身不包含扩散模型，需要自己提供 Codex 或 Claude 的 API 访问权限（即 --provider codex 实际调用的是 Codex CLI）。

  3. Python 3.10+ 是硬性要求：如果 python3 -m venv 在某个发行版上失败，需要使用标准 CPython build 而非系统自带版本。

  4. chroma 背景色选 magenta/green 以外时需慎：白色/米色背景用 matte extraction，如果角色本身有大面积白色则可能误切。工具支持 --key auto 自动判断四角颜色。

  5. Webview curation 需要图形环境：如果在没有显示器的服务器上跑，serve_curation.py 无法弹出浏览器，需要用 --run-dir 输出静态预览。

  6. Curation 是非破坏性的：所有帧变换记录在 curation.json sidecar 文件中，原始 PNG 永远不被覆写，最终打包时才应用变换。

  7. 单次运行独占锁：runio.py 在运行时持有写锁，同一 run dir 不能并发跑两个脚本，防止数据竞争。

与同类对比

工具 类型 核心功能 优势 局限
sprite-gen AI pipeline + 工具集 AI 驱动逐状态生成 + 去背 + 帧提取 + 打包 + recolor 完整 pipeline、webview curation、pixel-unfake、manifest 可供引擎直接消费 依赖外部 AI 模型，走动类动画仍 experimental
Adobe GenAI Spritesheet Generator 在线工具 单次生成精灵图 适合无代码用户 无帧级 curation、无 alpha 精度保障、无多色彩变体
Spritefusion Pro 游戏引擎插件 实时像素生成 集成在 Unity/Unreal 非 AI pipeline，需要大量人工调整
手动使用 Stable Diffusion 手工 + AI 逐帧生成 完全控制 无 pipeline 保障帧间一致性，切割和 alpha 纯手工

一句话推荐结论

sprite-gen 把 AI 生成和游戏引擎可消费资产之间的 gap 真正填上了——pipeline 保证帧间一致性和可重复的 alpha 质量，webview curation 让人类保持最终审美控制。如果你用 AI 生成角色动画资产，这是目前最完整的开源方案。