sprite-gen

sprite-gen 既是 Codex / Claude 可用技能，也是一套 Python CLI 工具，专门解决AI图像模型生成游戏精灵图的常见缺陷：角色面部漂移、背景抠除不干净、帧姿势错位、不符合网格规范，产出素材无法直接导入游戏引擎。用户仅需要输入一张基准画稿，工具可以输出符合游戏开发标准的精灵图集，或是透明背景的动态循环素材。

核心工作机制

工具会锁定角色身份，自动剥离背景生成标准Alpha透明通道，按网格提取干净帧，并生成机器可读的manifest.json.frame_layout清单文件，记录帧坐标、帧率、循环标记，游戏引擎可直接读取。内置策展预览页面，在最终打包前，开发者可以对比、剔除不合格帧，微调参数，实时预览动画循环效果，补齐AI生成难以搞定的最后一步素材校验。

整套工作流支持代理调用：接收用户请求，校验权限，自动补齐缺失参数，执行流水线交付素材；策展视图为可选功能，参数配置可单独保存，不会互相覆盖。

五大流水线工具组与场景工作流

A · 图集流水线

输入静态基准图+角色状态列表，输出带透明通道精灵图集sprite-sheet-alpha.png和清单文件，还能在待机帧烘焙呼吸动画Breathe效果。

核心命令：prepare、gen-set、extract、compose-atlas、curation

B · 视频转循环流水线

基于静态原画，调用Grok Imagine生成动画，自动裁切为无缝透明GIF/WebP帧条带。行走、奔跑循环依靠RIFE做跳帧修复、周期对齐；缺少RIFE时直接裁切并给出警告。还支持处理角色左右手不对称道具，单独生成正反朝向素材。

核心命令：video-set、video-prompt

C · 实用切片工具

独立工具，可对单张图像或精灵图集做抠图、网格切片；也可以把成品图集解包，转为可策展管理的素材目录。

核心命令：cutout、slice-sheet、unpack-atlas

D · 后期处理流水线

对已经生成的精灵图集做二次加工，生成确定性配色变体、骨骼图层合成，导出Aseprite格式文件，适配Phaser、Flame游戏引擎。

核心命令：recolor-palette、recolor、compose-layers、export-aseprite

E · 素材辅助工具

处理生成后的美术资源，制作可平铺背景、投射地面阴影，检测运动时序、落地姿态；脚部边界模糊时会标记测量结果为未验证。

核心命令：background-tile、shadow、inspect-motion

S · 场景合成工作流（可选）

把精灵图集、帧序列素材放到画布，配置摆放、相机、灯光，渲染PNG、MP4/GIF，并输出场景元数据。精灵素材生成步骤可独立于场景渲染。

交付物与关键特性

1. 标准透明精灵图集：真正Alpha透明通道，消除色键残留边缘，采用解混算法处理边缘。
2. 运行时清单 manifest.json.frame_layout：记录每帧矩形范围、帧率、循环标识，引擎无需手动计算网格。
3. Breathe待机呼吸动画：在策展完成的帧上烘焙像素级的形变效果，保持角色解剖结构。
4. Backbone Lattice网格系统：统一测量角色主体，保证所有帧严格对齐网格。
5. 运动循环处理：不同动作适配不同画布尺寸，自动识别循环周期；单次动作裁切为「静止→动作→静止」结构。
6. 确定性配色：相同输入固定输出，批量生成多套调色变体。
7. 内置QA校验：自动生成每个状态的GIF和总览表，方便人工审核运动效果。

环境与安装说明

• Python版本：CPython 3.10+，CI覆盖3.10、3.14，推荐全新虚拟环境venv运行。
• 基础依赖：Pillow、NumPy；视频流水线额外需要ffmpeg、img2webp，Grok动画需要XAI_API_KEY或本地Grok登录凭证。

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
sprite-gen --help

也可以作为AI技能安装到Codex：

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo aldegad/sprite-gen --path . --name sprite-gen

图像生成复用用户已订阅的Codex、Grok服务；OpenAI调用需要显式开启，单独计费，仓库不内置任何API密钥。