Descripción general
Esta guía te lleva paso a paso por el uso de pets en PicoPixel: desde elegir uno en el directorio hasta insertarlo en tu propio proyecto y hacer que reaccione a lo que sea que esté haciendo 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 propio pet, consulta Cómo enviar un pet. Este artículo está en el medio: es el tutorial práctico y detallado para usar un pet que alguien ya ha creado.
No se necesita experiencia previa en animación. Si puedes hacer clic en «Agregar al proyecto» y arrastrar un widget al lienzo, puedes darle a tu proyecto de ESP32 o LVGL un personaje vivo que reacciona.
¿Qué son los pets?
Un pet 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.
Los pets procedentes de paquetes de estilo Codex o Petdex normalmente incluyen 9 modos de fábrica, 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.
Esa es la idea central: un widget, muchos comportamientos, cambiados por tus condiciones.
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 todos los modos estén conectados por ti. Consulta ¿Qué es un sprite? para ver el contexto completo.
¿Por qué usar un pet?
Los pets 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 código. 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. El pet 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, un pet es una forma rápida y expresiva de mostrarlos, sin que tengas que escribir ningún código de animación.
Elige un pet del directorio
Para empezar, crea una cuenta en PicoPixel y luego dirígete al directorio de pets 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 del pet, haz clic en Agregar al proyecto. PicoPixel importa el pet y lo coloca directamente en tu panel: sin configuración, sin gestión de archivos.
Lo que acabas de obtener
Agregar un pet crea un único proyecto que contiene un widget Sprite precargado con todos los modos que trae ese pet. Á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 conteo 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 el pet a tus proyectos reales.
Tres formas de usar tu pet
El propio proyecto del pet es realmente solo un vehículo de entrega. Aquí hay tres formas de incorporarlo al proyecto que realmente quieres construir.
1. Copiar y pegar la capa
La opción más rápida: selecciona la capa del sprite en el proyecto del pet, cópiala, abre otro proyecto y pégala. El sprite llega con todos sus modos intactos. Perfecto para un uso puntual; si solo necesitas este pet en un lugar, ya está hecho.
2. Convertir el pet en una biblioteca (recomendado para reutilización)
Si vas a usar el pet en varios espacios de trabajo, convierte su proyecto en una biblioteca. Publicar un archivo hace que sus assets, incluido este sprite, estén disponibles para importarlos en cualquier lugar de los espacios de trabajo de tu equipo.
Para publicar:
- En el proyecto del pet, abre la pestaña Assets y elige Agregar biblioteca.
- Haz clic en Publicar.
Luego, para usarlo desde otro proyecto:
- Abre tu espacio de trabajo nuevo o existente.
- Elige Agregar biblioteca.
- Vincula la biblioteca del pet desde la lista de bibliotecas compartidas, 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 ese pet 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 del pet (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: perderás la separación limpia entre el pet y tu proyecto real, y el proyecto del pet está configurado como un escaparate, no como una plantilla. Opta primero por las opciones 1 o 2.
Conectar todo: hacer que el pet reaccione
Un pet que solo reproduce Idle no hace gran cosa. La recompensa viene del editor de eventos, donde indicas cuándo 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 el pet salta en el momento en que se presiona el botón.
Reemplaza el disparador por lo que exponga 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 el pet reaccione a ello. Para un resumen completo de disparadores, fuentes 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 pet se vea bien y funcione correctamente en hardware real.
- Elimina los modos que no uses. Esto se recomienda encarecidamente. Cada modo que conservas son más fotogramas almacenados en memoria, y los no utilizados son sobrecarga pura. Reducirlos importa especialmente en placas con almacenamiento o memoria limitados; elimina cualquier modo que no planees activar.
- No olvides los eventos. Un pet no hace nada por sí solo. 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. Apunta tu asistente de código al archivo
README.mddel código LVGL exportado —lo documenta— 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, un pet con los 9 modos y fotogramas grandes puede agotar la memoria y simplemente no renderizarse. Redúcelo a 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 los pets: modos, fotogramas y duraciones.
- Cómo usar el editor de eventos: cada disparador y acción para hacer que un pet reaccione.
- Guía de bibliotecas y componentes reutilizables: publica un pet una vez y reutilízalo en todas partes.
- Cómo enviar un pet: crea y comparte tu propio pet único con la comunidad.
- Galería de pets: explora los pets de la comunidad y consigue otro.
