breakout_game/

breakout-game.rs

//! 3D breakout: a paddle patrols the near wall of a walled court, batting a
//! ball at a grid of bricks. The ball is the only light in the scene, so it
//! draws its own glow across a dim court. Movement and collision are
//! fixed-step physics in `tick`; drawing interpolates between the last two
//! steps. Escape pauses; every menu offers a restart and a close.

use core::f32::consts::TAU;
use core::fmt::Display;
use core::time::Duration;

use mirage_engine::prelude::*;

/// The mesh source, next to `index.html` on the web and under the working
/// directory on the desktop — one path that resolves on both.
const MODEL: &str = "examples/assets/breakout.glb";

/// The game's sounds, alongside the mesh source — one file per [`Sound`]
/// variant, named by its stem inside `build`.
const SOUNDS: [&str; 9] = [
    "examples/assets/serve.ogg",
    "examples/assets/lost.ogg",
    "examples/assets/win.ogg",
    "examples/assets/gameover.ogg",
    "examples/assets/bounce.ogg",
    "examples/assets/break.ogg",
    "examples/assets/music.ogg",
    "examples/assets/menu_music.ogg",
    "examples/assets/click.ogg",
];

/// The paddle's playing surface, addressed and repainted every frame; its
/// underside and end caps go unnamed in the source, so they draw exactly as
/// it authored them.
const PADDLE_MESH: &str = "paddle";

const COURT_HALF_WIDTH: f32 = 6.0;
const COURT_HALF_DEPTH: f32 = 8.0;
const WALL_THICKNESS: f32 = 0.4;
const WALL_HEIGHT: f32 = 1.0;

/// Half the paddle's width and depth, matching the half-extents
/// `tools/breakout_fixture.py` authored the mesh at.
const PADDLE_HALF_WIDTH: f32 = 1.0;
const PADDLE_HALF_DEPTH: f32 = 0.25;
const PADDLE_HALF_HEIGHT: f32 = 0.12;
const PADDLE_Z: f32 = 6.6;
const PADDLE_SPEED: f32 = 9.0;
const PADDLE_LIMIT: f32 = COURT_HALF_WIDTH - WALL_THICKNESS - PADDLE_HALF_WIDTH;
const PADDLE_FLASH: f32 = 0.2;

const BALL_RADIUS: f32 = 0.22;
const BALL_SPEED: f32 = 7.5;

/// Ghost positions the ball's trail holds.
const TRAIL_LEN: usize = 5;
/// Smallest and largest a trail ghost's diameter shrinks to, as a fraction
/// of the ball's.
const TRAIL_SCALE_MIN: f32 = 0.28;
const TRAIL_SCALE_MAX: f32 = 0.82;
/// A trail ghost's emissive share of the ball's own; the tint alpha below
/// is what fades the glow back along the trail, so this stays constant per
/// ghost rather than fading a second time.
const TRAIL_EMISSIVE_PEAK: f32 = 0.75;
/// The tint alpha the oldest ghost fades to, never all the way to nothing.
const TRAIL_ALPHA_FLOOR: f32 = 0.15;

const BRICK_COLUMNS: usize = 8;
const BRICK_ROWS: usize = 5;
const BRICK_HALF_WIDTH: f32 = 0.55;
const BRICK_HALF_HEIGHT: f32 = 0.3;
const BRICK_HALF_DEPTH: f32 = 0.35;
const BRICK_GAP: f32 = 0.18;
/// The gap between rows, wider than [`BRICK_GAP`] between columns so each
/// row reads as its own band and a broken brick's gap shows against it.
const BRICK_ROW_GAP: f32 = 0.4;
const BRICK_HITS: u8 = 2;
const BRICK_ROW_COLORS: [Color; BRICK_ROWS] = [
    Color::rgb(0.80, 0.20, 0.24),
    Color::rgb(0.86, 0.47, 0.16),
    Color::rgb(0.85, 0.74, 0.18),
    Color::rgb(0.30, 0.62, 0.32),
    Color::rgb(0.24, 0.45, 0.78),
];

/// Sparks a broken brick sends outward.
const SPARK_BURST_COUNT: usize = 10;
/// Spark lifetime, in seconds.
const SPARK_LIFETIME: f32 = 0.45;
/// A spark's outward speed range, in meters per second.
const SPARK_SPEED_MIN: f32 = 2.5;
const SPARK_SPEED_MAX: f32 = 5.5;
/// Gravity that curves a spark's path back down.
const SPARK_GRAVITY: f32 = 6.0;
/// A spark's edge length at birth and where it shrinks to, in meters.
const SPARK_SIZE_START: f32 = 0.16;
const SPARK_SIZE_END: f32 = 0.02;
/// A spark's roll speed in the view plane, in radians per second.
const SPARK_SPIN_SPEED: f32 = 10.0;
/// A spark's emissive share of its row color; past `1.0` so it blooms. The
/// tint alpha below is what fades it out, so this stays constant per spark
/// rather than fading a second time.
const SPARK_EMISSIVE_PEAK: f32 = 2.0;

