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)。