# 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`