Community影像github.com

PixelForge — 全功能視覺多模態像素畫與動圖工坊

用於從零構建像素畫/圖示/大尺寸分層精靈、逆向反編譯並局部修改已有 PNG/GIF/精靈表、將高分圖或 AI 草圖轉為乾淨像素畫(Pixelate)、提取參考圖色板與明暗色階、製作帶 RotSprite 部件旋轉與可變幀率節奏的多動作動圖(GIF/APNG/WebP/Aseprite 圖集)、無縫 Tileset 3x3 拼接檢測及九宮格 UI。凡涉及像素畫創作、像素修改、像素化處理或像素動畫時調用此技能。

PixelForge — 全功能視覺多模態像素畫與動圖工坊 是什麼?

PixelForge 是一個全面的像素藝術創作、修改和動畫技能,專為視覺 LLM(如 Claude Code、Cursor、Codex)設計。它提供從零開始創建像素畫、圖示、多層次精靈,以及逆向工程和局部修改現有 PNG/GIF/精靈表的能力。該技能支援將高解析度圖像或 AI 生成的草圖轉換為乾淨的像素藝術(像素化),並能提取參考圖像的調色板和明暗色階。對於動畫,它支援多動作動畫製作,包括 RotSprite 部件旋轉、可變幀率節奏,並能輸出為 GIF、APNG、WebP 和 Aseprite 圖集。此外,還包括無縫 Tileset 3x3 拼接檢測和九宮格 UI 設計。PixelForge 透過 CLI 工具(pforge.py)和 Python 庫(pixelforge)提供功能,並可透過 MCP 伺服器直接調用多種工具,如 pixelforge_build、pixelforge_build_rig 和 pixelforge_palette_guide。它強調使用等寬 ASCII 字符網格、結構化部件(Rig)和幾何基元來生成像素藝術,並透過全息診斷面板(inspect.png)和像素檢查器(Pixel Linter)進行品質控制。開發人員可以透過讀取專題指南(如 animation_and_rigging.md 或 tileset_and_ui.md)來深入學習特定工作流程。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/scvxzf1/pixel-forge/tree/main

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

PixelForge — 視覺大模型像素畫構建、精修與動畫套件

本技能透過 ./scripts/pforge.py(同時提供 CLI 命令行與 pixelforge Python 庫,僅依賴 Pillow)賦予視覺 LLM 工業級像素資產生產與逆向精修能力。

一、核心鐵律(嚴禁違反)

  1. 禁止手寫稀疏座標點列:嚴禁堆砌幾十行 putpixel((x, y))。基礎圖形必須使用等寬 ASCII 字符網格(. 和空格固定代表透明)、緊湊局部部件 Rig(僅畫部件本身並透過 offset=(ox, oy) 定位,無需填滿整張畫布空點),或 PixelCanvas 像素級幾何原語(抗 L 角直線、對稱橢圓、Bayer 有序抖動)。
  2. 按分辨率選擇正確架構:
    • 16x16 ~ 32x32:直接編寫全畫布 ASCII 網格或輕量 Rig。
    • 48x48 ~ 64x64:必須分層/分部件(使用無外描邊色塊部件 + Rig(..., outline_mode="selout"|"outer") 自動統合描邊);修改局部細節時優先使用 Region Patch 局部切片而非全圖重繪。
    • 64x64 ~ 128x128+:使用 PixelCanvas 幾何底稿 + stamp() 局部印章 + dither_rect() 有序抖動 + 局部 Region Patch 精修。
  3. 強制多模態全息視覺閉環:
    • 每次生成或修改都會輸出全息診斷看板 <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、零樣板代碼的調用方式:

  1. 查色板單字符色階(杜絕猜錯字符報錯):
    • MCP:pixelforge_palette_guide(palette="endesga32");CLI:python3 <SKILL_DIR>/scripts/pforge.py palette-guide endesga32
    • 直接獲取按色相分組的 暗部 -> 中間調 -> 高光 字符鏈(如 'b' -> 'B' -> 'C'),無需翻表猜測。
  2. 多部件角色 / Boss / 多動作分層 .aseprite(0 行 Python 代碼,零算術吸附):
    • MCP 直調 pixelforge_build_rig(或 CLI pforge.py build-spec spec.json / Python build_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!
  3. 16x16~32x32 圖示與單幀小物件:
    • MCP 直調 pixelforge_build(支援直接畫無描邊色塊並傳 outline_mode="selout", add_shadow=True 自動包邊加陰影)。
  4. 複雜程序化幾何 / 等軸測 / 實機戰鬥沙盒腳本:
    • 先運行 python3 <SKILL_DIR>/scripts/pforge.py init-script work/run.py --template rig|sprite|scene|iso 一鍵生成自動配好相對 sys.path 的可運行腳手架,再填入邏輯(免去手寫路徑拼接排錯)。

三、六大標準工作流

1. 從零構建像素畫與多動作動畫

  1. 選定調色板:優先選用內置經典色板 "endesga32"、"pico8"、"sweetie16"、"resurrect64"、"gameboy",或用 pforge.py palette <ref.png> 提取參考圖色板與色階。預設左上光源(左上高光暖移、右下暗部冷移),推薦開啟 outline_mode="selout"(自適應光源描邊)。
  2. 構建與綁定:
    • 拓撲變化大(走路交叉腿、張嘴獠牙變形)→ 用 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。
  3. 運行腳本導出 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(或 Python generate_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 原生工具優先:若當前會話已連接 pixelforge MCP 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)。

相關技能