開源工具使用手冊 · 遊戲開發 / AI 圖像

Sprite-gen
透明動畫
與遊戲圖集

Sprite-gen 是 Python CLI 與 Codex／Claude Skill，從一張角色圖片建立透明影格、動畫預覽與遊戲圖集。它提供逐狀態圖片生成及影片轉動畫兩條流程，並以 manifest 記錄影格位置；交付前仍需檢查角色一致性、去背邊緣與動作連續性。

主要 Sprite 生成流程

3.11+

CPython 支援下限

2.11.0

本次核對的套件版本

2.0

Apache 原始碼授權

工具定位與產出

角色參考圖與
影格資料契約

Sprite-gen 以一張已確認的角色全身圖作為外觀參考。圖集流程為每種狀態生成一列姿勢，再移除色鍵背景、抽取透明影格並組合圖集；影片流程則將靜態圖交給 Grok Imagine，再從影片擷取透明動作序列。

遊戲端讀取 manifest.json.frame_layout 的絕對影格座標，並依 manifest 的動畫設定播放。不要從透明區域猜測格線，也不要把模型直接輸出的原始姿勢列當成最終素材。

適用情境包括角色短動作、遊戲原型與既有素材整理。官方將圖片生成路徑中的精確循環行走列為實驗性範圍；產出有影格、有透明背景，仍不代表動作已通過檢查。

A · 逐狀態圖集流程

確認角色圖→ prepare→ gen-set→ extract→ compose-atlas→ 動畫檢查

檔案用途

sprite-request.json：狀態、影格數、fps、色鍵與尺寸等設定。
sprite-sheet-alpha.png 與 manifest.json：遊戲圖集及對應播放資料。
curation.json：人工挑選、排序與影格變形設定；修改後重新組合輸出。
qa/ 與 qa-notes.md：動畫預覽、影格總覽與逐狀態檢查紀錄。

來源：Run contract、狀態與影格建議。

Python CLI 與 Skill

安裝與
執行環境

使用支援 venv 與 ensurepip 的 CPython 3.11 以上版本。先取得官方原始碼並進入專案根目錄，再執行 README 的安裝指令；套件相依包含 Pillow 與 NumPy。

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

Codex Skill 安裝入口

若 Codex 環境中已有官方 skill-installer，README 提供以下指令。安裝 Skill 後，仍須在它的實際安裝目錄完成上方虛擬環境設定。

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

依流程準備生成服務

GPT 圖片列：使用 gen-set --provider codex，先確認 Codex 登入與本次帳號的圖像使用權限。
影片轉動畫：另外需要 ffmpeg／ffprobe、img2webp 與自己的 Grok 登入或 XAI_API_KEY。
伺服器圖像生成：openai 是需明確選用、按次計費的 provider，不應視為訂閱路徑失敗時的自動替代。

來源：README、服務選擇與存取檢查、執行環境。

新終端機與 Agent 子程序。未啟用虛擬環境時，使用安裝目錄內的 .venv/bin/sprite-gen 絕對路徑。--help 能列出命令代表 CLI 可載入，不代表生成服務的配額或媒體權限已確認。

生成流程與獨立工具

命令分組與
選用方式

兩條生成流程各自有固定順序。去背、換色與場景工具可依素材狀態獨立使用，無須每次重跑生成。

A · 準備

prepare

建立 Run

根據角色圖及請求設定，建立提示詞、版面引導圖與工作目錄。

A · 生成

gen-set

逐狀態 姿勢列

使用同一角色參考生成各狀態的原始圖片列；GPT 圖片流程明確指定 codex。

A · 去背

extract

抽取 透明影格

處理色鍵、分離姿勢並依設定放置影格。角色重疊遮住的像素無法靠裁切還原。

A · 組合

compose-atlas

圖集與 Manifest

將影格及 curation 編輯結果組成透明圖集，記錄遊戲端使用的座標。

B · 影片動畫

video-set

影片轉 透明動作

依方向與狀態執行畫布、影片、去背影格和動作裁切；輸出 strip、GIF、WebP 與報告。

C · 素材整理

cutout / slice-sheet

既有素材 去背與拆分

處理獨立圖片或匯入的格狀圖片。既有圖集可用 unpack-atlas 轉成挑選用 Run。

D · 人工整理

curation

挑選與 動作預覽

在本機網頁介面調整順序、位置與變形；設定保存在 curation.json。

D · 後製

recolor / compose-layers

配色與 圖層組合

從完成的圖集產生配色變體，或依 rig 宣告合成圖層，不必重新生成圖片。

