agent-sprite-forge 詳細教學

Codex-first 2D 遊戲資產 skill：generate2dsprite + generate2dmap，從自然語言到 engine-ready PNG / GIF 的雙 skill 工作流完整剖析。

1. 專案定位

agent-sprite-forge 不是 prompt 集合，也不是 stable-diffusion wrapper，而是一個 agent skill pack：把「2D 遊戲美術生產流程」拆成兩個職責清晰的 Codex skill。

設計三原則：

Agent 主導創意決策 — sheet size、frame count、bundle 結構由 agent 從自然語言推理，不要求使用者填規格表。
Image gen 主導視覺 — 所有 raw sprite / map art 走 built-in image_gen，禁止 Three.js / Canvas / SVG / HTML-CSS / PIL shape drawing / procedural geometry / placeholder primitives 等「程式畫圖」。
Script 只當 deterministic processor — magenta chroma-key 去背、frame 切割、connected component 過濾、對齊、QC metadata、透明 PNG/GIF 匯出。腳本不寫創意 prompt，也不畫最終圖。

對什麼使用者最有價值：

用 Codex / Claude Code 做 indie game prototype 的開發者
要產 Godot / Unity / Phaser 可直接 import 的 sprite atlas 與 tilemap
想跳過 Photoshop 手切 frame 與 chroma-key 的 game jam 團隊

規模指標：2436 ⭐ / 246 🍴（2026-05-29），開源不到 6 週爆紅，主要靠 Codex 社群帶動。

2. 安裝指南

2.1 系統需求

Python 3.10+（推薦 3.11；類型註解用 dict[str, object] 新語法）
一個支援 Agent Skills 的 Codex / Claude Code / OpenAI Agent runtime
至少 2GB 可用磁碟（生成圖的 outputs/ 會長很快）

2.2 步驟

 1# 1. clone
 2git clone https://github.com/0x0funky/agent-sprite-forge.git
 3cd agent-sprite-forge
 4
 5# 2. 安裝 Python 依賴（依 CLAUDE.md 規範，優先用 uv）
 6uv venv && source .venv/bin/activate
 7uv pip install -r requirements.txt
 8# 或：pip install -r requirements.txt
 9
10# 3. 驗證 sprite processor 可用
11python skills/generate2dsprite/scripts/generate2dsprite.py list-options
12
13# 4. 把 skills/ 註冊到你的 agent runtime
14# Codex: codex skills add ./skills/generate2dsprite
15# Claude Code: 複製到 ~/.claude/skills/ 或 .claude/skills/

2.3 requirements.txt 全文

1numpy>=1.26
2Pillow>=10.0

就這兩個。整個專案沒有任何網路、資料庫、雲端 SDK 相依。

3. 核心架構解析

雙 skill 並行，共用「agent 推理 → image_gen → script 後處理」三段式：


