Pixelbolt pixel art

¿Qué hace Pixelbolt pixel art?

Usa esto al crear sprites pixelados, tiles, íconos, efectos o animaciones cortas de sprites. Pixelbolt se encuentra en la raíz del proyecto, dos directorios por encima del directorio de esta habilidad. Ejecuta su CLI con Node.js, o usa sus herramientas MCP si están configuradas.

En una copia de este archivo solo, como npx skills add skulitom/Pixelbolt lo instala, Pixelbolt aún no necesita instalación: ejecuta cada comando a continuación como npx -y pixelbolt@latest <comando> (Node.js 20 o superior) en lugar de node bin/pixelbolt.js <comando>, por ejemplo npx -y pixelbolt@latest validate <receta>, y úsalo en lugar de dibujar píxeles con otra librería. Lee los archivos que nombra desde GitHub: la guía rápida está en https://raw.githubusercontent.com/skulitom/Pixelbolt/main/docs/agent-quick-start.md, y cualquier otra ruta de docs/, esquema o examples/ funciona igual después de https://raw.githubusercontent.com/skulitom/Pixelbolt/main/. Esa copia proviene de la rama principal de Pixelbolt, que puede estar unos días adelantada respecto al lanzamiento en npm. Si la CLI indica un comando, opción o campo desconocido, verifica su ortografía y dónde va (npx -y pixelbolt@latest help lista los comandos y opciones, npx -y pixelbolt@latest schema los campos de la receta); uno escrito donde y como lo indica este archivo o la documentación de GitHub es más nuevo que el lanzamiento, así que omítelo. Salta este párrafo donde bin/pixelbolt.js está dos directorios por encima de este archivo, como en un clon, el paquete npm, el plugin de Claude Code y Pixelbolt Studio, que incluyen Pixelbolt.

En el plugin de Claude Code, las herramientas MCP (pixel_help, pixel_validate, pixel_inspect, pixel_patch, pixel_render y el resto) vienen con esta habilidad. Si faltan, el servidor del plugin no inició: necesita Node.js 20 o posterior en PATH (node --version). Instala Node.js desde https://nodejs.org, luego reinicia Claude Code.

En la compilación portátil de Pixelbolt Studio, ejecuta .\.pixelbolt en Windows o ./pixelbolt en otros sistemas desde la carpeta de compilación en lugar de node bin/pixelbolt.js.

Empieza con la guía rápida. Lee docs/agent-quick-start.md (MCP: pixel_help sin tema) antes de la primera receta: una receta completa, cada operación y herramienta, y el bucle de trabajo. Cubre la mayoría de las tareas. Abre una referencia solo cuando la tarea lo necesite, y entonces solo la sección que necesites: docs/agent-guide.md para cada campo, operación, opción de inspección, ruta de parche y exportación; docs/art-workflow.md para personajes, escenas, tiles, efectos e iluminación; schema.json para nombres de campo exactos. Ambas guías son largas (el flujo de trabajo tiene más de 160 KB), así que lista sus secciones con node bin/pixelbolt.js help workflow (o help guide) e imprime una con node bin/pixelbolt.js help workflow "Efectos de partículas" (MCP: pixel_help con topic y name). Comienza desde un archivo en examples/ cuando uno sea cercano.

