Guía de las mascotas de escritorio de Codex
Qué es esto
Pets es una función de Codex App (la versión de escritorio) de OpenAI: una ventanita transparente y siempre visible en la que vive una mascota pixel. No es un adorno: sus animaciones están ligadas al estado de ejecución de Codex.
- Mientras Codex genera código, la mascota entra en la animación de «trabajando» y tiembla del ajetreo;
- Cuando Codex se detiene a esperar tu entrada, la mascota pasa a «esperando tu respuesta» y levanta la cabeza para mirarte;
- Si la tarea sale bien, salta para celebrarlo; si falla, se desinfla en el acto y le sale un sudor frío.
No hace falta cambiar de ventana: con echarle un vistazo a la mascota ya sabes si toca volver a la terminal.
Cómo poner en marcha una mascota
- Asegúrate de tener instalada la versión de escritorio de Codex App (no la CLI a secas) y activa Pets en los ajustes;
- Descarga el
.pet.zipde cualquier mascota desde el catálogo; - Descomprímelo en la carpeta pets, una carpeta por mascota:
# macOS / Linux
~/.codex/pets/<id-de-la-mascota>/
├── pet.json
└── spritesheet.webp (también vale PNG)
# Windows
%USERPROFILE%\.codex\pets\<id-de-la-mascota>\Una vez colocada, la verás en el selector de mascotas de Codex App. Si no aparece, reinicia Codex App.
Especificación del spritesheet (oficial)
Todas las animaciones de la mascota van en una sola imagen: 1536×1872 píxeles, PNG o WebP, con fondo transparente, dividida en 8 columnas × 9 filas de 192×208 cada una. Ojo: cada fila usa un número distinto de fotogramas (así lo fija el contrato oficial animation-rows.md), y las celdas sobrantes de cada fila tienen que quedar totalmente transparentes. De arriba abajo, el orden es este:
| Fila | ID de estado | Nombre | Fotogramas usados | Duración del bucle | Cuándo se reproduce |
|---|---|---|---|---|---|
| 0 | idle | En reposo | 6 | 1100ms | Respira tranquila y parpadea de vez en cuando |
| 1 | running-right | Corre a la derecha | 8 | 1060ms | Codex la manda a trabajar hacia la derecha |
| 2 | running-left | Corre a la izquierda | 8 | 1060ms | De vuelta a casa |
| 3 | waving | Saludo | 4 | 700ms | Te saluda con la mano antes de empezar la tarea |
| 4 | jumping | Salto | 5 | 840ms | Tarea completada: salta de alegría |
| 5 | failed | Error | 8 | 1220ms | Algo falló: se queda mustia y con un sudor frío |
| 6 | waiting | Esperando tu respuesta | 6 | 1010ms | Codex se ha parado a esperar tu entrada y ella te mira fijamente |
| 7 | running | Trabajando | 6 | 820ms | Codex está generando código y ella tiembla del ajetreo |
| 8 | review | Revisión | 6 | 1030ms | Entorna los ojos y repasa tu código de lado a lado |
Unas cuantas reglas en las que es fácil tropezar:
- La mascota entera tiene que caber dentro de la celda de 192×208, incluso en el punto más alto del salto;
- Transparente significa transparente de verdad: los píxeles no usados deben tener alfa 0 y sin valores RGB residuales, y no se pueden dibujar «efectos separados» como sombras semitransparentes, sombras en el suelo o líneas de velocidad (el validate_atlas.py oficial lo comprueba píxel a píxel);
- No dibujes texto legible ni logotipos sobre la mascota;
- Los detalles tienen que ser grandes: el tamaño final de visualización es diminuto y un motivo de uno o dos píxeles no se ve.
Qué pinta tiene pet.json
{
"id": "momo",
"displayName": "Momo",
"description": "A round cream-orange cat.",
"spritesheetPath": "spritesheet.webp"
}Con cuatro campos basta. El id se escribe en minúsculas y números, y tiene que coincidir con el nombre de la carpeta; spritesheetPath es la ruta relativa a pet.json.
Crear la tuya
Opción uno: que la dibuje la IA (la vía oficial). OpenAI ofrece la habilidad hatch-pet en openai/skills. Una vez instalada en Codex, describe el personaje que quieres: la habilidad recurre a la generación de imágenes para dibujar las 9 filas de animación una a una, las monta automáticamente en un spritesheet que cumple la especificación y deja el resultado directamente en ~/.codex/pets/. Perfecto para quien busca un acabado cuidado de dibujo a mano.
Opción dos: dibujarla con código, fotograma a fotograma (nuestra vía). Las 91 mascotas de este sitio están generadas por programa con Python + Pillow: dibujamos el cuerpo con bloques de color sobre una rejilla lógica de 24×26 y luego parametrizamos cada fotograma según el estado (el reposo es el vaivén de la respiración más un parpadeo; el salto es la curva de desplazamiento de agacharse, estirarse, volar y aterrizar; el fallo es achatar el cuerpo y añadir ojos en X y sudor frío). Al final se monta todo en una imagen de 1536×1872 respetando los fotogramas oficiales de cada fila. Cuando llegamos a varias decenas de mascotas, lo abstrajimos a un modelo «guiado por configuración»: la forma del cuerpo, la paleta, las orejas, la cola, las gafas o la bufanda son parámetros, y añadir una mascota nueva se reduce a escribir diez líneas de configuración.
Las dos vías dan lo mismo: un spritesheet que cumple la especificación y un pet.json. Cuando lo tengas, tira la carpeta en el directorio pets y a rodar.
Preguntas frecuentes
¿La mascota no se mueve o no aparece? Revisa primero la estructura de carpetas: pet.json tiene que estar directamente dentro de pets/<id>/, sin la carpeta extra que suele salir al descomprimir. Después comprueba que la imagen mida exactamente 1536×1872.
¿Qué diferencia hay entre V1 y V2? Lo que en la comunidad llaman V2 añade, además de las 9 filas básicas, 16 fotogramas de «mirar alrededor» en distintas orientaciones, para que la mascota pueda girarse hacia el ratón. Las mascotas con la especificación básica de 9 filas (las de este sitio incluidas) siguen funcionando perfectamente en las versiones nuevas de Codex App.
¿Puedo modificar las mascotas de este sitio? Sí. Las 91 son obras pixel originales (la serie inspiración solo toma prestado el tema, no incluye personajes protegidos por derechos de autor): modifícalas y compártelas a tu gusto, sin necesidad de atribución.