pixel-mascot

Création d'une mascotte pixel

Une mascotte est un fichier SVG unique représentant du pixel art avec une animation CSS par étapes. Elle peut avoir plusieurs états (inactif, heureux, sommeil, marche, attaque…), chacun étant une classe sur l'élément racine : <svg class="joyeux"> joue l'état joyeux. Construisez les mascottes avec du code, jamais en éditant manuellement des centaines de <rect> : le dossier scripts/ de cette compétence (<kit> ci-dessous) contient un petit kit et un exemple fonctionnel. Tout est en Python de la bibliothèque standard ; rien à installer.

Lisez LESSONS.md à côté de ce fichier avant de dessiner quoi que ce soit. Il liste, avec le symptôme, la cause et la correction, ce qui a mal fonctionné lors de la création des premières mascottes, et la plupart de ces problèmes se reproduiront si vous ne les lisez pas.

Où placer les fichiers

Demandez à l'utilisateur où conserver la mascotte. S'il n'a pas de préférence, utilisez ~/pixel-mascots/<nom>/ (sous Windows %USERPROFILE%\pixel-mascots\<nom>\) :

Fichier	Description
make_<nom>.py	le constructeur : chaque modification se fait ici et est suivie d'une réexécution
<nom>.svg	le résultat de la construction, la mascotte elle-même
<nom>_overrides.json	les modifications manuelles de l'utilisateur depuis le studio, appliquées en dernier par le constructeur
sheet.png	l'aperçu, une image fixe par état

<nom> est composé de lettres minuscules, de chiffres et de traits d'union. Ne placez jamais les fichiers d'un utilisateur dans <kit> : il appartient au plugin installé et est remplacé lors des mises à jour.

Exécution des scripts

Utilisez le Python disponible sur la machine : python3 (macOS, Linux), python (Windows), ou uv run python là où un intermédiaire bloque l'utilisation directe de python. Les constructeurs importent le kit, donc placez <kit> dans PYTHONPATH lors de l'exécution :

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

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

preview.py et le studio n'ont pas besoin de PYTHONPATH ; le studio le définit pour les constructeurs qu'il exécute.

Ce que le SVG doit faire

