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)
- 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 lokaleRig-Komponenten (zeichne nur die Komponente selbst und positioniere sie mitoffset=(ox, oy)), oderPixelCanvas-Primitive (Anti-Corner-Linien, symmetrische Ellipsen, Bayer-geordnetes Dithering). - Wähle die richtige Architektur basierend auf der Auflösung:
16×16 ~ 32×32: Schreibe direkt ein vollflächiges ASCII-Raster oder eine leichteRig.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+: VerwendePixelCanvas-Geometrieentwurf +stamp()für lokale Stempel +dither_rect()für geordnetes Dithering + lokale Region-Patch-Verfeinerung.
- Erzwinge einen multimodalen, holografischen visuellen Kreislauf:
- Jede Erzeugung oder Änderung gibt ein holografisches Diagnose-Dashboard
<name>_inspect.pngaus (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 einenPixel Linter-Terminalbericht. - Vor der Auslieferung muss das
<name>_inspect.pngmit 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.
- Jede Erzeugung oder Änderung gibt ein holografisches Diagnose-Dashboard
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:
- 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.
- MCP:
- Multi-Part-Charaktere / Bosse / Multi-Action-Mehrschicht
.aseprite(0 Zeilen Python, keine manuelle Koordinatenberechnung).- Rufe direkt über MCP
pixelforge_build_rigauf (oder CLIpforge.py build-spec spec.json/ Pythonbuild_from_spec(spec)):- Fehlertolerantes Raster: Unterstützt
|..BBBB..| # Zeilenkommentarundpad_ragged=Truezum automatischen Auffüllen fehlender.! - Semantische Gelenkverankerung (keine Koordinaten-/Achsenberechnung): Setze den Hauptkörper auf
at="center", andere Komponenten aufattach_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 benutzerdefinierteposes), automatisch mit Schwertspuren/Staubeffekten, Schatten und Mehrschicht.aseprite!
- Fehlertolerantes Raster: Unterstützt
- Rufe direkt über MCP
- 16×16 bis 32×32 Icons und Einzelframe-Objekte:
- Rufe direkt über MCP
pixelforge_buildauf (unterstützt direkt das Zeichnen von Komponenten ohne Kontur mitoutline_mode="selout", add_shadow=Truefür automatische Kontur und Schatten).
- Rufe direkt über MCP
- Komplexe programmatische Geometrie / Isometrie / Spielkampf-Sandbox-Skripte:
- Führe
python3 <SKILL_DIR>/scripts/pforge.py init-script work/run.py --template rig|sprite|scene|isoaus, um ein sofort ausführbares Gerüst mit korrektemsys.pathzu generieren, und fülle dann die Logik ein (kein manuelles Debugging von Pfaden).
- Führe
3. Sechs Standard-Workflows
1. Pixel-Art und Multi-Action-Animation von Grund auf neu erstellen
- Wähle eine Palette: Verwende die integrierten Paletten wie
"endesga32","pico8","sweetie16","resurrect64","gameboy"oder extrahiere mitpforge.py palette <ref.png>eine Palette und ihre Helligkeitsstufen aus einem Referenzbild. Standard-Lichtquelle oben links (Glanzlichter oben links warm, Schatten unten rechts kalt). Empfehlungoutline_mode="selout"(adaptive, lichtquellenbasierte Kontur). - 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+rotspritefür Rotation um einen Ankerpunkt undsquash_stretch. - Schlag-Rhythmus → Verwende ungleichmäßige
durations_ms(z. B. Aufladen180ms→ Schlag40ms→ Freeze55ms→ Abklingen150ms), kombiniere mitvfx_slash_arc/vfx_dust_puff/vfx_hit_spark. - Ein Charakter, mehrere Aktionen (
idle/walk/attack) → VerwendeSpriteActor, um mit einem Klick einzelne Animationen und eine kombinierte Atlas-Datei<actor>_master_atlas.png/.jsonzu exportieren.
- Große topologische Veränderungen (überkreuzte Beine beim Gehen, deformierter Mund mit Fangzähnen) → Verwende ASCII-Keyframes oder ein
- Führe das Skript aus, um GIF + echtes halbtransparentes APNG + verlustfreies dynamisches WebP + Aseprite JSON zu exportieren. Überprüfe
_inspect.pngvisuell und korrigiere Fehler.
2. Vorhandene Pixel-Art bearbeiten (PNG / GIF / Spritesheet)
- Diagnose zuerst:
(Hinweis: Die Engine erkennt automatischpython3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/4×/8×vergrößerte Vorschaubilder und reduziert sie verlustfrei auf1×native Pixel. Verwende--keep-scale, um die Originalgröße beizubehalten.) - Kleine Bilder/komplette Frames dekompilieren und bearbeiten:
Zerlegt automatisch alle Frames und Dauern, generiertpython3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/edit_walk.pymit 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):
Muss das generierte# 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/*_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 Pythongenerate_blob47_tileset) auf, um alle Innen-/Außenecken automatisch zu generieren und eine Testinselkarte*_blob47_inspect.pngzu erstellen. 2:1isometrische Gebäude und 4/8-Richtungs-RPG-Charaktere: VerwendeIsoScene, um eine rissfreie2:1-Szene mit Dreiseiten-Beleuchtung zu bauen; verwendeDirectionalRig+export_multidir_sheets, um aus Frontal-KomponentenS/E/N/W-Vier- oder Acht-Richtungs-Rotations- und Lauf-Atlanten zu generieren, und überprüfe*_alignment_inspect.pngauf 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.pnglesen, 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"oderexport_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.pngund*_torch_orbit_6x.gifzu 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 endesga32aus (Flood-Fill-Entfernung des Hintergrunds, Connected-Component-Zerlegung, einheitliche Skalierung, Farbanpassung, Schätzung von Schulter-/Hals-/Schwertknauf-Achsen). Überprüfe*_autorig_pipeline.pngund verfeinere dann die Aktionen im generiertenrig_*.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; verwendeRig.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 mitpforge.py aseprite-inspect file.aseprite --unpack-layersoderdecompilerückwärts zerlegt werden. - MCP native Tools bevorzugen: Wenn eine
pixelforgeMCP Server-Verbindung besteht (exponiert 12 Tools wiepixelforge_palette_guide,pixelforge_build,pixelforge_build_rig,pixelforge_region_patch,pixelforge_scene_check,pixelforge_aseprite_inspect, jede Ausgabe enthältagent_checklist.must_view_imagesund(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/.