pixel-mascot

Creación de una mascota pixelada

Una mascota es un único archivo SVG de píxel art con animación CSS por pasos. Puede tener varios estados (inactivo, feliz, dormir, caminar, atacar…), cada uno como una clase en el elemento raíz: <svg class="happy"> reproduce happy. Construye mascotas con código, nunca editando a mano cientos de <rect>: la carpeta scripts/ de esta habilidad (<kit> debajo) contiene un pequeño kit y un ejemplo funcional. Todo es biblioteca estándar de Python; no hay nada que instalar.

Lee LESSONS.md junto a este archivo antes de dibujar nada. Enumera, con el síntoma, la causa y la solución, lo que salió mal mientras se creaban las primeras mascotas, y la mayor parte volverá a salir mal si se omite.

Dónde van las cosas

Pregunta al usuario dónde guardar la mascota. Si no tiene preferencia, usa ~/pixel-mascots/<nombre>/ (en Windows %USERPROFILE%\pixel-mascots\<nombre>\):

Archivo	Qué es
make_<nombre>.py	el constructor: cada cambio es una edición aquí y una re-ejecución
<nombre>.svg	la salida de la construcción, la mascota en sí
<nombre>_overrides.json	las ediciones manuales del usuario desde el estudio, aplicadas al final por el constructor
sheet.png	la vista previa, un fotograma fijo por estado

<nombre> son letras minúsculas, dígitos y guiones. Nunca pongas los archivos del usuario en <kit>: pertenece al plugin instalado y se reemplaza al actualizar.

Ejecución de los scripts

Usa el Python que tenga la máquina: python3 (macOS, Linux), python (Windows), o uv run python donde un bloqueador impida el python simple. Los constructores importan el kit, así que pon <kit> en PYTHONPATH al ejecutar uno:

PYTHONPATH="<kit>" python3 make_<nombre>.py <nombre>.svg

$env:PYTHONPATH = "<kit>"; python make_<nombre>.py <nombre>.svg

preview.py y el estudio no necesitan PYTHONPATH; el estudio lo establece para los constructores que ejecuta.

Qué debe hacer el SVG

