Descripción general
Esta guía te lleva paso a paso por el uso de mascotas en PicoPixel: desde elegir una en el directorio hasta insertarla en tu propio proyecto y hacer que reaccione a lo que haga tu hardware.
Esta guía se basa directamente en otras dos. Si quieres entender el concepto subyacente, lee primero ¿Qué es un sprite?. Si quieres publicar tu propia mascota, consulta Cómo enviar una mascota. Aquí nos centramos en la parte práctica: usar una mascota que alguien ya ha creado.
No se necesita experiencia previa en animación. Si puedes hacer clic en «Añadir al proyecto» y arrastrar un widget al lienzo, puedes darle a tu proyecto de ESP32 o LVGL un personaje animado que reaccione.
¿Qué son las mascotas?
Una mascota es un sprite: un único widget que contiene varias animaciones diferentes y te permite cambiar entre ellas a voluntad. Cada animación es un modo (también llamado estado o fase): «Idle», «Run right», «Jumping», etc.
Las mascotas procedentes de paquetes de estilo Codex o Petdex normalmente incluyen 9 modos ya preparados, por ejemplo: Idle, Run right, Run left, Waving, Jumping, Failed, Waiting, Running y Review. Cada modo es su propio pequeño bucle de fotogramas, y tú decides cuál se reproduce y cuándo.
La idea es sencilla: un widget con varias animaciones, y tú decides qué condiciones activan cada una.
A nivel técnico, LVGL no tiene un concepto nativo de sprite multiestado; lo construimos sobre el widget de imagen animada de LVGL para que no tengas que enlazar los modos a mano. Consulta ¿Qué es un sprite? para ver el contexto completo.
¿Por qué usar una mascota?
Las mascotas existen para darle vida a tu proyecto de ESP32 o LVGL. En lugar de una cara estática o una sola animación en bucle, el sprite reacciona: cambia de modo en función de lo que está ocurriendo realmente en tu dispositivo.
La inspiración original es un compañero de programación. Imagina una pantalla de estilo Codex donde un pequeño personaje reacciona a tu sesión de programación: en reposo mientras piensas, en modo «Review» mientras lee un diff, «Failed» cuando falla una compilación. La mascota refleja lo que está haciendo la aplicación.
PicoPixel va más allá: cualquier acción o disparador que puedas expresar, lo puedes animar. Algunos ejemplos:
- Cambia a Jumping cuando una lectura de temperatura supera un umbral.
- Reproduce Running mientras obtienes datos de una API y vuelve a Idle cuando llega la respuesta.
- Activa Waving cuando un sensor detecta movimiento, o Failed cuando una solicitud supera el tiempo de espera.
Si tu proyecto tiene estados que vale la pena mostrar, una mascota es una forma rápida y expresiva de mostrarlos, sin que tengas que escribir ningún código de animación.
Elige una mascota del directorio
Para empezar, crea una cuenta en PicoPixel y luego dirígete al directorio de mascotas en picopixel.io/pets.
Explora la galería, encuentra un personaje que te guste y abre su página de detalles.
En la página de detalles de la mascota, haz clic en Añadir al proyecto. PicoPixel importa la mascota y la coloca directamente en tu panel: sin configuración, sin gestión de archivos.
Lo que acabas de obtener
Agregar una mascota crea un único proyecto que contiene un widget Sprite precargado con todos los modos que trae esa mascota. Ábrelo y verás el sprite en el lienzo, con todos sus modos listados en el panel derecho: Idle, Run right, Run left, Waving, Jumping y el resto, cada uno con su propio número de fotogramas y duración.
Si el widget Sprite te resulta nuevo, la guía ¿Qué es un sprite? explica modos, fotogramas y duraciones en detalle.
Cambia a la pestaña Assets y encontrarás el mismo sprite guardado como un componente reutilizable en la biblioteca local del proyecto. Esta es la clave para mover la mascota a tus proyectos reales.
Tres formas de usar tu mascota
El proyecto de la mascota sirve para que puedas importarla con todos sus recursos. Tienes tres formas de incorporarla a tu propio diseño.
1. Copiar y pegar la capa
La opción más rápida: selecciona la capa del sprite en el proyecto de la mascota, cópiala, abre otro proyecto y pégala. El sprite llega con todos sus modos intactos. Perfecto para un uso puntual; si solo necesitas esta mascota en un lugar, ya está hecho.
2. Convertir la mascota en una biblioteca (recomendado para reutilización)
Si vas a usar la mascota en varios espacios de trabajo, convierte su proyecto en una biblioteca. Publicar un archivo hace que sus recursos, incluido este sprite, estén disponibles para importarlos en cualquier lugar de los espacios de trabajo de tu equipo.
Para publicar:
- En el proyecto de la mascota, abre la pestaña Assets y elige Add library.
- Haz clic en Publish.
Luego, para usarlo desde otro proyecto:
- Abre tu espacio de trabajo nuevo o existente.
- Elige Add library.
- Vincula la biblioteca de la mascota desde la lista de SHARED LIBRARIES, como se muestra a continuación.
Una vez vinculado, el sprite aparece en los Assets de ese espacio de trabajo. Arrástralo al lienzo y se cargará completamente preconfigurado, con todos los modos de esa mascota listos para usar.
Las bibliotecas son para reutilización dentro de tu equipo, no para publicar al mundo. Para saber exactamente qué contiene una biblioteca, cómo funciona la publicación y dónde aparecen las bibliotecas vinculadas, consulta la Guía de bibliotecas y componentes reutilizables.
3. Cambiar las propiedades del proyecto para que coincidan con tu hardware
También puedes simplemente editar las propiedades del proyecto de la mascota (tamaño de pantalla, placa de destino) para que coincidan con tu dispositivo y construir directamente en él. Esto funciona, pero no es el camino recomendado: la mascota dejará de estar separada de tu proyecto principal y tendrás que adaptar un archivo preparado para mostrarla, no una plantilla de tu dispositivo. Opta primero por las opciones 1 o 2.
Conectar todo: hacer que la mascota reaccione
Una mascota que solo reproduce Idle no hace gran cosa. Con el editor de eventos puedes indicar cuándo debe cambiar de modo.
El patrón es simple: cuando algo sucede, cambia a un modo. Eliges el disparador —una pulsación de botón, un cambio de valor, un temporizador— y seleccionas la acción Set Sprite Mode con el modo que quieres reproducir.
En la captura de pantalla de abajo añadimos un evento en un botón JUMP!: cuando se hace clic, la acción establece el modo del sprite en Jumping, por lo que la mascota salta en el momento en que se presiona el botón.
Reemplaza el disparador por la señal que produzca tu proyecto —una lectura de sensor, una llamada a la API que finaliza, un temporizador que se activa— y la misma conexión hace que la mascota reaccione a ello. Para un resumen completo de disparadores, orígenes y acciones, consulta Cómo usar el editor de eventos.
Algunas cosas a tener en cuenta
Unas pocas buenas prácticas harán que tu mascota se vea bien y funcione correctamente en hardware real.
- Elimina los modos que no uses. Cada modo añade fotogramas que ocupan memoria, aunque nunca lo actives. Reducirlos importa especialmente en placas con almacenamiento o memoria limitados; elimina cualquier modo que no planees activar.
- No olvides los eventos. Una mascota no hace nada por sí sola. Usa el editor de eventos para añadir una condición para cada modo que quieras reproducir, de la misma manera que conectamos el botón JUMP! arriba.
- Ten en cuenta la memoria de tu dispositivo. Las imágenes animadas necesitan suficiente RAM para almacenar sus fotogramas. Pide a tu asistente de programación que consulte el archivo
README.mddel código LVGL exportado —ahí se explica la configuración necesaria— o asegúrate de haber asignado suficiente memoria para imágenes animadas tú mismo. Si un sprite no aparece tras flashear, casi siempre es por esto.
Los sprites pueden ser pesados. En un microcontrolador pequeño, una mascota con los 9 modos y fotogramas grandes puede agotar la memoria y simplemente no renderizarse. Conserva solo los modos que realmente uses y confirma que tu configuración de LVGL asigna suficiente RAM para imágenes animadas.
Próximos pasos
- ¿Qué es un sprite?: el concepto detrás de las mascotas: modos, fotogramas y duraciones.
- Cómo usar el editor de eventos: cada disparador y acción para hacer que una mascota reaccione.
- Guía de bibliotecas y componentes reutilizables: publica una mascota una vez y reutilízala en todas partes.
- Cómo enviar una mascota: crea y comparte una mascota original con la comunidad.
- Galería de mascotas: explora las mascotas de la comunidad y elige otra.