const LIVES_START: u8 = 3;

/// Distance the row of held ball meshes sits in from the near wall, clear
/// of the paddle's own path and the brick grid.
const LIFE_ROW_MARGIN: f32 = 0.25;
/// Fixed `x` the row sits at, alongside the paddle's own path.
const LIFE_ROW_X: f32 = -COURT_HALF_WIDTH + WALL_THICKNESS + BALL_RADIUS + LIFE_ROW_MARGIN;
/// Gap between two held ball meshes in the row, center to center.
const LIFE_ROW_SPACING: f32 = BALL_RADIUS * 2.0 + 0.15;

const BALL_GLOW: Color = Color::rgb(1.0, 0.86, 0.42);
const BALL_LIGHT_RANGE: f32 = 9.0;
/// Past `1.0`, so the ball blooms rather than only glowing.
const BALL_EMISSIVE: Color = Color::rgb(2.2, 1.85, 0.9);
const WALL_COLOR: Color = Color::rgb(0.22, 0.24, 0.30);
const FLOOR_COLOR: Color = Color::rgb(0.08, 0.09, 0.12);
const PADDLE_BASE: Color = Color::rgb(0.75, 0.78, 0.85);
const PADDLE_FLASH_EMISSIVE: Color = Color::rgb(2.6, 2.6, 3.0);
/// A small emissive kept under [`PADDLE_FLASH_EMISSIVE`], so the paddle
/// stays visible where the ball's own light does not reach, rather than
/// drawing unlit.
const PADDLE_AMBIENT_EMISSIVE: Color = Color::rgb(0.05, 0.052, 0.06);

/// Baseline bloom spread during play; a brick break pulses on top of it.
const BLOOM_BASE: f32 = 0.08;
/// Bloom a brick break's pulse adds at its peak, above the baseline.
const BLOOM_PULSE_PEAK: f32 = 0.3;
/// Decay time for a brick break's bloom pulse back to the baseline.
const BRICK_FLASH: f32 = 0.25;
/// Exposure dip below `1.0` at the instant a ball is lost.
const EXPOSURE_DIP_DEPTH: f32 = 0.3;
/// Time for the exposure dip to recover after a ball is lost.
const LIFE_LOST_FLASH: f32 = 0.5;

/// Pitch the shared bounce clip plays at off the paddle; walls and bricks
/// play it at their own pitches instead, so one clip covers three surfaces.
const PADDLE_BOUNCE_PITCH: f32 = 1.15;
const WALL_BOUNCE_PITCH: f32 = 0.85;
const BRICK_BOUNCE_PITCH: f32 = 1.0;
/// Distance a break holds its full level within: the court lies about 20
/// meters from the camera, which is the listener, so a break at any brick is
/// heard.
const BRICK_BREAK_REFERENCE: f32 = 10.0;

/// Gameplay and menu music volume under their default gain.
const MUSIC_GAIN: f32 = 0.35;
/// Span a track fades in over, and the span its gain slides over when a menu
/// opens or closes, which is what makes the crossfade.
const MUSIC_CROSSFADE: Duration = Duration::from_secs(1);
/// Gameplay and menu music loop point; `ZERO` until each is set by ear.
const MUSIC_LOOP_FROM: Duration = Duration::ZERO;
const MENU_MUSIC_LOOP_FROM: Duration = Duration::ZERO;

fn main() {
    run(
        Config::new("Mirage: breakout game")
            .with_size(1280, 720)
            .with_assets([MODEL].into_iter().chain(SOUNDS)),
        Breakout::init,
    );
}

/// The loaded paddle: its playing surface, addressed and repainted every
/// frame; its underside and end caps go unnamed in the source, so they draw
/// exactly as it authored them.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Paddle;

/// The part a draw of [`Paddle`] can repaint: its playing surface.
#[derive(Part, Clone, Debug, PartialEq, Eq, Hash)]
enum PaddlePart {
    #[part("Paddle Face")]
    Face,
}

impl Mesh<PaddlePart> for Paddle {
    fn build(&self, assets: &Assets) -> MeshData<PaddlePart> {
        assets.mesh(PADDLE_MESH)
    }
}

// Everything else this game draws is an engine primitive, scaled, placed
// and given its color per draw.
meshes! { enum Shape { Paddle, Sphere, Cube, Plane, Quad } }

/// Every clip this game plays, named by its stem.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
enum Sound {
    Serve,
    BallLost,
    LevelClear,
    GameOver,
    /// Paddle and wall hits share this clip, differing only in pitch.
    Bounce,
    BrickBreak,
    Music,
    MenuMusic,
    Click,
}

