角色參考圖與影格資料契約
Sprite-gen 以一張已確認的角色全身圖作為外觀參考。圖集流程為每種狀態生成一列姿勢，再移除色鍵背景、抽取透明影格並組合圖集；影片流程則將靜態圖交給 Grok Imagine，再從影片擷取透明動作序列。
遊戲端讀取 manifest.json.frame_layout 的絕對影格座標，並依 manifest 的動畫設定播放。不要從透明區域猜測格線，也不要把模型直接輸出的原始姿勢列當成最終素材。
適用情境包括角色短動作、遊戲原型與既有素材整理。官方將圖片生成路徑中的精確循環行走列為實驗性範圍；產出有影格、有透明背景，仍不代表動作已通過檢查。
確認角色圖
prepare
gen-set
extract
compose-atlas
動畫檢查
檔案用途
sprite-request.json：狀態、影格數、fps、色鍵與尺寸等設定。sprite-sheet-alpha.png與manifest.json：遊戲圖集及對應播放資料。curation.json：人工挑選、排序與影格變形設定；修改後重新組合輸出。qa/與qa-notes.md：動畫預覽、影格總覽與逐狀態檢查紀錄。
來源：Run contract、狀態與影格建議。
安裝與執行環境
使用支援 venv 與 ensurepip 的 CPython 3.11 以上版本。先取得 官方原始碼並進入專案根目錄，再執行 README 的安裝指令；套件相依包含 Pillow 與 NumPy。
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
sprite-gen --helpCodex 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，不應視為訂閱路徑失敗時的自動替代。
命令分組與選用方式
兩條生成流程各自有固定順序。去背、換色與場景工具可依素材狀態獨立使用，無須每次重跑生成。
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 prepare --out-dir runs/hero \
--character-id hero --base-image base.png --request request.json
> sprite-gen gen-set --run-dir runs/hero --provider codex
> sprite-gen extract --run-dir runs/hero
> 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
> .venv/bin/python scripts/preview_animation.py --run-dir runs/hero
> 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、預覽及需要的匯出步驟，再檢查更新後的動畫。
使用邊界與失敗處理
影片動作與引擎整合
後續操作順序
**完成一組短動作。**先依範例建立 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/官方延伸閱讀
User workflow：服務選擇、登入檢查及獨立保存的 Sprite／Image 偏好。
Video pipeline：畫布、影格去背、單次動作與循環裁切。
Engine export：Phaser／Flame 格式、時長映射與播放限制。
本手冊核對於 2026-09-27，對應 原始碼 b725baa；套件版本依 pyproject.toml 為 2.11.0。命令與限制以該版本文件為依據，更新後請重新核對。