1. Un état par classe racine. Stylisez chaque état avec des sélecteurs .<état> .partie{...} ; les noms de classe sont les noms d'état de l'utilisateur (minuscules, traits d'union). Le constructeur écrit un état par défaut sur la racine (s.svg(..., state="inactif")), donc le fichier s'anime tout seul dans un navigateur ou une balise <img> ; une application affiche un autre état en changeant la classe de la racine. Si aucun état n'est nommé, créez-en un : inactif.
2. Placez chaque couleur dans une classe CSS à l'intérieur de son propre <style>. Une variable CSS (var(--accent,#hex)) ne fonctionne que là, jamais comme attribut fill=.
3. Animez avec des images clés steps(1) qui déplacent des cellules entières (translateY(-1px) dans un viewBox de cellules) ou font clignoter l'opacité.
4. Ayez un <title> (texte alternatif) et pas de <script>, pas de on…=, pas d'images, polices ou liens externes, afin qu'il soit sûr à afficher partout.
5. Définissez sa taille dessinée avec width/height sur la racine, un multiple entier de la grille : 32 cellules à 128 px (4 px par cellule), 20 cellules à 80 px.
6. Respectez la réduction de mouvement sauf si l'utilisateur dit le contraire : @media (prefers-reduced-motion:reduce){*{animation:none!important}}.

Le flux de travail

1. Déterminez ce qu'est la mascotte, ses états et ses 3 à 5 caractéristiques d'identité. Demandez ce qui la rend reconnaissable à 128 px, exagérez exactement ces éléments et laissez tomber tout le reste. Demandez quels états elle nécessite ; sans réponse, créez une boucle d'inactivité. L'idée de l'utilisateur décide, pas l'exemple ici. Si l'utilisateur partage des œuvres d'autres artistes, utilisez-les uniquement comme direction (proportions, style de contour, manière de dessiner un élément) : ne copiez jamais leurs pixels et ne placez jamais un personnage protégé par le droit d'auteur dans une construction qui est partagée ou publiée.

2. Trouvez son type dans ce tableau. Il indique en quelles parties diviser (chaque partie s'anime indépendamment) et ce qui peut porter un mouvement secondaire, ce qui rend une mascotte vivante plutôt qu'un autocollant qui rebondit.

   Type	Caractéristiques d'identité typiques	Parties, de l'arrière vers l'avant	Mouvement secondaire
   Personnage humanoïde	forme et couleur des cheveux, yeux, un accessoire, tenue, un objet tenu	cheveux-arrière, corps, tête (visage, frange, mèches avant), accessoire	hochement/inclinaison de tête, suivi des cheveux, balancement de l'accessoire
   Animal	oreilles, marques, queue, museau, couleur des yeux	queue, corps, oreilles (imbriquées dans la tête), tête	oreilles qui battent, queue qui remue, inclinaison de la tête
   Objet (lampe, tasse, plante, aspirateur robot)	silhouette, un détail signature	arrière (câble, socle), corps, visage (un visage dessiné dessus), parties mobiles	vapeur ou feuille qui bouge, clignotement de lumière, roues qui avancent
   Créature / blob / robot	silhouette, un élément bizarre (corne, antenne, visière, lueur)	arrière, corps, tête, appendice	compression et étirement, oscillation de l'antenne, clignotement de la lueur

   Les mascottes sans visage ont toujours besoin d'états lisibles : changez la pose, les effets et la vitesse plutôt que l'expression.

3. Choisissez la toile. 20×20 pour une forme simple avec peu de caractéristiques ; 32×32 pour tout ce qui a plusieurs caractéristiques ou un visage qui doit exprimer des émotions. Recadrez au niveau de la poitrine ou de l'assise pour les personnages : le visage et les caractéristiques d'identité ont plus besoin d'espace que les jambes. Dessinez à 4 px par cellule.

4. Copiez le modèle, <kit>/example_mascot.py (Miso, un chat avec trois états), vers make_<nom>.py dans le dossier de la mascotte, définissez NAME et remplacez les formes et les états. Gardez le constructeur : le SVG est un résultat de construction. Conservez la dernière étape du modèle, apply_overrides(...) : elle applique les modifications manuelles de l'utilisateur depuis le studio (étape 10), donc la reconstruction ne les perd jamais.

5. Dessinez de l'arrière vers l'avant, une partie par chose qui bouge indépendamment. Imbriquez un appendice à l'intérieur de ce à quoi il est attaché (oreilles à l'intérieur de la tête), afin qu'il suive le mouvement de cette partie et puisse toujours bouger indépendamment. Outils du kit : rect, ellipse, polygon (oreilles, nageoires, cornes), path (queues, câbles, tiges), line, zigzag_bottom (bordures de cheveux ou franges), paint(..., only=...) pour dessiner des détails sur des formes existantes, shade_edges pour les ombres et les bords. Appelez s.outline() une fois à la fin, afin que chaque partie porte son propre contour. Pour les personnages avec cheveux, suivez "Personnages avec cheveux" dans LESSONS.md.

6. Un visage (ou une pose) par état, sous forme de groupes activés/désactivés avec des règles d'opacité : f-ouvert par défaut, plus tout ce qui convient à chaque état. Les réactions se lisent mieux lorsqu'elles diffèrent par la forme, pas seulement par la couleur : yeux fermés ^ ^, yeux mi-clos, bouche ouverte, bande d'ombre. Les visages dessinés sur un personnage avec frange sautent les cellules de cheveux.

   • Adaptez chaque état au personnage. Lorsqu'un état ne lui convient pas, demandez et proposez des moments de sa propre histoire : un geste ou une scène signature. Les grands changements de silhouette se lisent à 128 px ; les petits détails (un bijou de 2 pixels, une bouche qui s'ouvre et se ferme) ne se lisent pas.
   • Un état peut échanger des parties entières, pas seulement des visages : un accessoire activé ou désactivé, un chapeau baissé pour dormir. Faites de chaque élément échangeable sa propre partie et masquez-le ou affichez-le avec .<état> .partie{opacity:…}. Limitez chaque règle à un état, afin que les autres états conservent leurs parties.
   • Lorsque l'utilisateur est incertain, construisez des alternatives au lieu de défendre une seule option : laissez le constructeur accepter un nom de variante comme argument, construisez chaque variante dans son propre fichier et montrez-les côte à côte. Conservez la variante que l'utilisateur a préférée avant : une restauration doit se faire avec un seul argument.

7. Effets avec s.fx(name, cls, frames) : étincelles, lignes de vitesse, Z, marques de vacillement, gouttes de sueur. Les images deviennent s1, s2… pour s'animer de manière décalée.