impl Sounds for Sound {
    fn build(&self, assets: &Assets) -> SoundData {
        match self {
            Sound::Serve => assets.sound("serve"),
            Sound::BallLost => assets.sound("lost"),
            Sound::LevelClear => assets.sound("win"),
            Sound::GameOver => assets.sound("gameover"),
            Sound::Bounce => assets.sound("bounce"),
            Sound::BrickBreak => assets.sound("break"),
            Sound::Music => assets.sound("music").streamed(),
            Sound::MenuMusic => assets.sound("menu_music").streamed(),
            Sound::Click => assets.sound("click"),
        }
    }
}

/// Distance the paddle is pushed; the bindings are alternatives, and the one
/// pushed furthest is kept.
#[derive(InputAxisAction, Clone, Copy, PartialEq)]
enum Move {
    Paddle,
}

impl InputAxisAction for Move {
    fn bindings(&self) -> Vec<AxisBinding> {
        match self {
            Move::Paddle => vec![
                AxisBinding::from(ButtonAxis {
                    negative: Key::A,
                    positive: Key::D,
                }),
                AxisBinding::from(ButtonAxis {
                    negative: Key::Left,
                    positive: Key::Right,
                }),
                AxisBinding::from(ButtonAxis {
                    negative: Pad::DPadLeft,
                    positive: Pad::DPadRight,
                }),
                AxisBinding::pad(PadAxis::LeftX),
            ],
        }
    }
}

/// Every verb this game reads as held or not.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Button {
    Serve,
    Pause,
}

impl InputButtonAction for Button {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Button::Serve => vec![Key::Space.into(), Pad::South.into()],
            Button::Pause => vec![Key::Escape.into(), Pad::Start.into()],
        }
    }
}

struct Controls;

impl InputActions for Controls {
    type Button = Button;
    type Axis = Move;
    type Axis2 = NoInputAxes2;
}

/// The action a controls-menu rebind is waiting on, if any.
#[derive(Clone, Copy, PartialEq)]
enum Listening {
    Button(Button),
    Move(Move),
}

/// One surviving or destroyed brick in the grid.
#[derive(Clone, Copy)]
struct Brick {
    row: usize,
    position: Vec3,
    hits_remaining: u8,
}

/// One spark from a broken brick's burst: its own position and velocity,
/// a roll that keeps advancing as it tumbles, and its age since spawn.
#[derive(Clone, Copy)]
struct Spark {
    position: Vec3,
    velocity: Vec3,
    roll: f32,
    age: f32,
    color: Color,
}

/// The round's current state.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Phase {
    /// The ball is held above the paddle, waiting for `Button::Serve`.
    Serving,
    Playing,
    Won,
    Lost,
}

struct Breakout {
    paddle_x: f32,
    paddle_prev_x: f32,
    ball_pos: Vec3,
    ball_prev: Vec3,
    ball_vel: Vec3,
    /// The ball's last few resolved positions, the newest first, plus one
    /// further so each drawn ghost has a previous tick to interpolate from;
    /// drawn as a fading trail.
    ball_trail: [Vec3; TRAIL_LEN + 1],
    bricks: Vec<Brick>,
    /// Live sparks from broken bricks, integrated and aged in `tick`.
    sparks: Vec<Spark>,
    score: u32,
    lives: u8,
    phase: Phase,
    paused: bool,
    paddle_flash: f32,
    /// Counts down from `BRICK_FLASH` after a brick breaks, pulsing bloom.
    brick_flash: f32,
    /// Counts down from `LIFE_LOST_FLASH` after a ball is lost, dipping
    /// exposure.
    life_lost_flash: f32,
    master_volume: f32,
    /// The action a controls-menu rebind is waiting on, if any.
    listening: Option<Listening>,
}

impl Breakout {
    /// Prepares every mesh kind so no draw hitches on its first frame, then
    /// starts the first round.
    fn init(_ctx: &mut InitContext<'_, Breakout>) -> Result<Self, Error> {
        Ok(Self::new())
    }

    fn new() -> Self {
        let mut game = Self {
            paddle_x: 0.0,
            paddle_prev_x: 0.0,
            ball_pos: Vec3::ZERO,
            ball_prev: Vec3::ZERO,
            ball_vel: Vec3::ZERO,
            ball_trail: [Vec3::ZERO; TRAIL_LEN + 1],
            bricks: spawn_bricks(),
            sparks: Vec::new(),
            score: 0,
            lives: LIVES_START,
            phase: Phase::Serving,
            paused: false,
            paddle_flash: 0.0,
            brick_flash: 0.0,
            life_lost_flash: 0.0,
            master_volume: 1.0,
            listening: None,
        };
        game.ready_serve();
        game
    }

    /// Starts a new round, keeping the player's volume setting.
    fn restart(&mut self) {
        let master_volume = self.master_volume;
        *self = Self::new();
        self.master_volume = master_volume;
    }

