CommunityImagegithub.com

PixelForge

A full-featured visual multimodal pixel art and animation workshop (PixelForge). Used for building pixel art/icons/large-scale layered sprites from scratch, reverse-compiling and locally editing existing PNG/GIF/spritesheets, pixelating HD images or AI sketches, extracting palettes and shading steps, creating multi-action animations with RotSprite rotation and variable frame timing (GIF/APNG/WebP/Aseprite atlas), and seamless Tileset 3x3 seam detection plus 9-slice UI. Invoke this skill whenever pixel art creation, modification, pixelation, or pixel animation is involved.

What is PixelForge?

PixelForge is an industrial-grade pixel art and animation toolkit designed for visual LLMs (like Claude, GPT-4, Gemini) and their agent integrations (Claude Code, Cursor, Codex, etc.). It provides a comprehensive, zero-friction pipeline for creating, editing, and animating pixel art directly from natural language or visual input. The skill is powered by a Python library (`pixelforge`) and CLI (`pforge.py`) with minimal dependencies (only Pillow). It enforces strict workflows to avoid common pitfalls like hand-writing coordinate lists, and offers multiple abstraction levels: ASCII character grids for small sprites, component-based `Rig` for multi-part characters with semantic joint attachment (no coordinate arithmetic required), and `PixelCanvas` for programmatic geometry. Key capabilities include: building multi-action layered `.aseprite` files with RotSprite rotation and squash-stretch, reverse-engineering and patching existing images via region-based extraction and semantic recolor, pixelating HD images with automatic palette quantization, generating seamless tilesets and auto-tiled blob47 terrain, creating HD-2D normal maps for dynamic lighting, and exporting to multiple formats (GIF, APNG, WebP, Aseprite atlas). Every generation or modification automatically produces a diagnostic inspection board (`_inspect.png`) with a color legend, coordinate grid, silhouette and onion skin overlays, plus a terminal Pixel Linter report. The agent is required to visually review this board before delivery. The skill also integrates with MCP (Model Context Protocol) providing 12 native tools (like `pixelforge_build_rig`, `pixelforge_region_patch`, `pixelforge_palette_guide`) that return structured checklists and fix prescriptions, making it ideal for iterative, agent-driven pixel art workflows. Platform support includes all major AI agent environments (Claude Code, Cursor, Codex, etc.) as the skill only depends on Python 3 and Pillow, and the MCP server can be self-hosted. The skill is especially useful for game developers, pixel artists, and AI-assisted content pipelines that need to produce or modify pixel art at any scale from 16x16 icons to 128x128+ layered characters, with strict quality control enforced by the diagnostic visuals.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/scvxzf1/pixel-forge/tree/main

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

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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)

  1. 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 part Rig (draw only the part itself and position it via offset=(ox, oy), no need to fill the whole canvas with empty dots), or PixelCanvas pixel-level geometric primitives (anti-L corner lines, symmetric ellipses, Bayer ordered dithering).
  2. Choose Correct Architecture by Resolution:
    • 16x16 ~ 32x32: Directly write a full-canvas ASCII grid or a lightweight Rig.
    • 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+: Use PixelCanvas geometry draft + stamp() local stamping + dither_rect() ordered dithering + local Region Patch refinement.
  3. 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 terminal Pixel Linter report.
    • 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.

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:

  1. 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.
  2. Multi-Part Character / Boss / Multi-Action Layered .aseprite (0 Lines of Python Code, Zero Arithmetic Snapping):
    • Directly call MCP pixelforge_build_rig (or CLI pforge.py build-spec spec.json / Python build_from_spec(spec)):
      • Forgiving Grid Syntax: Supports |..BBBB..| # Inline comment for visually aligned vertical lines and pad_ragged=True to 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 write attach_to="torso", side="top"|"left"|"right"|"bottom", hinge="grip", with canvas_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 custom poses), automatically includes slash/dust VFX, shadow, and multi-layered .aseprite!
  3. 16x16~32x32 Icons and Single-Frame Small Objects:
    • Directly call MCP pixelforge_build (supports directly drawing un-outlined color blocks and passing outline_mode="selout", add_shadow=True for automatic border and shadow addition).
  4. 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|iso to one-click generate a runnable scaffold with pre-configured relative sys.path, then fill in the logic (avoiding manual path concatenation and debugging).

