CommunityImagengithub.com

pixel-forge

Taller completo de píxeles y animación visual multimodal. Crea desde cero sprites, iconos y escenas, descompila y modifica PNG/GIF/hojas de sprites existentes, convierte imágenes de alta resolución o bocetos de IA en píxeles limpios, extrae paletas y tonos de imágenes de referencia, y produce animaciones multipose con rotación RotSprite y velocidad de cuadros variable (GIF/APNG/WebP/Atlas Aseprite). Incluye detección de teselas sin fisuras 3x3 y UI de nueve mosaicos.

¿Qué es pixel-forge?

PixelForge es un conjunto completo de herramientas de código abierto para la creación, edición y animación de píxeles art, diseñado para ser utilizado por agentes de IA (como Claude Code, Cursor, Codex) o directamente por desarrolladores. Proporciona una interfaz de línea de comandos (CLI) y una biblioteca Python (`pixelforge`) con dependencias mínimas (solo `Pillow`). El sistema permite construir sprites y animaciones desde cero usando una sintaxis declarativa basada en cuadrículas ASCII, descompilar y modificar archivos existentes (PNG, GIF, hojas de sprites), y aplicar efectos como pixelado a partir de imágenes de alta resolución o bocetos de IA. También ofrece capacidades avanzadas como rotación RotSprite para animación de personajes, extracción de paletas de colores, detección de costuras en teselas (3x3), generación de terreno automático (47 bloques), descomposición de imágenes conceptuales en partes reutilizables (Sketch-to-Rig) y soporte completo para el formato nativo `.aseprite` con capas etiquetadas y marcos de acción. Incluye un panel de diagnóstico holográfico (`_inspect.png`) para verificación visual y un linter de píxeles incorporado. Se integra con un servidor MCP que expone útiles herramientas para agentes de IA.

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

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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)

  1. 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), Rig de partes locales compactas (dibujar solo la parte y posicionar con offset=(ox, oy), sin llenar toda la tela de puntos vacíos), o primitivas geométricas a nivel de píxel de PixelCanvas (líneas rectas anti-L, elipses simétricas, tramado ordenado de Bayer).
  2. Elegir la arquitectura correcta según la resolución:
    • 16x16 ~ 32x32: Escribir directamente una cuadrícula ASCII completa o un Rig ligero.
    • 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 de PixelCanvas + sello local stamp() + tramado ordenado dither_rect() + parche de región local para refinamiento.
  3. 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 informe Pixel Linter en 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.

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:

  1. 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.
  2. Personaje de múltiples partes / Jefe / .aseprite de 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 CLI pforge.py build-spec spec.json / Python build_from_spec(spec)):
      • Sintaxis de cuadrícula tolerante a errores: ¡soporta |..BBBB..| # comentario al final de línea con líneas verticales de alineación visual y pad_ragged=True para 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 directamente attach_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" o poses personalizadas), ¡genera automáticamente efectos de destello de espada, nubes de polvo, sombras y un .aseprite multicapa!
  3. 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 pasar outline_mode="selout", add_shadow=True para contorno y sombra automáticos).
  4. 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|iso para generar un andamio ejecutable con sys.path relativo ya configurado, y luego rellenar la lógica (evitando tener que escribir y depurar rutas manualmente).

III. Seis flujos de trabajo estándar

1. Crear píxeles art y animaciones de múltiples acciones desde cero

  1. Seleccionar la paleta: Dar prioridad a las paletas clásicas integradas "endesga32", "pico8", "sweetie16", "resurrect64", "gameboy", o usar pforge.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 activar outline_mode="selout" (contorno adaptativo a la iluminación).
  2. 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 + rotsprite para rotación alrededor de un punto de anclaje y squash_stretch.
    • Ritmo de impacto → debe usar durations_ms no uniformes (por ejemplo, carga 180ms → golpe explosivo 40ms → fotograma de pausa 55ms → amortiguación 150ms), junto con vfx_slash_arc / vfx_dust_puff / vfx_hit_spark.
    • Múltiples acciones para un solo personaje (idle / walk / attack) → usar SpriteActor para exportar de una vez animaciones individuales y un atlas combinado <actor>_master_atlas.png/.json.
  3. Ejecutar el script para exportar GIF + APNG con transparencia real + WebP dinámico sin pérdidas + JSON de Aseprite, leer _inspect.png para la autocomprobación visual y eliminar defectos.

2. Modificar píxeles art existentes (PNG / GIF / hoja de sprites)

  • Primero, diagnosticar con la imagen:
    python3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/
    
    (Nota: El motor identificará automáticamente las previsualizaciones ampliadas 4x/8x a escala entera y las restaurará sin pérdida a la cuadrícula de píxeles nativa 1x; si se necesita mantener la escala original, añadir --keep-scale.)
  • Descompilación y modificación de imágenes pequeñas/todos los fotogramas:
    python3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/
    
    Descompone automáticamente todos los fotogramas y sus duraciones, genera edit_walk.py con 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+):
    # 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/
    
    Es obligatorio leer *_diff.png generado, 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 Python generate_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:1 y personajes RPG de 4/8 direcciones: Usar IsoScene para construir una escena de bloques isométricos 2:1 sin grietas, con iluminación de tres lados; usar DirectionalRig + export_multidir_sheets para derivar conjuntos de rotación y caminata de 4 u 8 direcciones S/E/N/W desde partes frontales, y leer *_alignment_inspect.png para 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_mockup para 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.png para 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" o export_hd2d_bundle(..., part_layers=rig.render_part_layers(..., part_profiles={"sword": "ridge"})), para exportar de una vez *_albedo.png, *_normal.png, *_emission.png compatibles con Godot/Unity y *_torch_orbit_6x.gif, y verificar *_hd2d_inspect.png con 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.png y luego continuar refinando las animaciones en el archivo rig_*.py generado.

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; usando Rig.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/.aseprite existentes se pueden descompilar con pforge.py aseprite-inspect file.aseprite --unpack-layers o decompile para 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 como pixelforge_palette_guide, pixelforge_build, pixelforge_build_rig, pixelforge_region_patch, pixelforge_scene_check, pixelforge_aseprite_inspect, etc., y cada retorno incluye agent_checklist.must_view_images y 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 .aseprite binarios 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).

Skills relacionados