Guide des mascottes Codex
De quoi s'agit-il
Pets est une fonction de Codex App d'OpenAI (version bureau) : une petite fenêtre transparente reste au premier plan de l'écran, et une mascotte pixel vit dedans. Ce n'est pas de la décoration — ses animations sont liées à l'état d'exécution de Codex :
- quand Codex génère du code, la mascotte passe en « au travail » et tremble d'activité sur place ;
- quand Codex s'arrête et attend votre saisie, elle bascule sur « attend votre réponse » et lève la tête pour vous fixer ;
- tâche réussie : elle saute pour célébrer. Tâche échouée : elle s'affaisse aussitôt, goutte de sueur à l'appui.
Plus besoin de changer de fenêtre : un coup d'œil à la mascotte suffit pour savoir s'il faut retourner voir le terminal.
Comment installer une mascotte
- Assurez-vous d'avoir la version bureau de Codex App (pas seulement le CLI) et activez Pets dans les réglages ;
- téléchargez le
.pet.zipde la mascotte de votre choix depuis le catalogue ; - décompressez-le dans le dossier pets, un dossier par mascotte :
# macOS / Linux
~/.codex/pets/<id-de-la-mascotte>/
├── pet.json
└── spritesheet.webp (PNG accepté aussi)
# Windows
%USERPROFILE%\.codex\pets\<id-de-la-mascotte>\Une fois en place, la nouvelle mascotte apparaît dans le sélecteur de Codex App. Si elle ne s'affiche pas, redémarrez Codex App.
Les specs du spritesheet (officielles)
Toutes les animations d'une mascotte tiennent dans une seule image : 1536×1872 pixels, en PNG ou WebP, fond transparent, découpée en 8 colonnes × 9 lignes de 192×208 chacune. Attention : le nombre d'images utilisées varie d'une ligne à l'autre (c'est le contrat officiel animation-rows.md qui le fixe), et les cases inutilisées d'une ligne doivent rester entièrement transparentes. De haut en bas :
| Ligne | ID d'état | Nom | Images utilisées | Durée de boucle | Déclencheur |
|---|---|---|---|---|---|
| 0 | idle | Repos | 6 | 1100ms | Respire tranquillement, cligne des yeux de temps en temps |
| 1 | running-right | Court à droite | 8 | 1060ms | Codex l'envoie bosser à droite |
| 2 | running-left | Court à gauche | 8 | 1060ms | Sur le chemin du retour |
| 3 | waving | Salut | 4 | 700ms | Un petit signe de la main avant de démarrer la tâche |
| 4 | jumping | Saut | 5 | 840ms | Tâche terminée, saut de joie |
| 5 | failed | Échec | 8 | 1220ms | Ça a planté : elle s'affaisse sur place, goutte de sueur à l'appui |
| 6 | waiting | Attend votre réponse | 6 | 1010ms | Codex s'arrête et attend une entrée : elle vous fixe |
| 7 | running | Au travail | 6 | 820ms | Codex génère du code, elle en tremble d'activité |
| 8 | review | Relecture | 6 | 1030ms | Les yeux plissés, elle balaie votre code de gauche à droite |
Quelques règles sur lesquelles on se casse facilement les dents :
- la mascotte doit tenir entièrement dans la case de 192×208, y compris au sommet d'un saut ;
- transparent veut dire vraiment transparent : l'alpha des pixels inutilisés doit être à 0 sans valeur RVB résiduelle, et pas question de dessiner d'« effets détachés » comme une ombre semi-transparente, une ombre portée au sol ou des lignes de vitesse (le script officiel validate_atlas.py vérifie pixel par pixel) ;
- pas de texte lisible ni de logo sur la mascotte ;
- voyez grand pour les détails : la taille d'affichage finale est minuscule, un motif d'un ou deux pixels est tout simplement invisible.
À quoi ressemble pet.json
{
"id": "momo",
"displayName": "Momo",
"description": "A round cream-orange cat.",
"spritesheetPath": "spritesheet.webp"
}Quatre champs suffisent. id s'écrit en minuscules et chiffres, et doit correspondre au nom du dossier ; spritesheetPath est un chemin relatif à pet.json.
Fabriquer la sienne
Méthode 1 : laisser l'IA dessiner (la voie officielle). OpenAI propose la compétence hatch-pet dans openai/skills. Une fois installée dans Codex, décrivez le personnage voulu : elle fait appel à la génération d'images pour dessiner les 9 lignes d'animation une par une, les assemble automatiquement au bon format, et dépose le résultat directement dans ~/.codex/pets/. Idéal si vous cherchez un rendu dessiné à la main et soigné.
Méthode 2 : dessiner image par image en code (notre voie). Les 91 mascottes de ce site sont générées par programme avec Python + Pillow : le corps est composé d'aplats de couleur sur une grille logique de 24×26, puis chaque image reçoit ses paramètres selon l'état — le repos, c'est la respiration plus le clignement ; le saut, une courbe de déplacement accroupi/étiré/en l'air/atterrissage ; l'échec, un corps aplati avec des yeux en croix et une goutte de sueur. Le tout est enfin assemblé en une grande image de 1536×1872 selon le nombre d'images officiel de chaque ligne. Passé la barre des quelques dizaines de mascottes, nous avons tout abstrait en « piloté par configuration » : forme du corps, palette, oreilles, queue, lunettes, écharpe sont des paramètres, et ajouter une mascotte tient en dix lignes de config.
Les deux voies produisent la même chose : un spritesheet conforme et un pet.json. Il ne reste qu'à déposer le dossier dans pets et c'est parti.
Questions fréquentes
La mascotte ne bouge pas ou n'apparaît pas ? Vérifiez d'abord la hiérarchie des dossiers : pet.json doit se trouver directement dans pets/<id>/, sans dossier intermédiaire issu de la décompression. Vérifiez ensuite que l'image fait exactement 1536×1872.
Quelle différence entre V1 et V2 ? Ce que la communauté appelle V2 ajoute, en plus des 9 lignes de base, 16 images de « regard alentour » selon l'orientation, pour que la mascotte puisse suivre la souris. Les mascottes au format 9 lignes (dont les nôtres) restent parfaitement utilisables dans les versions récentes de Codex App.
Peut-on modifier les mascottes du site ? Oui. Les 91 sont des créations pixel originales (la série inspirations ne reprend que des genres, aucun personnage protégé par le droit d'auteur) : modifiez-les et rediffusez-les librement, sans obligation de mention.