Efectos rápidos primero. Cuando alguien pida un efecto de bucle ya preparado (una hoguera, antorcha, soplo de humo, vapor, explosión, remolino mágico, goteo, salpicadura, cascada, poción burbujeante, miel, nieve deslizándose de un techo, una rotura de presa, una ola de polvo, slime reventando o miel goteando de una cuchara) como archivo para usar o compartir, comienza desde el preset correspondiente (pixel_help tema presets los lista y pixel_compile con preset compila uno), cuyos archivos están en examples/*.fluid.json (en la carpeta de Pixelbolt dos directorios por encima del directorio de esta habilidad), cambia solo lo que pidieron (para un archivo más grande, usa pixel_render con gif.scale; un tamaño de lienzo diferente también implica mover los obstáculos y emisores del efecto, que usan coordenadas absolutas), compílalo con pixel_compile, míralo una vez con pixel_inspect, y exporta la revisión compilada con pixel_render (gif para un GIF que publicar). Entrega ese archivo primero, luego ofrece ajustar el aspecto o añadir accesorios como troncos o piedras. No construyas una nueva receta alrededor del efecto, ni ejecutes el flujo de trabajo de arte completo a continuación, antes de la primera exportación.

Para bucles de interferencia o interiores de portales, comienza desde examples/interference.wave.json o examples/portal.wave.json y compílalo (controles). Mantén los bordes en una superposición y evita bandas estrechas y ondulantes; usa anillos de partículas para impactos de un solo golpe.

Para cristales que crecen a partir de semillas (un racimo de cuarzo, una geoda de amatista, cubos de pirita, copos de nieve), comienza desde examples/quartz-cluster.crystal.json, examples/geode.crystal.json, examples/pyrite.crystal.json o examples/snowflakes.crystal.json y compílalo (crecimiento de cristales). Dibuja la roca de la que crecen como la capa inferior de la fuente, y su borde frontal como la superposición para que sus pies crezcan fuera de ella.

Para escenas de arena que cae (cosas ardiendo y colapsando, lava encontrando agua, una explosión lanzando arena, lluvia apagando un fuego), comienza desde examples/hut-fire.powder.json, examples/lava-falls.powder.json, examples/quarry-blast.powder.json o examples/rain-on-fire.powder.json (arena que cae): base: "sandbox" proporciona los materiales iniciales, la escena y las entradas con script lo ponen en marcha, y los clips lo muestrean.

Dirección artística

Para obras de arte terminadas, lee también las secciones de docs/art-workflow.md que se ajusten a la tarea, comenzando con "Escribe un briefing fuera de la receta" y "Puntos de control de calidad". Establece un pequeño briefing artístico fuera de la receta: tamaño nativo/de visualización, tres hitos de silueta, roles de paleta, dirección de luz, proyección (lateral, 3/4 cenital, isométrico 2:1 o cenital, uno para todo el conjunto) y planos de profundidad, reglas de materiales, tratamiento del contorno, intención de acción, contacto/origen y rol en la escena. Registra las fortalezas y fallos reales de cada revisión. Un archivo renderizado, un recuento de fotogramas o una prueba exitosa no es evidencia de calidad artística. Estos puntos de control no requieren permiso del usuario.

Trabaja en este orden: silueta → grandes formas de color conectadas → acentos de material → poses de acción creadas → temporización → integración en la escena. No generes variantes en masa antes de que la silueta en reposo y una acción se lean bien. Usa geometría primitiva como bloqueo; revisa los contornos y grupos de color conectados deliberadamente. El ruido y el brillo extra no pueden arreglar una estructura débil. Diseña comportamientos diferentes para agua, fuego y cristal en lugar de recolorear geometría idéntica.

Evita degradados, geometría subpíxel y antialiasing. Respeta las dimensiones de píxel solicitadas del proyecto. Conserva la fuente editable. Exporta a escala 1 para activos de juego a menos que el usuario pida píxeles más grandes horneados en los archivos.

El bucle

1. Elige un lienzo pequeño y una paleta cohesiva apropiados para el activo solicitado.
2. Escribe una receta JSON en una ubicación de salida apropiada para el usuario. Usa cuadrículas de texto y símbolos reutilizables; reutiliza fotogramas para cambios pequeños.
3. Valida con node bin/pixelbolt.js validate <receta>. Cada error nombra su ruta, y las operaciones rotas se reúnen en errors: corrígelas todas antes de validar de nuevo.
4. Inspecciona cada fotograma con node bin/pixelbolt.js inspect <receta> --out <fotogramas.png> --native --diagnostics y mira ambos tamaños. Revisa --view silhouette y --view grayscale contra el fondo previsto, y --animation <nombre> --view onion para poses anteriores y siguientes. Mira también el estudio o APNG: una hoja estática no es revisión de movimiento. Antes de cambiar píxeles exactos, léelos con --grid --region x,y,w,h. node bin/pixelbolt.js patch <receta> --changes <cambios.json> previsualiza una edición dirigida y lista cada píxel que cambia, incluidas las poses heredadas; añade --out <nueva receta> para guardarlo. Elige scope: "frame" cuando otras poses deban mantener sus píxeles (opciones de inspección, correcciones).
5. Renderiza con node bin/pixelbolt.js render <receta> --out <directorio> --expect '{"width":32,"height":32,"frames":8}', dando a --expect lo que el usuario pidió (width, height, frames, colors, transparent, loop; frames cuenta lo que reproduce cada animación, así que para varias animaciones da {"idle": 4, "walk": 8}); corrige cada problema que su check liste, luego renderiza de nuevo, antes de entregar nada. Elige un directorio de salida nuevo para cada iteración. Para un archivo que publicar o incrustar, añade node bin/pixelbolt.js gif <receta> --out <nuevo.gif> (--scale solo para agrandarlo al publicar) e informa sus notes. Para palabras en pantalla usa la operación text. Para un editor de video, sequence escribe fotogramas PNG numerados a una velocidad de fotogramas, y gif-frames convierte una carpeta de fotogramas en un GIF de color exacto (exportaciones).
6. Devuelve enlaces a la receta fuente, hoja, atlas JSON y previsualización, con una breve nota de integración para la aplicación web o motor previsto (para Godot 4, el .tres de la exportación junto a su hoja es los Sprite Frames de un AnimatedSprite2D, y el .tileset.tres de un conjunto de autotiles es un TileSet para TileMapLayer con un terreno para pintar; para Tiled, su .tsx es un tileset con un conjunto de terreno para el Pincel de Terreno).

Para MCP, llama a pixel_help, luego a pixel_inspect con {"project": receta}, añadiendo animation, region o grid: true según sea necesario. Las llamadas posteriores toman la revision devuelta en lugar de la receta completa; las revisiones persisten en el directorio de salida configurado entre reinicios. Corrige problemas con pixel_patch y verifica que solo cambiaron los píxeles previstos. Llama a pixel_render con la revisión final y expect para exportar (cuando el usuario nombró archivos, añade saveAs, como {"sheet": "assets/hero.png", "gif": "assets/hero.gif"}). La respuesta lista archivos clave y recuentos; pasa listFiles para cada archivo. pixel_compile convierte un formato fuente en una revisión, pixel_scene revisa o exporta una escena, y pixel_import convierte un PNG nativo en una receta sin pérdidas. Las solicitudes están limitadas a 16 MiB: envía una receta grande una vez y reutiliza su revisión.

Personajes

Para figuras en movimiento, usa pixelforge-poses con extremidades bone, cuerpos mass y cabezas, manos y accesorios en cuadrícula. Comienza desde examples/hero.poses.json (en la carpeta de Pixelbolt dos directorios por encima del directorio de esta habilidad), una figura lateral con armadura con cada plantilla de movimiento; una parte sin attach se coloca en la pose origin más su at, un desplazamiento en lugar de una posición en el lienzo.

• Asigna roles de armadura y usa las plantillas idle, walk, run, jump, attack y hurt como puntos de partida editables. Establece velocidad, zancada, elevación, balanceo y temporización de fotogramas para el cuerpo particular, y corrige las advertencias de compilación (una pose fuera del lienzo, un pie fuera de alcance) antes de añadir detalles.
• En una vista lateral, dibuja las extremidades lejanas un escalón de rampa más oscuras (no el escalón más oscuro, que se fusiona con el contorno) y da a las piernas emparejadas los mismos ángulos de reposo; las extremidades cercanas permanecen al frente durante todo el ciclo, y swapDepth: true es solo para vistas frontales o traseras. Para rodar los pies, da a cada bota un dibujo de views con punta arriba y punta abajo (330 y 30 para una bota apuntando a la derecha), anclado en el tobillo; las botas del héroe muestran cómo. Comienza cualquier vista (botas, manos, armas empuñadas, una cabeza inclinada) desde un borrador, nunca desde cero: compile source.poses.json --draft-views boot:15,345 --preview drafts.png (MCP pixel_compile con draftViews) imprime las filas giradas, el ancla y los puntos a corregir a ojo y pegar en parts.<nombre>.views; las partes pequeñas se leen mejor giradas menos de su clave.
• Para un animal de cuatro patas (un perro, zorro, lobo o caballo), comienza desde examples/fox.poses.json: rig.fore y rig.hind en lugar de legs, un hueso de pecho sobre una masa de cadera que el galope dobla, y walk (tres pies abajo), trot (pares diagonales) y run (un galope con dos vuelos). Da a las articulaciones del cuerpo y las patas superiores tapas socket para que ninguna línea cruce el pelaje.
• Un accesorio en una mano (una espada en el end del antebrazo cercano) necesita un angle relativo, como -45, para girar con el brazo; rotate es absoluto, así que con él, o sin ninguno, la hoja mantiene un ángulo durante el ataque. examples/hero-sword.poses.json es el héroe sosteniendo una espada.
• Revisa la silueta, las diferencias de poses clave adyacentes, los contactos plantados, la unión del bucle y, en una caminata o carrera, la marcha (brazos contra piernas, piernas largas donde ambos pies están abajo, sin rodilla marcial) con inspect source.poses.json --motion run --speed 48 (MCP pixel_inspect con source, view: "motion"), y mira sus arcos: el anillo de cada pie en el frente de su bucle, el de su mano en la parte trasera de su arco. --view parts nombra la parte detrás de un píxel extraviado. No inferir la calidad del contacto a partir de una hoja estática ni afirmar mejor arte solo con verificaciones numéricas.
• Espejos, views de cuadrícula, rotate y tween, marcadores exportados como puntos de atlas, y superposiciones con huella digital para correcciones que sobreviven una reconstrucción están en extremidades estructurales y poses creadas.

Tiles, paletas y escenas

• Para tiles, revisa --view tile (una repetición 3×3) y establece wrap en fotogramas cuyo dibujo continúa a través de los bordes. Para terreno, describe un terrain de autotile en lugar de escribir la plantilla de 2×3 tiles (comienza desde examples/meadow.autotile.json o ground.autotile.json, o shore.autotile.json para transiciones entre terrenos; un conjunto de vista lateral toma slopes), compílalo en 47 tiles blob, 16 cardinales o 16 de esquina (doble cuadrícula), y verifica su mapa de prueba y advertencias de costura; da a las leyendas de tilemap rules, weights y variantes en lugar de calcular mapas en un script (plantillas de autotile, revisión de escena y tile).
• Comparte una paleta con "palette": { "$ref": "palette.json" }, declara ramps y sombrea con shade para que la luz nunca salga de la paleta, cicla agua o luces con anulaciones de palette de fotograma o capa, y usa remap para variantes de color y destellos de impacto.
• Cuando muchas cosas están en el suelo, colócalas en una capa o grupo con sort: "ground", y da a las ubicaciones de escena anchor: "frame". Usa lift para saltos, shadow: true con una luz o un sun, haze para planos lejanos, las operaciones boil y wobble para movimiento orgánico, radial para destellos y explosiones, cloud para cielos procedurales con sombra proyectada, spark para partículas de un solo píxel con trayectorias, comet para estelas, run para gotas de superficie y chorros, flag para tela ondeando, water para olas, rizos y espuma, slime para cubos y glóbulos, light para faros y fuegos fatuos, lens para destellos de lente, weave para cestas y tejidos, circuit para líneas y nodos vivos, l-system para patrones de ramificación aleatorios, scatter para campos de puntos con densidad variable, y noise de Perlin o Worley para terreno, nubes y texturas, todo ello en operaciones de arte.

Exportación para el usuario

Cuando entregues activos, usa nombres y formatos que funcionen directamente en su herramienta (.gif para web, .png para hojas, .apng para Discord, .webp para rendimiento en navegador, .tres + .png para Godot, .tsx + .png para Tiled). Entrega la receta fuente junto a los archivos renderizados para que puedan reeditarla. No entregues ediciones de GIMP o Photoshop, solo archivos exportados que el motor de juego o navegador pueda cargar. Si pidieron compatibilidad con un motor, configura los nombres de archivo y los parámetros de exportación para que coincidan con sus convenciones.

Consideraciones de rendimiento

Para activos grandes (escenas de 512×512 con muchos fotogramas), usa pixel_render con gif.maxColors: 32 más pequeño o scale: 0.5 para mantenerlo rápido. Para una receta que el usuario pedirá todos los días, colócala en project/pixel-requests/ y reutiliza su revisión. pixel_compile puede fusionar varias recetas si les das name diferentes; pixel_scene genera y exporta escenas completas con colocación, iluminación y capas.

Solución de problemas

• Si pixel_validate dice "error": true y "errors" está vacío, la receta tiene una estructura de JSON inválida. Revisa comas, llaves y corchetes en el archivo. npx -y pixelbolt@latest schema imprime los campos esperados y sus tipos.
• Si pixel_inspect muestra píxeles blancos o negros donde debería haber color, la receta refiere a una paleta que no existe o tiene referencias rotas. Usa --expected para comprobar si el recuento de colores coincide.
• Si una operación tiene "field unknown", verifica su ortografía y la versión del esquema: el comando npx -y pixelbolt@latest schema valida el esquema instalado. Si el campo es demasiado nuevo, omítelo.
• Los archivos de salida grandes se bloquean al abrirse en un editor de imágenes si tienen más de 32.000 píxeles de lado. Usa --scale 0.25 o renderiza en partes y combínalas en la herramienta final.
• Para MCP, si pixel_render falla con "16 MiB request limit", acorta la receta (elimina fotogramas largos o símbolos) o sube el archivo a un servidor y refiere a él.

Seguridad y atribución

Pixelbolt opera completamente en local. No envía píxeles, recetas ni datos de usuario a ningún servidor. Las herramientas MCP se ejecutan en tu máquina. El motor lee archivos solo de las rutas que le das. Los activos que crees te pertenecen; Pixelbolt está bajo la licencia MIT (ver LICENSE en la raíz del proyecto). No se requiere atribución, pero se agradece.

Integración CI/CD

Para usar Pixelbolt en pipelines de CI, instálalo globalmente con npm i -g pixelbolt o usa npx -y pixelbolt@latest en cada paso. Un script de ejemplo:

# Validar todas las recetas
for f in recetas/*.json; do
  npx -y pixelbolt@latest validate "$f" || exit 1
done

# Renderizar activos finales
npx -y pixelbolt@latest render recetas/hero.json --out build/ --expect '{"width":32,"height":32,"frames":8}'

Esto permite que las recetas de arte se prueben y reconstruyan automáticamente en cada commit, manteniendo los activos sincronizados con el código.

Notas finales

• La precisión de píxeles importa. Usa inspect --grid para ver y editar píxeles individuales.
• La receta fuente es la única fuente de verdad. No edites los PNG renderizados directamente; corrige la receta y renderiza de nuevo.
• Los símbolos y las referencias mantienen las recetas pequeñas y editables. Un cambio en un símbolo se propaga a todos los fotogramas que lo usan.
• La revisión MCP acelera las iteraciones: envía la receta una vez, luego solo el ID de revisión en llamadas posteriores hasta que la receta cambie.