D · 引擎匯出

export-aseprite

相容 JSON

提供 Phaser／Flame 可讀的 Aseprite 格式資料；沿用既有 PNG，不產生 .aseprite 原始檔。

E · 獨立工具

inspect-motion

動作與 接觸量測

檢查重複姿勢、時序與接觸證據。同組還有 background-tile 與 shadow。

S · 選用流程

scene-render

既有素材 場景合成

讀取素材與 scene.json 的放置、鏡頭及光源設定，產生畫格或影片。

設定 · 工作入口

workflow

存取與 選擇檢查

唯讀檢查登入、已存偏好與缺少的選項，回傳 ready、needs-input 或 blocked。

依目標選擇流程

目前素材與目標	入口	交付檢查
角色圖 → 短動作圖集	A · 逐狀態圖集流程	透明圖集、座標與動作預覽
角色圖 → 影片衍生動作	B · 影片動畫流程	結果表、動作檔案與品質報告
既有圖集 → 挑選與修整	匯入 → 挑選 → 組合	套用人工修改後的正式匯出
完成素材 → 場景影片	S · 場景合成流程	場景設定、畫格與檢查資料

來源：官方流程索引、命令路由、引擎匯出。

官方操作原則

生成與檢查的
六項約束

以下依官方流程文件整理。先固定素材與設定，再檢查生成結果，避免用後製掩蓋動作缺陷。

角色參考圖鎖定

確認全身未被裁切，比例、風格、方向與角色外觀符合目標。像素風格需要參考圖本身具有可量測的格線。

來源 · atlas-workflow

數值設定集中管理

尺寸、影格數、fps 與色鍵由 sprite-request.json 管理。使用 prepare 產生提示詞與版面引導，避免在多處手動維護同一數值。

來源 · run-contract

生成服務明確指定

workflow 檢查登入與缺少的選項；登入狀態不保證媒體權限或剩餘配額。GPT 姿勢列使用 codex，角色底圖所選的服務可獨立設定。

來源 · user-workflow

先交付檔案，再選用挑選介面

Curation 是選用步驟。若人工調整了順序或影格，重新組合圖集或匯出 curated 結果，避免交付尚未套用編輯的 frames/ 快取。

來源 · curation、run-contract

動態檢查與逐格檢查

同時觀看 GIF 與影格總覽。循環動作檢查首尾銜接；單次動作檢查起始、過程及結束。動作失敗時重生該列，不以改播放速度代替通過判定。

來源 · qa-motion

單一工作目錄的寫入權

同一個 Run 由單一工作者寫入。抽取失敗會留下 extract-failure.json；先讀取原因並修正，不繞過完整影格檢查強行組合圖集。

來源 · run-contract

三種短動作的圖集範例

角色圖片到
可檢查的輸出

以下為依官方指令改寫的操作範例，未在本文製作時呼叫生成服務。假設已完成安裝並啟用虛擬環境，準備好 base.png，且已確認 Codex 帳號可執行本次圖像生成。

先將下列內容存成專案根目錄的 request.json。設定取自官方簡單動作建議：idle 循環播放，attack 與 jump 為單次動作；此範例不包含行走與跑步。

{
  "states": {
    "idle": {
      "frames": 4, "fps": 4, "loop": true,
      "action": "subtle breathing and one blink"
    },
    "attack": {
      "frames": 4, "fps": 8, "loop": false,
      "action": "simple windup, strike, recovery attack pose sequence with no detached effects"
    },
    "jump": {
      "frames": 4, "fps": 8, "loop": false,
      "action": "simple jump arc: crouch, takeoff, airborne, landing"
    }
  }
}
      

sprite-gen · 操作範例，非實測紀錄

# 1. 建立角色 Run 與生成材料 sprite-gen prepare --out-dir runs/hero \ --character-id hero --base-image base.png --request request.json

# 2. 呼叫已確認可用的生成服務；此步驟會使用服務額度 sprite-gen gen-set --run-dir runs/hero --provider codex

# 3. 抽取透明影格；發生錯誤時先停止並讀取報告 sprite-gen extract --run-dir runs/hero

# 4. 組合圖集、產生預覽與結構檢查 sprite-gen compose-atlas --run-dir runs/hero sprite-gen compose-gif --run-dir runs/hero --out-dir runs/hero/previews sprite-gen inspect --run-dir runs/hero

# 5. 在原始碼根目錄產生 QA 影格總覽與 GIF .venv/bin/python scripts/preview_animation.py --run-dir runs/hero