    /// Centers the paddle and places the ball above it, waiting for
    /// [`Button::Serve`].
    fn ready_serve(&mut self) {
        self.paddle_x = 0.0;
        self.paddle_prev_x = 0.0;
        self.ball_pos = Vec3::new(
            0.0,
            BALL_RADIUS,
            PADDLE_Z - PADDLE_HALF_DEPTH - BALL_RADIUS - 1.2,
        );
        self.ball_prev = self.ball_pos;
        self.ball_vel = Vec3::ZERO;
        self.ball_trail = [self.ball_pos; TRAIL_LEN + 1];
        self.phase = Phase::Serving;
    }

    /// Sends the held ball back up-court, into play.
    fn launch(&mut self) {
        self.ball_vel = Vec3::new(0.35, 0.0, -1.0).normalize() * BALL_SPEED;
        self.phase = Phase::Playing;
    }

    /// Holds the ball above the paddle while it waits to be served, tracking
    /// the paddle's own steering, and launches it once the player serves.
    fn hold_ball(&mut self, ctx: &mut TickContext<'_, Breakout>) {
        self.ball_prev = self.ball_pos;
        self.ball_pos.x = self.paddle_x;
        self.ball_trail = [self.ball_pos; TRAIL_LEN + 1];

        if !ctx.ui_wants_keyboard() && ctx.pressed(Button::Serve) {
            self.launch();
            ctx.play(Sound::Serve);
        }
    }

    fn step_paddle(&mut self, axis: f32, dt: f32) {
        self.paddle_prev_x = self.paddle_x;
        self.paddle_x =
            (self.paddle_x + axis * PADDLE_SPEED * dt).clamp(-PADDLE_LIMIT, PADDLE_LIMIT);
    }

    fn step_ball(&mut self, ctx: &mut TickContext<'_, Breakout>, dt: f32) {
        self.ball_prev = self.ball_pos;
        self.ball_pos += self.ball_vel * dt;

        self.bounce_walls(ctx);
        self.bounce_paddle(ctx);
        self.bounce_bricks(ctx);
        self.push_trail();

        if self.ball_pos.z - BALL_RADIUS > COURT_HALF_DEPTH {
            self.lose_life(ctx);
        }
    }

    /// Shifts the ghost trail back one slot and records the ball's newly
    /// resolved position at the front.
    fn push_trail(&mut self) {
        self.ball_trail.rotate_right(1);
        self.ball_trail[0] = self.ball_pos;
    }

    fn bounce_walls(&mut self, ctx: &mut TickContext<'_, Breakout>) {
        let left = -COURT_HALF_WIDTH + WALL_THICKNESS;
        let right = COURT_HALF_WIDTH - WALL_THICKNESS;
        let top = -COURT_HALF_DEPTH + WALL_THICKNESS;

        let mut hit = false;
        if self.ball_pos.x - BALL_RADIUS < left {
            self.ball_pos.x = left + BALL_RADIUS;
            self.ball_vel.x = self.ball_vel.x.abs();
            hit = true;
        } else if self.ball_pos.x + BALL_RADIUS > right {
            self.ball_pos.x = right - BALL_RADIUS;
            self.ball_vel.x = -self.ball_vel.x.abs();
            hit = true;
        }

        if self.ball_pos.z - BALL_RADIUS < top {
            self.ball_pos.z = top + BALL_RADIUS;
            self.ball_vel.z = self.ball_vel.z.abs();
            hit = true;
        }

        if hit {
            ctx.play(Sound::Bounce.pitch(WALL_BOUNCE_PITCH));
        }
    }

    /// Bounces the ball off the paddle, steering it by where it landed.
    fn bounce_paddle(&mut self, ctx: &mut TickContext<'_, Breakout>) {
        if self.ball_vel.z <= 0.0 {
            return;
        }
        let reach_x = PADDLE_HALF_WIDTH + BALL_RADIUS;
        let reach_z = PADDLE_HALF_DEPTH + BALL_RADIUS;
        let dx = self.ball_pos.x - self.paddle_x;
        let dz = self.ball_pos.z - PADDLE_Z;
        if dx.abs() > reach_x || dz.abs() > reach_z {
            return;
        }

        let offset = (dx / PADDLE_HALF_WIDTH).clamp(-1.0, 1.0);
        self.ball_vel = Vec3::new(offset, 0.0, -1.0).normalize() * BALL_SPEED;
        self.ball_pos.z = PADDLE_Z - reach_z;
        self.paddle_flash = PADDLE_FLASH;
        ctx.play(Sound::Bounce.pitch(PADDLE_BOUNCE_PITCH));
    }