1. Un estado por clase raíz. Estiliza cada estado con selectores .<estado> .parte{...}; los nombres de clase son los nombres de estado del usuario (minúsculas, guiones). El constructor escribe un estado predeterminado en la raíz (s.svg(..., state="idle")), para que el archivo se anime solo en un navegador o en un <img>; una aplicación muestra otro estado cambiando la clase de la raíz. Si no se nombran estados, crea uno: idle.
2. Pon cada color en una clase CSS dentro de su propio <style>. Una variable CSS (var(--accent,#hex)) funciona solo allí, nunca como atributo fill=.
3. Anima con fotogramas clave steps(1) que muevan celdas enteras (translateY(-1px) en un viewBox de celdas) o parpadeen la opacidad.
4. Ten un <title> (texto alternativo) y ningún <script>, ni on…=, ni imágenes externas, fuentes o enlaces, para que sea seguro mostrarlo en cualquier lugar.
5. Establece su tamaño dibujado con width/height en la raíz, un múltiplo entero de la cuadrícula: 32 celdas a 128 px (4 px por celda), 20 celdas a 80 px.
6. Respeta el movimiento reducido a menos que el usuario diga lo contrario: @media (prefers-reduced-motion:reduce){*{animation:none!important}}.

El flujo de trabajo

1. Define qué es la mascota, sus estados y sus 3-5 rasgos de identidad. Pregunta qué la hace reconocible a 128 px, exagera exactamente esos rasgos y descarta todo lo demás. Pregunta qué estados necesita; si no hay respuesta, crea un bucle inactivo. La idea del usuario decide, no el ejemplo aquí. Si el usuario comparte arte de otros artistas, úsalo solo como referencia (proporciones, estilo de contorno, cómo se dibuja un rasgo): nunca copies sus píxeles, y nunca pongas un personaje con derechos de autor en una construcción que se comparta o publique.

2. Encuentra su tipo en esta tabla. Indica qué partes dividir (cada parte se anima por sí sola) y qué puede llevar movimiento secundario, que es lo que hace que una mascota se sienta viva en lugar de una calcomanía que rebota.

   Tipo	Rasgos de identidad típicos	Partes, de atrás a adelante	Movimiento secundario
   Personaje humanoide	forma y color del cabello, ojos, un accesorio, atuendo, un objeto sostenido	hair-back, body, head (cara, flequillo, mechones frontales), prop	movimiento de cabeza/asentir, seguimiento del cabello, balanceo del objeto
   Animal	orejas, marcas, cola, hocico, color de ojos	tail, body, ears (anidado en la cabeza), head	orejas que caen, movimiento de cola, inclinación de cabeza
   Objeto (lámpara, taza, planta, aspiradora robot)	silueta, un detalle distintivo	back (cable, soporte), body, face (una cara dibujada en él), moving bits	vapor o movimiento de hoja, parpadeo de luz, paso de ruedas
   Criatura / blob / robot	silueta, un rasgo extraño (cuerno, antena, visor, brillo)	back, body, head, appendage	estiramiento y compresión, bamboleo de antena, parpadeo de brillo

   Las mascotas sin cara aún necesitan estados legibles: cambia la pose, los efectos y la velocidad en lugar de la expresión.

3. Elige el lienzo. 20×20 para una forma simple con pocos rasgos; 32×32 para cualquier cosa con varios rasgos o una cara que deba expresarse. Recorta al pecho o al asiento para personajes: la cara y los rasgos de identidad necesitan más espacio que las piernas. Dibuja a 4 px por celda.

4. Copia la plantilla, <kit>/example_mascot.py (Miso, un gato con tres estados), a make_<nombre>.py en la carpeta de la mascota, establece NAME y reemplaza las formas y estados. Mantén el constructor: el SVG es una salida de construcción. Mantén el último paso de la plantilla, apply_overrides(...): aplica las ediciones manuales del usuario desde el estudio (paso 10), así que reconstruir nunca las pierde.

5. Dibuja de atrás a adelante, una parte por cada cosa que se mueva por sí sola. Anida un apéndice dentro de aquello a lo que está unido (orejas dentro de la cabeza), para que siga el movimiento de esa parte y pueda moverse por sí solo. Herramientas del kit: rect, ellipse, polygon (orejas, aletas, cuernos), path (colas, cables, tallos), line, zigzag_bottom (bordes de cabello o flequillo), paint(..., only=...) para dibujar detalles sobre formas existentes, shade_edges para sombras y bordes. Llama a s.outline() una vez al final, para que cada parte lleve su propio contorno. Para personajes con cabello, sigue "Personajes con cabello" en LESSONS.md.

6. Una cara (o pose) por estado, como grupos activados con reglas de opacidad: f-open por defecto, más lo que encaje en cada estado. Las reacciones se leen mejor cuando difieren en forma, no solo en color: ojos cerrados ^ ^, ojos semicerrados, boca abierta, una banda de sombra. Las caras dibujadas en un personaje con flequillo saltan las celdas del cabello.

   • Ajusta cada estado al personaje. Cuando un estado no le sienta bien, pregunta, y ofrece momentos de su propia historia: un gesto o escena característico. Los grandes cambios de silueta se leen a 128 px; los detalles pequeños (una gema de 2 píxeles, una boca que se abre y cierra) no.
   • Un estado puede intercambiar partes enteras, no solo caras: un accesorio puesto o quitado, un sombrero bajado para dormir. Haz que cada pieza intercambiable sea su propia parte y ocúltala o muéstrala con .<estado> .parte{opacity:…}. Limita cada regla a un estado, para que los otros estados mantengan sus partes.
   • Cuando el usuario no está seguro, construye alternativas en lugar de discutir por una: deja que el constructor tome un nombre de variante como argumento, construye cada una en su propio archivo, y muéstralas lado a lado. Mantén la variante que le gustó al usuario antes: una reversión debe ser un solo argumento.

7. Efectos con s.fx(nombre, cls, fotogramas): destellos, líneas de velocidad, Z's, marcas de tambaleo, gotas de sudor. Los fotogramas se convierten en s1, s2… para animar fuera de sincronía.

8. Movimiento: fotogramas clave steps(1) y movimientos de celdas enteras (el píxel art debe avanzar por pasos, no deslizarse). La figura completa se coloca en un grupo .rig que salta o se balancea; además:

   • la cabeza se mueve, inclina o asiente por sí sola (hasta 2 celdas);
   • los apéndices (cabello, orejas, cola, antena) siguen con un retraso de como máximo un cuarto de ciclo; medio ciclo los pone en el lado opuesto y se lee como una estela;
   • los accesorios y partes móviles funcionan ligeramente fuera de ritmo. Un bucle inactivo es lento y pequeño: respiración, un parpadeo, una cola.

9. Construye y míralo antes de mostrarlo a alguien (comandos como en "Ejecución de los scripts"):

   PYTHONPATH="<kit>" python3 make_<nombre>.py <nombre>.svg
   python3 <kit>/preview.py <nombre>.svg sheet.png
   

   luego lee sheet.png: un fotograma fijo por estado, de izquierda a derecha. La vista previa muestra solo poses estáticas. Para ver el movimiento, inicia el estudio en segundo plano y abre http://127.0.0.1:8765/ en un navegador (el panel de navegador integrado, si lo hay):

   python3 <kit>/studio/server.py --svg <nombre>.svg --build make_<nombre>.py
   

   Muestra cada estado animándose en su propio marco. --states a,b selecciona y ordena los estados (por defecto: todos los estados que usa el CSS, en el orden en que aparecen por primera vez); --port cambia el puerto. Los usuarios revisan desde capturas de pantalla y a menudo marcan problemas en rojo: mapea las marcas a las celdas alineándolas con rasgos que conoces (la fila de los ojos, la boca), luego redibuja a lo largo de ellas. Después de una refactorización que no debería cambiar nada visible, construye la versión antigua y la nueva y compara los archivos byte a byte (cmp o fc /b).

10. Ediciones manuales. Cuando el usuario quiera arreglar píxeles por sí mismo, envíalo al /editor.html del estudio: pintar, borrar y elegir colores por estado, deshacer, luego guardar, lo que escribe <nombre>_overrides.json y reconstruye. Cada píxel pertenece a una parte y se mueve con ella; el editor indica qué parte y qué estados lo muestran. Una mascota sin constructor también funciona (omite --build): el estudio mantiene una copia sin modificar y las ediciones en <nombre>_studio/ junto al SVG y escribe el resultado en el SVG. Después de que el usuario edite, lee su archivo de anulaciones y la vista previa reconstruida antes de cambiar cualquier otra cosa, y di si una edición parece accidental (un píxel solitario lejos del resto).

11. Entrega: di dónde está el SVG, qué estado reproduce por defecto, y cómo mostrar otro (establece la clase de la raíz; un <img> no puede, así que una aplicación que cambie estados debe incluir el SVG en línea o cargarlo en un <object> o <iframe>).

profile.json (para una aplicación que muestre la mascota)

Una aplicación puede necesitar más que clases raíz: variables CSS en la raíz, clases adicionales, etiquetas de estado fijas. Un profile.json colocado en <kit> junto a preview.py le indica a la vista previa y al estudio. Cada clave es opcional:

{
  "states": [{ "class": "happy", "name": "happy", "label": "happy · on success", "style": "--speed:.5s" }],
  "rootClass": "always-animate",
  "swatches": { "var": "--accent", "label": "accent", "colors": ["#8FA8E8", "#ED93B1"] },
  "workdir": "~/my-app/studio"
}

states fija el orden, los nombres de los botones, los títulos y un estilo raíz por estado; rootClass se agrega a la raíz en cada fotograma; swatches agrega botones de color que establecen una variable CSS; workdir reemplaza <nombre>_studio/ para mascotas sin constructor. Este plugin no incluye ninguno.

Archivos en esta habilidad

Archivo	Qué es
LESSONS.md	Lo que funcionó y lo que no, con causas y soluciones. Léelo primero.
scripts/pixelkit.py	Formas (rect, ellipse, polygon, path, line), partes, sombreado, contornos por parte, salida SVG.
scripts/example_mascot.py	Miso: un gato de 32×32 con estados inactivo, feliz y dormido; la plantilla a copiar.
scripts/preview.py	Hoja PNG, un fotograma fijo por estado, solo biblioteca estándar.
scripts/pixel_overrides.py	Aplica ediciones manuales a un SVG terminado; los constructores lo llaman al final.
scripts/studio/	server.py + site/: cada estado animándose, y un editor de píxeles, para cualquier mascota. Solo local (127.0.0.1).