# 人工檢查 qa/ 動畫與圖像，將各狀態結果記錄於 qa-notes.md # 檢查通過後，若需 Aseprite 相容資料，再執行： sprite-gen export-aseprite --run-dir runs/hero

交付驗收條件

sprite-sheet-alpha.png 存在；角色影格非空，透明邊緣沒有不必要的色鍵殘留。
manifest.json.frame_layout 可對應實際圖集的每個影格；檢查抽取與組合報告中的失敗項目。
qa/idle.gif 首尾可銜接；attack、jump 的起始、中間與結束動作可辨識。
qa-notes.md 記錄各狀態的 pass、best-effort 或 experimental，不以檔案存在代替動作品質判定。
如有執行引擎匯出，exports/aseprite.json 與圖集一起交付；遊戲程式仍需依 manifest 設定單次或循環播放。

人工挑選後的重新輸出

執行 sprite-gen curation --run-dir runs/hero 可開啟本機挑選介面。修改完成後，重新執行 compose-atlas、預覽及需要的匯出步驟，再檢查更新後的動畫。

來源：範例設定、執行順序、動作檢查。

品質與執行限制

使用邊界與
失敗處理

精確行走仍需逐次驗證。官方將 walk／run 等循環移動列為實驗性狀態，除非本次動作連續性檢查已通過。角色只有上下晃動、腳底漂移或首尾跳動時，不能標示為通過。
朝向偵測可能誤判。即使回報高信心也需要看圖確認。預設 --facing-fix none 只記錄；選用 mirror 或 regen 前先核對，鏡像會交換左右側裝備的位置。
提示詞無法還原裁掉的肢體。影片生成前需要足夠畫布空間。video-set 對 jump 與 attack 使用不同畫布配置；已在原始影片中出框的部分無法靠去背補回。
登入、訂閱與配額是不同資訊。workflow 的登入探測不證明本次媒體使用權限。API 路徑可能使用另外計費的額度；先明確選定服務與計費方式，不默默切換 provider。
後製取決於素材是否完整。姿勢可分離時，extract 能處理偏離格線的角色；被其他姿勢遮住的像素無法由固定裁切補齊。動作失敗應重生該狀態並重新檢查。
Aseprite 匯出有格式邊界。輸出為相容 JSON，不是可編輯的 .aseprite 檔。loop 政策保留在 manifest；官方說明其 CI 未執行 Phaser 瀏覽器或 Flutter runtime 整合測試。
原始影格不包含全部人工修改。curation 的選擇、變形與像素編輯由 compose／export 套用。對外提供單張 PNG 時，使用 curated 匯出，不直接複製 frames/。
本機 Run 不具資料庫等級的中斷保證。一般程序例外有回復機制，但強制終止程序可能留下混合狀態。保留錯誤報告，依一致性檢查結果重新執行；不要刪除報告假裝成功。

來源：動作限制、朝向選項、影片畫布、匯出限制、資料與中斷保證範圍。

進階路徑

影片動作與
引擎整合

後續操作順序

完成一組短動作。先依範例建立 idle、attack、jump，確認透明影格、播放設定與 QA 紀錄一致。
評估影片路徑。準備符合色鍵背景要求的角色圖、Grok 存取與影片工具，再使用下方 README 指令。檢查 set/table.md 與各項報告。
確認方向。側面素材需讓角色圖、畫布與提示詞的 facing 一致；若角色朝左，依文件明確指定 --facing left。
依引擎匯出。Phaser 使用預設 Aseprite JSON；Flame 依官方文件使用 --format json-hash --split-states。在目標遊戲中驗證速度、影格範圍與 loop 行為。
加入選用後製。有配色、圖層或場景需求時，再閱讀 recolor、layer-tracks 與 scene 文件。場景合成可在 Sprite 素材交付後獨立進行。

sprite-gen video-set --base side=still.png --states idle,walk,run,jump,attack --out-dir set/
      

影片路徑的獨立驗收。此指令使用 Grok 影片服務；輸出逐項整理在 set/table.md，不是 A 路徑的 runtime atlas。即使成功寫出 GIF／WebP，仍需播放檢查動作、輪廓與首尾銜接。

官方延伸閱讀

User workflow：服務選擇、登入檢查及獨立保存的 Sprite／Image 偏好。
Video pipeline：畫布、影格去背、單次動作與循環裁切。
Engine export：Phaser／Flame 格式、時長映射與播放限制。

本手冊核對於 2026-09-27，對應原始碼 b725baa；套件版本依 pyproject.toml 為 2.11.0。命令與限制以該版本文件為依據，更新後請重新核對。