    /// Bounces the ball off the nearest overlapping brick, damaging it.
    fn bounce_bricks(&mut self, ctx: &mut TickContext<'_, Breakout>) {
        let reach_x = BRICK_HALF_WIDTH + BALL_RADIUS;
        let reach_z = BRICK_HALF_DEPTH + BALL_RADIUS;
        let mut broken = None;

        for brick in self
            .bricks
            .iter_mut()
            .filter(|brick| brick.hits_remaining > 0)
        {
            let dx = self.ball_pos.x - brick.position.x;
            let dz = self.ball_pos.z - brick.position.z;
            if dx.abs() > reach_x || dz.abs() > reach_z {
                continue;
            }

            if reach_x - dx.abs() < reach_z - dz.abs() {
                self.ball_vel.x = if dx < 0.0 {
                    -self.ball_vel.x.abs()
                } else {
                    self.ball_vel.x.abs()
                };
            } else {
                self.ball_vel.z = if dz < 0.0 {
                    -self.ball_vel.z.abs()
                } else {
                    self.ball_vel.z.abs()
                };
            }

            brick.hits_remaining -= 1;
            self.score += 10 * (BRICK_ROWS - brick.row) as u32;
            ctx.play(Sound::Bounce.pitch(BRICK_BOUNCE_PITCH));
            if brick.hits_remaining == 0 {
                ctx.play(
                    Sound::BrickBreak
                        .at(brick.position)
                        .reference(BRICK_BREAK_REFERENCE),
                );
                self.brick_flash = BRICK_FLASH;
                broken = Some((brick.position, BRICK_ROW_COLORS[brick.row]));
            }
            break;
        }

        if let Some((position, color)) = broken {
            self.spawn_sparks(position, color);
        }

        if self.bricks.iter().all(|brick| brick.hits_remaining == 0) {
            self.phase = Phase::Won;
            ctx.play(Sound::LevelClear);
        }
    }

    /// Sends [`SPARK_BURST_COUNT`] sparks outward and upward from a broken
    /// brick's position, spread by index so no randomness is needed.
    fn spawn_sparks(&mut self, position: Vec3, color: Color) {
        for i in 0..SPARK_BURST_COUNT {
            let t = i as f32 / SPARK_BURST_COUNT as f32;
            let azimuth = t * TAU;
            let rise = 0.6 + 0.4 * (t * 3.0).fract();
            let speed = SPARK_SPEED_MIN.lerp(SPARK_SPEED_MAX, (t * 5.0).fract());
            let direction = Vec3::new(azimuth.cos(), rise, azimuth.sin()).normalize();
            self.sparks.push(Spark {
                position,
                velocity: direction * speed,
                roll: azimuth,
                age: 0.0,
                color,
            });
        }
    }

    /// Integrates and ages the live sparks, dropping any past their
    /// lifetime.
    fn step_sparks(&mut self, dt: f32) {
        for spark in &mut self.sparks {
            spark.velocity.y -= SPARK_GRAVITY * dt;
            spark.position += spark.velocity * dt;
            spark.age += dt;
        }
        self.sparks.retain(|spark| spark.age < SPARK_LIFETIME);
    }

    fn lose_life(&mut self, ctx: &mut TickContext<'_, Breakout>) {
        self.life_lost_flash = LIFE_LOST_FLASH;
        self.lives = self.lives.saturating_sub(1);
        if self.lives == 0 {
            self.phase = Phase::Lost;
            ctx.play(Sound::GameOver);
        } else {
            ctx.play(Sound::BallLost);
            self.ready_serve();
        }
    }

    fn camera() -> Camera {
        Camera::new(
            View::look_at(Vec3::new(0.0, 13.5, 12.5), Vec3::new(0.0, 0.0, 0.5)),
            Projection::perspective(50.0),
        )
    }

    /// The paddle's face material: fully lit by the court's own lights, its
    /// base tone flashed with emissive light past `1.0` just after it last
    /// hit the ball, and a small emissive kept under that so it stays
    /// visible where the ball's own light does not reach.
    fn paddle_face_material(&self) -> Material {
        let t = (self.paddle_flash / PADDLE_FLASH).clamp(0.0, 1.0);
        let flash = PADDLE_FLASH_EMISSIVE.dimmed(t);
        let emissive = Color::rgb(
            PADDLE_AMBIENT_EMISSIVE.red + flash.red,
            PADDLE_AMBIENT_EMISSIVE.green + flash.green,
            PADDLE_AMBIENT_EMISSIVE.blue + flash.blue,
        );
        Material::lit(PADDLE_BASE).emissive(emissive)
    }