flowchart TD
    U["User: 自然語言請求
『幫我做一個側視英雄攻擊動畫』"] --> A{"Codex Agent
推理 asset_type / mode"}

    A -- "sprite / character / FX" --> S1["generate2dsprite SKILL.md
agent 寫 art prompt"]
    A -- "map / scene / parallax" --> M1["generate2dmap SKILL.md
agent 寫 map prompt"]

    S1 --> IG1["built-in image_gen
raw sheet on #FF00FF"]
    M1 --> IG2["built-in image_gen
base + props on #FF00FF"]

    IG1 --> P1["generate2dsprite.py process
chroma-key + split + align + QC"]
    IG2 --> P2["extract_prop_pack.py
+ compose_layered_preview.py"]

    P1 --> O1["transparent PNG frames
+ GIF + pipeline-meta.json"]
    P2 --> O2["base.png + props/ + layered-preview.png
+ engine metadata JSON"]

    O1 --> E["Godot / Unity / Phaser
engine import"]
    O2 --> E

3.1 兩個 skill 的職責切分

Skill	處理目標	關鍵腳本	Magenta 規則
`generate2dsprite`	角色 / 怪物 / NPC / 法術 / 投射物 / 衝擊 / 道具 / FX	`generate2dsprite.py` (911 行)	`#FF00FF` solid 背景，預設 threshold=100
`generate2dmap`	場景 base / 分層地圖 / prop pack / parallax / tilemap	`extract_prop_pack.py` (337 行) + `compose_layered_preview.py` (143 行)	base 可選 magenta，prop pack 強制 magenta

3.2 為什麼用 #FF00FF magenta？

絕對不會出現在自然色彩中（人眼少見、AI 生成偏 warm tone）→ chroma-key 不誤砍主體。
純 RGB(255, 0, 255)，單一閾值距離計算 就能精準分離 (color_distance 函式)。
業界標準（早期 game asset workflow 沿用至今）。

3.3 兩段 threshold 設計

generate2dsprite.py 的 remove_bg_magenta() 用兩個閾值：

threshold=100：核心區域分離（內部像素必須距 magenta > 100 才保留）
edge_threshold=150：邊緣容忍（避免抗鋸齒像素被誤殺）

這也是 #3 issue「透明通道紫色殘留」的源頭：非 pixel art 的漸層邊緣容易卡在 100–150 之間，留下紫色 halo。

4. Helper Scripts 詳細用法

4.1 generate2dsprite.py

雙子命令架構：

 1# 列所有支援的 target / mode / NPC role
 2python generate2dsprite.py list-options
 3
 4# 由 agent 呼叫：建立 prompt（不會自動跑 image_gen）
 5python generate2dsprite.py build-prompt \
 6  --target player --mode 2x2 \
 7  --prompt "side-view warrior with sword, idle loop" \
 8  --write /tmp/prompt.txt \
 9  --write-json /tmp/prompt.json
10
11# image_gen 完成後：後處理 raw sheet
12python generate2dsprite.py process \
13  --input /tmp/raw-sheet.png \
14  --target player --mode 2x2 \
15  --output-dir ./outputs/hero_idle \
16  --component-mode largest \
17  --align feet \
18  --shared-scale \
19  --threshold 100 --edge-threshold 150

關鍵 flag：

Flag	意義	用在哪
`--component-mode largest`	只留最大的 connected component	英雄 body sheet（避免 FX 殘片）
`--component-mode all`	保留所有 component	FX / projectile / impact sheet
`--align center/bottom/feet`	各 frame 對齊基準	walk/run 通常 `feet`；idle hover 用 `center`
`--shared-scale`	所有 frame 共用同 scale	hero body 強制開（避免幀間 size 漂移）
`--reject-edge-touch`	觸邊就 reject 整張	嚴格 QC 流程

4.2 extract_prop_pack.py

把一張 2x2 / 3x3 / 4x4 magenta-background 的 prop sheet 切成獨立 PNG：

1python extract_prop_pack.py \
2  --input /tmp/cyber-canal-prop-pack.png \
3  --rows 3 --cols 3 \
4  --output-dir ./outputs/cyber_canal/props \
5  --labels "barrel,crate,lamp,sign,terminal,vent,pipe,grate,puddle"

每個 cell 內：去 magenta → connected component → alpha bbox → trim → 寫 PNG + sidecar JSON metadata。

4.3 compose_layered_preview.py

把 base.png + 多個 prop PNG（含 placement metadata JSON）合成 QA preview：

1python compose_layered_preview.py \
2  --base ./outputs/stoneford/base.png \
3  --props-manifest ./outputs/stoneford/props.json \
4  --output ./outputs/stoneford/layered-preview.png

props.json 結構：[{path: "props/lamp.png", x_pct: 0.42, y_pct: 0.68, anchor: "bottom"}, ...]。

5. 應用場景

5.1 indie game prototype（最強場景）

1User: "我要做側視 ARPG，主角持劍，需要 idle / run / attack / jump，配 hit FX"
2Agent → generate2dsprite × 5：
3  - idle 2x2 body grid
4  - run 2x3 body grid（feet aligned, shared scale）
5  - attack 2x2 body-only（不含劍光弧）
6  - jump 2x2 body grid
7  - slash_arc 2x2 FX sheet（component_mode=all）
8Agent → 自動組 engine atlas 給 Godot

5.2 tower defense / survivors-like 場景

1User: "Godot tower defense，森林主題"
2Agent → generate2dmap：
3  - scene_mode + clean_hd + 32×32 tile align
4  - base.png：純地面（無樹、無塔位）
5  - dressed reference：在 base 上 view_image 再生成
6  - prop pack 3x3：樹 / 塔位 / 石頭 / 灌木 / 路標 / ...
7  - extract_prop_pack.py 切 9 個 PNG
8  - compose_layered_preview.py 合成 QA preview
9  - 輸出 .tscn 場景 + Y-sort + collision metadata

5.3 game jam 48 小時 sprint

把「美術瓶頸」從 4–8 小時砍到 30–60 分鐘，agent 自動處理 prompt 細節 + chroma-key + frame split。

5.4 已收錄 showcase（README）

Godot tower defense（forest theme）
Unity WebGL survivors-like
JavaScript RPG（Phaser-like）
Pokémon-like overworld + monster sprites

6. 資安掃描報告

6.1 掃描範圍

項目	結果
Network call（curl / wget / requests / urllib）	❌ 無
`eval` / `exec` / `os.system` / `subprocess`	❌ 無
`pickle` / `__import__` / `shell=True`	❌ 無
Hardcoded secret / token / API key	❌ 無
`input()` / 互動式提示（可被注入）	❌ 無
File write 限制	✅ 僅寫 `--output-dir` 指定路徑
Path traversal 防護	✅ 用 `Path()` 統一處理，無字串拼接
第三方依賴	✅ 僅 numpy + Pillow（兩個業界主流套件）

6.2 紅黃綠燈總評

🟢 綠燈（低風險）

評語：純本地圖像處理工具，零網路 / 零外部呼叫 / 零密碼處理 / 零 shell 注入面。整個 codebase 只有 numpy 陣列運算 + Pillow Image.open / save。可放心在離線 / 公司內網環境跑，唯一可能風險是 Pillow / numpy 本身的 CVE（建議 pip-audit 定期掃）。

6.3 補充注意

項目	注意點
🟡 中性提醒	生成圖經 built-in `image_gen` 走第三方 LLM endpoint（OpenAI / Anthropic），prompt 內容會送雲端 — 若 prompt 含敏感 IP（角色設計稿、客戶素材），須走機密邊界。
🟡 中性提醒	`outputs/` 預設 `.gitignore`，不會誤 commit 生成圖；但要小心多人協作時 outputs/ 體積膨脹。
🟢 正面	`agents/openai.yaml` 的 `allow_implicit_invocation: true` 表示 agent 會主動觸發 — 是設計意圖，非風險。

7. FAQ

Q1. issue #3 提到「透明通道紫色殘留」怎麼辦？ A：典型出現在非 pixel art（clean HD / hand-painted）的邊緣抗鋸齒像素。三個解法：

把 --edge-threshold 從 150 降到 100–120
後處理用 PIL 對 alpha < 255 的邊緣做 dilation + premultiply
在 image_gen prompt 強調 “hard-edged silhouette, no anti-aliasing border”

Q2. 為什麼禁止 1xN single-row sheet？ A：image_gen 在水平長條圖上容易：(1) 主體 horizontal drift；(2) 各 frame 比例不一致；(3) crop 不齊。改用 multi-row 後三個問題同時解決。

Q3. 我可以拿來生 logo / UI / icon 嗎？ A：技術上可以（chroma-key 通用），但 skill 設計目標是「遊戲動態資產」。靜態 logo / UI 直接走 image_gen + Pillow 後處理就好，不必走這套。

Q4. 跟 stable-diffusion ControlNet pipeline 比？ A：定位不同。本 repo 是「agent 用自然語言驅動的整合式遊戲資產 skill」，sd 是「pixel-level 視覺控制」。組合使用：用 sd 產 raw，再丟進這個 repo 的 process 命令做切割對齊。

Q5. 為什麼 sprite skill 才 263 + 911 行就賣得這麼好？ A：價值在「規則 prompt」，不在 code 行數。SKILL.md 與 references/ 把多年踩坑經驗（feet anchor / shared scale / body-only / FX 分離 / no 1xN）codify 給 agent，讓 Codex 一次到位、不需多輪 retry。

8. 進階技巧

8.1 hero_action_bundle 工作流（README 推薦）

不要一次 prompt 出 4x4 包含 idle/run/attack/jump 的 atlas。改：

逐 action 出 2x2/2x3 grid（agent 嚴控 body scale + feet anchor 跨 action 一致）
每張 QC（reject if --reject-edge-touch 命中）
過 QC 後用 Python 把 4 張合成 engine-required atlas
寫 origin / anchor metadata JSON（Godot SpriteFrames、Unity AnimationClip 都吃）

8.2 reference handoff 模式

讓 image_gen 認得「dressed reference」就是「base + 提案物件」的延伸：

先 generate base，存檔
馬上 view_image 把 base 載入 conversation context
下一次 image_gen prompt 明寫「use the image immediately above as visual reference, preserve horizon / road shape / entry direction」
生 dressed reference 後才進 prop 生成階段

8.3 stage_canvas 統一原則（side-scroll 場景）

如果做 platformer：

一開始就鎖 stage_canvas=1536x864（除非 engine 已用其他比例）
sky / far_bg / mid_bg / near_bg / foreground_overlay 同一 canvas size
不同 layer 只差 scroll_factor（0.1 / 0.3 / 0.6 / 0.9 / 1.2）
不要為 parallax 改 aspect — 解析度跑掉會在運行時 stretching artifact

8.4 prop pack 分類

square 包（2x2/3x3/4x4）只放 compact 物件（桶、燈、箱、招牌、終端機）。禁止放：platform / floor / bridge / wall / ladder / gate / door / long hazard / 寬高物件 / 帶 collision 的物件 — 那些用 1x3/1x4 strip 或 custom wide cell 或 tileset atlas。

9. 整合進其他工作流

對接點	整合方式
Godot 4.x	`extract_prop_pack.py` 直出 PNG → import 後設 `Y-Sort` → `compose_layered_preview.py` 的 JSON 可直接生 `.tscn` placeholder（README 範例有）
Unity 6 / 2D Tilemap	`generate2dmap` 走 `tile_mode`；切好的 PNG 用 Sprite Editor 設 9-slice / pivot
Phaser 3	sprite atlas + `pipeline-meta.json` 直接讀，frame 名稱對齊 anim key
Three.js + 2D plane	透明 PNG / GIF 當 texture，配 plane + alphaTest 0.5
本 template 工作流	`gh-tutorial-qd:` (Layer 12) 把本 repo 包成教學交付；`docling:` 處理 README 表格；`paper-tutorial:` 不適用（非學術 paper）

10. 重點摘要 Checklist

我理解 agent 寫 prompt、image_gen 出圖、script 後處理 的三段式
我知道 #FF00FF 是強制 chroma-key 背景，不能改成其他色
我會用 --shared-scale + --align feet 處理英雄 body sheet
我會用 --component-mode largest（body）/ all（FX）區分情境
我不會用 1xN single-row sheet
我會逐 action 出 grid + QC，過了才合成 engine atlas
我知道 playable map 的 base 不能 bake runtime object
side-scroll 我會鎖一個 stage_canvas 給所有 layer 共用
我清楚這 repo 零網路 / 零 subprocess，可放公司內網跑
我會留意非 pixel art 的紫色 halo（issue #3）並調 --edge-threshold

11. 進一步閱讀

原始 repo：https://github.com/0x0funky/agent-sprite-forge
5 種語言 README（英 / 繁中 / 簡中 / 日 / 韓）
skills/generate2dsprite/references/prompt-rules.md（319 行 prompt 規則精華）
skills/generate2dsprite/references/modes.md（124 行模式對照）
skills/generate2dmap/references/map-strategies.md（341 行 map 選型決策樹）
skills/generate2dmap/references/layered-map-contract.md（layer 分離合約）
skills/generate2dmap/references/prop-pack-contract.md（prop 分類規則）
showcase: README §Showcase（Godot / Unity / Phaser-like 完整 demo）
同類比較：CLAUDE.md Layer 4 graphify（codebase 知識圖）/ Layer 8 docling（PDF 結構化）— 本 repo 屬於「agent skill 設計範本」可作為自製 skill 的參考底座

本教學由 AI-Knowledge Template / Layer 12 gh-tutorial-qd 自動生成於 2026-05-29。資安結論：🟢 綠燈 — 純本地圖像處理，零網路 / 零 subprocess / 零密碼面。

agent-sprite-forge 詳細教學 — Codex 2D 遊戲資產雙 skill 完整指南

Contents

agent-sprite-forge 詳細教學

1. 專案定位

2. 安裝指南

2.1 系統需求

2.2 步驟

2.3 requirements.txt 全文

3. 核心架構解析

3.1 兩個 skill 的職責切分

3.2 為什麼用 #FF00FF magenta？

3.3 兩段 threshold 設計

4. Helper Scripts 詳細用法

4.1 generate2dsprite.py

4.2 extract_prop_pack.py

4.3 compose_layered_preview.py

5. 應用場景

5.1 indie game prototype（最強場景）

5.2 tower defense / survivors-like 場景

5.3 game jam 48 小時 sprint

5.4 已收錄 showcase（README）

6. 資安掃描報告

6.1 掃描範圍

6.2 紅黃綠燈總評

6.3 補充注意

7. FAQ

8. 進階技巧

8.1 hero_action_bundle 工作流（README 推薦）

8.2 reference handoff 模式

8.3 stage_canvas 統一原則（side-scroll 場景）

8.4 prop pack 分類

9. 整合進其他工作流

10. 重點摘要 Checklist

11. 進一步閱讀

Comments

agent-sprite-forge 詳細教學 — Codex 2D 遊戲資產雙 skill 完整指南

Contents

agent-sprite-forge 詳細教學

1. 專案定位

2. 安裝指南

2.1 系統需求

2.2 步驟

2.3 requirements.txt 全文

3. 核心架構解析

3.1 兩個 skill 的職責切分

3.2 為什麼用 #FF00FF magenta？

3.3 兩段 threshold 設計

4. Helper Scripts 詳細用法

4.1 generate2dsprite.py

4.2 extract_prop_pack.py

4.3 compose_layered_preview.py

5. 應用場景

5.1 indie game prototype（最強場景）

5.2 tower defense / survivors-like 場景

5.3 game jam 48 小時 sprint

5.4 已收錄 showcase（README）

6. 資安掃描報告

6.1 掃描範圍

6.2 紅黃綠燈總評

6.3 補充注意

7. FAQ

8. 進階技巧

8.1 hero_action_bundle 工作流（README 推薦）

8.2 reference handoff 模式

8.3 stage_canvas 統一原則（side-scroll 場景）

8.4 prop pack 分類

9. 整合進其他工作流

10. 重點摘要 Checklist

11. 進一步閱讀

Related Posts

Comments