CommunityBildgithub.com

PixelForge — Pixel-Art-Werkbank

Voll ausgestattete visuell-multimodale Pixel-Art- und Animations-Werkstatt (PixelForge). Erstellt Pixel-Art/Sprites/Animationen von Grund auf, dekompiliert und modifiziert vorhandene PNGs/GIFs/Spritesheets, pixeliert hochauflösende Bilder oder KI-Skizzen, extrahiert Paletten und Helligkeitsstufen, erstellt Multi-Action-Animationen mit RotSprite-Rotation und variablem Frame-Rhythmus (GIF/APNG/WebP/Aseprite-Atlas) und erkennt nahtlose Tileset-3x3-Verbindungen sowie 9-Slice-UI.

Was ist PixelForge — Pixel-Art-Werkbank?

PixelForge ist ein umfassendes Toolkit für visuelle KI-Agenten zur professionellen Pixel-Art-Erstellung, -Bearbeitung und -Animation. Es wird über ein einzelnes Python-Skript (`pforge.py`) gesteuert, das sowohl eine CLI als auch eine Python-Bibliothek (`pixelforge`) bereitstellt, und unterstützt eine breite Palette von Arbeitsabläufen. Dazu gehören der Aufbau von Figuren und Animationen von Grund auf mit ASCII-Gittern oder einer deklarativen, koordinatenfreien Spezifikation (`build_from_spec`), die semantische Reverse-Engineering- und lokale Bearbeitung vorhandener PNGs/GIFs/Spritesheets (einschließlich Region-Patch-Chirurgie) sowie die Pixelierung von KI-Konzeptskizzen. Ein besonderer Schwerpunkt liegt auf einem agentengesteuerten „Zero-Friction“-Workflow, der die Token-Nutzung minimiert: Beispielsweise ermöglicht die MCP-Integration den direkten Aufruf von Werkzeugen wie `pixelforge_build_rig` für Multi-Part-Figuren mit semantischer Gelenkverankerung, ohne dass Koordinaten oder Achsen manuell berechnet werden müssen. Zu den weiteren Funktionen gehören nahtloses Tiling (3×3, Blob47, Wang), 2:1-isometrische Szeneerstellung, HD-2D-Normal-Mapping und eine bidirektionale `.aseprite`-Projektunterstützung. Jeder generierte oder bearbeitete Vermögenswert wird von einem visuellen Diagnose-Dashboard (`_inspect.png`) und einem `Pixel Linter`-Bericht begleitet, die eine strenge Qualitätskontrolle durch den Agenten erzwingen, um Probleme wie Treppenstufen (Jaggies), Lücken in Konturen und Farbkonflikte zu erkennen.

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

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

PixelForge — Visuell-multimodale Pixel-Art-Erstellung, -Verfeinerung und Animationswerkbank

Diese Fähigkeit verleiht visuellen LLMs mit ./scripts/pforge.py (CLI und Python-Bibliothek pixelforge mit nur Pillow als Abhängigkeit) industrietaugliche Pixel-Asset-Produktion und Reverse-Engineering-Fähigkeiten.