    fn draw_court(&self, ctx: &mut FrameContext<'_, Breakout>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    COURT_HALF_WIDTH * 2.0,
                    1.0,
                    COURT_HALF_DEPTH * 2.0,
                )))
                .material(Material::lit(FLOOR_COLOR)),
        );

        let side_half = Vec3::new(WALL_THICKNESS * 0.5, WALL_HEIGHT * 0.5, COURT_HALF_DEPTH);
        for side in [-1.0, 1.0] {
            let x = side * (COURT_HALF_WIDTH - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    side_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(x, side_half.y, 0.0),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }

        let top_half = Vec3::new(COURT_HALF_WIDTH, WALL_HEIGHT * 0.5, WALL_THICKNESS * 0.5);
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                top_half * 2.0,
                Quat::IDENTITY,
                Vec3::new(0.0, top_half.y, -COURT_HALF_DEPTH + WALL_THICKNESS * 0.5),
            ))
            .material(Material::lit(WALL_COLOR)),
        );
    }

    fn draw_bricks(&self, ctx: &mut FrameContext<'_, Breakout>) {
        let scale = Vec3::new(
            BRICK_HALF_WIDTH * 2.0,
            BRICK_HALF_HEIGHT * 2.0,
            BRICK_HALF_DEPTH * 2.0,
        );
        for brick in self.bricks.iter().filter(|brick| brick.hits_remaining > 0) {
            let health = f32::from(brick.hits_remaining) / f32::from(BRICK_HITS);
            let color = BRICK_ROW_COLORS[brick.row].dimmed(0.4 + 0.6 * health);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    scale,
                    Quat::IDENTITY,
                    brick.position,
                ))
                .material(Material::shaded(color, health)),
            );
        }
    }

    /// Draws the live spark burst: additive, tumbling by roll as they age,
    /// shrinking and fading out over their lifetime.
    fn draw_sparks(&self, ctx: &mut FrameContext<'_, Breakout>) {
        for spark in &self.sparks {
            let age = (spark.age / SPARK_LIFETIME).clamp(0.0, 1.0);
            let fade = 1.0 - age;
            let size = SPARK_SIZE_START.lerp(SPARK_SIZE_END, age);
            ctx.draw(
                Quad.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(size),
                    Quat::IDENTITY,
                    spark.position,
                ))
                .billboard()
                .roll(spark.roll + spark.age * SPARK_SPIN_SPEED)
                .material(
                    Material::color(spark.color.with_alpha(fade))
                        .emissive(spark.color.dimmed(SPARK_EMISSIVE_PEAK))
                        .additive(),
                ),
            );
        }
    }

    /// Draws the ball's ghost trail, each ghost smaller and more transparent
    /// than the one ahead of it; each ghost's position interpolates between
    /// its own last two resolved ticks by the same `alpha` the ball itself
    /// draws at, and its radius clamps to what the ball's own radius has
    /// left over its distance from the head, so a ghost still close to the
    /// ball never draws past its edge.
    fn draw_trail(&self, ctx: &mut FrameContext<'_, Breakout>, alpha: f32) {
        let head = self.ball_trail[1].lerp(self.ball_trail[0], alpha);
        for i in 0..TRAIL_LEN {
            let position = self.ball_trail[i + 1].lerp(self.ball_trail[i], alpha);
            let age = (i + 1) as f32 / TRAIL_LEN as f32;
            let fade = (1.0 - age).max(TRAIL_ALPHA_FLOOR);
            let radius = (BALL_RADIUS * TRAIL_SCALE_MIN.lerp(TRAIL_SCALE_MAX, fade))
                .min((BALL_RADIUS - head.distance(position)).max(0.0));
            let scale = Vec3::splat(radius * 2.0);
            ctx.draw(
                Sphere { subdivisions: 2 }
                    .at(Transform::from_scale_rotation_translation(
                        scale,
                        Quat::IDENTITY,
                        position,
                    ))
                    .material(
                        Material::color(BALL_GLOW.with_alpha(fade))
                            .emissive(BALL_EMISSIVE.dimmed(TRAIL_EMISSIVE_PEAK)),
                    ),
            );
        }
    }

    /// Draws one held ball for every life past the one in play, set in a
    /// row alongside the paddle's own path.
    fn draw_lives(&self, ctx: &mut FrameContext<'_, Breakout>) {
        let held_lives = self.lives.saturating_sub(1);
        for slot in 0..held_lives {
            let z = PADDLE_Z + (slot + 1) as f32 * LIFE_ROW_SPACING;
            ctx.draw(
                Sphere { subdivisions: 2 }
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(BALL_RADIUS * 2.0),
                        Quat::IDENTITY,
                        Vec3::new(LIFE_ROW_X, BALL_RADIUS, z),
                    ))
                    .material(
                        Material::color(BALL_GLOW)
                            .emissive(BALL_EMISSIVE)
                            .additive(),
                    ),
            );
        }
    }

    fn overlay(&mut self, ctx: &mut FrameContext<'_, Breakout>) {
        let bricks_left = self
            .bricks
            .iter()
            .filter(|brick| brick.hits_remaining > 0)
            .count();
        // Read before `ctx.ui` so a rebind changes what the hint reads this
        // frame too.
        let move_hint = bindings_text(ctx.bindings(Move::Paddle));
        let pause_hint = bindings_text(ctx.bindings(Button::Pause));
        let serve_hint = bindings_text(ctx.bindings(Button::Serve));
        ctx.ui(|ui| {
            ui.horizontal(|ui| {
                ui.label(egui::RichText::new(format!("score {}", self.score)).size(32.0));
                ui.label(format!("{bricks_left} bricks left"));
            });
            ui.label(format!("move: {move_hint} · {pause_hint} to pause"));
            if self.phase == Phase::Serving {
                ui.label(format!("{serve_hint} to serve"));
            }
        });

        match self.phase {
            Phase::Serving | Phase::Playing if self.paused => self.menu(ctx, "paused", false),
            Phase::Won => self.menu(ctx, "you win", true),
            Phase::Lost => self.menu(ctx, "game over", true),
            _ => {}
        }
    }

    fn menu(&mut self, ctx: &mut FrameContext<'_, Breakout>, title: &str, over: bool) {
        let mut clicked = false;
        let mut quit = false;

        // `ctx.ui` cannot borrow `ctx`, so anything the controls list needs is
        // read first and applied after.
        let buttons: Vec<(Button, String)> = Button::all()
            .into_iter()
            .map(|action| (action, bindings_text(ctx.bindings(action))))
            .collect();
        let axes: Vec<(Move, String)> = Move::all()
            .into_iter()
            .map(|action| (action, bindings_text(ctx.bindings(action))))
            .collect();
        let listening = self.listening;
        let actuated_button = (!ctx.ui_wants_keyboard())
            .then(|| ctx.actuated_button())
            .flatten();
        let actuated_axis = (!ctx.ui_wants_keyboard())
            .then(|| ctx.actuated_axis())
            .flatten();
        let mut reset = None;

        ctx.ui(|ui| {
            egui::Window::new(title)
                .collapsible(false)
                .resizable(false)
                .anchor(egui::Align2::CENTER_CENTER, egui::Vec2::ZERO)
                .show(ui.ctx(), |ui| {
                    if over {
                        ui.label(format!("score {}", self.score));
                    }
                    if !over {
                        ui.add(
                            egui::Slider::new(&mut self.master_volume, 0.0..=1.0).text("volume"),
                        );
                        if ui.button("resume").clicked() {
                            self.paused = false;
                            clicked = true;
                        }
                        ui.separator();
                        ui.heading("controls");
                        for (action, text) in &buttons {
                            controls_row(
                                ui,
                                action.name(),
                                text,
                                listening == Some(Listening::Button(*action)),
                                &mut self.listening,
                                Listening::Button(*action),
                                &mut reset,
                            );
                        }
                        for (action, text) in &axes {
                            controls_row(
                                ui,
                                action.name(),
                                text,
                                listening == Some(Listening::Move(*action)),
                                &mut self.listening,
                                Listening::Move(*action),
                                &mut reset,
                            );
                        }
                    }
                    if ui.button("restart").clicked() {
                        self.restart();
                        clicked = true;
                    }
                    if ui.button("quit").clicked() {
                        quit = true;
                    }
                });
        });

        match (self.listening, actuated_button, actuated_axis) {
            (Some(Listening::Button(action)), Some(binding), _) => {
                ctx.rebind(action, vec![binding]);
                self.listening = None;
            }
            (Some(Listening::Move(action)), _, Some(binding)) => {
                ctx.rebind(action, vec![binding]);
                self.listening = None;
            }
            _ => {}
        }
        match reset {
            Some(Listening::Button(action)) => ctx.rebind(action, action.bindings()),
            Some(Listening::Move(action)) => ctx.rebind(action, action.bindings()),
            None => {}
        }

        if clicked {
            ctx.play(Sound::Click);
        }
        if quit {
            ctx.close();
        }
    }

    /// Sustains both tracks every frame, and the gain goes to whichever the
    /// game calls for: gameplay music while a round is live, serving
    /// included, and menu music whenever a menu covers it.
    ///
    /// Each fades in over [`MUSIC_CROSSFADE`] and slides every later gain
    /// over it, which is the crossfade itself; the one at no gain costs no
    /// voice while its playback goes on under the other.
    fn sustain_music(&self, ctx: &mut FrameContext<'_, Breakout>) {
        let playing = !self.paused && matches!(self.phase, Phase::Serving | Phase::Playing);
        let gain = |wanted: bool| match wanted {
            true => MUSIC_GAIN,
            false => 0.0,
        };

        ctx.sustain(
            Sound::Music
                .gain(gain(playing))
                .fade(MUSIC_CROSSFADE)
                .glide(MUSIC_CROSSFADE)
                .loop_from(MUSIC_LOOP_FROM),
        );
        ctx.sustain(
            Sound::MenuMusic
                .gain(gain(!playing))
                .fade(MUSIC_CROSSFADE)
                .glide(MUSIC_CROSSFADE)
                .loop_from(MENU_MUSIC_LOOP_FROM),
        );
    }
}

