Vue d'ensemble
Ce guide vous accompagne dans l'utilisation des pets dans PicoPixel : depuis le choix d'un pet dans le répertoire jusqu'à son intégration dans votre propre projet et sa réaction à ce que fait votre matériel.
Ce guide s'appuie directement sur deux autres guides. Si vous souhaitez comprendre le concept sous-jacent, lisez d'abord Qu'est-ce qu'un sprite ?. Si vous souhaitez publier votre propre pet, consultez Comment soumettre un pet. Cet article se situe entre les deux : c'est le tutoriel pratique et concret pour utiliser un pet déjà créé par quelqu'un d'autre.
Aucune expérience préalable en animation n'est nécessaire. Si vous pouvez cliquer sur « Ajouter au projet » et faire glisser un widget sur un canevas, vous pouvez donner à votre projet ESP32 ou LVGL un personnage vivant et réactif.
Que sont les pets ?
Un pet est un sprite : un widget unique qui contient plusieurs animations différentes et vous permet de passer de l'une à l'autre à la demande. Chaque animation est un mode (aussi appelé état ou phase) : « Idle », « Run right », « Jumping », etc.
Les pets issus de packs de style Codex ou Petdex sont généralement livrés avec 9 modes par défaut, par exemple Idle, Run right, Run left, Waving, Jumping, Failed, Waiting, Running et Review. Chaque mode est sa propre petite boucle d'images, et c'est vous qui décidez lequel joue et quand.
C'est toute l'idée : un widget, de nombreux comportements, commutés par vos conditions.
Sur le plan technique, LVGL n'a pas de concept natif de sprite multi-états — nous l'avons construit au-dessus du widget d'image animée LVGL, de sorte que tous les modes sont câblés pour vous. Consultez Qu'est-ce qu'un sprite ? pour le contexte complet.
Pourquoi utiliser un pet ?
Les pets sont conçus pour donner vie à votre projet ESP32 ou LVGL. Au lieu d'un visage statique ou d'une seule animation en boucle, le sprite réagit : il change de mode en fonction de ce qui se passe réellement sur votre appareil.
L'inspiration originale est un compagnon de code. Imaginez un écran de style Codex où un petit personnage réagit à votre session de codage : en repos pendant que vous réfléchissez, en mode « Review » pendant qu'il lit un diff, « Failed » quand une compilation échoue. Le pet reflète ce que fait l'application.
PicoPixel va plus loin : toute action ou déclencheur que vous pouvez exprimer, vous pouvez l'animer. Quelques exemples :
- Passez en mode Jumping lorsqu'une lecture de température dépasse un seuil.
- Jouez Running pendant la récupération de données depuis une API, puis revenez à Idle quand la réponse arrive.
- Déclenchez Waving quand un capteur détecte un mouvement, ou Failed quand une requête expire.
Si votre projet a des états qui méritent d'être montrés, un pet est un moyen rapide et expressif de les afficher, sans aucun code d'animation de votre part.
Choisir un pet dans le répertoire
Pour commencer, créez un compte PicoPixel, puis rendez-vous dans le répertoire des pets sur picopixel.io/pets.
Parcourez la galerie, trouvez un personnage qui vous plaît et ouvrez sa page de détail.
Sur la page de détail du pet, cliquez sur Ajouter au projet. PicoPixel importe le pet et le dépose directement dans votre tableau de bord : aucune configuration, aucune gestion de fichiers.
Ce que vous venez d'obtenir
L'ajout d'un pet crée un projet unique contenant un widget Sprite préchargé avec tous les modes que ce pet propose. Ouvrez-le et vous verrez le sprite sur le canevas, avec tous ses modes listés dans le panneau de droite — Idle, Run right, Run left, Waving, Jumping et les autres — chacun avec son propre nombre d'images et sa durée.
Si le widget Sprite vous est nouveau, le guide Qu'est-ce qu'un sprite ? explique en détail les modes, les images et les durées.
Passez à l'onglet Assets et vous trouverez le même sprite enregistré en tant que composant réutilisable dans la bibliothèque locale du projet. C'est la clé pour déplacer le pet dans vos vrais projets.
Trois façons d'utiliser votre pet
Le projet propre au pet n'est vraiment qu'un vecteur de livraison. Voici trois façons de l'intégrer dans le projet que vous souhaitez réellement construire.
1. Copier-coller le calque
L'option la plus rapide : sélectionnez le calque du sprite dans le projet du pet, copiez-le, ouvrez un autre projet et collez-le. Le sprite arrive avec tous ses modes intacts. Parfait pour un usage ponctuel — si vous n'avez besoin de ce pet qu'à un seul endroit, c'est terminé.
2. Transformer le pet en bibliothèque (recommandé pour la réutilisation)
Si vous comptez utiliser le pet dans plusieurs espaces de travail, transformez son projet en bibliothèque. Publier un fichier rend ses assets — y compris ce sprite — disponibles à l'import dans n'importe quel espace de travail de votre équipe.
Pour publier :
- Dans le projet du pet, ouvrez l'onglet Assets et choisissez Ajouter une bibliothèque.
- Cliquez sur Publier.
Ensuite, pour l'utiliser depuis un autre projet :
- Ouvrez votre espace de travail nouveau ou existant.
- Choisissez Ajouter une bibliothèque.
- Liez la bibliothèque du pet depuis la liste des bibliothèques partagées, comme indiqué ci-dessous.
Une fois lié, le sprite apparaît dans les Assets de cet espace de travail. Glissez-déposez-le sur le canevas et il se charge entièrement préconfiguré, avec tous les modes de ce pet prêts à l'emploi.
Les bibliothèques concernent la réutilisation au sein de votre équipe, pas la publication au monde entier. Pour savoir exactement ce que contient une bibliothèque, comment fonctionne la publication et où apparaissent les bibliothèques liées, consultez le Guide des bibliothèques et composants réutilisables.
3. Modifier les propriétés du projet pour correspondre à votre matériel
Vous pouvez aussi simplement modifier les propriétés du projet du pet (taille d'écran, carte cible) pour correspondre à votre appareil et construire directement dedans. Cela fonctionne, mais ce n'est pas l'approche recommandée : vous perdez la séparation nette entre le pet et votre vrai projet, et le projet du pet est configuré comme une vitrine, pas comme un modèle. Privilégiez d'abord les options 1 ou 2.
Câblage : faire réagir le pet
Un pet qui ne joue que Idle ne fait pas grand-chose. La récompense vient de l'éditeur d'événements, où vous indiquez quand changer de mode.
Le principe est simple : quand quelque chose se produit, basculez vers un mode. Vous choisissez le déclencheur — une pression de bouton, un changement de valeur, un minuteur — et sélectionnez l'action Set Sprite Mode, puis le mode à jouer.
Dans la capture d'écran ci-dessous, nous avons ajouté un événement sur un bouton JUMP! : lorsqu'il est cliqué, l'action passe le mode du sprite en Jumping, de sorte que le pet saute au moment où le bouton est pressé.
Remplacez le déclencheur par ce que votre projet expose — une lecture de capteur, une fin d'appel API, un minuteur qui se déclenche — et le même câblage fait réagir le pet. Pour un aperçu complet des déclencheurs, sources et actions, consultez Utiliser l'éditeur d'événements.
Quelques points à garder à l'esprit
Quelques bonnes pratiques permettront à votre pet d'avoir un bon rendu et de bien fonctionner sur du vrai matériel.
- Supprimez les modes que vous n'utiliserez pas. C'est fortement recommandé. Chaque mode conservé représente plus d'images stockées en mémoire, et les modes inutilisés sont une surcharge pure. L'allègement est surtout important sur les cartes avec peu de stockage ou de mémoire — supprimez tout mode que vous ne comptez pas déclencher.
- N'oubliez pas les événements. Un pet ne fait rien par lui-même. Utilisez l'éditeur d'événements pour ajouter une condition pour chaque mode que vous souhaitez jouer, comme nous avons câblé le bouton JUMP! ci-dessus.
- Faites attention à la mémoire de votre appareil. Les images animées nécessitent suffisamment de RAM pour stocker leurs images. Pointez votre assistant de codage vers le fichier
README.mddans le code LVGL exporté — il le documente — ou assurez-vous d'avoir alloué suffisamment de mémoire pour les images animées vous-même. Si un sprite n'apparaît pas après le flashage, c'est presque toujours la cause.
Les sprites peuvent être lourds. Sur un petit microcontrôleur, un pet avec les 9 modes et de grandes images peut épuiser la mémoire et simplement ne pas s'afficher. Réduisez-le aux modes que vous utilisez réellement et confirmez que votre configuration LVGL alloue suffisamment de RAM pour les images animées.
Prochaines étapes
- Qu'est-ce qu'un sprite ? : le concept derrière les pets — modes, images et durées.
- Utiliser l'éditeur d'événements : chaque déclencheur et action pour faire réagir un pet.
- Guide des bibliothèques et composants réutilisables : publiez un pet une fois et réutilisez-le partout.
- Comment soumettre un pet : créez et partagez votre propre pet unique avec la communauté.
- Galerie de pets : parcourez les pets de la communauté et choisissez-en un autre.
