Capítulo 14. Renderizado 2D: sprites, atlas, capas y cámara

//! cap-14 — sección 14.7: cámara 2D mínima.
fn setup_camera(mut commands: Commands) {
    // Esto solo: Camera2d trae, vía required components,
    // la Projection ortográfica por defecto + el resto del bundle.
    commands.spawn(Camera2d);
}

Solo si querés override (ej. 1 metro = 32 píxeles, o un viewport cuadrado), escribís la Projection a mano. Para cambiar el scaling, usás el campo scaling_mode con uno de los ScalingMode válidos:

//! cap-14 — sección 14.7: cámara 2D con escalado explícito.
use bevy::camera::{OrthographicProjection, Projection, ScalingMode};

fn setup_camera_32px(mut commands: Commands) {
    // Ejemplo: tile de 32×32 px == 1 unidad de mundo.
    // `ScalingMode::Fixed { width, height }` fija la resolución lógica.
    commands.spawn((
        Camera2d,
        Projection::Orthographic(OrthographicProjection {
            scaling_mode: ScalingMode::Fixed { width: 800.0 / 32.0, height: 600.0 / 32.0 },
            ..OrthographicProjection::default_2d()
        }),
    ));
}

Cuidado con la API vieja: OrthographicProjection::with_scaling(1.0 / 32.0) NO existe. El método with_scaling recibe un ScalingMode (enum), no un f32. Y el campo OrthographicProjection::scale se eliminó en 0.15 (PR #15075). Las variantes válidas de ScalingMode son: Fixed, WindowSize, AutoMin, AutoMax, FixedVertical, FixedHorizontal.

Una cámara que sigue al player es de las primeras cosas que escribís en cualquier juego:

//! cap-14 — sección 14.7: cámara que sigue al player con smoothing.
fn follow_player(
    time: Res<Time>,
    player: Query<&Transform, With<Player>>,
    mut camera: Query<&mut Transform, (Without<Player>, With<Camera2d>)>,
) {
    let Ok(player_xform) = player.single() else { return; };
    let Ok(mut cam_xform) = camera.single_mut() else { return; };

    let target = player_xform.translation;
    let k = 5.0;                                  // velocidad del lerp.
    cam_xform.translation = cam_xform.translation
        .lerp(target, (time.delta_secs() * k).min(1.0));
}

El .lerp(target, alpha) es lineal: para un ease-out suave cambiá a smoothstep o Vec3::lerp con un factor exponencial. La versión production-grade usa exponential_decay o un spring damper (modelo resorte-amortiguador), pero con un lerp de factor 5 * dt se siente bien al 99 % de los jugadores.

Truco: si querés que la cámara "mire siempre un poco adelante de la dirección de movimiento", guardás la velocidad del player en un componente Velocity y le sumás vel.normalize() 30.0 al target. Es Celeste* puro.

14.8 RenderTarget como componente separado (0.18+)

Hasta 0.17, decidir si una cámara renderizaba a pantalla o a una textura era cuestión de métodos en el plugin. En 0.18, es un componente: RenderTarget. En 0.19, además, lo conectaron a required components (cap. 8), así que Camera2d lo trae automáticamente.

Analogía: el RenderTarget es como el sobre de un envío postal. La carta es la cámara (con sus parámetros); el sobre dice "esto va a la pantalla" o "esto va a un buzón interno".

//! cap-14 — sección 14.8: render a una textura (offscreen) en 0.18.
use bevy::camera::{OrthographicProjection, Projection, ScalingMode};
use bevy::render::render_resource::TextureDescriptor;
use bevy::render::texture::ImageFormat;

fn setup_minimap_camera(
    mut commands: Commands,
    mut images: ResMut<Assets<Image>>,
) {
    let minimap_image = Image {
        texture_descriptor: TextureDescriptor {
            label: Some("minimap"),
            size: Extent3d { width: 256, height: 256, depth_or_array_layers: 1 },
            dimension: TextureDimension::D2,
            format: ImageFormat::Rgba8UnormSrgb,
            mip_level_count: 1,
            sample_count: 1,
            usage: TextureUsages::RENDER_ATTACHMENT | TextureUsages::TEXTURE_BINDING,
            view_formats: &[],
        },
        ..default()
    };
    let minimap_handle = images.add(minimap_image);

    commands.spawn((
        Camera2d,
        Projection::Orthographic(OrthographicProjection {
            // Zoom del minimapa: media ventana visible.
            scaling_mode: ScalingMode::WindowSize(2.0),  // 2 = el contenido se ve a la mitad.
            ..OrthographicProjection::default_2d()
        }),
        RenderTarget::from(minimap_handle),
    ));
}

¿Para qué querés renderizar a una textura? Tres casos típicos:

• Minimapa: una segunda cámara apunta al mismo mundo desde arriba, con zoom, y renderiza a un Image de 256×256 que después mostrás en la esquina de la pantalla.
• Render de un personaje antes del post-process (cap. 16): pintás el personaje aparte para aplicarle blur solo a él.
• Mirror effect (Geometry Wars, Hyper Light Drifter): un shader muestra el mundo duplicado y con un sample raro.

La metedura 14.C (al final del capítulo) muestra el error típico: olvidar el flag TEXTURE_BINDING y que la textura salga negra porque nadie puede samplearla.

14.9 Múltiples cámaras y RenderLayers

Los RenderLayers existen en Bevy desde hace muchas versiones (desde 0.6), pero a menudo pasan desapercibidos: cada entidad y cada cámara tiene un layer id (un entero de 32 bits, así que tenés 32 capas distintas). Si el layer mask (máscara binaria de capas activas) del objeto intersecta con el de la cámara, se ve; si no, se ignora.

//! cap-14 — sección 14.9: aislar el HUD en su propio layer.
use bevy::camera::visibility::RenderLayers;

const LAYER_WORLD: u8 = 0;
const LAYER_HUD:   u8 = 1;

fn setup(mut commands: Commands) {
    commands.spawn((
        Camera2d,
        RenderLayers::from_layers(&[LAYER_WORLD, LAYER_HUD]),  // ve ambas.
    ));
}

fn spawn_hud(mut commands: Commands) {
    commands.spawn((
        Sprite::from_image(/* tu HUD */),
        Transform::from_xyz(0.0, 0.0, 100.0),
        RenderLayers::layer(LAYER_HUD),   // solo la cámara del HUD.
    ));
}

Esto resuelve tres problemas clásicos:

1. *No querés que el HUD sufra post-process***. La cámara del HUD va a la pantalla sin tocar; la del mundo sí pasa por bloom y chromatic aberration.
2. Querés ocultar objetos durante cinemáticas. Les cambiás el layer a LAYER_HUD y desaparecen del mundo, pero siguen "existiendo" para un query.
3. *Querés un minimap*** sin tener que spawnearlo offscreen. Le das a los tiles un layer aparte y la cámara del minimapa los renderiza.

La regla práctica: si en tu juego tenés más de dos "profundidades" (mundo, hud, cinemática), usá RenderLayers desde el día uno. Vas a ahorrarte meses de rehacer jerarquías.

14.10 Color spaces: Linear vs sRGB, y por qué te importa

Este es el apartado que nadie lee hasta que un día la pantalla queda demasiado oscura. Bevy 0.18 migró la convención por defecto a Srgb para el color de Sprite (el tinte), pero el framebuffer se considera lineal en operaciones internas (mezclas, post-process, iluminación). ¿Por qué? Porque la matemática de luz es lineal, y si la hacés en sRGB terminás con bandas visibles en los degradés.

Reglas duras:

• PNG/JPG importados: se asume sRGB. Bevy los marca como Rgba8UnormSrgb y el shader los "lineariza" al leerlos.
• Colores de código (Color::srgb(0.5, 0.5, 0.5)): en 0.18 con la nueva convención, podés escribir Color::srgb(0.5, 0.5, 0.5) y Bevy lo interpreta como sRGB. Para colores lineales puros usás Color::linear_rgb(...).
• Post-process (cap. 16): trabaja en lineal y convierte a sRGB en el último pass (el tonemap o color grading final).
• Mezcla con luces: si tu luz tiene Color::srgb(1.0, 0.9, 0.7), al multiplicar por la textura en lineal te queda un resultado más oscuro de lo que esperás si venías de Unity. La regla: bajá la luz un poco (srgb(0.7, 0.65, 0.55)) para compensar.

Analogía: sRGB es el "idioma del monitor", y lineal es el "idioma de las matemáticas". Bevy traduce entre los dos automáticamente, pero si sabés cuándo se traduce y cuándo no, evitás colores lavados o quemados.

14.11 Glosario del capítulo

Sprite (componente): rectángulo visual con textura, color de tinte, anchor y (desde 0.15) un campo opcional `texture_atlas`.
Image (asset): textura GPU, `Handle<Image>` + descriptor de formato.
TextureAtlas (struct, NO componente desde 0.15): referencia a un `Handle<TextureAtlasLayout>` + índice del frame actual. Vive dentro de `Sprite.texture_atlas`.
TextureAtlasLayout (asset): estructura con el grid (cols, filas, tamaño).
Anchor (concepto): punto del sprite que coincide con su `Transform` (centro, top-left, etc.).
Camera2d (componente): marcador que define una cámara ortográfica 2D. Por required components inserta `Projection::Orthographic`, `Camera`, `GlobalTransform`, etc.
RenderTarget (componente): a dónde "entrega" la imagen la cámara (pantalla o textura).
RenderLayers (componente): máscara de capas que decide qué ve cada cámara.
Render graph (concepto): DAG (grafo acíclico dirigido) de nodos de render conectados.
Batch / batching (técnica): agrupar sprites con mismo material en un solo draw call.
Cull / culling (técnica): descartar entidades fuera de la cámara antes de dibujarlas.
Parallax (técnica): capas que se mueven a distintas velocidades para simular profundidad.
Linear RGB (espacio de color): espacio donde la luz se mezcla de forma matemáticamente correcta.
sRGB (espacio de color): espacio "humano" que usa el monitor; gamma-encoded.
Tone mapping (técnica): compresión del rango HDR (alto rango dinámico) a LDR (rango bajo) en el último pass.

14.12 Trivia histórica

Super Mario Bros (Nintendo, 1985) — uno de los primeros juegos mainstream con *spritesheet* en una sola imagen. Cada cuadro de Mario era un recorte de 16×32 px; sin atlas, la NES habría muerto de RAM.
Stardew Valley (ConcernedApe, 2016) — toda la escena renderiza en una sola pasada con un *tilemap* de 16×16, pero el efecto de *lighting* diario se logra con un *overlay* por capa (`RenderLayers` puro, hecho a mano en MonoGame).
Hyper Light Drifter (Heart Machine, 2016) — la cámara sigue con un *spring damper* casero; nada de cinemática. Un *lerp* simple (cap. 14.7) habría sido demasiado rígido para su estética de "personaje herido".
Inside (Playdead, 2016) — todo el *color grading* (recoloración tonal de la imagen) es un *post-process* aplicado a una escena renderizada en lineal. Esa escena es la "la misma" que este capítulo describe, pero con un nodo extra al final.
Braid (Number None, 2008) — su render usaba *render-to-texture* por niveles: cada nivel era una textura pintada y después distorsionada. La idea es la misma que `RenderTarget::from(...)` en 0.18.

14.13 Metedura de pata

❌ Cargo.toml con `bevy = "0.18"` sin features.
✅ `bevy = { version = "0.18", features = ["2d"] }`.
💡 Por qué: sin `2d`, Bevy no incluye `bevy_sprite` ni `bevy_camera_2d`. El binario compila, pero `use bevy::sprite::Sprite` falla con `unresolved import`.

❌ `Sprite::from_image(asset_server.load("player.png"))` con un `Image` de 64×64 y `Transform::from_xyz(mouse_x, mouse_y, 0.0)`. El sprite queda "corrido" del cursor.
✅ Agregá `Anchor::CENTER` o usá `Transform::from_xyz` ajustado a la mitad del sprite.
💡 Por qué: el anchor por defecto es el centroide en 0.18, pero si esperás comportamiento de versiones viejas (esquina top-left), la posición del sprite se desfasará.

❌ `RenderTarget::from(image_handle)` pero el `Image` fue creada con `usage: TextureUsages::RENDER_ATTACHMENT` solamente.
✅ Agregá también `TextureUsages::TEXTURE_BINDING` para que un `Sprite` pueda leerla, o `TextureUsages::COPY_DST` si la vas a actualizar por CPU.
💡 Por qué: el *sampler* de un sprite no se puede enlazar si la textura no permite bind. Resultado: cuadro negro y llanto.

🎯 14.14 Patrón del capítulo: "layer cake" (capas como un pastel)

Problema: tu escena crece. Empiezas con player y suelo. Pronto tienes fondo, niebla, HUD, cinemática, minimapa. Si todo vive en el mismo World con Z arbitrarios, terminas con un sistema de capas imposible de razonar y "el HUD se ve raro solo cuando activo el bloom".

Solución: estructura el render como un pastel de capas independientes, cada una con su cámara (si hace falta), su RenderLayers, y opcionalmente su RenderTarget. La cámara "raíz" compone el pastel al final.

┌──────────────────────────────────────┐
│ Capa HUD (LAYER_HUD)                 │ Z 100, sin post-process.
├──────────────────────────────────────┤
│ Capa Player + efectos (LAYER_WORLD)  │ Z 1-3, post-process.
├──────────────────────────────────────┤
│ Capa mundo (LAYER_WORLD)             │ Z 0-2, post-process.
└──────────────────────────────────────┘

Cuándo sí:

• Juegos con HUD, cinemáticas, minimapas o distintas condiciones climáticas.
• Cuando querés aplicar post-process solo a una parte de la pantalla.
• Equipos con varios programadores: cada uno toca una capa sin pisar al otro.

Cuándo no:

• Prototipos o game jams (overhead cognitivo).
• Juegos donde TODO comparte el mismo post-process (un twin-stick puro, por ejemplo).
• Si tenés una sola capa y ya, no hace falta.

Los RenderLayers (que ya estaban desde 0.6) hacen este patrón trivial. Con la API moderna de cámara basada en required components (0.15+), spawnear varias cámaras con distintos RenderLayers es aún más barato. Usalo en serio.

Lo que vimos

• El pipeline 2D: cámara → culling → batching → framebuffer → post-process.
• Cargo.toml con features = ["2d"] para no inflar el binario.
• Sprite/Image/TextureAtlas como el contrato entre tu lógica y la GPU.
• Transform (local) vs GlobalTransform (propagado); no pises el global.
• Z-order manual, Y-sort y RenderLayers como tres maneras de ordenar.
• Camera2d como entidad y lerp simple para que siga al player.
• RenderTarget como componente en 0.18, ideal para minimapas y composición.
• Color spaces Linear vs sRGB: cuando mezclar a mano, respetá las conversiones.

En el siguiente

Ya tenemos sprites sueltos. Capítulo 15: el caso masivo. Vamos a meter miles de tiles en un mundo, con bevy_ecs_tilemap, chunks para no freír la RAM, animaciones por tile, y la artimaña del autotiling con máscaras de bits. Después de leer ese cap, el "fondo" de tu juego pasa de ser "muchos sprites" a "una matriz con identidad".