/// One action's name, its live bindings, a rebind control that starts
/// listening for a new one, and a reset to its defaults; cancel is a
/// button rather than Escape, since Escape is itself a binding a listen
/// could capture.
fn controls_row(
    ui: &mut egui::Ui,
    name: &str,
    bindings: &str,
    listening: bool,
    target: &mut Option<Listening>,
    action: Listening,
    reset: &mut Option<Listening>,
) {
    ui.horizontal(|ui| {
        ui.label(format!("{name}: {bindings}"));
        if listening {
            ui.label("listening");
            if ui.button("cancel").clicked() {
                *target = None;
            }
        } else if ui.button("rebind").clicked() {
            *target = Some(action);
        }
        if ui.button("reset").clicked() {
            *reset = Some(action);
        }
    });
}

/// The controls-menu text for a live binding list: each alternative,
/// separated, in the order the player can use them.
fn bindings_text<B: Display>(bindings: Vec<B>) -> String {
    bindings
        .iter()
        .map(ToString::to_string)
        .collect::<Vec<_>>()
        .join(", ")
}

fn spawn_bricks() -> Vec<Brick> {
    let cell = BRICK_HALF_WIDTH * 2.0 + BRICK_GAP;
    let row_span = BRICK_HALF_DEPTH * 2.0 + BRICK_ROW_GAP;
    let grid_width = cell * BRICK_COLUMNS as f32 - BRICK_GAP;
    let start_x = -grid_width * 0.5 + BRICK_HALF_WIDTH;
    let start_z = -COURT_HALF_DEPTH + WALL_THICKNESS + BRICK_HALF_DEPTH + 0.6;

    (0..BRICK_ROWS)
        .flat_map(|row| {
            (0..BRICK_COLUMNS).map(move |column| Brick {
                row,
                position: Vec3::new(
                    start_x + column as f32 * cell,
                    BRICK_HALF_HEIGHT,
                    start_z + row as f32 * row_span,
                ),
                hits_remaining: BRICK_HITS,
            })
        })
        .collect()
}