III. Six Standard Workflows

1. Building Pixel Art and Multi-Action Animation from Scratch

  1. Choose a Palette: Prefer built-in classic palettes like "endesga32", "pico8", "sweetie16", "resurrect64", "gameboy", or use pforge.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 enable outline_mode="selout" (adaptive lighting outline).
  2. Build and Rig:
    • Large topology changes (walking leg crossing, open mouth fang deformation) -> Use ASCII keyframes or a Part multi-state dictionary {"closed": ..., "open": ...}.
    • Rigid body rotation/squash (box lid opening on hinge, sword swing, breathing bounce) -> Use Rig + rotsprite for rotation around anchor point and squash_stretch.
    • Hit feel rhythm -> Must use non-uniform durations_ms (e.g., charge 180ms -> explosive swing 40ms -> pause frame 55ms -> recovery 150ms), paired with vfx_slash_arc / vfx_dust_puff / vfx_hit_spark.
    • Single character, multiple actions (idle / walk / attack) -> Use SpriteActor to one-click export individual animations and a merged atlas <actor>_master_atlas.png/.json.
  3. Run the script to export GIF + True Semitransparent APNG + Lossless Animated WebP + Aseprite JSON, read _inspect.png for visual self-inspection, and fix defects.

2. Modifying Existing Pixel Art (PNG / GIF / Spritesheet)

  • First, Diagnose via Image Inspection:
    python3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/
    
    (Note: The engine automatically recognizes 4x/8x integer upscaled preview images and losslessly restores them to the 1x native pixel grid; add --keep-scale to preserve original size.)
  • Small Image / Full Frame Reverse Compilation Modification:
    python3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/
    
    Automatically decomposes all frames and frame delays, generates edit_walk.py with semantic character palette and _inspect.png. Modify the script and re-run.
  • Large Image Local Surgical Refinement (Region Patch, Highly Recommended for 48x48+):
    # 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/
    
    Must read the generated *_diff.png to 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 Python generate_blob47_tileset). It automatically synthesizes all inner/outer corners and lays out a test archipelago map *_blob47_inspect.png.
  • 2:1 Isometric Buildings and 4/8-Directional RPG Characters: Use IsoScene to build a zero-fracture 2:1 three-face-illuminated isometric block scene; use DirectionalRig + export_multidir_sheets to derive S/E/N/W four- or eight-direction rotation and walking sprite sheets from front-facing parts. Check *_alignment_inspect.png to 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_mockup to composite real-time combat/exploration GIFs with Y-axis occlusion sorting and jumping text UI. Must read *_scene_inspect.png to 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" or export_hd2d_bundle(..., part_layers=rig.render_part_layers(..., part_profiles={"sword": "ridge"})) to one-click export Godot/Unity compatible *_albedo.png, *_normal.png, *_emission.png and *_torch_orbit_6x.gif. Inspect *_hd2d_inspect.png for 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 generated rig_*.py.

6. Native .aseprite Binary Layered Project Read/Write and Direct MCP Tool Calls

  • Bidirectional .aseprite Project Support: All build pipelines default to direct output of native binary <name>.aseprite; using Rig.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/.aseprite files can be reverse-engineered directly with pforge.py aseprite-inspect file.aseprite --unpack-layers or decompile.
  • Prefer Native MCP Tools: If the current session is connected to a pixelforge MCP Server (exposing 12 tools including pixelforge_palette_guide, pixelforge_build, pixelforge_build_rig, pixelforge_region_patch, pixelforge_scene_check, pixelforge_aseprite_inspect, etc., each return including agent_checklist.must_view_images and (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 .aseprite Layered 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).

Related Skills