PixelForge — Construcción, refinamiento y animación de píxeles art para modelos de visión
Esta habilidad proporciona al LLM visual una capacidad industrial de producción y refinamiento inverso de activos de píxeles, a través de ./scripts/pforge.py (que ofrece tanto una interfaz CLI como una biblioteca Python pixelforge, con dependencia única en Pillow).
I. Reglas de oro estrictas (prohibido violarlas)
- Prohibido escribir listas de coordenadas dispersas a mano: Está terminantemente prohibido acumular decenas de líneas de
putpixel((x, y)). Las formas básicas deben usar cuadrículas de caracteres ASCII de ancho fijo (donde.y espacio representan transparencia de forma fija),Rigde partes locales compactas (dibujar solo la parte y posicionar conoffset=(ox, oy), sin llenar toda la tela de puntos vacíos), o primitivas geométricas a nivel de píxel dePixelCanvas(líneas rectas anti-L, elipses simétricas, tramado ordenado de Bayer). - Elegir la arquitectura correcta según la resolución:
16x16 ~ 32x32: Escribir directamente una cuadrícula ASCII completa o unRigligero.48x48 ~ 64x64: Debe ser por capas/partes (usar partes de bloques de color sin contorno +Rig(..., outline_mode="selout"|"outer")para unificar el contorno automáticamente); para modificar detalles locales, es preferible usar parches de región (Region Patch) en lugar de redibujar toda la imagen.64x64 ~ 128x128+: Usar un boceto geométrico dePixelCanvas+ sello localstamp()+ tramado ordenadodither_rect()+ parche de región local para refinamiento.
- Circuito cerrado de visión holográfica obligatorio:
- Cada generación o modificación generará un panel de diagnóstico holográfico
<name>_inspect.png(que contiene: leyenda de caracteres de paleta[char] #HEX+ cuadrícula de coordenadas(X, Y)con base en 0 y línea de suelo de referencia + vista previa real sobre fondo claro/oscuro sin cuadrícula + rastro de movimiento de cebolla rojo/azul de la silueta) y un informePixel Linteren la terminal. - ¡Antes de entregar, es obligatorio usar una herramienta de visualización de imágenes (como
read_file/view_image/Read) para examinar<name>_inspect.png(para tareas de modificación, también<name>_diff.png)! - Comparando las coordenadas en la imagen y las advertencias del Linter, verificar uno por uno: fugas en el contorno exterior (especialmente en previsualizaciones sobre fondo claro para contornos oscuros), dientes de sierra en líneas diagonales/curvas (Jaggies), desplazamiento del pie entre fotogramas (
baseline_y), y cambios de píxeles no deseados. Solo después de corregir y volver a verificar se puede entregar.
- Cada generación o modificación generará un panel de diagnóstico holográfico
II. Árbol de decisión de camino más corto con fricción cero para el agente (¡dar prioridad a la salida directa de cero scripts!)
Antes de actuar, elegir la forma de invocación que ahorre más tokens y código repetitivo, según la siguiente prioridad:
- Consultar tonos de caracteres de paleta (¡evitar errores de caracteres adivinados!):
- MCP:
pixelforge_palette_guide(palette="endesga32"); CLI:python3 <SKILL_DIR>/scripts/pforge.py palette-guide endesga32 - Obtener directamente la cadena de caracteres agrupados por tono
Sombra -> Tono medio -> Iluminación(por ejemplo,'b' -> 'B' -> 'C'), sin necesidad de buscar en tablas.
- MCP:
- Personaje de múltiples partes / Jefe /
.asepritede múltiples acciones con capas (0 líneas de código Python, sin aritmética de ajuste):- Llamada directa a MCP
pixelforge_build_rig(o CLIpforge.py build-spec spec.json/ Pythonbuild_from_spec(spec)):- Sintaxis de cuadrícula tolerante a errores: ¡soporta
|..BBBB..| # comentario al final de líneacon líneas verticales de alineación visual ypad_ragged=Truepara rellenar automáticamente los.faltantes al final! - Ajuste semántico de articulaciones (sin calcular coordenadas ni puntos de pivote): El torso principal se define con
at="center", el resto de partes escriben directamenteattach_to="torso", side="top"|"left"|"right"|"bottom", hinge="grip",canvas_size="auto"calcula automáticamente el cuadro delimitador del cuerpo completo y reserva márgenes para evitar que la espada se salga del lienzo. - Preajuste de acción en una línea:
clips={"idle": "idle_breathe", "attack": "melee_attack", "hit": "hurt_flash"}(también soporta"float_bob","slime_bounce"oposespersonalizadas), ¡genera automáticamente efectos de destello de espada, nubes de polvo, sombras y un.asepritemulticapa!
- Sintaxis de cuadrícula tolerante a errores: ¡soporta
- Llamada directa a MCP
- Iconos de 16x16 ~ 32x32 y objetos pequeños de un solo fotograma:
- Llamada directa a MCP
pixelforge_build(soporta dibujar bloques de color sin contorno y pasaroutline_mode="selout", add_shadow=Truepara contorno y sombra automáticos).
- Llamada directa a MCP
- Geometría programática compleja / Isométrica / Script de sandbox de combate real:
- Primero ejecutar
python3 <SKILL_DIR>/scripts/pforge.py init-script work/run.py --template rig|sprite|scene|isopara generar un andamio ejecutable consys.pathrelativo ya configurado, y luego rellenar la lógica (evitando tener que escribir y depurar rutas manualmente).
- Primero ejecutar
III. Seis flujos de trabajo estándar
1. Crear píxeles art y animaciones de múltiples acciones desde cero
- Seleccionar la paleta: Dar prioridad a las paletas clásicas integradas
"endesga32","pico8","sweetie16","resurrect64","gameboy", o usarpforge.py palette <ref.png>para extraer la paleta y tonos de una imagen de referencia. Iluminación predeterminada desde la esquina superior izquierda (iluminación cálida arriba a la izquierda, sombra fría abajo a la derecha). Se recomienda activaroutline_mode="selout"(contorno adaptativo a la iluminación). - Construir y vincular:
- Grandes cambios topológicos (como piernas cruzadas al caminar, transformación de colmillos al abrir la boca) → usar fotogramas clave ASCII o un diccionario de múltiples estados
Part{"closed": ..., "open": ...}. - Rotación/estiramiento de cuerpos rígidos (como tapa de caja girando sobre bisagra, movimiento de espada, respiración/rebote) → usar
Rig+rotspritepara rotación alrededor de un punto de anclaje ysquash_stretch. - Ritmo de impacto → debe usar
durations_msno uniformes (por ejemplo, carga180ms→ golpe explosivo40ms→ fotograma de pausa55ms→ amortiguación150ms), junto convfx_slash_arc/vfx_dust_puff/vfx_hit_spark. - Múltiples acciones para un solo personaje (
idle/walk/attack) → usarSpriteActorpara exportar de una vez animaciones individuales y un atlas combinado<actor>_master_atlas.png/.json.
- Grandes cambios topológicos (como piernas cruzadas al caminar, transformación de colmillos al abrir la boca) → usar fotogramas clave ASCII o un diccionario de múltiples estados
- Ejecutar el script para exportar GIF + APNG con transparencia real + WebP dinámico sin pérdidas + JSON de Aseprite, leer
_inspect.pngpara la autocomprobación visual y eliminar defectos.
2. Modificar píxeles art existentes (PNG / GIF / hoja de sprites)
- Primero, diagnosticar con la imagen:
(Nota: El motor identificará automáticamente las previsualizaciones ampliadaspython3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/4x/8xa escala entera y las restaurará sin pérdida a la cuadrícula de píxeles nativa1x; si se necesita mantener la escala original, añadir--keep-scale.) - Descompilación y modificación de imágenes pequeñas/todos los fotogramas:
Descompone automáticamente todos los fotogramas y sus duraciones, generapython3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/edit_walk.pycon paleta de caracteres semánticos y_inspect.png. Después de modificar el script, volver a ejecutar. - Cirugía de parche local para imágenes grandes (Region Patch, muy recomendado para 48x48+):
Es obligatorio leer# 1) Recortar una cuadrícula local usando coordenadas (X,Y,W,H) comenzando en 0; la imagen de autocomprobación generada conserva automáticamente las marcas de coordenadas X/Y globales. python3 <SKILL_DIR>/scripts/pforge.py region-extract hero.png --box 14,6,20,18 -o work/patch/ # 2) Editar el archivo de cuadrícula de caracteres .txt recortado y luego volver a escribir, generando automáticamente una imagen de comparación triple Before | After | Diff python3 <SKILL_DIR>/scripts/pforge.py region-apply hero.png --patch work/patch/hero_x14_y6_w20_h18.json -o work/out/*_diff.pnggenerado, confirmar que los cambios caen estrictamente en el área objetivo y que la transición de bordes es natural. - Recolorización semántica con un solo comando / variante de facción:
python3 <SKILL_DIR>/scripts/pforge.py recolor slime.gif --map B=R,b=r,C=Y -o work/fire_slime/
3. Convertir imágenes de alta resolución / bocetos conceptuales de IA en píxeles art (Pixelate & Clean)
Cuando el usuario proporciona ilustraciones de alta resolución, fotos o "pseudo-píxeles art" de IA con bordes borrosos:
# Para ilustraciones/imágenes conceptuales usar contrast_box; para pseudo-píxeles art de IA usar --mode dominant_block para eliminar cuadrículas torcidas y colores espurios
python3 <SKILL_DIR>/scripts/pforge.py pixelate draft.png --size 48x48 --palette endesga32 --outline "#181425" -o work/px/
Leer las imágenes *_compare.png y *_inspect.png generadas. En el archivo edit_*.py generado automáticamente, retocar manualmente los brillos en los ojos y alisar los escalones del contorno antes de entregar.
4. Teselas de mapa sin fisuras, terreno automático de 47 bloques (Auto-Tile), UI de nueve mosaicos, isométrico y autocomprobación de brillo de escena de juego real
- Ladrillo único sin fisuras y UI de nueve mosaicos:
pforge.py tile grass.png(detección de costuras rotas 3x3 marcadas en rojo);pforge.py nine-slice frame.png --margins 4,4,4,4 --size 160x56. - Terreno automático de 47 bloques Blob / 16 bloques Wang: Solo proporcionar dos ladrillos base (frente/fondo), llamar a
pforge.py autotile --fg grass.png --bg water.png --mode blob47(o Pythongenerate_blob47_tileset), combinará automáticamente todas las esquinas interiores y exteriores y desplegará un mapa de islas de prueba*_blob47_inspect.png. - Edificios isométricos
2:1y personajes RPG de 4/8 direcciones: UsarIsoScenepara construir una escena de bloques isométricos2:1sin grietas, con iluminación de tres lados; usarDirectionalRig+export_multidir_sheetspara derivar conjuntos de rotación y caminata de 4 u 8 direccionesS/E/N/Wdesde partes frontales, y leer*_alignment_inspect.pngpara verificar las líneas de alineación horizontal de la cabeza y los pies. - Sandbox de escena de juego real con múltiples activos y autocomprobación de brillo en escala de grises: Usar
SceneComposer+render_pixel_text(tipografía compacta de píxeles integrada) +build_scene_mockuppara sintetizar una animación de combate/exploración con orden de superposición del eje Y y UI de texto saltarín. Es obligatorio leer*_scene_inspect.pngpara verificar el mapa de calor de contraste del mapa de grises y la silueta, eliminando el conflicto de brillo que hace que el personaje se fusione con el fondo.
5. Iluminación dinámica de píxeles normales HD-2D y "descomposición de imagen generada → vinculación automática (Sketch-to-Rig)"
- Mapa de normales HD-2D e iluminación de antorcha de 360°: Llamar a
pforge.py normalmap hero.png --emit "#2CE8F5"oexport_hd2d_bundle(..., part_layers=rig.render_part_layers(..., part_profiles={"sword": "ridge"})), para exportar de una vez*_albedo.png,*_normal.png,*_emission.pngcompatibles con Godot/Unity y*_torch_orbit_6x.gif, y verificar*_hd2d_inspect.pngcon imagen de verificación de iluminación puntual en cuatro cuadrantes. - Descomposición automática de imagen conceptual y vinculación (Sketch-to-Rig): Para una imagen conceptual con partes sobre fondo de color sólido, ejecutar
pforge.py autorig sheet.png --canvas 56x56 --palette endesga32(eliminación segura de fondo por inundación de bordes, descomposición de componentes conectados, escalado unificado de colores, inferencia de puntos de pivote de hombros/cuello/empuñadura de espada), verificar*_autorig_pipeline.pngy luego continuar refinando las animaciones en el archivorig_*.pygenerado.
6. Lectura y escritura de archivos .aseprite binarios nativos con capas y llamada directa a herramientas MCP
- Soporte bidireccional de proyectos
.aseprite: Todos los flujos de construcción generan por defecto el archivo binario nativo<name>.aseprite; usandoRig.render_named_layers_sequence(poses)+write_aseprite(...), las partes y efectos se pueden guardar como capas de línea de tiempo independientes + etiquetas de acción + cortes de punto de pivote de articulación. Los artistas humanos pueden continuar dibujando por capas directamente en Aseprite; los archivos.ase/.asepriteexistentes se pueden descompilar conpforge.py aseprite-inspect file.aseprite --unpack-layersodecompilepara su análisis inverso. - Priorizar las herramientas nativas de MCP: Si la sesión actual ya está conectada al servidor MCP
pixelforge(que expone 12 herramientas comopixelforge_palette_guide,pixelforge_build,pixelforge_build_rig,pixelforge_region_patch,pixelforge_scene_check,pixelforge_aseprite_inspect, etc., y cada retorno incluyeagent_checklist.must_view_imagesy una receta de reparación(x, y)), es preferible llamar directamente a las herramientas MCP en lugar de escribir scripts temporales manuales.
IV. Plantilla declarativa sin aritmética Python
import sys
sys.path.insert(0, "/path/to/pixel-forge/scripts")
from pforge import build_from_spec, format_palette_guide
# Construir un personaje con múltiples partes, múltiples acciones y capas independientes .aseprite sin aritmética de coordenadas
res = build_from_spec({
"name": "ember_knight",
"palette": "endesga32",
"canvas_size": "auto",
"outline_mode": "selout",
"parts": [
{"name": "torso", "at": "center", "grid": ["|..RRRR..| # Pechera", "|.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")
# ¡Luego, asegúrese de verificar todos los paneles en res["agent_checklist"]["must_view_images"] usando herramientas visuales!
V. Manual de referencia avanzado (leer según sea necesario, divulgación progresiva)
Antes de ejecutar tareas específicas, consulte las guías temáticas bajo este directorio de habilidad:
- Modelado de píxeles art, antialiasing de clústeres de color, tonos claro-oscuro y técnicas de tramado: craft_and_shading.md
- Descompilación inversa, cirugía de parches locales para imágenes grandes y refinamiento de pixelado de imágenes de IA: edit_and_pixelate.md
- Rig de partes múltiples, rotación RotSprite, recetas de duración de fotogramas de impacto y biblioteca de efectos: animation_and_rigging.md
- Diseño de teselas sin fisuras 3x3 y especificaciones de UI de 9 cortes: tileset_and_ui.md
- Terreno automático de 47 bloques, autocomprobación de brillo de escena real, isométrico 2:1 y derivación de personajes de 4/8 direcciones: world_iso_and_scene.md
- Iluminación dinámica de píxeles normales HD-2D y descomposición automática de imágenes conceptuales de IA con vinculación: hd2d_and_autorig.md
- Lectura y escritura de archivos
.asepritebinarios nativos con capas y guía del servidor MCP: aseprite_and_mcp.md - Diccionario de referencia rápida de parámetros CLI completos y API de Python: cli_and_api.md
- Scripts de ejemplo ejecutables: Consulte los 10 scripts de extremo a extremo en el directorio
./examples/(01~10).