impl Game for Breakout {
    type Meshes = Shape;
    type Sounds = Sound;
    type InputActions = Controls;
    type Skyboxes = NoSkyboxes;
    type SurfaceStyles = ();
    type PostEffects = ();

    fn tick(&mut self, ctx: &mut TickContext<'_, Breakout>) {
        if self.paused {
            return;
        }

        let dt = ctx.dt().as_secs_f32();
        self.paddle_flash = (self.paddle_flash - dt).max(0.0);
        self.brick_flash = (self.brick_flash - dt).max(0.0);
        self.life_lost_flash = (self.life_lost_flash - dt).max(0.0);
        self.step_sparks(dt);

        // Decay runs before the end-screen return below, so the last pulse and
        // burst do not stay on screen.
        if matches!(self.phase, Phase::Won | Phase::Lost) {
            return;
        }

        let axis = if ctx.ui_wants_keyboard() {
            0.0
        } else {
            ctx.axis(Move::Paddle)
        };
        self.step_paddle(axis, dt);

        match self.phase {
            Phase::Serving => self.hold_ball(ctx),
            _ => self.step_ball(ctx, dt),
        }
    }

    fn frame(&mut self, ctx: &mut FrameContext<'_, Breakout>) {
        if matches!(self.phase, Phase::Serving | Phase::Playing) && ctx.pressed(Button::Pause) {
            self.paused = !self.paused;
        }

        ctx.set_volume(self.master_volume);
        self.sustain_music(ctx);

        ctx.set_camera(Self::camera());

        let brick_pulse = (self.brick_flash / BRICK_FLASH).clamp(0.0, 1.0);
        ctx.set_bloom((BLOOM_BASE + brick_pulse * BLOOM_PULSE_PEAK).clamp(0.0, 1.0));

        let life_lost_t = (self.life_lost_flash / LIFE_LOST_FLASH).clamp(0.0, 1.0);
        ctx.set_exposure((1.0 - life_lost_t * EXPOSURE_DIP_DEPTH).clamp(0.0, 1.0));

        // The tick moves nothing behind a menu, so a frame there draws the last
        // step whole rather than interpolating from the one before.
        let alpha = match self.phase {
            Phase::Serving | Phase::Playing if !self.paused => ctx.alpha(),
            _ => 1.0,
        };
        let paddle_x = self.paddle_prev_x.lerp(self.paddle_x, alpha);
        let ball_pos = self.ball_prev.lerp(self.ball_pos, alpha);

        ctx.light(Light::point(ball_pos, BALL_GLOW, BALL_LIGHT_RANGE).shadow());

        self.draw_court(ctx);
        self.draw_bricks(ctx);
        self.draw_sparks(ctx);
        self.draw_lives(ctx);

        ctx.draw(
            Paddle
                .at(Transform::from_translation(Vec3::new(
                    paddle_x,
                    PADDLE_HALF_HEIGHT,
                    PADDLE_Z,
                )))
                .material_of(PaddlePart::Face, self.paddle_face_material()),
        );

        self.draw_trail(ctx, alpha);
        ctx.draw(
            Sphere { subdivisions: 2 }
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(BALL_RADIUS * 2.0),
                    Quat::IDENTITY,
                    ball_pos,
                ))
                .material(
                    Material::color(BALL_GLOW)
                        .emissive(BALL_EMISSIVE)
                        .additive(),
                ),
        );

        self.overlay(ctx);
    }
}