Community图像github.com

pixel-forge

全功能视觉多模态像素画与动图工坊(PixelForge)。用于从零构建像素画/图标/大尺寸分层精灵、 逆向反编译并局部修改已有 PNG/GIF/精灵表、将高分图或 AI 草图转为干净像素画(Pixelate)、 提取参考图色板与明暗色阶、制作带 RotSprite 部件旋转与可变帧率节奏的多动作动图(GIF/APNG/WebP/Aseprite 图集)、 无缝 Tileset 3x3 拼接检测及九宫格 UI。凡涉及像素画创作、像素修改、像素化处理或像素动画时调用此技能。

pixel-forge 是什么?

pixel-forge is a Claude Code agent skill that 全功能视觉多模态像素画与动图工坊(PixelForge)。用于从零构建像素画/图标/大尺寸分层精灵、 逆向反编译并局部修改已有 PNG/GIF/精灵表、将高分图或 AI 草图转为干净像素画(Pixelate)、 提取参考图色板与明暗色阶、制作带 RotSprite 部件旋转与可变帧率节奏的多动作动图(GIF/APNG/WebP/Aseprite 图集)、 无缝 Tileset 3x3 拼接检测及九宫格 UI。凡涉及像素画创作、像素修改、像素化处理或像素动画时调用此技能。.

兼容平台~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 — 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).

相关技能