1. Kernregeln (Unbedingt einhalten)

  1. Keine handgeschriebenen, spärlichen Koordinatenlisten: Verwende niemals Dutzende von Zeilen mit putpixel((x, y)). Verwende stattdessen ASCII-Zeichenraster mit fester Breite (. und Leerzeichen stehen für Transparenz), kompakte lokale Rig-Komponenten (zeichne nur die Komponente selbst und positioniere sie mit offset=(ox, oy)), oder PixelCanvas-Primitive (Anti-Corner-Linien, symmetrische Ellipsen, Bayer-geordnetes Dithering).
  2. Wähle die richtige Architektur basierend auf der Auflösung:
    • 16×16 ~ 32×32: Schreibe direkt ein vollflächiges ASCII-Raster oder eine leichte Rig.
    • 48×48 ~ 64×64: Muss in Schichten/Komponenten aufgeteilt werden (verwende Komponenten ohne Außenkontur + Rig(..., outline_mode="selout"|"outer") für automatische, einheitliche Konturen); verwende für lokale Änderungen Region Patch, nicht das gesamte Bild.
    • 64×64 ~ 128×128+: Verwende PixelCanvas-Geometrieentwurf + stamp() für lokale Stempel + dither_rect() für geordnetes Dithering + lokale Region-Patch-Verfeinerung.
  3. Erzwinge einen multimodalen, holografischen visuellen Kreislauf:
    • Jede Erzeugung oder Änderung gibt ein holografisches Diagnose-Dashboard <name>_inspect.png aus (enthält: Farbpaletten-Legende [char] #HEX + 0-basiertes (X, Y)-Koordinatenraster mit Bodenlinie + Vorschau ohne Raster auf hellem/dunklem Hintergrund + Silhouette und rot-cyan Zwiebelhaut-Bewegungsspur) sowie einen Pixel Linter-Terminalbericht.
    • Vor der Auslieferung muss das <name>_inspect.png mit einem Bildbetrachter (z. B. read_file / view_image / Read) überprüft werden! (Bei Änderungen auch <name>_diff.png!)
    • Überprüfe anhand der Koordinaten und Linter-Warnungen die folgenden Punkte: Lücken in der Außenkontur (insbesondere bei dunklen Konturen auf hellem Hintergrund), Treppenstufen (Jaggies) bei Diagonalen/Kurven, Fuß-Boden-Versatz (baseline_y) zwischen Frames und unbeabsichtigte Pixeländerungen. Korrigiere und überprüfe erneut, bevor du auslieferst.

2. Entscheidungsbaum für den schnellsten Weg des Agenten (Priorisiere Null-Skript-Ausführung!)

Wähle vor dem Start die folgende Priorität für den sparsamsten und boilerplate-freien Aufruf:

  1. Paletten-Farbton-Leitfaden für einzelne Zeichen (vermeide Fehler durch Raten).
    • MCP: pixelforge_palette_guide(palette="endesga32"); CLI: python3 <SKILL_DIR>/scripts/pforge.py palette-guide endesga32
    • Erhalte direkt die nach Farbton gruppierten Zeichenketten Schatten -> Mittelton -> Glanzlicht (z. B. 'b' -> 'B' -> 'C'), ohne Tabelle.
  2. Multi-Part-Charaktere / Bosse / Multi-Action-Mehrschicht .aseprite (0 Zeilen Python, keine manuelle Koordinatenberechnung).
    • Rufe direkt über MCP pixelforge_build_rig auf (oder CLI pforge.py build-spec spec.json / Python build_from_spec(spec)):
      • Fehlertolerantes Raster: Unterstützt |..BBBB..| # Zeilenkommentar und pad_ragged=True zum automatischen Auffüllen fehlender .!
      • Semantische Gelenkverankerung (keine Koordinaten-/Achsenberechnung): Setze den Hauptkörper auf at="center", andere Komponenten auf attach_to="torso", side="top"|"left"|"right"|"bottom", hinge="grip", canvas_size="auto" berechnet automatisch die Bounding Box und reserviert Platz für Animationen (z. B. Schwertschwünge).
      • Voreingestellte Aktionen: clips={"idle": "idle_breathe", "attack": "melee_attack", "hit": "hurt_flash"} (unterstützt auch "float_bob", "slime_bounce" oder benutzerdefinierte poses), automatisch mit Schwertspuren/Staubeffekten, Schatten und Mehrschicht .aseprite!
  3. 16×16 bis 32×32 Icons und Einzelframe-Objekte:
    • Rufe direkt über MCP pixelforge_build auf (unterstützt direkt das Zeichnen von Komponenten ohne Kontur mit outline_mode="selout", add_shadow=True für automatische Kontur und Schatten).
  4. Komplexe programmatische Geometrie / Isometrie / Spielkampf-Sandbox-Skripte:
    • Führe python3 <SKILL_DIR>/scripts/pforge.py init-script work/run.py --template rig|sprite|scene|iso aus, um ein sofort ausführbares Gerüst mit korrektem sys.path zu generieren, und fülle dann die Logik ein (kein manuelles Debugging von Pfaden).

3. Sechs Standard-Workflows

1. Pixel-Art und Multi-Action-Animation von Grund auf neu erstellen

  1. Wähle eine Palette: Verwende die integrierten Paletten wie "endesga32", "pico8", "sweetie16", "resurrect64", "gameboy" oder extrahiere mit pforge.py palette <ref.png> eine Palette und ihre Helligkeitsstufen aus einem Referenzbild. Standard-Lichtquelle oben links (Glanzlichter oben links warm, Schatten unten rechts kalt). Empfehlung outline_mode="selout" (adaptive, lichtquellenbasierte Kontur).
  2. Konstruktion und Bindung:
    • Große topologische Veränderungen (überkreuzte Beine beim Gehen, deformierter Mund mit Fangzähnen) → Verwende ASCII-Keyframes oder ein Part-Dictionary mit mehreren Zuständen {"closed": ..., "open": ...}.
    • Starrkörperrotation/Stauchung (Deckel, der sich um ein Scharnier öffnet, Schwertschwünge, Atmung/Hüpfen) → Verwende Rig + rotsprite für Rotation um einen Ankerpunkt und squash_stretch.
    • Schlag-Rhythmus → Verwende ungleichmäßige durations_ms (z. B. Aufladen 180ms → Schlag 40ms → Freeze 55ms → Abklingen 150ms), kombiniere mit vfx_slash_arc / vfx_dust_puff / vfx_hit_spark.
    • Ein Charakter, mehrere Aktionen (idle / walk / attack) → Verwende SpriteActor, um mit einem Klick einzelne Animationen und eine kombinierte Atlas-Datei <actor>_master_atlas.png/.json zu exportieren.
  3. Führe das Skript aus, um GIF + echtes halbtransparentes APNG + verlustfreies dynamisches WebP + Aseprite JSON zu exportieren. Überprüfe _inspect.png visuell und korrigiere Fehler.

2. Vorhandene Pixel-Art bearbeiten (PNG / GIF / Spritesheet)

  • Diagnose zuerst:
    python3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/
    
    (Hinweis: Die Engine erkennt automatisch 4×/8× vergrößerte Vorschaubilder und reduziert sie verlustfrei auf 1× native Pixel. Verwende --keep-scale, um die Originalgröße beizubehalten.)
  • Kleine Bilder/komplette Frames dekompilieren und bearbeiten:
    python3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/
    
    Zerlegt automatisch alle Frames und Dauern, generiert edit_walk.py mit einer semantischen Farbpaletten-Legende und _inspect.png. Bearbeite das Skript und führe es erneut aus.
  • Große Bilder lokal chirurgisch verfeinern (Region Patch, empfohlen ab 48×48):
    # 1) Extrahiere lokales Raster mit 0-basierter Box (X,Y,B,H). Das Selbstprüfungsbild behält automatisch die globalen X/Y-Koordinaten bei!
    python3 <SKILL_DIR>/scripts/pforge.py region-extract hero.png --box 14,6,20,18 -o work/patch/
    # 2) Bearbeite die extrahierte .txt-Zeichenraster-Datei und schreibe sie zurück. Ausgabe: Before | After | Diff Vergleichsbild
    python3 <SKILL_DIR>/scripts/pforge.py region-apply hero.png --patch work/patch/hero_x14_y6_w20_h18.json -o work/out/
    
    Muss das generierte *_diff.png überprüfen, um sicherzustellen, dass die Änderungen streng im Zielbereich liegen und die Kanten nahtlos sind.
  • Farbwechsel mit einem Befehl / Fraktionsvariante:
    python3 <SKILL_DIR>/scripts/pforge.py recolor slime.gif --map B=R,b=r,C=Y -o work/fire_slime/
    

3. Hochauflösende Bilder / KI-Konzeptskizzen in Pixel-Art umwandeln (Pixelieren und Bereinigen)

Wenn Benutzer hochauflösende Illustrationen, Fotos oder KI-„Pseudo-Pixel-Art“ mit unscharfen Kanten bereitstellen:

# Illustrationen/Konzeptzeichnungen mit contrast_box; KI-Pseudo-Pixel-Art mit --mode dominant_block
python3 <SKILL_DIR>/scripts/pforge.py pixelate draft.png --size 48x48 --palette endesga32 --outline "#181425" -o work/px/

Lies die generierten *_compare.png und *_inspect.png, füge in der automatisch generierten edit_*.py manuell Glanzlichter in den Augen hinzu und glätte die Treppenstufen der Konturen, bevor du auslieferst.

4. Nahtlose Kacheln, 47-Kacheln Auto-Tile, 9-Slice-UI, Isometrie und Helligkeitsprüfung von Spielszenen

  • Nahtlose Einzelkacheln und 9-Slice-UI: pforge.py tile grass.png (3×3 Verbindungsfehler in Rot markieren); pforge.py nine-slice frame.png --margins 4,4,4,4 --size 160×56.
  • 47-Kacheln Blob / 16-Kacheln Wang Auto-Tile: Gib zwei Basis-Kacheln (Vordergrund/Hintergrund) an, rufe pforge.py autotile --fg grass.png --bg water.png --mode blob47 (oder Python generate_blob47_tileset) auf, um alle Innen-/Außenecken automatisch zu generieren und eine Testinselkarte *_blob47_inspect.png zu erstellen.
  • 2:1 isometrische Gebäude und 4/8-Richtungs-RPG-Charaktere: Verwende IsoScene, um eine rissfreie 2:1-Szene mit Dreiseiten-Beleuchtung zu bauen; verwende DirectionalRig + export_multidir_sheets, um aus Frontal-Komponenten S/E/N/W-Vier- oder Acht-Richtungs-Rotations- und Lauf-Atlanten zu generieren, und überprüfe *_alignment_inspect.png auf horizontale Kopf-/Fuß-Ausrichtungslinien.
  • Multi-Asset-Spielszene-Sandbox und Graustufen-Helligkeitsprüfung: Verwende SceneComposer + render_pixel_text (integrierte kompakte Pixel-Schriftart) + build_scene_mockup, um eine Kampf-/Erkundungsanimation mit Y-Sortierung und Text-UI zu erstellen. Muss *_scene_inspect.png lesen, um die Graustufen-Zusammenkneif-Augen-Prüfung und die Kontrast-Hitzekarte zu überprüfen und Hell/Dunkel-Probleme zu vermeiden.

5. HD-2D Pixel-Normal-Map-Dynamikbeleuchtung und „Konzeptbild zerlegen → automatisch riggen“ (Sketch-to-Rig)

  • HD-2D Normal Map und 360°-Fackelbeleuchtung: Rufe pforge.py normalmap hero.png --emit "#2CE8F5" oder export_hd2d_bundle(..., part_layers=rig.render_part_layers(..., part_profiles={"sword": "ridge"})) auf, um mit einem Klick Godot/Unity-kompatible *_albedo.png, *_normal.png, *_emission.png und *_torch_orbit_6x.gif zu exportieren, und überprüfe das *_hd2d_inspect.png-Quadranten-Punktlicht-Testbild.
  • Explosions-Konzeptbild automatisch zerlegen und riggen (Sketch-to-Rig): Für ein Konzeptbild mit Komponenten auf einfarbigem Hintergrund führe pforge.py autorig sheet.png --canvas 56×56 --palette endesga32 aus (Flood-Fill-Entfernung des Hintergrunds, Connected-Component-Zerlegung, einheitliche Skalierung, Farbanpassung, Schätzung von Schulter-/Hals-/Schwertknauf-Achsen). Überprüfe *_autorig_pipeline.png und verfeinere dann die Aktionen im generierten rig_*.py.

6. Native .aseprite binäre Mehrschicht-Projekt-Lese-/Schreibunterstützung und MCP-Tool-Aufrufe

  • Bidirektionale .aseprite-Projektunterstützung: Alle Build-Workflows exportieren standardmäßig natives binäres <name>.aseprite; verwende Rig.render_named_layers_sequence(poses) + write_aseprite(...), um Komponenten und Effekte als unabhängige Timeline-Layer + Aktions-Tags + Gelenk-Slices zu speichern, die menschliche Künstler direkt in Aseprite weiterbearbeiten können; Vorhandene .ase/.aseprite-Dateien können mit pforge.py aseprite-inspect file.aseprite --unpack-layers oder decompile rückwärts zerlegt werden.
  • MCP native Tools bevorzugen: Wenn eine pixelforge MCP Server-Verbindung besteht (exponiert 12 Tools wie pixelforge_palette_guide, pixelforge_build, pixelforge_build_rig, pixelforge_region_patch, pixelforge_scene_check, pixelforge_aseprite_inspect, jede Ausgabe enthält agent_checklist.must_view_images und (x, y) Korrektur-Rezepte), rufe direkt die MCP-Tools auf, anstatt temporäre Skripte zu schreiben.

4. Python deklarative Vorlage ohne Arithmetik

import sys
sys.path.insert(0, "/path/to/pixel-forge/scripts")
from pforge import build_from_spec, format_palette_guide

# Arithmetikfreie Koordinatenkonstruktion eines Multi-Part, Multi-Action, Multi-Layer .aseprite Charakters
res = build_from_spec({
    "name": "ember_knight",
    "palette": "endesga32",
    "canvas_size": "auto",
    "outline_mode": "selout",
    "parts": [
        {"name": "torso", "at": "center", "grid": ["|..RRRR..| # Brustplatte", "|.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"
})
# Überprüfe danach unbedingt alle Dashboards in res["agent_checklist"]["must_view_images"]!

5. Erweitertes Referenzhandbuch (Bei Bedarf lesen, stufenweise Offenlegung)

Führe vor der Ausführung spezifischer Aufgaben die folgenden thematischen Leitfäden in diesem Skill-Verzeichnis aus:

  • Pixel-Art-Formgebung, Farbcluster-Anti-Aliasing, Hell/Dunkel-Stufen und Dithering-Techniken: craft_and_shading.md
  • Reverse Engineering, lokale Patch-Operationen für große Bilder und KI-Bildpixelierung-Verfeinerung: edit_and_pixelate.md
  • Multi-Part-Skelett-Rigs, RotSprite-Rotation, Schlag-Frame-Dauer-Rezepte und Effektbibliothek: animation_and_rigging.md
  • Nahtloses Tileset 3×3-Kachel-Design und 9-Slice-UI-Standards: tileset_and_ui.md
  • 47-Kacheln Auto-Tiles, Helligkeitsprüfung für Spielszenen, 2:1-Isometrie und 4/8-Richtungs-Charakterableitung: world_iso_and_scene.md
  • HD-2D Pixel-Normal-Map-Dynamikbeleuchtung und automatische Zerlegung/Rigging von KI-Konzeptbildern: hd2d_and_autorig.md
  • Native .aseprite-Mehrschicht-Binärprojekt-Lese-/Schreib- und MCP-Server-Leitfaden: aseprite_and_mcp.md
  • Vollständiges CLI-Argument- und Python-API-Schnellnachschlagewörterbuch: cli_and_api.md
  • Ausführbare Praxisbeispielskripte: Siehe die 10 End-to-End-Skripte (01–10) im Verzeichnis ./examples/.

Verwandte Skills