farolero/docs/premium_game_ui_pipeline.md

Pipeline para UI premium de juego

Objetivo: construir pantallas vistosas sin convertir una maqueta en “un PNG gigante”. La UI debe seguir siendo mantenible, animable, responsive, localizable y performante.

Regla obligatoria: arte generado de alta calidad

Una pantalla premium NO se considera terminada si solo usa gradientes, CustomPainter, iconos Material y glows simples. Eso puede servir como scaffolding, pero no alcanza el nivel visual buscado.

Para cada pantalla o lote premium hay que definir y generar assets artísticos reales:

Capa	Asset esperado	Transparencia
Fondo atmosférico	Imagen generada opaca, móvil vertical, 1080x1920 o similar	No necesaria
Hero/emblema/mascota	Imagen generada PNG/WebP de alta calidad	Obligatoria
Marco de panel/botón	Imagen generada con bordes/brillos premium	Obligatoria
Burst/glow/humo/confetti	Overlay generado pictórico	Obligatoria
Iconos/medallas/avatares	128-256 px o 512 px si son hero	Obligatoria

Si el asset va encima de Flutter, debe tener fondo transparente real. Si el generador no entrega alpha nativo, se genera con chroma-key plano, se elimina localmente y se valida que las esquinas tengan alpha=0.

La regla práctica es brutal pero necesaria: si el resultado parece Flutter con filtros, todavía falta arte.

Diagnóstico en Farolero

Los assets de assets/rewards/ mezclan dos usos distintos:

Asset	Estado	Uso correcto
reward_header_glow.png	PNG RGBA, pero sus esquinas son opacas (alpha=255)	Sirve como fondo/placa completa. No sirve como overlay transparente encima de UI.
medal_unlock_burst.png	Esquinas transparentes (alpha=0)	Correcto como burst/glow overlay, pendiente de revisar si tiene alpha tenue ocupando demasiado lienzo.
fire_progress_burst.png	Canal alpha, pero hay alpha parcial en bordes	Casi correcto; conviene limpiar/fade de bordes para evitar manchas al componer.

Conclusión: la sospecha era buena. Para componer pantallas premium sin “machacar” capas, los elementos decorativos deben ir separados y con transparencia real. Los fondos sí pueden ser opacos.

Regla base

No generar “la pantalla final” como imagen. Generar un kit por capas:

1. Fondo base: puede ser opaco, normalmente WebP/JPG/PNG grande.
2. Overlays atmosféricos: glows, rays, humo, confetti, sparks, viñetas. PNG/WebP con alpha.
3. Elementos hero: insignias, medallas, placas, marcos. PNG con alpha o SVG si es vector limpio.
4. Layout real: textos, botones, barras de progreso y estado en Flutter.
5. Motion:
   • flutter_animate: transiciones de widgets, shimmer, scale, blur, secuencias.
   • confetti: celebraciones puntuales, controlando cantidad de partículas.
   • Rive: animación interactiva compleja, state machines, assets vectoriales vivos.
   • Lottie: animaciones After Effects exportadas a JSON.

Tamaños recomendados

Tipo	Tamaño razonable	Notas
Iconos/avatar/medalla pequeña	128–256 px	En Farolero 256 px está bien como master.
Burst circular/hero	512–1024 px	Transparente, recortado al contenido útil.
Banner/header overlay	1024–1536 px ancho	2048 solo si realmente ocupa pantalla grande o tablet.
Fondo full screen	1080×1920 o variantes	Mejor optimizar por target móvil.

Flutter soporta variantes por densidad (1.0x, 2.0x, 3.0x), así que para iconos repetidos conviene usar assets resolution-aware en vez de un único PNG enorme.

Criterios de aceptación de un asset transparente

Antes de integrarlo:

• Las esquinas deben tener alpha=0, salvo que sea fondo opaco.
• El bounding box visible debe estar centrado.
• No debe haber “velo” semitransparente cubriendo todo el lienzo si el asset es overlay.
• El archivo debe estar recortado al área necesaria, dejando margen visual controlado.
• Si se anima con escala/blur, dejar margen suficiente para no cortar glow.

Pros y contras por técnica

Técnica	Pros	Contras	Usarla para
PNG/WebP alpha	Alta fidelidad artística, fácil de componer	Puede pesar mucho, cuidado con overdraw	Glows, bursts, placas, humo, partículas baked
SVG	Ligero, escalable	Menos pictórico; filtros complejos pueden costar	Iconos limpios, formas, marcas
CustomPainter	Performante para geometría simple	Difícil lograr arte premium complejo	Rayos, líneas, fondos geométricos
flutter_animate	Rápido, mantenible, ideal para UI real	No reemplaza arte base	Entrada de paneles, shimmer, contadores
confetti	Perfecto para celebración	Muchas partículas pueden costar	Victoria, medalla desbloqueada
Rive	Interactivo y profesional	Requiere .riv y pipeline propio	Mascotas, insignias vivas, state machines
Lottie	Muy bueno para AE JSON	No todo AE exporta perfecto; revisar performance	Animaciones cerradas no interactivas

Flujo correcto de trabajo

1. Dirección visual: definir moodboard/prototipo y separar qué es fondo, qué es overlay y qué es UI real.
2. Lista de capas: documentar asset, tamaño, transparencia, punto de anclaje y uso.
3. Generación: pedir assets individuales, no pantallas completas, con fondo transparente cuando sean overlays.
4. Validación técnica: verificar alpha/corners/bounding box/tamaño.
5. Integración Flutter: componer con Stack, Positioned, widgets reales y animaciones controladas.
6. Performance: evitar Opacity grande y saveLayer innecesario; precalcular transparencias estáticas cuando se pueda.
7. Revisión visual: comparar contra maqueta y ajustar por capas, no rehacer toda la pantalla.

Fuentes revisadas

• Flutter assets e imágenes: https://docs.flutter.dev/ui/assets/assets-and-images
• Flutter performance: https://docs.flutter.dev/perf/best-practices
• Flutter animations: https://docs.flutter.dev/ui/animations
• Rive Flutter runtime: https://rive.app/docs/runtimes/flutter/flutter
• Lottie Flutter: https://pub.dev/packages/lottie
• flutter_animate: https://pub.dev/packages/flutter_animate
• confetti: https://pub.dev/packages/confetti