8. Mouvement : images clés steps(1) et déplacements de cellules entières (le pixel art doit avancer par pas, pas glisser). La figure entière se trouve dans un groupe .rig qui sautille ou se balance ; par-dessus :

   • la tête hoche, s'incline ou hoche indépendamment (jusqu'à 2 cellules) ;
   • les appendices (cheveux, oreilles, queue, antenne) suivent avec un décalage d'au plus un quart de cycle ; un demi-cycle les place du côté opposé et donne l'impression d'une traînée ;
   • les accessoires et les parties mobiles fonctionnent légèrement décalés. Une boucle d'inactivité est lente et petite : respiration, clignement des yeux, queue.

9. Construisez et examinez avant de montrer à quiconque (commandes comme dans "Exécution des scripts") :

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

   puis lisez sheet.png : une image fixe par état, de gauche à droite. L'aperçu montre uniquement les poses au repos. Pour voir le mouvement, démarrez le studio en arrière-plan et ouvrez http://127.0.0.1:8765/ dans un navigateur (le panneau de navigateur intégré, s'il existe) :

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

   Il montre chaque état animé dans son propre cadre. --states a,b sélectionne et ordonne les états (par défaut : tous les états utilisés par le CSS, dans l'ordre de leur première apparition) ; --port change le port. Les utilisateurs examinent les captures d'écran et marquent souvent les problèmes en rouge : faites correspondre les marques aux cellules en les alignant avec les caractéristiques que vous connaissez (la rangée des yeux, la bouche), puis redessinez le long de celles-ci. Après un refactoring qui ne devrait rien changer de visible, construisez l'ancienne et la nouvelle version et comparez les fichiers octet par octet (cmp ou fc /b).

10. Modifications manuelles. Lorsque l'utilisateur souhaite corriger des pixels lui-même, envoyez-le vers /editor.html du studio : peindre, effacer et choisir des couleurs par état, annuler, puis sauvegarder, ce qui écrit <nom>_overrides.json et reconstruit. Chaque pixel appartient à une partie et se déplace avec elle ; l'éditeur indique à quelle partie et à quels états il appartient. Une mascotte sans constructeur fonctionne aussi (omettez --build) : le studio conserve une copie non modifiée et les modifications dans <nom>_studio/ à côté du SVG et écrit le résultat dans le SVG. Après que l'utilisateur a modifié, lisez son fichier de modifications et l'aperçu reconstruit avant de changer quoi que ce soit d'autre, et dites si une modification semble accidentelle (un pixel isolé loin du reste).

11. Remettez le travail : dites où se trouve le SVG, quel état il joue par défaut et comment en afficher un autre (définissez la classe de la racine ; une balise <img> ne le peut pas, donc une application qui change d'état intègre le SVG en ligne ou le charge dans un <object> ou un <iframe>).

profile.json (pour une application qui affiche la mascotte)

Une application peut avoir besoin de plus que des classes racines : variables CSS sur la racine, classes supplémentaires, libellés d'état fixes. Un fichier profile.json placé dans <kit> à côté de preview.py informe l'aperçu et le studio. Chaque clé est optionnelle :

{
  "states": [{ "class": "joyeux", "name": "joyeux", "label": "joyeux · sur succès", "style": "--speed:.5s" }],
  "rootClass": "toujours-animer",
  "swatches": { "var": "--accent", "label": "accent", "colors": ["#8FA8E8", "#ED93B1"] },
  "workdir": "~/mon-app/studio"
}

states fixe l'ordre, les noms des boutons, les légendes et un style racine par état ; rootClass est ajouté à la racine dans chaque image ; swatches ajoute des boutons de couleur qui définissent une variable CSS ; workdir remplace <nom>_studio/ pour les mascottes sans constructeur. Ce plugin n'en fournit aucun.

Fichiers de cette compétence

Fichier	Description
LESSONS.md	Ce qui a fonctionné et ce qui n'a pas fonctionné, avec causes et corrections. Lisez-le en premier.
scripts/pixelkit.py	Formes (rect, ellipse, polygon, path, line), parties, ombrage, contours par partie, sortie SVG.
scripts/example_mascot.py	Miso : un chat 32×32 avec les états inactif, joyeux et sommeil ; le modèle à copier.
scripts/preview.py	Feuille PNG, une image fixe par état, uniquement la bibliothèque standard.
scripts/pixel_overrides.py	Applique les modifications manuelles à un SVG terminé ; les constructeurs l'appellent en dernier.
scripts/studio/	server.py + site/ : chaque état en animation, et un éditeur de pixels, pour toute mascotte. Local uniquement (127.0.0.1).