Descripción general
Esta guía te explica todo lo que necesitas saber sobre los sprites en PicoPixel: qué son, cuándo usarlos, cómo crear el tuyo paso a paso, cómo hacer que reaccione a lo que ocurre en pantalla y cómo reutilizarlo para no tener que construir lo mismo dos veces.
No necesitas experiencia previa en animación; si puedes arrastrar y soltar una imagen, puedes crear un sprite.
¿Qué es?
Un sprite es un único widget de PicoPixel que contiene varias animaciones diferentes y te permite cambiar entre ellas cuando quieras. Cada animación se llama modo o estado, por ejemplo "Idle", "Running" o "Happy".
Imagínalo como un personaje de videojuego. El personaje es un único elemento en pantalla, pero puede caminar, saltar o saludar dependiendo de lo que suceda. Un sprite funciona igual: un widget, muchas apariencias, y tú decides cuál se reproduce.
¡Con el potente editor de eventos de PicoPixel puedes activar diferentes estados para darle vida a tu sprite!
Ejemplo: Supón que tienes un personaje animado, o quieres crear tu propia cara de stack-chan para tu ESP32 u otra aplicación LVGL. Puedes usar un único sprite y activar condicionalmente diferentes modos como "Running", "Thinking", "Failed" y más, sin tener que gestionar un montón de widgets separados.
A nivel técnico, LVGL no admite nativamente sprites con diferentes estados, así que construimos el nuestro propio basado en el widget de imagen animada de LVGL. Obtienes la comodidad sin tener que conectar nada tú mismo.
¿Cuándo debo usar un sprite?
No todas las imágenes necesitan ser sprites. Aquí tienes una forma rápida de decidir:
- ¿Una imagen fija y estática? Usa una Image normal. Los sprites son excesivos para algo que nunca se mueve.
- ¿Una animación que simplemente se repite para siempre (como un cargador giratorio)? Usa un Animated Image. Es más sencillo y ligero.
- ¿Algo que necesita cambiar según lo que ocurre, una cara que sonríe cuando una tarea tiene éxito, o un personaje que pasa de idle a running? Eso es exactamente para lo que sirve un sprite.
La regla general: si tu gráfico tiene más de un "estado de ánimo" o "comportamiento" y quieres cambiar entre ellos, usa un sprite.
¿Cómo crear un sprite?
- Selecciona el widget "Sprite". En la barra lateral derecha puedes añadir tu primer modo de ese sprite. Por ejemplo, quizás el primer estado sea "Idle". Dale a cada estado un nombre claro para reconocerlo más tarde cuando configures los disparadores.
- Sube una secuencia de imágenes, el conjunto de fotogramas que componen este modo. Cada fotograma es solo una imagen, y reproducirlos en orden es lo que crea la animación, como un libro animado.
- Puedes ajustar la duración para ese estado específico. Una duración mayor reproduce la animación más lentamente; una menor la acelera.
- Añade otro estado. Se requieren un mínimo de 2 modos. (Si solo necesitas una animación, es mejor usar el widget Animated Image, consulta ¿Cuándo debo usar un sprite? arriba.)
- Usa la pestaña/editor de Events para activar y alternar condicionalmente entre tus diferentes estados. Esto es lo que hace que el sprite se sienta vivo; más sobre esto en la siguiente sección.
Todas las imágenes o fotogramas deben tener exactamente las mismas dimensiones en todos los modos de un sprite. Si un fotograma es 64×64 y otro es 80×80, el sprite no se alineará correctamente. Redimensiónalos para que coincidan antes de subirlos.
Mantén el número de fotogramas y el tamaño de la imagen en valores razonables. Más fotogramas e imágenes más grandes se ven más fluidos, pero usan más memoria en tu dispositivo, algo a tener en cuenta para microcontroladores pequeños. Consulta Problemas comunes si tu sprite no aparece después de flashear.
Dar vida a tu sprite
Un sprite que siempre muestra el mismo estado no hace mucho. La magia ocurre cuando le dices cuándo cambiar, y para eso sirve el editor de Events.
La idea es simple: cuando algo ocurre, cambiar a un estado. Tú eliges el "algo" (una pulsación de botón, un cambio de valor, un temporizador, etc.) y PicoPixel hace el resto.
Un ejemplo típico:
- Tu sprite empieza en el estado "Idle" por defecto.
- En el editor de Events, añades un evento: cuando se presione un botón, cambiar el sprite al estado "Running".
- Añade otro evento: cuando la tarea termine, cambiar a "Happy" (o volver a "Idle").
Eso es todo; tu sprite ahora reacciona a lo que hace el usuario, sin código de tu parte. Puedes encadenar tantos como quieras para construir widgets genuinamente expresivos.
Empieza pequeño. Primero haz que dos estados cambien entre sí, confirma que se ve bien en la vista previa y luego añade más estados una vez que estés satisfecho con el comportamiento.
¿Cómo reutilizar un sprite?
Una vez que has construido un sprite, probablemente no quieras reconstruirlo desde cero en cada proyecto. La función Biblioteca te permite guardarlo una vez e insertarlo en cualquier proyecto.
- Haz clic derecho en tu widget sprite completado y haz clic en "Add Library Widget".
- Esto crea una entrada reutilizable en tu biblioteca en la pestaña Assets. Piénsalo como tu estante personal de widgets listos para usar.
- Para mover esa biblioteca entre proyectos o compartirla con un compañero, ve a Library y haz clic en Exportar.
- Ahora cuando crees un nuevo proyecto o abras un espacio de trabajo existente, puedes importar esa biblioteca e insertar el sprite directamente: no se requiere reconstrucción.
- Todos los fotogramas, duraciones y estados se sincronizan perfectamente desde la copia original que creaste, por lo que se comporta exactamente igual en todos los lugares donde lo uses.
Problemas comunes
El sprite no aparece cuando se flashea al dispositivo.
- Esto es casi siempre un problema de memoria: tu dispositivo necesita suficiente RAM para almacenar los fotogramas del sprite.
- Esto se configura en tu configuración de LVGL y no es algo que PicoPixel pueda cambiar por ti; depende de tu placa específica.
- El archivo
README.mdexportado lo menciona, por lo que tu asistente de IA puede ayudarte a actualizar la configuración del SDK/LVGL para tu dispositivo embebido.
Los fotogramas parecen desalineados o saltan.
- Verifica que cada fotograma en cada estado tenga exactamente las mismas dimensiones. Incluso unos pocos píxeles de diferencia afectarán la alineación.
La animación se reproduce demasiado rápido o demasiado lento.
- Ajusta la duración del estado afectado. Recuerda que cada estado tiene su propia duración, por lo que puede que necesites ajustarlos individualmente.
El sprite no me deja guardarlo / pide otro estado.
- Un sprite necesita al menos 2 estados. Si solo tienes uno, añade un segundo estado o cambia al widget Animated Image en su lugar.
