PixelForge — Visual Large Model Pixel Art Construction, Refinement, and Animation Suite
This skill provides industrial-grade pixel asset production and reverse refinement capabilities to visual LLMs via ./scripts/pforge.py (which offers both a CLI command line and the pixelforge Python library, relying only on Pillow).
I. Core Mandates (No Violation Allowed)
- No Hand-Writing Sparse Coordinate Points: Do not pile up dozens of
putpixel((x, y))lines. Basic shapes must use monospace ASCII character grids (.and space fixedly represent transparency), compact local partRig(draw only the part itself and position it viaoffset=(ox, oy), no need to fill the whole canvas with empty dots), orPixelCanvaspixel-level geometric primitives (anti-L corner lines, symmetric ellipses, Bayer ordered dithering). - Choose Correct Architecture by Resolution:
16x16 ~ 32x32: Directly write a full-canvas ASCII grid or a lightweightRig.48x48 ~ 64x64: Must be layered/component-based (use un-outlined color block parts +Rig(..., outline_mode="selout"|"outer")for automatic unified outlining); when modifying local details, prioritize Region Patch local slices over full-image redraw.64x64 ~ 128x128+: UsePixelCanvasgeometry draft +stamp()local stamping +dither_rect()ordered dithering + local Region Patch refinement.
- Mandatory Multimodal Holographic Visual Closure:
- Each generation or modification outputs a holographic diagnostic board
<name>_inspect.png(containing: character palette legend[char] #HEX+ 0-based(X, Y)coordinate grid with ground baseline + ungridded light/dark dual-background real preview + silhouette and red-cyan onion skin motion trail) and a terminalPixel Linterreport. - Before delivery, you MUST use an image viewing tool (e.g.,
read_file/view_image/Read) to personally inspect<name>_inspect.png(for modification tasks, also inspect<name>_diff.png)! - Cross-reference coordinates on the image and the Linter warnings, one by one to check for: gaps in the outer contour (especially check dark outlines on a light background preview), staircase jaggies on diagonal/curved lines, foot baseline drift between frames (
baseline_y), and unintended pixel changes. Only pass for delivery after fixing these issues and re-checking.
- Each generation or modification outputs a holographic diagnostic board
II. Agent Zero-Friction Shortest Path Decision Tree (Prioritize Zero-Script Direct Output!)
Before starting, choose the calling method that saves the most tokens and requires zero boilerplate code, in the following priority order:
- Look Up Single-Character Shade Steps in Palette (Avoid Errors from Guessing the Wrong Character!):
- MCP:
pixelforge_palette_guide(palette="endesga32"); CLI:python3 <SKILL_DIR>/scripts/pforge.py palette-guide endesga32 - Directly obtain character chains (
shadow -> midtone -> highlight) grouped by hue (e.g.,'b' -> 'B' -> 'C'), no need to rummage through tables guessing.
- MCP:
- Multi-Part Character / Boss / Multi-Action Layered
.aseprite(0 Lines of Python Code, Zero Arithmetic Snapping):- Directly call MCP
pixelforge_build_rig(or CLIpforge.py build-spec spec.json/ Pythonbuild_from_spec(spec)):- Forgiving Grid Syntax: Supports
|..BBBB..| # Inline commentfor visually aligned vertical lines andpad_ragged=Trueto automatically fill in missing trailing.! - Semantic Joint Attachment (No Need for Coordinate or Pivot Calculation!): Set the main body part's
at="center", other parts just writeattach_to="torso", side="top"|"left"|"right"|"bottom", hinge="grip", withcanvas_size="auto"automatically calculating the full body bounding box while preserving margin for sword swing to prevent cropping. - One-Liner Animation Presets:
clips={"idle": "idle_breathe", "attack": "melee_attack", "hit": "hurt_flash"}(also supports"float_bob","slime_bounce", or customposes), automatically includes slash/dust VFX, shadow, and multi-layered.aseprite!
- Forgiving Grid Syntax: Supports
- Directly call MCP
- 16x16~32x32 Icons and Single-Frame Small Objects:
- Directly call MCP
pixelforge_build(supports directly drawing un-outlined color blocks and passingoutline_mode="selout", add_shadow=Truefor automatic border and shadow addition).
- Directly call MCP
- Complex Procedural Geometry / Isometric / Real-Time Combat Sandbox Scripts:
- First run
python3 <SKILL_DIR>/scripts/pforge.py init-script work/run.py --template rig|sprite|scene|isoto one-click generate a runnable scaffold with pre-configured relativesys.path, then fill in the logic (avoiding manual path concatenation and debugging).
- First run
III. Six Standard Workflows
1. Building Pixel Art and Multi-Action Animation from Scratch
- Choose a Palette: Prefer built-in classic palettes like
"endesga32","pico8","sweetie16","resurrect64","gameboy", or usepforge.py palette <ref.png>to extract a palette and shade steps from a reference image. Default top-left lighting (top-left highlight warm shift, bottom-right shadow cold shift), recommended to enableoutline_mode="selout"(adaptive lighting outline). - Build and Rig:
- Large topology changes (walking leg crossing, open mouth fang deformation) -> Use ASCII keyframes or a
Partmulti-state dictionary{"closed": ..., "open": ...}. - Rigid body rotation/squash (box lid opening on hinge, sword swing, breathing bounce) -> Use
Rig+rotspritefor rotation around anchor point andsquash_stretch. - Hit feel rhythm -> Must use non-uniform
durations_ms(e.g., charge180ms-> explosive swing40ms-> pause frame55ms-> recovery150ms), paired withvfx_slash_arc/vfx_dust_puff/vfx_hit_spark. - Single character, multiple actions (
idle/walk/attack) -> UseSpriteActorto one-click export individual animations and a merged atlas<actor>_master_atlas.png/.json.
- Large topology changes (walking leg crossing, open mouth fang deformation) -> Use ASCII keyframes or a
- Run the script to export GIF + True Semitransparent APNG + Lossless Animated WebP + Aseprite JSON, read
_inspect.pngfor visual self-inspection, and fix defects.
2. Modifying Existing Pixel Art (PNG / GIF / Spritesheet)
- First, Diagnose via Image Inspection:
(Note: The engine automatically recognizespython3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/4x/8xinteger upscaled preview images and losslessly restores them to the1xnative pixel grid; add--keep-scaleto preserve original size.) - Small Image / Full Frame Reverse Compilation Modification:
Automatically decomposes all frames and frame delays, generatespython3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/edit_walk.pywith semantic character palette and_inspect.png. Modify the script and re-run. - Large Image Local Surgical Refinement (Region Patch, Highly Recommended for 48x48+):
Must read the generated# 1) Slice out a local grid by 0-based coordinate box (X,Y,W,H); the generated self-inspection image automatically retains global X/Y coordinate ticks! python3 <SKILL_DIR>/scripts/pforge.py region-extract hero.png --box 14,6,20,18 -o work/patch/ # 2) Edit the extracted .txt character grid, then write back; automatically outputs a Before | After | Diff triple comparison image python3 <SKILL_DIR>/scripts/pforge.py region-apply hero.png --patch work/patch/hero_x14_y6_w20_h18.json -o work/out/*_diff.pngto confirm changes are strictly within the target area and edges blend naturally. - One-Click Semantic Recolor / Faction Variant:
python3 <SKILL_DIR>/scripts/pforge.py recolor slime.gif --map B=R,b=r,C=Y -o work/fire_slime/
3. HD Image / AI Concept Sketch to Pixel Art (Pixelate & Clean)
When a user provides a high-resolution illustration, photo, or an AI-generated "pseudo-pixel art" with messy edges:
# Use contrast_box for illustrations/concept art; use --mode dominant_block for AI pseudo-pixel art to eliminate skewed grids and noise
python3 <SKILL_DIR>/scripts/pforge.py pixelate draft.png --size 48x48 --palette endesga32 --outline "#181425" -o work/px/
Inspect the generated *_compare.png and *_inspect.png. In the auto-generated edit_*.py, manually add eye highlights, smooth outline jaggies, then deliver.
4. Seamless Map Tiles, 47-Tile Auto-Tile, 9-Slice UI, Isometric, and Real-Time Scene Brightness Self-Check
- Seamless Single Tile and 9-Slice UI:
pforge.py tile grass.png(detects 3x3 seam breaks and marks them in red);pforge.py nine-slice frame.png --margins 4,4,4,4 --size 160x56. - 47-Tile Blob / 16-Tile Wang Auto-Tile Terrain: Provide only front/back two base tiles, call
pforge.py autotile --fg grass.png --bg water.png --mode blob47(or Pythongenerate_blob47_tileset). It automatically synthesizes all inner/outer corners and lays out a test archipelago map*_blob47_inspect.png. 2:1Isometric Buildings and 4/8-Directional RPG Characters: UseIsoSceneto build a zero-fracture2:1three-face-illuminated isometric block scene; useDirectionalRig+export_multidir_sheetsto deriveS/E/N/Wfour- or eight-direction rotation and walking sprite sheets from front-facing parts. Check*_alignment_inspect.pngto verify head/foot horizontal alignment lines.- Multi-Asset Real-Time Scene Sandbox and Grayscale Brightness Self-Check: Use
SceneComposer+render_pixel_text(built-in compact pixel font) +build_scene_mockupto composite real-time combat/exploration GIFs with Y-axis occlusion sorting and jumping text UI. Must read*_scene_inspect.pngto check the pure grayscale squint image and contour contrast heatmap, eliminating brightness conflicts where the character blends into the background.
5. HD-2D Pixel Normal Map Dynamic Lighting and "Image Deconstruction → Automatic Rigging (Sketch-to-Rig)"
- HD-2D Normal Map and 360° Torch Lighting: Call
pforge.py normalmap hero.png --emit "#2CE8F5"orexport_hd2d_bundle(..., part_layers=rig.render_part_layers(..., part_profiles={"sword": "ridge"}))to one-click export Godot/Unity compatible*_albedo.png,*_normal.png,*_emission.pngand*_torch_orbit_6x.gif. Inspect*_hd2d_inspect.pngfor the four-quadrant point light verification image. - Explosion Setting Image Automatic Part Extraction and Rigging (Sketch-to-Rig): Run
pforge.py autorig sheet.png --canvas 56x56 --palette endesga32(safe edge-flood fill background removal, connectivity-based part separation, unified scale color locking, shoulder/neck/sword hilt pivot inference) on a concept diagram with a solid color background. Inspect*_autorig_pipeline.png, then refine actions on the generatedrig_*.py.
6. Native .aseprite Binary Layered Project Read/Write and Direct MCP Tool Calls
- Bidirectional
.asepriteProject Support: All build pipelines default to direct output of native binary<name>.aseprite; usingRig.render_named_layers_sequence(poses)+write_aseprite(...), parts and VFX can be saved as independent timeline layers + action tags + joint pivot Slices. Human artists can directly continue layering and drawing in Aseprite; existing.ase/.asepritefiles can be reverse-engineered directly withpforge.py aseprite-inspect file.aseprite --unpack-layersordecompile. - Prefer Native MCP Tools: If the current session is connected to a
pixelforgeMCP Server (exposing 12 tools includingpixelforge_palette_guide,pixelforge_build,pixelforge_build_rig,pixelforge_region_patch,pixelforge_scene_check,pixelforge_aseprite_inspect, etc., each return includingagent_checklist.must_view_imagesand(x, y)fix prescriptions), prefer calling MCP tools directly instead of writing temporary scripts.
IV. Python Zero-Arithmetic Declarative Template
import sys
sys.path.insert(0, "/path/to/pixel-forge/scripts")
from pforge import build_from_spec, format_palette_guide
# Build a multi-part, multi-action character with independent layered .aseprite using zero-arithmetic coordinates
res = build_from_spec({
"name": "ember_knight",
"palette": "endesga32",
"canvas_size": "auto",
"outline_mode": "selout",
"parts": [
{"name": "torso", "at": "center", "grid": ["|..RRRR..| # Breastplate", "|.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")
# Afterwards, be sure to visually inspect all dashboards listed in res["agent_checklist"]["must_view_images"]!
V. Advanced Reference Manual (Read on Demand, Progressive Disclosure)
Before executing specific sub-tasks, please consult the topic-specific guides in this skill's directory as needed:
- Pixel Art Styling, Color Cluster Anti-Aliasing, Light and Dark Shade Steps, and Dithering Techniques: craft_and_shading.md
- Reverse Deconstruction, Large Image Local Patch Surgery, and AI Image Pixelation Refinement: edit_and_pixelate.md
- Multi-Component Skeleton Rig, RotSprite Rotation, Hit Feel Frame Timing Recipes, and VFX Library: animation_and_rigging.md
- Seamless Tileset 3x3 Seam Design and 9-Slice UI Specs: tileset_and_ui.md
- 47-Tile Auto-Terrain, Real-Time Scene Brightness Self-Check, 2:1 Isometric, and 4/8-Directional Character Derivation: world_iso_and_scene.md
- HD-2D Pixel Normal Map Dynamic Lighting and AI Setting Image Automatic Part Deconstruction and Rigging: hd2d_and_autorig.md
- Native
.asepriteLayered Binary Project Read/Write and MCP Server Guide: aseprite_and_mcp.md - Complete CLI Parameter and Python API Quick Reference: cli_and_api.md
- Runable Practical Example Scripts: See the 10 end-to-end scripts in the
./examples/directory (01~10).