aldegad/sprite-gen

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

什么是 sprite‑gen？

sprite‑gen 是一个基于 Python 的命令行工具（也是 Codex/Claude 技能），可将游戏角色的单一静态插画转换为可直接使用的精灵表。它的工作方式如下：

提示图像模型（例如 Grok Imagine、Codex、Claude）为每个动画状态（空闲、行走、攻击等）生成一系列帧。
移除背景色键并提取干净、透明的 PNG 帧。
将这些帧组装成图集（sprite‑sheet‑alpha.png），并附带机器可读的清单（manifest.json.frame_layout），告知游戏引擎每帧的精确矩形、其 FPS 以及是否循环播放。
可选地，从视频片段生成循环、重新着色调色板、添加呼吸空闲循环，甚至从多个资产构建简单场景。

该工具面向希望获得高质量像素艺术精灵但不想手动绘制每一帧的独立开发者或爱好者。

主要功能（来自 README）

功能	作用	使用方法
图集行流水线 (A)	从一张基础图像生成透明精灵表 + 清单。包括自动“呼吸”空闲循环。	`prepare → gen-set → extract → compose-atlas`（CLI 命令）
视频转循环流水线 (B)	将基础图像输入视频模型，为每个运动状态生成无缝透明循环，然后按自然周期剪切片段。	`video-set`（创建工作）→ `video-canvas → video → video-frames → video-loop`
策展网页视图	交互式 UI，在烘焙最终图集之前比较、拒绝或调整生成的帧。	`sprite-gen curation --run-dir <run>`（可选）
实用工具 (C)	剪切单个图像、切片多单元表、将现有图集解包回单个帧。	`cutout`, `slice-sheet`, `unpack-atlas`
后处理 (D)	确定性重新着色、图层合成、导出为 Aseprite/Phaser/Flame 格式。	`recolor`, `compose-layers`, `export-aseprite`
资产工具 (E)	创建平铺背景、生成投影阴影、检查运动时间和接触点。	`background-tile`, `shadow`, `inspect-motion`
场景创建 (S)	组合多个精灵图集和其他 PNG，渲染带有相机和光照元数据的场景（PNG、MP4、GIF）。	`scene-render`, `scene-inspect`
朝向/左右手处理	检测或强制侧视精灵的左右朝向；如果错误，可以镜像或重新生成。	`--facing`, `--facing-fix` 标志（`gen`/`video-set`）
多提供商支持	支持 Codex、Claude、Grok Imagine，以及用于服务器端的显式 `openai` 提供商。	`--provider codex` 等
确定性输出	相同输入 → 相同输出字节（对版本控制很重要）。	`recolor-palette` + `recolor` 流水线

谁可能觉得有用？

独立游戏开发者：需要像素艺术角色，但没有时间或技能手动绘制每个动画帧。
像素艺术爱好者：希望尝试 AI 生成的运动循环，同时完全控制最终资产。
工具构建者：需要一种可编程的方式为流水线（例如游戏资产的 CI）生成精灵图集。

快速入门（来自 README）

# 1. 创建干净的虚拟环境并安装包
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. 从单个角色图像生成图集
sprite-gen prepare --out-dir run --character-id hero --base-image base.png
sprite-gen gen-set --run-dir run --provider codex   # 生成帧行
sprite-gen extract --run-dir run                  # 制作透明 PNG
sprite-gen compose-atlas --run-dir run            # 生成 sprite-sheet-alpha.png + manifest.json

# 3. （可选）打开策展 UI 调整帧
sprite-gen curation --run-dir run

对于基于视频的循环，请一次性安装 RIFE（sprite-gen rife install）并运行 video-set 工作流。

限制与注意事项（来自 README）

生成帧的质量取决于底层图像/视频模型；该工具只能微调或镜像帧，不能保证完美朝向。
方向检测（--facing-fix）默认是仅记录，即使高置信度也可能出错。
某些流水线（例如视频循环）需要外部凭据（grok CLI 登录或 XAI_API_KEY）。
“行走/奔跑”循环循环被标记为实验性，直到运动 QA 通过。
需要 Python 3.11+；不再支持 3.10。

许可证

Apache‑2.0 – 免费用于商业和非商业用途。

以上信息均直接来自仓库的 README，未添加任何外部假设。