系統定位
Agent Sprite Forge 是供 Claude Code、Codex 與 Grok 使用的 2D 遊戲素材技能組。角色動畫流程以一張核准主圖固定外觀，每個動作生成一段影片，再處理去背、對位、循環、變速與封裝。
| 輸入 | 處理 | 輸出 |
|---|---|---|
| 角色描述、參考圖或既有主圖 | 生成候選、局部修改、人工核准 | 主圖與 master.json |
| 核准主圖、動作清單 | 每動作影片、QC、去背、對位及時序處理 | 畫格、循環或單次動作 |
| 完成畫格及選取時序 | HD 或像素後製、封裝與解碼驗證 | PNG 圖集、WebM、packed MP4、animation.json |
| 地圖規格與美術素材 | 碰撞、導覽與可達性檢查 | 地圖資料、預覽與匯出檔 |
遊戲邏輯仍需自行實作。碰撞、傷害、角色移動與狀態切換不由生成影片決定。
安裝與驗證
- 未完成：
已安裝 Python 3.10+，並確認
python指向該版本。 - 未完成：
已安裝 Git，以及使用中的 Claude Code 或 Codex。
- 未完成：
動畫流程需要 ffmpeg 5.1+、
libvpx-vp9與libx264編碼器，且 ffmpeg 可從 PATH 執行。 - 未完成：
已準備可用的媒體路徑：自己的 API 帳號、已登入的本機 CLI，或既有素材。
- 未完成：
已決定角色的顯示尺寸、朝向、HD／像素後製與輸出目標。
Claude Code 可使用官方 README 列出的 plugin 安裝流程：
claude plugin marketplace add 0x0funky/agent-sprite-forge --sparse .claude-plugin skills
claude plugin install agent-sprite-forge@agent-sprite-forge
python -m pip install "numpy>=1.26" "Pillow>=10.1" "scipy>=1.11"從乾淨的原始碼副本安裝 Codex 技能。後文的直接 CLI 範例也從這個 repository 根目錄執行。
git clone https://github.com/0x0funky/agent-sprite-forge.git
cd agent-sprite-forge
python -m pip install -r requirements.txt
python tools/install_skills.py --apply --host codex
python tools/install_skills.py --check --host codexCodex 預設位置為 ~/.codex/skills，設定 CODEX_HOME 時使用其下的 skills。若要安裝至 ~/.agents/skills，改用 --host agents；安裝工具會先備份既有副本並寫入 SHA-256 清單。
重新開啟 Agent 工作階段以載入技能，再檢查媒體路由與影片工具：
python skills/generate2dmedia/scripts/forge_doctor.py --no-exec --json
python skills/generate2dmedia/scripts/route_media.py resolve --kind image
python skills/generate2dmedia/scripts/route_media.py resolve --kind video
python skills/video2dsprite/scripts/video2dsprite.py doctor--no-exec 不啟動外部命令；部分能力可維持 UNKNOWN，路由解析也不代表帳號已完成生成驗證。forge_doctor.py --verify-route 搭配 --execute 會消耗一次配額，不屬於唯讀檢查。
核心能力
主圖與素材
$generate2dsprite
建立角色主圖與素材規格
生成、修改及核准角色主圖；處理道具、圖示與 FX 圖集。角色動作交給 video2dsprite，預設採 HD 後製。
角色動畫
$video2dsprite
主圖轉動作影片與畫格
每個動作使用同一張主圖，依序執行品質檢查、去背、對位、循環或變速、後製及封裝，也可處理使用者提供的影片。
地圖與場景
$generate2dmap
建立場景與可遊玩地圖資料
處理圖塊、道具、視差與 HD-2D 場景；以資料定義碰撞、出生點與出口。可達性檢查不驗證碰撞是否符合畫面。
媒體路由
$generate2dmedia
選擇生成服務並記錄呼叫
統一路由圖片及影片請求，檢查能力、保存工作紀錄與費用估算。素材規格與品質審核由其他技能處理。
程式繪圖
$codeart2d
規格驅動的像素、SVG 與特效
提供 PixelSpec、骨架動畫、程序式特效及圖塊工具。限明確要求或無可用生成路由時使用，具有自己的風格與尺寸限制。
角色動畫依序處理主圖、候選影片、畫格與封裝。QC 數值可找出比例或邊界問題，身分與動作仍需人工確認。
| 階段 | 工具 | 檢查內容 |
|---|---|---|
| 主圖 | master_still.py | 外觀、朝向、邊界、核准紀錄 |
| 動作候選 | sprite_set.py | 主圖一致性、動作清單、重試與修正語句 |
| 去背與對位 | video2dsprite.py、register_clip.py | alpha 邊緣、背景殘色、固定比例與錨點 |
| 循環或變速 | gait_loop.py、retime.py | 接縫、腳步接地、打擊事件及停留時長 |
| 後製 | finish_frames.py | 共用角色比例、顏色鎖定、HD 或像素輸出 |
| 封裝 | engine_export.py | animation.json、圖集、影片與解碼驗證 |
操作原則
主圖核准與局部修改
每個角色先核准一張主圖。接近需求的候選以 edit 指定單一修改，避免重新生成時改變武器、服裝或臉部；其他動作沿用主圖的身分描述與比例。
動作分段與遊戲邏輯
一段影片只處理一個動作。走路循環不可用倒放補齊，攻擊回復也不應反向播放；遊戲端控制位移、傷害與事件觸發。
共用尺度與去背設定
同角色的動作共用主圖比例與去背設定。不要逐格依 alpha 邊界縮放；主體顏色接近背景色時改用其他底色或保護色設定。
數值與視覺審核
開啟 contact sheet、完成畫格與角色比例並排圖。檢查臉、武器、朝向、接地與淺深背景上的邊緣；保留每項 WARN 或 FAIL，不將數值通過當成美術核准。
預設媒體路由先使用已設定金鑰的 API，再嘗試已登入的本機 CLI。專案將設定金鑰視為呼叫授權，生成時不逐次詢問；開始前先確認路由與費用設定。
| 路徑 | 可用範圍 | 操作限制 |
|---|---|---|
| API | OpenAI、Google Gemini、xAI、BytePlus、fal.ai 的已設定路徑 | 能力依服務與模型而異，明確選擇的路徑優先 |
| 本機 CLI | Codex／Grok 圖片；Grok 圖片轉影片 | 仍消耗訂閱配額，登入不等於 API 金鑰 |
| 程式繪圖 | 明確指定，或回報 no-route | 不可靜默代替已要求的生成素材 |
呼叫記錄保存在 .forge/ledger.jsonl，個別輸出含 job.json。預設沒有費用或配額上限；--budget-usd、--max-calls 與 FORGE_MAX_PAID_REQUESTS 需主動設定，FORGE_SESSION_IMAGES／FORGE_SESSION_VIDEOS 可限制種類配額。
--max-takes 限制每動作每輪候選數，並非專案費用上限。估價表不是即時帳單；缺少已確認價格時，--budget-usd 可能拒絕該路徑，不能假設每個供應商都可使用相同預算檢查。
操作範例
範例角色為側面朝右、穿青綠披風與紅圍巾的原創劍士 Aria，輸出待機、走路與攻擊。以下是供讀者執行的指令，未在本次查證中生成素材；所有路徑皆從已複製的 repository 根目錄起算。
先為新專案設定示例上限，再生成主圖。這些上限是操作範例，既有 ledger 記錄也會影響可用次數。
export FORGE_MAX_PAID_REQUESTS=4
export FORGE_SESSION_IMAGES=1
export FORGE_SESSION_VIDEOS=3
python skills/generate2dsprite/scripts/master_still.py generate \
--name aria --subject "a young swordswoman, full body" \
--identity "short dark hair, teal cloak, red scarf, one steel sword" \
--facing right --class hero --finish hd --takes 1 \
--output-dir art/aria-takes依生成結果 JSON 中的 takes[*].artifact 路徑開啟成功候選，檢查身分、朝向與邊界。至少 2 份候選成功時才建立 takes.png，本例的單份候選不會產生該圖。確認候選符合需求後，才核准主圖：
python skills/generate2dsprite/scripts/master_still.py approve \
--run art/aria-takes --take 1 --output-dir art/aria-master核准步驟寫入 master.png、master_rgba.png 與 master.json。建立動作計畫後，先閱讀 set_plan.json 中的提示與動作設定，再執行生成。
python skills/video2dsprite/scripts/sprite_set.py plan \
--master art/aria-master/master.json --output-dir art/aria-set \
--actions idle,walk,attack --finish hd --target-height 256 \
--max-takes 1 --jobs 1 --formats png,webm,packed
python skills/video2dsprite/scripts/sprite_set.py run --plan art/aria-set/set_plan.json
python skills/video2dsprite/scripts/sprite_set.py review --plan art/aria-set/set_plan.json檢查 review/ 下每個動作的 sheet、完成畫格及 lineup。範例限制每動作一份候選與單一生成工作；失敗時先讀 QC 與費用紀錄，不直接加大重試次數。
只有看過對應畫格且判定可用時，才逐項執行 accept。下例假設三個動作的第一份候選皆已通過人工審核。
python skills/video2dsprite/scripts/sprite_set.py accept --plan art/aria-set/set_plan.json --action idle --take 1
python skills/video2dsprite/scripts/sprite_set.py accept --plan art/aria-set/set_plan.json --action walk --take 1
python skills/video2dsprite/scripts/sprite_set.py accept --plan art/aria-set/set_plan.json --action attack --take 1
python skills/video2dsprite/scripts/sprite_set.py report --plan art/aria-set/set_plan.json
python skills/generate2dmedia/scripts/media_ledger.py summaryreport 列出路由、候選、QC、循環、時序與封裝路徑。再次執行同一計畫會沿用已存在的候選影片；需要修正時，使用 retake 指定問題，再確認費用上限後重跑。
報告中的 actions[*].outputs.package 路徑以素材組根目錄為準；影片解碼驗證通過後，對應目錄才會有 verify-qa.json。若另選候選或保留片段，核准後再執行 run 完成後製與封裝；需要重新驗證時，使用新的報告路徑以免覆蓋既有紀錄。
限制與注意事項
| 問題 | 影響 | 處理方式 |
|---|---|---|
| 快速肢體、跳躍或陌生服裝造成外觀漂移 | 武器改形、臉部遮蔽、比例改變 | 回看主圖及候選，指定局部修正或重拍 |
| 背景色接近角色顏色 | 去背侵蝕衣物或留下殘色 | 改底色、保護設計色，並在淺深背景檢查 |
| 手腳觸碰影片邊界 | 動作已被裁切 | 重新生成並增加動作空間；補白無法恢復缺少的畫面 |
| 最後一格或循環不符合起始姿勢 | 轉場跳動、走路接縫 | 檢查路由是否支援尾格，使用循環選取並實際播放 |
| 新輸出目錄已存在 | 工具拒絕寫入 | 使用新目錄；不要覆蓋上一份已核准交付物 |
sprite_set.py 的影片封裝使用 animation.json；generate2dsprite 的 export_engine.py --clips 需要另一種 animation-clips.json 契約。不要直接把前者傳給後者；Godot 或 Aseprite 交付前，先依 frames-and-clips 文件建立相符的 clip 資料，再匯出並在實際編輯器測試。
官方主要開發及測量環境為 Windows，macOS／Linux 尚未完成相同驗證。數值 QA 不核准解剖、角色身分或動作品質，程式工具的確定性也以相同建置環境為範圍。
後續操作
| 下一個需求 | 操作路徑 | 驗收重點 |
|---|---|---|
| 擴充跑步、跳躍或受傷 | 以同一主圖建立其他動作計畫 | 跨動作比例、接地與狀態切換 |
| 像素風格 | 指定 pixel 後製、共用色盤與固定畫格 | alpha、輪廓、像素網格與循環 |
| 可遊玩地圖 | 使用 generate2dmap 的資料、導覽與預覽流程 | 碰撞對照畫面、路徑可達性及出口 |
| 正式引擎交付 | 建立相容 clip 契約，使用對應 exporter | 編輯器實際匯入、事件與執行時播放 |
從官方 README 確認技能分工，依 sprite-set 文件調整動作與時序。交付前逐項核對已知限制，保存可重現的計畫、原始素材與 QA。