Sprite Forge 是做什麼的?
Sprite Forge 可將文字轉換為遊戲就緒的 2D 資產,並在此機器的 GPU 上執行(底層使用 ComfyUI;會自動啟動)。所有內容皆不會發送至付費服務。每個結果都會被裁剪出乾淨的邊緣、裁切、調整大小、檢查,並附帶清單儲存;系統會進行多次嘗試並保留最佳結果。
如何呼叫
優先使用 sprite-forge MCP 工具(當可用時):
list_profiles、generate_sprite、create_character、animate_pixel、make_normal_map、get_job、check_image、models、forge_status。
否則,請從 Sprite Forge 資料夾使用命令列;每個命令會輸出一個 JSON 物件:
python forge.py profiles
python forge.py sprite <name> "<prompt>" -p sprite --project <game folder>
python forge.py sprite <name> "<prompt>" -p pixel_sprite --set grid=32 --set palette=project --project <game folder>
python forge.py character <id> "<who, outfit, colours, props>" --project <game folder>
python forge.py sprite <name> -p turnaround --character <id> --set directions=8 --project <game folder>
python forge.py sprite <name> -p animation --character <id> --set action=walk --set facing=right --project <game folder>
python forge.py animate <name> <sprite.png> "<the motion>" --pose "<frame 1>" --pose "<frame 2>" ...
python forge.py normal <sprite.png>
python forge.py check <file.png> --kind sprite
退出碼 0 = 正常,2 = 已完成但結果未通過檢查,1 = 錯誤。
選擇設定檔
| 設定檔 | 用途 | 輸出 |
|---|---|---|
sprite | 道具、物品、拾取物、武器、家具、UI 元件 | 透明 PNG,已裁切,在方形畫布上居中 |
icon | 技能/物品圖示、徽章、按鈕 | 方形 PNG 加上 256/128/64 像素版本 |
pixel_sprite | 真正的像素藝術:角色、物品、敵人 | 真實像素網格(例如 32 像素),硬邊 Alpha,有限或具名色盤,加上 x8 預覽 |
character | 可重複使用的角色參考圖 | 全身透明 PNG,腳踩在地平線上 |
pixel_character | 同上,但以像素藝術風格繪製 | 像素藝術圖集的參考 |
turnaround | 角色面向 4 或 8 個方向 | 影格 + <name>_sheet.png + <name>.atlas.json |
animation | 走路、跑步、閒置、攻擊、跳躍、受傷、死亡、施法 | 影格 + 圖集 + 附帶動畫標籤的圖集 |
tile | 地面、牆壁、地板、水面、植被 | 無縫方形紋理 + 3x3 平鋪預覽(可選像素版本) |
portrait | 對話頭像、卡片、關鍵美術圖 | 全解析度影像 |
vfx | 爆炸、煙霧、魔法爆發、打擊火花 | 影格 + 圖集 + 圖集;亮度即透明度 |
animate_pixel(工具) | 根據描述為現有像素精靈添加動畫 | 在精靈自身網格與色盤上的影格 + 圖集 + GIF |
每個圖集也會生成 <name>.gif(循環播放),方便使用者觀看。
每種設定檔都有三個預設:fast(一次快速嘗試)、standard(預設值)、max(使用較大模型或更多嘗試;轉向/動畫使用 Qwen-Image-Edit)。請註明你使用了哪個預設。
工作流程
- 始終傳遞遊戲專案資料夾(
project_dir/--project)。其spriteforge.json提供了樣式、輸出資料夾、角色資料夾以及每個設定檔的設定,以保持遊戲美術風格一致。如果它沒有此檔案,請主動建立一個(forge.py init <dir>)。 - 按照設定檔的
prompt_guide編寫提示(list_profiles會回傳)。描述物件本身,而非圖片:不要寫「一個精靈圖」,不要寫背景,提示中不要出現鏡頭用語——請使用params.view設定角度(front view、side view、top-down view、isometric view)。 - 若角色會出現多次:請先建立它。
create_character(或使用設定了character的character設定檔)會儲存參考;轉向和動畫是基於它的編輯,因此角色能保持統一外觀。對於像素藝術圖集,請使用profile: "pixel_character"並傳遞params.pixel_grid(例如 32)給圖集。 - 較長的任務是非同步的。 如果工具回傳了一個任務 ID,請呼叫
get_job並設定wait_seconds: 50,直到狀態不再是queued或running。一次只能執行一個任務。 - 檢視預覽圖。 每個結果都會附帶一張預覽圖像(在棋盤格背景上的精靈)。在確認資產完成前請務必檢查:主體是否錯誤、是否被裁切、是否包含第二個物體、是否有光暈、影格是否不是同一個角色。回報該檔案、其尺寸、任何
problems,並提及.spriteforge/<name>/中的其他嘗試。
像素藝術
- 影像模型只會繪製像素藝術風格;Sprite Forge 會將其變為真正的像素藝術:它會找出模型的像素網格(或強制設定
grid),取每個儲存格的主色,移除雜散像素,讓 Alpha 通道完全開/關,並限制色盤。未經此步驟,切勿聲稱某個精靈是像素藝術。 grid:精靈最長邊的像素值(16、24、32、48、64)。設定為"auto"則保留模型繪製的像素大小。palette:pico8、gameboy、nes、endesga32、sweetie16、一組十六進制顏色列表,或**"project"**——為整個遊戲凍結一個色盤(由第一個像素資產儲存為專案中的palette.hex,後續所有資產皆重複使用)。對於一個遊戲,請使用"project"。outline: true會添加 1 像素的深色外框;canvas: 32會將精靈放置於 32x32 的網格上。- 不套用遞色(因為會導致動畫閃爍)。
為現有像素精靈添加動畫
當使用者已有像素精靈(自己的,或使用 pixel_sprite 製作的)並描述一個動作時,請使用 animate_pixel:例如「讓史萊姆彈跳」、「讓騎士揮劍」。它會在每個影格中保留精靈的準確像素尺寸和色盤。
image:PNG 圖像(原始尺寸最多 256 像素,或經過放大且像素硬邊的副本)。description:動作描述。walk / run / idle / attack / jump / hurt / death / cast 會使用內建的關鍵姿勢。- 對於其他動作,請自行編寫
poses:每個影格用一行簡短的文字說明變化,例如劍擊["將劍高舉過頭頂", "劍在頂點,身體向後傾", "將劍向下揮至身前", "攻擊後劍已放低"]。3-6 個影格效果最佳。這些是關鍵姿勢,而非中間影格。 params.include_original: true會將未修改的精靈作為第 0 影格;params.fps。- 檢視 GIF / 預覽:如果某個影格遺失或改變了精靈的一部分,請使用新的
seed或preset: "max"(每個影格更多嘗試)重新執行。
法線貼圖(2D 照明)
針對使用 2D 光照的遊戲(Godot CanvasTexture + Light2D、Unity 2D 光照、Phaser light2d),請傳遞 params.normal_map: true 給 sprite、icon、pixel_sprite、character、turnaround、animation 或 animate_pixel,或是在任何現有 PNG 上呼叫 make_normal_map。
- 寫入
<name>_normal.png(或<name>_sheet_normal.png,佈局與圖集相同)以及<name>_lit_preview.png(從左、上、右、下方向打光的精靈預覽)——請向使用者展示預覽圖。 - 像素藝術會保留其像素網格,並具有清晰、對齊的法線。
- 預設慣例為 OpenGL(綠色 = 向上),Godot 和 Unity 使用此慣例;若為 DirectX 則設定
normal_y: "down"/y: "down"。normal_strength0.5 為輕微,2 為強烈。 - 浮雕是從繪圖中推斷得出的(輪廓、顏色區域、亮部),並非實際建模:它在動態光源下表現良好,但並非真實的深度掃描。
當結果顯示 failed_check
檔案已寫入,但不應直接使用。problems 會說明原因。
| 問題 | 修復方式 |
|---|---|
cut off | 使用新的 seed 重新執行;加入 "small, centred, with space around it" 或提高 params.padding。 |
several objects | 僅命名一個物件;使用新的 seed 重新執行。 |
background not removed / empty | 描述一個實心物體;保持 background 簡單;重新執行。 |
may not look like the character(圖集) | 使用新的 seed 或 preset: "max" 重新執行該圖集;保持角色提示簡單。 |
may not have turned(轉向) | 使用 preset: "max" 重新執行(Qwen-Image-Edit 能更好地跟隨視角變化)。 |
no clear pixel grid found | 圖片並非以像素藝術方式繪製:將 grid 設定為一個數字,或重新執行。 |
visible seam(地磚) | 使用有機表面或提高 params.blend;重新執行。 |
much smaller than the original(animate_pixel) | 該影格遺失了精靈的一部分:使用新的 seed 重新執行,或提供更清晰的姿勢。 |
flat: almost a single colour | 模型繪製了一個剪影:使用新的 seed 重新執行;並加上「使用全彩」的描述。 |
相同的 name 加上相同的設定會回傳現有檔案;更改設定、seed,或傳遞 force: true 以生成新檔案。
自訂
- 每個專案:
spriteforge.json(style、style_preset、output_dir、characters_dir、profiles.<id>.params,例如{"pixel_sprite": {"params": {"grid": 32, "palette": "project"}}})。 - 每次呼叫:
params,例如{"size": 256, "candidates": 6, "view": "side view", "directions": 4, "action": "attack", "facing": "down"}。list_profiles會列出每個參數並附帶說明。 - 新增設定檔:在專案的
spriteforge_profiles/目錄下建立一個小的 JSON 檔案,並extends其中一個設定檔。 - 模型與硬體:
models工具會報告每個設定檔和預設需要哪些模型以及缺少哪些模型。下載檔案很大——請先詢問使用者再進行安裝。 - 授權:Sprite Forge 安裝的每個模型均允許對您製作的內容進行商業使用(FLUX.2 Klein 4B、Z-Image Turbo、Qwen-Image-Edit 2511 以及像素 LoRA:Apache 2.0;BiRefNet 和 CLIP:MIT)。部分商店(例如 Steam、itch.io)會要求您揭露 AI 生成的資產。