PixelForge — 視覺大模型像素畫構建、精修與動畫套件
本技能透過 ./scripts/pforge.py(同時提供 CLI 命令行與 pixelforge Python 庫,僅依賴 Pillow)賦予視覺 LLM 工業級像素資產生產與逆向精修能力。
一、核心鐵律(嚴禁違反)
- 禁止手寫稀疏座標點列:嚴禁堆砌幾十行
putpixel((x, y))。基礎圖形必須使用等寬 ASCII 字符網格(.和空格固定代表透明)、緊湊局部部件Rig(僅畫部件本身並透過offset=(ox, oy)定位,無需填滿整張畫布空點),或PixelCanvas像素級幾何原語(抗 L 角直線、對稱橢圓、Bayer 有序抖動)。 - 按分辨率選擇正確架構:
16x16 ~ 32x32:直接編寫全畫布 ASCII 網格或輕量Rig。48x48 ~ 64x64:必須分層/分部件(使用無外描邊色塊部件 +Rig(..., outline_mode="selout"|"outer")自動統合描邊);修改局部細節時優先使用 Region Patch 局部切片而非全圖重繪。64x64 ~ 128x128+:使用PixelCanvas幾何底稿 +stamp()局部印章 +dither_rect()有序抖動 + 局部 Region Patch 精修。
- 強制多模態全息視覺閉環:
- 每次生成或修改都會輸出全息診斷看板
<name>_inspect.png(內含:字符色板圖例[char] #HEX+ 0 起始(X, Y)座標網格與地面基準線 + 無網格深/淺雙底實機預覽 + 剪影與紅青洋蔥皮運動軌跡)及終端Pixel Linter報告。 - 交付前必須調用看圖工具(如
read_file/view_image/Read)親自查看<name>_inspect.png(修改任務還需查看<name>_diff.png)! - 對照圖上座標與 Linter 警告,逐一排查:外輪廓漏口(尤其在淺色底預覽下檢查深色描邊)、斜線/弧線階梯鋸齒(Jaggies)、幀間腳底漂移(
baseline_y)及非預期改動像素,修完複檢通過後方可交付。
- 每次生成或修改都會輸出全息診斷看板
二、Agent 零摩擦最短路徑決策樹(優先零腳本直出!)
動手前按以下優先級選擇最省 Token、零樣板代碼的調用方式:
- 查色板單字符色階(杜絕猜錯字符報錯):
- MCP:
pixelforge_palette_guide(palette="endesga32");CLI:python3 <SKILL_DIR>/scripts/pforge.py palette-guide endesga32 - 直接獲取按色相分組的
暗部 -> 中間調 -> 高光字符鏈(如'b' -> 'B' -> 'C'),無需翻表猜測。
- MCP:
- 多部件角色 / Boss / 多動作分層
.aseprite(0 行 Python 代碼,零算術吸附):- MCP 直調
pixelforge_build_rig(或 CLIpforge.py build-spec spec.json/ Pythonbuild_from_spec(spec)):- 容錯網格語法:支援
|..BBBB..| # 行尾註釋視覺對齊豎線與pad_ragged=True自動補齊漏寫的末尾.! - 語義關節吸附(免算座標與軸心):主軀幹設
at="center",其餘部件直接寫attach_to="torso", side="top"|"left"|"right"|"bottom", hinge="grip",canvas_size="auto"自動測算全身包圍盒並預留揮劍防裁切邊距。 - 一動作預設:
clips={"idle": "idle_breathe", "attack": "melee_attack", "hit": "hurt_flash"}(還支援"float_bob"、"slime_bounce"或自定義poses),自動附帶刀光/煙塵特效、陰影與多圖層.aseprite!
- 容錯網格語法:支援
- MCP 直調
- 16x16~32x32 圖示與單幀小物件:
- MCP 直調
pixelforge_build(支援直接畫無描邊色塊並傳outline_mode="selout", add_shadow=True自動包邊加陰影)。
- MCP 直調
- 複雜程序化幾何 / 等軸測 / 實機戰鬥沙盒腳本:
- 先運行
python3 <SKILL_DIR>/scripts/pforge.py init-script work/run.py --template rig|sprite|scene|iso一鍵生成自動配好相對sys.path的可運行腳手架,再填入邏輯(免去手寫路徑拼接排錯)。
- 先運行
三、六大標準工作流
1. 從零構建像素畫與多動作動畫
- 選定調色板:優先選用內置經典色板
"endesga32"、"pico8"、"sweetie16"、"resurrect64"、"gameboy",或用pforge.py palette <ref.png>提取參考圖色板與色階。預設左上光源(左上高光暖移、右下暗部冷移),推薦開啟outline_mode="selout"(自適應光源描邊)。 - 構建與綁定:
- 拓撲變化大(走路交叉腿、張嘴獠牙變形)→ 用 ASCII 關鍵幀或
Part多狀態字典{"closed": ..., "open": ...}。 - 剛體旋轉/擠壓(箱蓋繞鉸鏈掀開、揮劍、呼吸彈跳)→ 用
Rig+rotsprite繞錨點旋轉與squash_stretch。 - 打擊感節奏 → 必須使用非均勻
durations_ms(如蓄力180ms→ 爆發揮砍40ms→ 頓幀55ms→ 緩衝150ms),配合vfx_slash_arc/vfx_dust_puff/vfx_hit_spark。 - 單角色多動作(
idle/walk/attack)→ 使用SpriteActor一鍵導出獨立動圖與合併圖集<actor>_master_atlas.png/.json。
- 拓撲變化大(走路交叉腿、張嘴獠牙變形)→ 用 ASCII 關鍵幀或
- 運行腳本導出 GIF + 真半透明 APNG + 無損動態 WebP + Aseprite JSON,讀取
_inspect.png視覺自檢並消缺。
2. 基於已有像素畫做修改(PNG / GIF / 精靈表)
- 先看圖診斷:
(註:引擎會自動識別python3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/4x/8x整數倍放大預覽圖並無損還原為1x原生像素網格;若需保留原尺寸加--keep-scale。) - 小圖/全幀反編譯修改:
自動拆解所有幀與幀時長,生成帶語義字符色板的python3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/edit_walk.py與_inspect.png,修改腳本後重跑即可。 - 大圖局部手術式精修(Region Patch,強烈推薦 48x48+ 使用):
必須讀取生成的# 1) 按 0 起始座標框 (X,Y,W,H) 切出局部網格,生成的自檢圖自動保留全局 X/Y 座標刻度! python3 <SKILL_DIR>/scripts/pforge.py region-extract hero.png --box 14,6,20,18 -o work/patch/ # 2) 編輯切出的 .txt 字符網格後回寫,自動輸出 Before | After | Diff 三聯對比圖 python3 <SKILL_DIR>/scripts/pforge.py region-apply hero.png --patch work/patch/hero_x14_y6_w20_h18.json -o work/out/*_diff.png,確認改動嚴格落在目標區域且邊緣銜接自然。 - 一鍵語義換色 / 陣營變體:
python3 <SKILL_DIR>/scripts/pforge.py recolor slime.gif --map B=R,b=r,C=Y -o work/fire_slime/
3. 高分圖 / AI 概念草圖轉像素畫(Pixelate & Clean)
當用戶提供高分辨率插畫、照片或邊緣糊亂的 AI「偽像素圖」時:
# 插畫/概念圖用 contrast_box;AI 偽像素圖用 --mode dominant_block 消除歪斜網格與雜色
python3 <SKILL_DIR>/scripts/pforge.py pixelate draft.png --size 48x48 --palette endesga32 --outline "#181425" -o work/px/
讀取生成的 *_compare.png 與 *_inspect.png,在自動生成的 edit_*.py 中手工點亮眼睛高光、修順輪廓階梯後再交付。
4. 無縫地圖塊、47塊自動地形(Auto-Tile)、九宮格 UI、等軸測與實機場景明度自檢
- 無縫單磚與九宮格 UI:
pforge.py tile grass.png(3x3 接縫斷層標紅檢測);pforge.py nine-slice frame.png --margins 4,4,4,4 --size 160x56。 - 47塊 Blob / 16塊 Wang 自動拼接地形:僅提供前景/背景兩張底磚,調用
pforge.py autotile --fg grass.png --bg water.png --mode blob47(或 Pythongenerate_blob47_tileset),自動合成全部內外轉角並鋪出測試群島地圖*_blob47_inspect.png。 2:1等軸測建築與 4/8 向 RPG 角色:使用IsoScene構建零裂縫2:1三面受光等軸測體塊場景;使用DirectionalRig+export_multidir_sheets從正面部件派生S/E/N/W四向或八向旋轉與行走圖集,並讀取*_alignment_inspect.png核對頭頂/腳底水平對齊線。- 多資產實機場景沙盒與灰度明度自檢:使用
SceneComposer+render_pixel_text(內置緊湊像素字庫)+build_scene_mockup合成帶 Y 軸遮擋排序與跳字 UI 的實機戰鬥/探索動圖,必須讀取*_scene_inspect.png檢查純灰度瞇眼圖與輪廓對比度熱力圖,消除角色融入背景的明度打架問題。
5. HD-2D 像素法線動態光影與「生圖拆件 → 自動綁骨(Sketch-to-Rig)」
- HD-2D 法線貼圖與 360° 火把受光:調用
pforge.py normalmap hero.png --emit "#2CE8F5"或export_hd2d_bundle(..., part_layers=rig.render_part_layers(..., part_profiles={"sword": "ridge"})),一鍵導出兼容 Godot/Unity 的*_albedo.png、*_normal.png、*_emission.png與*_torch_orbit_6x.gif,並查看*_hd2d_inspect.png四象限點光源驗證圖。 - 爆炸設定圖自動拆件綁骨(Sketch-to-Rig):對純色底部件分解概念圖運行
pforge.py autorig sheet.png --canvas 56x56 --palette endesga32(邊緣漫水安全去底、連通域拆件、統一比例鎖色、肩/頸/劍柄軸心推斷),查看*_autorig_pipeline.png後在生成的rig_*.py上繼續精修動作。
6. 原生 .aseprite 二進制分層工程讀寫與 MCP 工具直調
- 雙向
.aseprite工程支援:所有構建流程預設直出原生二進制<name>.aseprite;使用Rig.render_named_layers_sequence(poses)+write_aseprite(...)可將各部件與特效保存為獨立時間軸圖層 + 動作標籤 + 關節軸心 Slice,人類畫師可在 Aseprite 中直接分層續畫;已有.ase/.aseprite文件可直接用pforge.py aseprite-inspect file.aseprite --unpack-layers或decompile逆向拆解。 - MCP 原生工具優先:若當前會話已連接
pixelforgeMCP Server(暴露pixelforge_palette_guide、pixelforge_build、pixelforge_build_rig、pixelforge_region_patch、pixelforge_scene_check、pixelforge_aseprite_inspect等 12 個工具,且每次返回均附帶agent_checklist.must_view_images與(x, y)修復處方),優先直調 MCP 工具替代手寫臨時腳本。
四、Python 零算術聲明式模板
import sys
sys.path.insert(0, "/path/to/pixel-forge/scripts")
from pforge import build_from_spec, format_palette_guide
# 零算術座標構建多部件、多動作、帶獨立圖層 .aseprite 的角色
res = build_from_spec({
"name": "ember_knight",
"palette": "endesga32",
"canvas_size": "auto",
"outline_mode": "selout",
"parts": [
{"name": "torso", "at": "center", "grid": ["|..RRRR..| # 胸甲", "|.RYYYYR.|", "|RRRRRRRR|", "|.rrrrrr.|"]},
{"name": "head", "attach_to": "torso", "side": "top", "grid": ["|.1111.|", "|1KKKK1|", "|.2222.|"]},
{"name": "sword", "attach_to": "torso", "side": "right", "hinge": "grip", "outline_group": 1,
"grid": ["|.W.|", "|.1.|", "|YYY|", "|.o.|"]},
],
"clips": {"idle": "idle_breathe", "attack": "melee_attack", "hit": "hurt_flash"},
}, output_dir="output")
# 隨後務必用視覺工具查看 res["agent_checklist"]["must_view_images"] 中的全部看板!
五、進階參考手冊(按需讀取,漸進式披露)
執行具體細分任務前,請按需查閱本技能目錄下的專題指南:
- 像素畫造型、色簇抗鋸齒、明暗色階與抖動技法:craft_and_shading.md
- 逆向拆解、大圖局部 Patch 手術與 AI 圖像素化精修:edit_and_pixelate.md
- 多部件骨骼 Rig、RotSprite 旋轉、打擊感幀長配方與特效庫:animation_and_rigging.md
- 無縫 Tileset 3x3 拼接設計與 9-Slice UI 規範:tileset_and_ui.md
- 47塊自動地形、實機場景明度自檢、2:1 等軸測與 4/8 向角色派生:world_iso_and_scene.md
- HD-2D 像素法線動態光影與 AI 設定圖自動拆件綁骨:hd2d_and_autorig.md
- 原生
.aseprite分層二進制工程讀寫與 MCP Server 指南:aseprite_and_mcp.md - 完整 CLI 參數與 Python API 速查字典:cli_and_api.md
- 可運行實戰範例腳本:參見
./examples/目錄下的 10 個端到端腳本(01~10)。