PixelForge — Construction, retouche et animation de pixel art pour modèles visuels
Ce skill permet aux LLMs visuels de produire des actifs pixel art de qualité industrielle et de les retoucher inversement via ./scripts/pforge.py (CLI + bibliothèque Python pixelforge, dépend uniquement de Pillow).
1. Règles fondamentales (strictement obligatoires)
- Interdiction d'écrire des listes de coordonnées clairsemées : Il est interdit d'accumuler des dizaines de lignes
putpixel((x, y)). Les formes de base doivent utiliser une grille de caractères ASCII à largeur fixe (.et espace représentent systématiquement la transparence), des sous-parties localesRig(ne dessiner que la pièce elle-même et la positionner viaoffset=(ox, oy), sans remplir de points vides sur toute la toile), ou les primitives géométriques pixel dePixelCanvas(lignes anti-crénelées, ellipses symétriques, tramage Bayer). - Choisir la bonne architecture selon la résolution :
16x16 ~ 32x32: Écrire directement une grille ASCII pleine toile ou unRigléger.48x48 ~ 64x64: Doit être divisé en couches/sous-parties (utiliser des sous-parties sans contour +Rig(..., outline_mode="selout"|"outer")pour un contour unifié automatique) ; pour les modifications locales, privilégier Region Patch plutôt qu'un redessin complet.64x64 ~ 128x128+: Utiliser un canevasPixelCanvas+stamp()pour les tampons locaux +dither_rect()pour le tramage ordonné + Region Patch pour les retouches fines.
- Boucle visuelle holographique multimodale obligatoire :
- Chaque génération ou modification produit un tableau de bord d'inspection
<name>_inspect.png(contenant : légende des caractères de la palette[car] #HEX+ grille de coordonnées(X, Y)commençant à 0 et ligne de base au sol + aperçu réel sans grille sur fond sombre/clair + trajectoire de mouvement en oignon rouge/cyan et silhouette) et un rapportPixel Linteren terminal. - Avant de livrer, doit obligatoirement utiliser un outil de visualisation (ex :
read_file/view_image/Read) pour consulter<name>_inspect.png(pour les modifications, aussi<name>_diff.png) ! - Vérifier une par une sur l'image les coordonnées et les avertissements du Linter : trous dans le contour extérieur (surtout sur fond clair), crénelage en escalier sur les diagonales/arcs (
Jaggies), dérive de la ligne de pied entre les frames (baseline_y), et modifications non intentionnelles. Ne livrer qu'après correction et re-vérification.
- Chaque génération ou modification produit un tableau de bord d'inspection
2. Arbre de décision du chemin le plus court (zéro friction, zéro code scaffold !)
Avant de commencer, choisir la méthode d'appel la plus économe en tokens et sans code passe-partout :
- Consulter les nuances de caractères de la palette (éviter les erreurs de prédiction de caractères) :
- MCP :
pixelforge_palette_guide(palette="endesga32"); CLI :python3 <SKILL_DIR>/scripts/pforge.py palette-guide endesga32 - Obtient directement les chaînes de caractères groupées par teinte
Ombre -> Ton moyen -> Lumière(ex :'b' -> 'B' -> 'C'), sans avoir à chercher dans des tables.
- MCP :
- Personnage multi-parties / Boss /
.asepritemulti-actions (0 ligne de code Python, zéro calcul d'adsorption) :- Appel direct MCP
pixelforge_build_rig(ou CLIpforge.py build-spec spec.json/ Pythonbuild_from_spec(spec)) :- Syntaxe de grille tolérante : Supporte les
|..BBBB..| # commentaire de fin de ligneavec barres verticales d'alignement visuel etpad_ragged=Truepour compléter automatiquement les.manquants en fin de ligne ! - Adsorption sémantique des articulations (pas besoin de calculer les coordonnées ni les pivots) : Le torse central définit
at="center", les autres parties écrivent directementattach_to="torso", side="top"|"left"|"right"|"bottom", hinge="grip",canvas_size="auto"calcule automatiquement la boîte englobante complète avec marge de sécurité anti-découpage pour les épées. - Préréglages d'action en une ligne :
clips={"idle": "idle_breathe", "attack": "melee_attack", "hit": "hurt_flash"}(support aussi"float_bob","slime_bounce"ouposespersonnalisées), avec effets de traînée/particules, ombres et.asepritemulti-couche !
- Syntaxe de grille tolérante : Supporte les
- Appel direct MCP
- Icônes et petits objets fixes 16x16 ~ 32x32 :
- Appel direct MCP
pixelforge_build(support du dessin de blocs de couleur sans contour + passage deoutline_mode="selout", add_shadow=Truepour un contour et une ombre automatiques).
- Appel direct MCP
- Scripts de géométrie procédurale complexe / isométrique / bac à sable de combat en temps réel :
- D'abord exécuter
python3 <SKILL_DIR>/scripts/pforge.py init-script work/run.py --template rig|sprite|scene|isopour générer d'une touche un échafaudage exécutable avecsys.pathrelatif déjà configuré, puis remplir la logique (pas besoin d'écrire manuellement la concaténation de chemins sujette aux erreurs).
- D'abord exécuter
3. Six workflows standards
1. Création de pixel art et d'animations multi-actions à partir de zéro
- Choisir la palette : Privilégier les palettes classiques intégrées
"endesga32","pico8","sweetie16","resurrect64","gameboy", ou utiliserpforge.py palette <ref.png>pour extraire la palette et les nuances d'une image de référence. Source lumineuse par défaut en haut à gauche (haut-gauche chaud + clair, bas-droite froid + ombre). Recommanderoutline_mode="selout"(contour adaptatif à la lumière). - Construire et lier :
- Changements topologiques importants (mouvement de jambes croisées, déformation de bouche avec crocs) → Utiliser des images clés ASCII ou un dictionnaire multi-états
Part{"fermé": ..., "ouvert": ...}. - Rotation/compression de corps rigide (couvercle de caisse qui s'ouvre sur charnière, coup d'épée, rebond de respiration) → Utiliser
Rig+rotspritepour rotation autour d'un point d'ancrage etsquash_stretch. - Rythme d'impact → Doit utiliser des
durations_msnon uniformes (ex : charge180ms→ coup violent40ms→ arrêt sur image55ms→ amorti150ms), combiné àvfx_slash_arc/vfx_dust_puff/vfx_hit_spark. - Un personnage avec plusieurs actions (
idle/walk/attack) → UtiliserSpriteActorpour exporter d'une touche les animations individuelles et l'atlas fusionné<actor>_master_atlas.png/.json.
- Changements topologiques importants (mouvement de jambes croisées, déformation de bouche avec crocs) → Utiliser des images clés ASCII ou un dictionnaire multi-états
- Exécuter le script pour exporter GIF + APNG semi-transparent + WebP dynamique sans perte + Aseprite JSON, consulter
_inspect.pngpour l'auto-inspection visuelle et corriger les défauts.
2. Modifier un pixel art existant (PNG / GIF / feuille de sprites)
- D'abord diagnostiquer avec une image :
(Note : Le moteur reconnaît automatiquement les aperçus agrandispython3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/4x/8xet les réduit en grille native1x; ajouter--keep-scalesi besoin de conserver la taille d'origine.) - Décompilation et modification d'images petites/toutes les frames :
Décompose automatiquement toutes les frames et leurs durées, génèrepython3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/edit_walk.pyavec une palette de caractères sémantique et_inspect.png. Modifier le script et relancer. - Retouche chirurgicale locale pour grandes images (Region Patch, fortement recommandé pour 48x48+) :
Doit consulter le# 1) Découper une grille locale selon les coordonnées (X,Y,W,H) commençant à 0 ; l'image d'inspection conserve automatiquement les graduations X/Y globales ! python3 <SKILL_DIR>/scripts/pforge.py region-extract hero.png --box 14,6,20,18 -o work/patch/ # 2) Éditer le fichier texte .txt de la grille découpée, puis réécrire ; sortie automatique d'une image de comparaison Avant | Après | Diff python3 <SKILL_DIR>/scripts/pforge.py region-apply hero.png --patch work/patch/hero_x14_y6_w20_h18.json -o work/out/*_diff.pnggénéré pour confirmer que les modifications sont strictement dans la zone cible et que la jonction de bord est naturelle. - Re-coloration sémantique en une touche / variante de faction :
python3 <SKILL_DIR>/scripts/pforge.py recolor slime.gif --map B=R,b=r,C=Y -o work/fire_slime/
3. Conversion d'image haute résolution / croquis concept AI en pixel art (Pixelate & Clean)
Lorsque l'utilisateur fournit une illustration haute résolution, une photo ou une "fausse pixel art" générée par AI aux bords flous :
# Pour les illustrations/concepts : utiliser contrast_box ; pour les fausses pixel art AI : utiliser --mode dominant_block pour éliminer les grilles tordues et les couleurs parasites
python3 <SKILL_DIR>/scripts/pforge.py pixelate draft.png --size 48x48 --palette endesga32 --outline "#181425" -o work/px/
Consulter les *_compare.png et *_inspect.png générés. Dans le fichier edit_*.py auto-généré, peaufiner manuellement les reflets dans les yeux et lisser les contours en escalier avant de livrer.
4. Tileset sans couture, auto-tiling 47 tuiles, UI 9-slice, isométrique et vérification de la luminosité des scènes en temps réel
- Tuile simple sans couture et UI 9-slice :
pforge.py tile grass.png(détection des défauts de jonction 3x3 en rouge) ;pforge.py nine-slice frame.png --margins 4,4,4,4 --size 160x56. - Auto-tiling 47 tuiles Blob / 16 tuiles Wang : Fournir uniquement deux tuiles de base (avant-plan et arrière-plan), appeler
pforge.py autotile --fg grass.png --bg water.png --mode blob47(ou Pythongenerate_blob47_tileset), qui synthétise automatiquement tous les coins intérieurs/extérieurs et génère une carte test d'archipel*_blob47_inspect.png. - Bâtiments isométriques
2:1et personnages RPG 4/8 directions : UtiliserIsoScenepour construire des scènes de blocs isométriques2:1sans fissures, éclairés sur trois faces ; utiliserDirectionalRig+export_multidir_sheetspour dériver des sprites de rotation et de marche dans les directionsS/E/N/Wou les 8 directions à partir d'une seule pièce de face, puis consulter*_alignment_inspect.pngpour vérifier les lignes d'alignement horizontal de la tête/des pieds. - Bac à sable de scène temps réel multi-actifs et vérification de la luminosité en niveaux de gris : Utiliser
SceneComposer+render_pixel_text(police pixel compacte intégrée) +build_scene_mockuppour synthétiser un GIF de combat/exploration en temps réel avec tri d'occlusion Y et UI à texte sauté. Doit obligatoirement consulter*_scene_inspect.pngpour vérifier la carte de chaleur de contraste des silhouettes en niveaux de gris et éliminer les problèmes de luminosité où le personnage se fond dans le fond.
5. Éclairage dynamique de normale pixel HD-2D et "croquis vers rig" (Sketch-to-Rig)
- Carte de normales HD-2D et éclairage torche 360° : Appeler
pforge.py normalmap hero.png --emit "#2CE8F5"ouexport_hd2d_bundle(..., part_layers=rig.render_part_layers(..., part_profiles={"épée": "ridge"})), exporter d'une touche*_albedo.png,*_normal.png,*_emission.pnget*_torch_orbit_6x.gifcompatibles Godot/Unity, puis consulter*_hd2d_inspect.pngpour l'image de validation à 4 quadrants avec sources lumineuses ponctuelles. - Décomposition et liaison automatiques d'une image de conception explosive (Sketch-to-Rig) : Pour une image concept avec des parties sur fond uni, exécuter
pforge.py autorig sheet.png --canvas 56x56 --palette endesga32(détourage de fond sécurisé par inondation de bord, décomposition par composantes connexes, verrouillage des couleurs à l'échelle unifiée, inférence des pivots d'épaule/cou/poignée d'épée), consulter*_autorig_pipeline.pngpuis continuer à peaufiner les actions dans le fichierrig_*.pygénéré.
6. Lecture/écriture de projets .aseprite binaires multi-couches natifs et appels directs d'outils MCP
- Support bidirectionnel des projets
.aseprite: Tous les workflows de construction sortent par défaut en binaire natif<name>.aseprite; utiliserRig.render_named_layers_sequence(poses)+write_aseprite(...)pour enregistrer chaque partie et effet en couches de timeline indépendantes + étiquettes d'action + Slice d'axe d'articulation, permettant aux artistes humains de continuer à dessiner directement dans Aseprite en couches ; les fichiers.ase/.asepriteexistants peuvent être décompilés inversement avecpforge.py aseprite-inspect file.aseprite --unpack-layersoudecompile. - Priorité aux outils MCP natifs : Si la session en cours est connectée au serveur MCP
pixelforge(exposantpixelforge_palette_guide,pixelforge_build,pixelforge_build_rig,pixelforge_region_patch,pixelforge_scene_check,pixelforge_aseprite_inspectet 12 outils, chaque retour incluantagent_checklist.must_view_imageset une prescription de correction(x, y)), privilégier les appels directs MCP plutôt que d'écrire des scripts temporaires.
IV. Template déclaratif Python sans arithmétique
import sys
sys.path.insert(0, "/chemin/vers/pixel-forge/scripts")
from pforge import build_from_spec, format_palette_guide
# Construction d'un personnage multi-parties, multi-actions, avec .aseprite en couches indépendantes, sans aucun calcul de coordonnées
res = build_from_spec({
"name": "chevalier_braise",
"palette": "endesga32",
"canvas_size": "auto",
"outline_mode": "selout",
"parts": [
{"name": "torse", "at": "center", "grid": ["|..RRRR..| # plastron", "|.RYYYYR.|", "|RRRRRRRR|", "|.rrrrrr.|"]},
{"name": "tête", "attach_to": "torse", "side": "top", "grid": ["|.1111.|", "|1KKKK1|", "|.2222.|"]},
{"name": "épée", "attach_to": "torse", "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")
# Ensuite, vérifier impérativement avec un outil visuel tous les tableaux de bord dans res["agent_checklist"]["must_view_images"] !
V. Manuel de référence avancé (lecture à la demande, divulgation progressive)
Avant d'exécuter une tâche spécifique, consulter les guides spécialisés dans le répertoire de ce skill :
- Mise en forme pixel art, anti-crénelage des clusters de couleurs, nuances et techniques de tramage : craft_and_shading.md
- Décompilation inverse, chirurgie locale par Patch sur grandes images, et retouche de pixel art issu d'AI : edit_and_pixelate.md
- Rig multi-parties, rotation RotSprite, recettes de durée de frame pour l'impact et bibliothèque d'effets : animation_and_rigging.md
- Conception de tileset sans couture 3x3 et normes UI 9-slice : tileset_and_ui.md
- Auto-tiling 47 tuiles, vérification de luminosité des scènes temps réel, isométrique 2:1 et dérivation de personnages 4/8 directions : world_iso_and_scene.md
- Éclairage dynamique de normale pixel HD-2D et décomposition/liaison automatique d'image concept AI : hd2d_and_autorig.md
- Lecture/écriture de projets
.asepritebinaires multi-couches natifs et guide du serveur MCP : aseprite_and_mcp.md - Dictionnaire de référence rapide des paramètres CLI et de l'API Python : cli_and_api.md
- Scripts d'exemple exécutables : Voir les 10 scripts de bout en bout dans le répertoire
./examples/(01à10).