Struct Material 

pub struct Material { /* private fields */ }

A surface’s shading: a tint, how strongly lights affect it, and the light it adds of its own.

A tint alpha under 1.0 draws the surface in the transparent pass: sorted back to front, blended over what is behind it, and never written to depth.

Set as a slot’s default, or per draw with Instance::material.

Implementations

impl Material

pub const fn color(color: Color) -> Self

A flat color; lights do not affect it.

Examples found in repository

examples/material-playground.rs (line 300)

fn emissive_material() -> Material {
    Material::color(EMISSIVE_BASE).emissive(EMISSIVE_GLOW)
}

/// A shading map whose checker goes between low occlusion, roughness and
/// metallic and full occlusion, roughness and metallic, so all three read
/// apart across [`ShadingMapped`].
fn shading_checker() -> ShadingData {
    ShadingData::rgba8(
        MAP_SIZE,
        checker_pixels(MAP_SIZE, SHADING_CELL, SHADING_LOW, SHADING_HIGH),
    )
}

/// An emissive map whose checker goes between full glow and none, so
/// [`EMISSIVE_GLOW`] shapes across [`EmissiveMapped`] instead of casting
/// whole.
fn emissive_checker() -> TextureData {
    TextureData::rgba8(
        MAP_SIZE,
        checker_pixels(MAP_SIZE, EMISSIVE_CELL, [0, 0, 0], [255, 255, 255]),
    )
}

fn checker_pixels(size: UVec2, cell: u32, low: [u8; 3], high: [u8; 3]) -> Vec<u8> {
    let mut pixels = Vec::with_capacity((size.x * size.y * 4) as usize);
    for y in 0..size.y {
        for x in 0..size.x {
            let on = ((x / cell) + (y / cell)).is_multiple_of(2);
            let [red, green, blue] = if on { high } else { low };
            pixels.extend_from_slice(&[red, green, blue, u8::MAX]);
        }
    }
    pixels
}

/// A relief whose normals turn across a wave that repeats over the map:
/// each texel's slope comes from the partial derivatives of a
/// `sin(u) * sin(v)` height field at `BUMP_SLOPE`'s peak, computed at that
/// texel and not sampled from any other.
fn relief_bumps() -> ReliefData {
    let size = MAP_SIZE;
    let turns = core::f32::consts::TAU * BUMP_WAVES;
    let mut pixels = Vec::with_capacity((size.x * size.y * 4) as usize);
    for y in 0..size.y {
        for x in 0..size.x {
            let u = (x as f32 + 0.5) / size.x as f32;
            let v = (y as f32 + 0.5) / size.y as f32;
            let slope_u = BUMP_SLOPE * (turns * u).cos() * (turns * v).sin();
            let slope_v = BUMP_SLOPE * (turns * u).sin() * (turns * v).cos();
            let normal = Vec3::new(-slope_u, -slope_v, 1.0).normalize();
            let encode = |signed: f32| ((signed * 0.5 + 0.5) * 255.0).round() as u8;
            pixels.extend_from_slice(&[encode(normal.x), encode(normal.y), encode(normal.z), 0]);
        }
    }
    ReliefData::normals(size, pixels)
}

/// `BannerCloth`'s vertices and indices, built twice over: the columns as
/// authored, facing `+Z`, and the same columns again facing `-Z`, their
/// triangles in the other order so both draw front side out.
fn banner_mesh() -> MeshData {
    let mut vertices = Vec::with_capacity(((BANNER_COLUMNS + 1) * 4) as usize);
    for normal in [Vec3::Z, Vec3::NEG_Z] {
        for column in 0..=BANNER_COLUMNS {
            let u = column as f32 / BANNER_COLUMNS as f32;
            let x = u * BANNER_WIDTH;
            for v in [0.0, 1.0] {
                vertices.push(Vertex::new(
                    Vec3::new(x, -v * BANNER_HEIGHT, 0.0),
                    normal,
                    Vec2::new(u, v),
                ));
            }
        }
    }

    let side = BANNER_COLUMNS + 1;
    let mut indices = Vec::with_capacity((BANNER_COLUMNS * 12) as usize);
    for column in 0..BANNER_COLUMNS {
        let top_left = column * 2;
        let bottom_left = top_left + 1;
        let top_right = top_left + 2;
        let bottom_right = top_left + 3;
        indices.extend([
            bottom_left,
            bottom_right,
            top_right,
            bottom_left,
            top_right,
            top_left,
        ]);

        let back = side * 2;
        indices.extend([
            back + top_right,
            back + bottom_right,
            back + bottom_left,
            back + top_left,
            back + top_right,
            back + bottom_left,
        ]);
    }

    MeshData::new(vertices, indices)
}

/// Displaced by a wave that grows away from its `x = 0` edge; casts the
/// shadow of where it was placed, unmoved by its own wave. Its one value
/// is the clock its wave slides on.
#[derive(Default, ShaderValues)]
struct Banner {
    time: f32,
}

impl SurfaceStyle for Banner {
    const PASS: DrawPass = DrawPass::Opaque;
    const DISPLACE: Option<&'static str> = Some(include_str!("material_playground_banner.wgsl"));
}

/// A surface that reads no light of the scene's own: it draws its own
/// pulsing tint, added over what is behind it, through the color it pulses
/// through and the clock the pulse is timed by.
#[derive(Default, ShaderValues)]
struct Field {
    tint: Color,
    time: f32,
}

impl SurfaceStyle for Field {
    const PASS: DrawPass = DrawPass::Additive;
    const SURFACE: Option<&'static str> = Some(include_str!("material_playground_field.wgsl"));
}

surface_styles! { enum Looks { Banner, Field } }

/// A whole scene lighting choice: it names a sky and, kept with it, the
/// sun that lights the scene, so a choice cannot leave the two apart.
/// `Dawn`, `Noon`, `Dusk` and `Night` each pair a gradient with a sun of
/// its own color and direction; `Clear`, `Classic`, `ImageDawn` and
/// `Sinister` each pair a loaded image with a sun that fits it, and
/// `LightBlueStars` and `BlueStars` pair a loaded space image with none;
/// `Default` is the engine's own grey sky and white sun.
///
/// [`Skyboxes`] proves every value at startup, so it must be [`Eq`] and
/// [`Hash`] over a fixed [`Skyboxes::catalog`] — a sky and sun a player
/// set to any color and direction live could never meet, since `f32` is
/// neither. This fixed, named set is the shape this file chose in its
/// place: the side area offers it as one row, and shows the chosen sky's
/// own light and its sun's own strength as text, read only, rather than
/// controls a game could not build from. See this example's report for
/// what that choice costs.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
enum Sky {
    Dawn,
    Noon,
    Dusk,
    Night,
    Clear,
    Classic,
    ImageDawn,
    Sinister,
    LightBlueStars,
    BlueStars,
    Default,
}

impl Sky {
    const ALL: [Sky; 11] = [
        Self::Dawn,
        Self::Noon,
        Self::Dusk,
        Self::Night,
        Self::Clear,
        Self::Classic,
        Self::ImageDawn,
        Self::Sinister,
        Self::LightBlueStars,
        Self::BlueStars,
        Self::Default,
    ];

    fn name(self) -> &'static str {
        match self {
            Self::Dawn => "dawn",
            Self::Noon => "noon",
            Self::Dusk => "dusk",
            Self::Night => "night",
            Self::Clear => "clear day",
            Self::Classic => "classic",
            Self::ImageDawn => "dawn image",
            Self::Sinister => "sinister night",
            Self::LightBlueStars => "light blue stars",
            Self::BlueStars => "blue stars",
            Self::Default => "default",
        }
    }

    /// The fraction of its own light this sky lands and reflects, through
    /// [`SkyboxData::lit_by`]: fixed per choice, so a bright one does not
    /// read too bright, and a dark one does not read too dark, under the
    /// frame's own lights.
    fn light(self) -> f32 {
        match self {
            Self::Dawn => 0.4,
            Self::Noon => 0.5,
            Self::Dusk => 0.35,
            Self::Night => 0.3,
            Self::Clear => CLEAR_SKY_LIGHT,
            Self::Classic => CLASSIC_SKY_LIGHT,
            Self::ImageDawn => DAWN_SKY_LIGHT,
            Self::Sinister => SINISTER_SKY_LIGHT,
            Self::LightBlueStars => LIGHT_BLUE_STARS_LIGHT,
            Self::BlueStars => BLUE_STARS_LIGHT,
            Self::Default => 1.0,
        }
    }

    /// The sun this choice pairs with its sky: direction, color and
    /// strength resolved together, so a choice cannot leave them apart.
    /// `None` for the two space images, which pair with no sun at all.
    fn sun(self) -> Option<(Vec3, Color, f32)> {
        match self {
            Self::Dawn => Some((
                Vec3::new(-1.0, -0.15, 0.05),
                Color::rgb(1.0, 0.7, 0.45),
                1.4,
            )),
            Self::Noon => Some((
                Vec3::new(-0.15, -1.0, -0.1),
                Color::rgb(1.0, 1.0, 0.98),
                1.6,
            )),
            Self::Dusk => Some((
                Vec3::new(1.0, -0.15, 0.05),
                Color::rgb(1.0, 0.55, 0.25),
                1.2,
            )),
            Self::Night => Some((
                Vec3::new(-0.3, -0.7, -0.6),
                Color::rgb(0.55, 0.65, 0.85),
                0.15,
            )),
            Self::Clear => Some((
                Vec3::new(-0.2, -1.0, -0.15),
                Color::rgb(1.0, 0.98, 0.9),
                1.5,
            )),
            Self::Classic => Some((
                Vec3::new(-0.4, -0.9, -0.2),
                Color::rgb(1.0, 0.95, 0.85),
                1.3,
            )),
            Self::ImageDawn => Some((Vec3::new(-1.0, -0.2, 0.1), Color::rgb(1.0, 0.75, 0.5), 1.1)),
            Self::Sinister => Some((Vec3::new(0.4, -0.5, -0.7), Color::rgb(0.4, 0.5, 0.75), 0.1)),
            Self::LightBlueStars | Self::BlueStars => None,
            Self::Default => Some((Vec3::new(-0.4, -1.0, -0.6), Color::WHITE, 1.0)),
        }
    }

    /// The color the sky reads under the horizon, through
    /// [`SkyboxData::with_ground`]: the floor as lit under this choice's own
    /// sun and [`Self::light`], so it moves with them, not only with the
    /// image. `None` for the gradient skies and `Default`, which need no
    /// ground, and for the two space images, which hold space below the
    /// horizon as well.
    fn ground(self) -> Option<Color> {
        match self {
            Self::Clear => Some(Color::rgb(0.501, 0.517, 0.449)),
            Self::Classic => Some(Color::rgb(0.420, 0.405, 0.379)),
            Self::ImageDawn => Some(Color::rgb(0.073, 0.053, 0.032)),
            Self::Sinister => Some(Color::rgb(0.012, 0.014, 0.020)),
            Self::Dawn
            | Self::Noon
            | Self::Dusk
            | Self::Night
            | Self::LightBlueStars
            | Self::BlueStars
            | Self::Default => None,
        }
    }
}

impl Catalog for Sky {
    fn catalog() -> Vec<Self> {
        Self::ALL.to_vec()
    }
}

impl Skyboxes for Sky {
    fn build(&self, assets: &Assets) -> SkyboxData {
        let sky = match self {
            Self::Dawn => SkyboxData::gradient(
                Color::rgb(0.55, 0.55, 0.75),
                Color::rgb(0.95, 0.6, 0.35),
                Color::rgb(0.12, 0.08, 0.06),
            ),
            Self::Noon => SkyboxData::gradient(
                Color::rgb(0.2, 0.45, 0.85),
                Color::rgb(0.75, 0.82, 0.9),
                Color::rgb(0.3, 0.3, 0.28),
            ),
            Self::Dusk => SkyboxData::gradient(
                Color::rgb(0.18, 0.1, 0.3),
                Color::rgb(0.85, 0.35, 0.2),
                Color::rgb(0.03, 0.02, 0.03),
            ),
            Self::Night => SkyboxData::gradient(
                Color::rgb(0.02, 0.02, 0.06),
                Color::rgb(0.05, 0.05, 0.1),
                Color::rgb(0.0, 0.0, 0.0),
            ),
            Self::Clear => assets.skybox("sky-clear"),
            Self::Classic => assets.skybox("sky-classic"),
            Self::ImageDawn => assets.skybox("sky-dawn"),
            Self::Sinister => assets.skybox("sky-sinister"),
            Self::LightBlueStars => assets.skybox("sky-stars-lightblue"),
            Self::BlueStars => assets.skybox("sky-stars-blue"),
            Self::Default => SkyboxData::gradient(DEFAULT_SKY, DEFAULT_SKY, DEFAULT_SKY),
        };
        let sky = match self.ground() {
            Some(ground) => sky.with_ground(ground),
            None => sky,
        };

        sky.lit_by(self.light())
    }
}

/// `color` scaled by `strength`, the value a [`Light`] reads.
fn scaled(color: Color, strength: f32) -> Color {
    Color::rgb(
        color.red * strength,
        color.green * strength,
        color.blue * strength,
    )
}

/// One light's color and strength, held apart from the position that
/// names it, plus whether it casts.
#[derive(Clone, Copy)]
struct Glow {
    color: Color,
    strength: f32,
    shadow: bool,
}

impl Glow {
    /// `color` scaled by `strength`, the value a [`Light`] reads.
    fn scaled(self) -> Color {
        scaled(self.color, self.strength)
    }
}

/// Every key and button this game reads apart from the UI: held, `Look`
/// turns the camera by the pointer's own motion, `Forward`/`Back`/
/// `Left`/`Right` move it along the view and to its side, and `Up`/
/// `Down` move it along the world's own up.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Move {
    Forward,
    Back,
    Left,
    Right,
    Up,
    Down,
    Look,
}

impl InputButtonAction for Move {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Self::Forward => vec![Key::W.into()],
            Self::Back => vec![Key::S.into()],
            Self::Left => vec![Key::A.into()],
            Self::Right => vec![Key::D.into()],
            Self::Up => vec![Key::Space.into()],
            Self::Down => vec![Key::LeftShift.into()],
            Self::Look => vec![MouseButton::Right.into()],
        }
    }
}

/// The pointer's own motion, read only while [`Move::Look`] is held.
#[derive(InputAxis2Action, Clone, Copy, PartialEq)]
enum Turn {
    Look,
}

impl InputAxis2Action for Turn {
    fn bindings(&self) -> Vec<Axis2Binding> {
        match self {
            Self::Look => vec![Axis2Binding::pointer().scale(LOOK_SENSITIVITY)],
        }
    }
}

/// How far the wheel moved this frame, read to scale the move speed.
#[derive(InputAxisAction, Clone, Copy, PartialEq)]
enum Speed {
    Wheel,
}

impl InputAxisAction for Speed {
    fn bindings(&self) -> Vec<AxisBinding> {
        match self {
            Self::Wheel => vec![AxisBinding::from(WheelDelta::Up).scale(4.0)],
        }
    }
}

struct Controls;

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

struct Playground {
    eye: Vec3,
    yaw: f32,
    pitch: f32,
    speed_scale: f32,

    sky: Sky,
    sun_shadow: bool,

    lamp: Glow,
    spotlight: Glow,

    front_tint: Color,
    front_roughness: f32,
    front_metallic: f32,
    shading_map_on: bool,
    relief_map_on: bool,
    emissive_map_on: bool,

    exposure: f32,
    bloom: f32,
}

impl Playground {
    fn init(ctx: &mut InitContext<'_, Self>) -> Result<Self, Error> {
        let _ = ctx;
        Ok(Self {
            eye: START_EYE,
            yaw: START_YAW,
            pitch: START_PITCH,
            speed_scale: 1.0,

            sky: Sky::Default,
            sun_shadow: true,

            lamp: Glow {
                color: Color::rgb(0.9, 0.55, 0.3),
                strength: 3.0,
                shadow: false,
            },
            spotlight: Glow {
                color: Color::rgb(0.4, 0.6, 1.0),
                strength: 6.0,
                shadow: true,
            },

            front_tint: Color::rgb(0.7, 0.25, 0.2),
            front_roughness: 0.4,
            front_metallic: 0.0,
            shading_map_on: true,
            relief_map_on: true,
            emissive_map_on: true,

            exposure: START_EXPOSURE,
            bloom: START_BLOOM,
        })
    }

    /// This frame's forward direction, from `yaw` (turning around the
    /// world's own up) and `pitch` (turning up or down).
    fn forward(&self) -> Vec3 {
        Vec3::new(
            -self.pitch.cos() * self.yaw.sin(),
            self.pitch.sin(),
            -self.pitch.cos() * self.yaw.cos(),
        )
    }

    /// The camera this frame draws from: `eye` looking along `forward`.
    fn camera(&self) -> Camera {
        Camera::new(
            View::look_at(self.eye, self.eye + self.forward()),
            Projection::perspective(CAMERA_FOV),
        )
    }

    /// A held `Move::Look` (the right mouse button) turns the camera by
    /// the pointer's own motion, the same way it moves: dragging right
    /// turns the view right and left turns it left, dragging down turns
    /// it to look further down at the scene, dragging up back toward the
    /// horizon. `W`/`A`/`S`/`D` move along the view and to its side,
    /// `Space`/`Left Shift` up and down, and the wheel scales how far
    /// each move goes. The `eye` is held above the ground plane wherever
    /// it moves.
    fn fly_camera(&mut self, ctx: &mut FrameContext<'_, Self>) {
        if !ctx.ui_wants_pointer() && ctx.down(Move::Look) {
            let look = ctx.axis2(Turn::Look);
            self.yaw -= look.x;
            self.pitch = (self.pitch + look.y).clamp(-PITCH_LIMIT, PITCH_LIMIT);
        }

        let wheel = ctx.axis(Speed::Wheel);
        if !ctx.ui_wants_pointer() && wheel != 0.0 {
            self.speed_scale =
                (self.speed_scale * SPEED_STEP.powf(wheel)).clamp(MIN_SPEED_SCALE, MAX_SPEED_SCALE);
        }

        let forward = self.forward();
        let right = Vec3::new(self.yaw.cos(), 0.0, -self.yaw.sin());
        let mut move_by = Vec3::ZERO;
        if ctx.down(Move::Forward) {
            move_by += forward;
        }
        if ctx.down(Move::Back) {
            move_by -= forward;
        }
        if ctx.down(Move::Right) {
            move_by += right;
        }
        if ctx.down(Move::Left) {
            move_by -= right;
        }
        if ctx.down(Move::Up) {
            move_by += Vec3::Y;
        }
        if ctx.down(Move::Down) {
            move_by -= Vec3::Y;
        }
        if move_by.length_squared() > 1.0 {
            move_by = move_by.normalize();
        }

        self.eye += move_by * MOVE_SPEED * self.speed_scale * ctx.dt().as_secs_f32();
        self.eye.y = self.eye.y.max(MIN_EYE_HEIGHT);
    }

    /// The material [`Front`] draws with, resolved new from its sliders
    /// every frame — the override [`Instance::material`] takes, in place
    /// of a baked one.
    fn front_material(&self) -> Material {
        Material::lit(self.front_tint)
            .roughness(self.front_roughness)
            .metallic(self.front_metallic)
    }

    /// Every draw this game makes: the ground, each map pair, the front
    /// sphere, the reflection row and the pillars beside it.
    fn draw_scene(&self, ctx: &mut FrameContext<'_, Self>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR).roughness(0.9)),
        );

        Self::draw_pair(
            ctx,
            SHADING_Z,
            SPHERE_RADIUS,
            ShadingPlain.at(Vec3::ZERO).into_set(),
            ShadingMapped.at(Vec3::ZERO).into_set(),
            self.shading_map_on,
        );
        Self::draw_pair(
            ctx,
            RELIEF_Z,
            SPHERE_RADIUS,
            ReliefPlain.at(Vec3::ZERO).into_set(),
            ReliefMapped.at(Vec3::ZERO).into_set(),
            self.relief_map_on,
        );
        Self::draw_pair(
            ctx,
            EMISSIVE_Z,
            CUBE_SIZE / 2.0,
            EmissivePlain.at(Vec3::ZERO).into_set(),
            EmissiveMapped.at(Vec3::ZERO).into_set(),
            self.emissive_map_on,
        );

        ctx.draw(
            Front
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FRONT_SCALE),
                    Quat::IDENTITY,
                    FRONT_POSITION,
                ))
                .material(self.front_material()),
        );

        self.draw_reflect_row(ctx);
        self.draw_outpost(ctx);
    }

    /// One pair at depth `z`, its centers `height` above the ground: `plain`
    /// on the left always, and on the right `mapped` where `mapped_on` is
    /// set, `plain` again where it is not — the same position drawing the
    /// same base material with and without the map.
    fn draw_pair(
        ctx: &mut FrameContext<'_, Self>,
        z: f32,
        height: f32,
        plain: Instance<Shape, Looks>,
        mapped: Instance<Shape, Looks>,
        mapped_on: bool,
    ) {
        ctx.draw(plain.clone().at(Vec3::new(-PAIR_HALF_SPACING, height, z)));
        let right = if mapped_on { mapped } else { plain };
        ctx.draw(right.at(Vec3::new(PAIR_HALF_SPACING, height, z)));
    }

    /// A row of built-in `Sphere` draws at rising roughness, each
    /// `metallic(1.0)` with its tint white, so what draws is the sky's own
    /// reflection alone.
    fn draw_reflect_row(&self, ctx: &mut FrameContext<'_, Self>) {
        let start = -REFLECT_ROW_SPACING * (REFLECT_ROW_COUNT as f32 - 1.0) / 2.0;
        for index in 0..REFLECT_ROW_COUNT {
            let x = start + index as f32 * REFLECT_ROW_SPACING;
            let roughness = index as f32 / (REFLECT_ROW_COUNT as f32 - 1.0);
            ctx.draw(
                Sphere {
                    subdivisions: SPHERE_SUBDIVISIONS,
                }
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(REFLECT_ROW_RADIUS * 2.0),
                    Quat::IDENTITY,
                    Vec3::new(x, REFLECT_ROW_RADIUS, REFLECT_ROW_Z),
                ))
                .material(
                    Material::lit(Color::WHITE)
                        .roughness(roughness)
                        .metallic(1.0),
                ),
            );
        }
    }

    /// Three pillars and a pole a light can shadow, beside `Banner`'s
    /// displaced cloth and `Field`'s pulsing sphere — [`OUTPOST`] moves the
    /// whole group clear of the rest of the scene.
    fn draw_outpost(&self, ctx: &mut FrameContext<'_, Self>) {
        let clock = ctx.elapsed().as_secs_f32();

        for &(position, scale) in &PILLARS {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    scale,
                    Quat::IDENTITY,
                    OUTPOST + position,
                ))
                .material(Material::lit(Color::rgb(0.55, 0.5, 0.45))),
            );
        }

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                POLE_SCALE,
                Quat::IDENTITY,
                OUTPOST + POLE_POSITION,
            ))
            .material(Material::lit(Color::rgb(0.3, 0.24, 0.18))),
        );

        ctx.set_surface_style(Banner { time: clock });
        ctx.draw(
            BannerCloth
                .at(Transform::from_translation(OUTPOST + BANNER_MOUNT))
                .material(Material::lit(Color::rgb(0.75, 0.12, 0.12)))
                .surface_style::<Banner>(),
        );

        ctx.set_surface_style(Field {
            tint: Color::rgb(0.25, 0.75, 1.0),
            time: clock,
        });
        ctx.draw(
            Sphere { subdivisions: 2 }
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FIELD_ORB_SCALE),
                    Quat::IDENTITY,
                    OUTPOST + FIELD_ORB_POSITION,
                ))
                .material(Material::color(Color::BLACK))
                .surface_style::<Field>(),
        );
    }

examples/sprite-adventure.rs (line 682)

    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(FLAME_SHEET).pixelated())
            .with_material(Material::color(FLAME_TINT).additive())
    }
}

/// The player's sprite, cutout with its own relief, its sheet shared
/// with `examples/isometric-board.rs`.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Walker;

impl Mesh for Walker {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(WALKER_SHEET).pixelated())
            .with_relief(assets.relief(WALKER_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// The cave floor tile.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct CaveFloor;

impl Mesh for CaveFloor {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(CAVE_SHEET).pixelated())
    }
}

/// The cave wall face.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct CaveWall;

impl Mesh for CaveWall {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(CAVE_SHEET).pixelated())
    }
}

/// The loaded door, drawn as its source authored it.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Door;

impl Mesh for Door {
    fn build(&self, assets: &Assets) -> MeshData {
        assets.mesh(DOOR_MESH)
    }
}

/// The loaded gem, repainted whole per draw so its glow color shifts.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Gem;

impl Mesh for Gem {
    fn build(&self, assets: &Assets) -> MeshData {
        assets.mesh(GEM_MESH)
    }
}

// Everything this game can draw: the meshes above, plus the styled water,
// the dark filling a looked-into mouth's opening, and the door's own frame,
// which draw the bare engine primitives Plane, Quad and Cube.
meshes! {
    enum Shape {
        Ground, Shore, Crate, Well, WellMouth, Stone, Bush, Rock, Torch,
        Flame, Walker, CaveFloor, CaveWall, Door, Gem, Plane, Quad, Cube,
    }
}

/// The interact click and the gem's chime, shared with the other examples.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
enum Sound {
    Interact,
    Gem,
}

impl Sounds for Sound {
    fn build(&self, assets: &Assets) -> SoundData {
        match self {
            Sound::Interact => assets.sound("click"),
            Sound::Gem => assets.sound("win"),
        }
    }
}

// ---------------------------------------------------------------------
// Input
// ---------------------------------------------------------------------

/// Player movement: `WASD`, arrows, or a stick — the strongest reading is
/// kept.
#[derive(InputAxis2Action, Clone, Copy, PartialEq)]
enum Move {
    Walk,
}

impl InputAxis2Action for Move {
    fn bindings(&self) -> Vec<Axis2Binding> {
        match self {
            Move::Walk => vec![
                Axis2Binding::from(ButtonAxis2 {
                    left: Key::A,
                    right: Key::D,
                    down: Key::S,
                    up: Key::W,
                }),
                Axis2Binding::from(ButtonAxis2 {
                    left: Key::Left,
                    right: Key::Right,
                    down: Key::Down,
                    up: Key::Up,
                }),
                Axis2Binding::stick(Stick::Left),
            ],
        }
    }
}

/// The two verbs this game reads as an edge: interacting with the door, and
/// a reset of the world to every saved key's fallback.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Button {
    Interact,
    Reset,
}

impl InputButtonAction for Button {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Button::Interact => vec![Key::E.into(), Pad::West.into()],
            Button::Reset => vec![Key::R.into()],
        }
    }
}

struct Controls;

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

// ---------------------------------------------------------------------
// Save data
// ---------------------------------------------------------------------

/// The player's last position, read at startup and saved on area
/// transition and gem pickup.
#[derive(Saves, Clone, Copy)]
enum Position {
    X,
    Z,
}

impl SaveKey for Position {
    type Value = f64;

    fn fallback(&self) -> f64 {
        match self {
            Position::X => PLAYER_SPAWN.x as f64,
            Position::Z => PLAYER_SPAWN.z as f64,
        }
    }
}

/// The area the player is in, and whether the gem is taken.
#[derive(Saves, Clone, Copy)]
enum Flag {
    InCave,
    GemTaken,
}

impl SaveKey for Flag {
    type Value = bool;

    fn fallback(&self) -> bool {
        false
    }
}

// ---------------------------------------------------------------------
// The player's facing
// ---------------------------------------------------------------------

/// The player's last facing: also its row in the sheet, top to bottom.
#[derive(Clone, Copy, PartialEq)]
enum Facing {
    Toward = 0,
    Right = 1,
    Away = 2,
    Left = 3,
}

impl Facing {
    /// The facing `heading` points in, favoring its larger axis; `None` at
    /// rest, so the caller can keep the last facing.
    fn from_heading(heading: Vec2) -> Option<Self> {
        if heading == Vec2::ZERO {
            return None;
        }
        Some(if heading.x.abs() > heading.y.abs() {
            if heading.x > 0.0 {
                Self::Right
            } else {
                Self::Left
            }
        } else if heading.y > 0.0 {
            Self::Away
        } else {
            Self::Toward
        })
    }
}

// ---------------------------------------------------------------------
// The game
// ---------------------------------------------------------------------

/// The ground tile at `col, row`: the path's dirt along [`PATH_COLUMN`],
/// the verges that edge it, and a hashed grass variant everywhere else.
fn ground_cell(col: i32, row: i32) -> Frame {
    let (column, sheet_row) = match col - PATH_COLUMN {
        0 => (PATH_DIRT + row.rem_euclid(2) as u32, PATH_ROW),
        -1 => (PATH_WEST_VERGE, PATH_ROW),
        1 => (PATH_EAST_VERGE, PATH_ROW),
        _ => (
            (col * 31 + row * 17).rem_euclid(GROUND_COLUMNS as i32) as u32,
            GRASS_ROW,
        ),
    };

    Sheet::new(UVec2::new(GROUND_COLUMNS, GROUND_ROWS)).cell_at(UVec2::new(column, sheet_row))
}

/// The stone sheet's plain masonry, laid `tiles` times across: the sampler
/// wraps, so a window wider than the sheet repeats the course.
fn masonry(tiles: f32) -> Frame {
    let course = 1.0 / STONE_ROWS as f32;

    Frame::rect(Vec2::new(0.0, 1.0 - course), Vec2::new(tiles, 1.0))
}

/// The wall or door's alpha `fraction` of the way from [`SOLID`] to
/// [`GHOST_ALPHA`].
fn ghost_alpha(fraction: f32) -> f32 {
    SOLID + (GHOST_ALPHA - SOLID) * fraction
}

/// The wall face in column `variant`, windowed to the meters `standing` of
/// one course, measured up from that course's own base: every row of the
/// cave sheet below the floor's covers [`WALL_HEIGHT`], so a course keeps
/// the floor's texels to the meter however it is cut.
fn cave_wall_face(variant: u32, standing: Range<f32>) -> Frame {
    let cell = Vec2::new(1.0 / CAVE_COLUMNS as f32, 1.0 / CAVE_ROWS as f32);
    let left = (variant % CAVE_COLUMNS) as f32 * cell.x;
    let face = (CAVE_FLOOR_ROW + 1) as f32 * cell.y;
    let up_from_base = |height: f32| 1.0 - (1.0 - face) * (height / WALL_HEIGHT);

    Frame::rect(
        Vec2::new(left, up_from_base(standing.end)),
        Vec2::new(left + cell.x, up_from_base(standing.start)),
    )
}

/// The logical point egui paints the physical pixel `pixel` at.
fn logical(pixel: Vec2, pixels_per_point: f32) -> egui::Pos2 {
    let point = pixel / pixels_per_point;
    egui::pos2(point.x, point.y)
}

fn main() {
    run(
        Config::new("Mirage: sprite adventure")
            .with_size(1280, 720)
            .with_assets([
                MODEL,
                WALKER_SOURCE,
                WALKER_RELIEF_SOURCE,
                GROUND_SOURCE,
                BUSH_SOURCE,
                BUSH_RELIEF_SOURCE,
                ROCK_SOURCE,
                ROCK_RELIEF_SOURCE,
                TORCH_RELIEF_SOURCE,
                CRATE_SOURCE,
                WELL_SOURCE,
                STONE_SOURCE,
                CAVE_SOURCE,
                POND_SOURCE,
                TORCH_SOURCE,
                FLAME_SOURCE,
                INTERACT_SOUND,
                GEM_SOUND,
            ]),
        Keep::init,
    );
}

struct Keep {
    area: Area,
    position: Vec3,
    previous: Vec3,
    facing: Facing,
    walk_ticks: u32,
    simulated: Duration,
    door_opening: bool,
    /// Ticks the door has been opening for, at a cap of
    /// [`DOOR_SWING_TICKS`]: how long its world prompt reads "opening" once
    /// it starts.
    swing_ticks: u32,
    gem_taken: bool,
    /// How far the door wall's fade from [`SOLID`] to [`GHOST_ALPHA`] has
    /// run as of the last tick: `0.0` to `1.0`.
    ghost: f32,
    /// Set by the panel's reset button, since its click lands in a frame
    /// rather than a tick; read and cleared on the next tick.
    reset_requested: bool,
}

impl Keep {
    /// Prepares every startup-cataloged mesh and resumes wherever the last
    /// run left the player.
    fn init(ctx: &mut InitContext<'_, Keep>) -> Result<Self, Error> {
        let startup = ctx.startup();
        let gem_taken = startup.saved(Flag::GemTaken);
        let area = if startup.saved(Flag::InCave) {
            Area::Cave
        } else {
            Area::Overworld
        };
        let position = Vec3::new(
            startup.saved(Position::X) as f32,
            0.0,
            startup.saved(Position::Z) as f32,
        );

        Ok(Self {
            area,
            position,
            previous: position,
            facing: Facing::Toward,
            walk_ticks: 0,
            simulated: Duration::ZERO,
            door_opening: gem_taken,
            swing_ticks: if gem_taken { DOOR_SWING_TICKS } else { 0 },
            gem_taken,
            ghost: 0.0,
            reset_requested: false,
        })
    }

    fn camera(position: Vec3, offset: Vec3) -> Camera {
        Camera::new(
            View::look_at(position + offset, position),
            Projection::perspective(CAMERA_FOV),
        )
    }

    /// Obstacles from the overworld's props: the crates, turned as they are
    /// drawn, the well's rim, the open water the shoreline rings, the
    /// mouth's pillars, and each flora's base.
    fn overworld_obstacles() -> impl Iterator<Item = Obstacle> + Clone {
        CRATE_POSITIONS
            .into_iter()
            .map(|(x, z, turn)| {
                Obstacle::footprint(Vec2::new(x, z), Vec2::splat(CRATE_SIZE * turned_span(turn)))
            })
            .chain([
                Obstacle::footprint(WELL_POSITION.xz(), WELL_SIZE.xz()),
                Obstacle::footprint(POND_CENTER.xz(), Vec2::splat(POND_WATER_HALF * 2.0)),
            ])
            .chain(
                ENTRANCE
                    .pillars()
                    .map(|at| Obstacle::footprint(at.xz(), MOUTH_PILLAR_SIZE.xz())),
            )
            .chain(FLORA.into_iter().map(|(x, z, rock)| {
                let base = if rock { ROCK_FOOTPRINT } else { BUSH_FOOTPRINT };
                Obstacle::footprint(Vec2::new(x, z), Vec2::splat(base))
            }))
    }

    /// Obstacles from the cave: the torch posts, its own mouth's pillars,
    /// the runs of wall either side of the doorway and of the mouth, and the
    /// `door` leaf.
    fn cave_obstacles(door: Obstacle) -> impl Iterator<Item = Obstacle> + Clone {
        TORCH_POSITIONS
            .into_iter()
            .map(|(x, z)| Obstacle::footprint(Vec2::new(x, z), Vec2::splat(TORCH_STAND_WIDTH)))
            .chain(
                EXIT.pillars()
                    .map(|at| Obstacle::footprint(at.xz(), MOUTH_PILLAR_SIZE.xz())),
            )
            .chain(SIDES.into_iter().flat_map(|side| {
                [
                    Self::wall_run(side, DOOR_Z),
                    Self::wall_run(side, CAVE_LIP_Z),
                ]
            }))
            .chain([door])
    }

    /// One of the two runs of wall either side of a one-tile opening on the
    /// room's axis, at `z`.
    fn wall_run(side: f32, z: f32) -> Obstacle {
        Obstacle::footprint(
            Vec2::new(side * (DOORWAY_HALF + DOOR_WALL_END) * 0.5, z),
            Vec2::new(DOOR_WALL_END - DOORWAY_HALF, TILE_SIZE),
        )
    }

    /// Obstacle from the door leaf's own footprint: the box over its four
    /// corners, swung back against the wall once the door is opened.
    fn door_obstacle(&self) -> Obstacle {
        let hinge = DOOR_HINGE.xz();
        let across = DOOR_THICKNESS * 0.5;
        let corner = |along: f32, aside: f32| {
            let (x, z) = if self.door_opening {
                (aside, -along)
            } else {
                (along, aside)
            };
            hinge + Vec3::new(x, 0.0, z).xz()
        };

        Obstacle::over([
            corner(0.0, -across),
            corner(0.0, across),
            corner(DOOR_WIDTH, -across),
            corner(DOOR_WIDTH, across),
        ])
    }

    /// Pushes the player out of every obstacle their circle has walked into,
    /// over as many passes as it takes for one to leave them where the last
    /// one did — overlapping obstacles need more than one.
    fn push_out_of(&mut self, obstacles: impl Iterator<Item = Obstacle> + Clone) {
        /// Passes an overlap is given to settle before the frame takes what
        /// it has; ones this game builds settle in two.
        const PASSES: u32 = 4;

        let mut standing = self.position.xz();
        for _ in 0..PASSES {
            let settled = obstacles.clone().fold(standing, |point, obstacle| {
                obstacle.push_out(point, PLAYER_RADIUS)
            });
            if settled == standing {
                break;
            }
            standing = settled;
        }

        self.position.x = standing.x;
        self.position.z = standing.y;
    }

    fn tick_overworld(&mut self, ctx: &mut TickContext<'_, Keep>) {
        self.push_out_of(Self::overworld_obstacles());
        self.position.x = self.position.x.clamp(-CLEARING_HALF, CLEARING_HALF);
        self.position.z = self.position.z.clamp(-CLEARING_HALF, CLEARING_HALF);

        if ENTRANCE.holds(self.position) {
            if ENTRANCE.holds(self.previous) {
                self.position.z = self.previous.z;
            } else {
                self.enter_cave(ctx);
            }
        }
    }

    fn tick_cave(&mut self, ctx: &mut TickContext<'_, Keep>) {
        self.push_out_of(Self::cave_obstacles(self.door_obstacle()));
        self.position.x = self.position.x.clamp(-CAVE_HALF_WIDTH, CAVE_HALF_WIDTH);
        self.position.z = self.position.z.clamp(CAVE_WALK_FAR_Z, CAVE_WALK_NEAR_Z);

        let target = if self.position.z < DOOR_WALL_NEAR_Z {
            1.0
        } else {
            0.0
        };
        let step = 1.0 / GHOST_RAMP_TICKS as f32;
        self.ghost += (target - self.ghost).clamp(-step, step);

        if !self.door_opening
            && ctx.pressed(Button::Interact)
            && self.position.distance(INTERACT_POINT) < INTERACT_RADIUS
        {
            self.door_opening = true;
            self.swing_ticks = 0;
            ctx.play(Sound::Interact);
        }
        if self.door_opening && self.swing_ticks < DOOR_SWING_TICKS {
            self.swing_ticks += 1;
        }

        if !self.gem_taken && self.position.distance(GEM_POSITION) < PICKUP_RADIUS {
            self.gem_taken = true;
            ctx.play(Sound::Gem);
            ctx.save(Flag::GemTaken, true);
            ctx.save(Position::X, self.position.x as f64);
            ctx.save(Position::Z, self.position.z as f64);
        }

        if EXIT.holds(self.position) {
            if EXIT.holds(self.previous) {
                self.position.z = self.previous.z;
            } else {
                self.exit_cave(ctx);
            }
        }
    }

    /// Puts the player back at [`PLAYER_SPAWN`] with the cave and the gem
    /// returned to their saved fallbacks, all in this tick: a reset saves
    /// every key's own fallback, since there is nothing to clear it to.
    fn reset(&mut self, ctx: &mut TickContext<'_, Keep>) {
        ctx.save(Position::X, Position::X.fallback());
        ctx.save(Position::Z, Position::Z.fallback());
        ctx.save(Flag::InCave, Flag::InCave.fallback());
        ctx.save(Flag::GemTaken, Flag::GemTaken.fallback());

        self.area = Area::Overworld;
        self.position = PLAYER_SPAWN;
        self.previous = PLAYER_SPAWN;
        self.gem_taken = false;
        self.door_opening = false;
        self.swing_ticks = 0;
        self.ghost = 0.0;
    }

    /// Steps into the cave at [`CAVE_SPAWN`], saving the transition.
    fn enter_cave(&mut self, ctx: &mut TickContext<'_, Keep>) {
        self.area = Area::Cave;
        self.position = CAVE_SPAWN;
        self.previous = CAVE_SPAWN;
        ctx.save(Flag::InCave, true);
        ctx.save(Position::X, CAVE_SPAWN.x as f64);
        ctx.save(Position::Z, CAVE_SPAWN.z as f64);
    }

    /// Steps back out to the mouth at [`RETURN_SPAWN`], saving the
    /// transition.
    fn exit_cave(&mut self, ctx: &mut TickContext<'_, Keep>) {
        self.area = Area::Overworld;
        self.position = RETURN_SPAWN;
        self.previous = RETURN_SPAWN;
        ctx.save(Flag::InCave, false);
        ctx.save(Position::X, RETURN_SPAWN.x as f64);
        ctx.save(Position::Z, RETURN_SPAWN.z as f64);
    }

    fn draw_ground(&self, ctx: &mut FrameContext<'_, Keep>) {
        for col in -GROUND_DRAW_HALF..=GROUND_DRAW_HALF {
            for row in -GROUND_DRAW_HALF..=GROUND_DRAW_HALF {
                ctx.draw(
                    Ground
                        .at(Vec3::new(
                            col as f32 * TILE_SIZE,
                            0.0,
                            row as f32 * TILE_SIZE,
                        ))
                        .frame(ground_cell(col, row)),
                );
            }
        }
    }

    /// Two staggered rows of bushes around the clearing, open where the path
    /// leaves it, drawn between the camera and the ground's edge. The rows
    /// running along `Z` skip their two ends, which the rows running along
    /// `X` already cover.
    fn draw_hedgerow(&self, ctx: &mut FrameContext<'_, Keep>) {
        for (row, half) in [HEDGE_INNER_HALF, HEDGE_OUTER_HALF].into_iter().enumerate() {
            let row = row as i32;
            // The inner row covers both corners; the outer one is half a
            // span in from each, backing the gaps the inner row leaves.
            let spans = ((2.0 * half / HEDGE_STEP).round() as i32).max(1);
            let span = 2.0 * half / spans as f32;
            let steps = spans - row;
            for step in 0..=steps {
                let along = -half + (step as f32 + 0.5 * row as f32) * span;
                let scale = if (step + row) % 2 == 0 { 1.0 } else { 0.8 };
                let (width, height) = (BUSH_WIDTH * scale, BUSH_HEIGHT * scale);
                // The path leaves through the rows running along `X`, so only
                // those two open around it.
                let gated = along.abs() < HEDGE_GATE_HALF;
                let corner = step == 0 || step == steps;
                let places = [
                    (along, -half, gated),
                    (along, half, gated),
                    (-half, along, corner),
                    (half, along, corner),
                ];
                for (x, z, skip) in places {
                    if skip {
                        continue;
                    }
                    ctx.draw(
                        Bush.at(Transform::from_scale_rotation_translation(
                            Vec3::new(width, height, width),
                            Quat::IDENTITY,
                            Vec3::new(x, height * 0.5, z),
                        ))
                        .upright(),
                    );
                }
            }
        }
    }

    /// The pond: a square of styled water, and the shoreline sprite laid over
    /// it, which rings the open middle and hides the water's own edges.
    fn draw_pond(&self, ctx: &mut FrameContext<'_, Keep>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(POND_WATER_HALF * 2.0),
                    Quat::IDENTITY,
                    POND_CENTER,
                ))
                .material(Material::shaded(WATER_COLOR, WATER_LITNESS))
                .surface_style::<Water>(),
        );
        ctx.draw(
            Shore
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(POND_HALF * 2.0),
                    Quat::IDENTITY,
                    Vec3::new(POND_CENTER.x, 0.0, POND_CENTER.z),
                ))
                .frame(Sheet::new(UVec2::new(POND_CELLS, 1)).cell(POND_SHORE_CELL)),
        );
    }

    fn draw_crates(&self, ctx: &mut FrameContext<'_, Keep>) {
        for &(x, z, turn) in &CRATE_POSITIONS {
            ctx.draw(Crate.at(Transform::from_scale_rotation_translation(
                Vec3::splat(CRATE_SIZE),
                Quat::from_rotation_y(turn),
                Vec3::new(x, CRATE_SIZE * 0.5, z),
            )));
        }
    }

    /// The well: its rim in grey masonry, and the mouth cell laid over the
    /// rim's top face.
    fn draw_well(&self, ctx: &mut FrameContext<'_, Keep>) {
        let cells = Sheet::new(UVec2::new(WELL_CELLS, 1));
        ctx.draw(
            Well.at(Transform::from_scale_rotation_translation(
                WELL_SIZE,
                Quat::IDENTITY,
                WELL_POSITION + Vec3::Y * (WELL_SIZE.y * 0.5),
            ))
            .frame(cells.cell(WELL_RIM_CELL)),
        );
        ctx.draw(
            WellMouth
                .at(Transform::from_scale_rotation_translation(
                    Vec3::new(WELL_SIZE.x, 1.0, WELL_SIZE.z),
                    Quat::IDENTITY,
                    WELL_POSITION + Vec3::Y * (WELL_SIZE.y + WELL_MOUTH_LIFT),
                ))
                .frame(cells.cell(WELL_MOUTH_CELL)),
        );
    }

    fn draw_flora(&self, ctx: &mut FrameContext<'_, Keep>) {
        for &(x, z, rock) in &FLORA {
            let (width, height) = if rock {
                (ROCK_WIDTH, ROCK_HEIGHT)
            } else {
                (BUSH_WIDTH, BUSH_HEIGHT)
            };
            let standing = Transform::from_scale_rotation_translation(
                Vec3::new(width, height, width),
                Quat::IDENTITY,
                Vec3::new(x, height * 0.5, z),
            );
            let flora: Instance<Shape, _> = if rock {
                Rock.at(standing).into_set()
            } else {
                Bush.at(standing).into_set()
            };
            ctx.draw(flora.upright());
        }
    }

    /// One stone box drawn on the ground at `at`, `size` across, sampling
    /// the part of the sheet `frame` covers.
    fn draw_stone(ctx: &mut FrameContext<'_, Keep>, at: Vec3, size: Vec3, frame: Frame) {
        ctx.draw(
            Stone
                .at(Transform::from_scale_rotation_translation(
                    size,
                    Quat::IDENTITY,
                    at + Vec3::Y * (size.y * 0.5),
                ))
                .frame(frame),
        );
    }

    /// Two stone pillars drawn where `mouth` blocks the player, each a
    /// capital over its own course of masonry, and, on the one the camera
    /// looks into, the lintel across their tops and the dark filling
    /// the opening under it.
    fn draw_mouth(ctx: &mut FrameContext<'_, Keep>, mouth: Mouth) {
        for at in mouth.pillars() {
            Self::draw_stone(ctx, at, MOUTH_PILLAR_SIZE, Frame::default());
        }
        if !mouth.looked_into() {
            return;
        }

        Self::draw_stone(
            ctx,
            mouth.at + Vec3::Y * MOUTH_PILLAR_SIZE.y,
            MOUTH_LINTEL_SIZE,
            masonry(MOUTH_LINTEL_TILES),
        );
        ctx.draw(
            Quad.at(Transform::from_scale_rotation_translation(
                Vec3::new(MOUTH_PILLAR_OFFSET * 2.0, MOUTH_DARK_HEIGHT, 1.0),
                Quat::IDENTITY,
                mouth.at + Vec3::Y * (MOUTH_DARK_HEIGHT * 0.5),
            ))
            .material(Material::color(Color::BLACK)),
        );
    }

examples/isometric-board.rs (line 542)

    fn draw_reachable_mark(&self, ctx: &mut FrameContext<'_, Board>, tile: (i32, i32)) {
        let center = tile_center(tile) + Vec3::Y * REACHABLE_MARK_LIFT;
        ctx.draw(
            Plane
                .at(Transform::from_scale_rotation_translation(
                    Vec3::new(
                        TILE_SIZE * REACHABLE_MARK_SCALE,
                        1.0,
                        TILE_SIZE * REACHABLE_MARK_SCALE,
                    ),
                    Quat::IDENTITY,
                    center,
                ))
                .material(Material::color(REACHABLE_MARK)),
        );
    }

    /// A mark bright enough to read past the sprite's own tint under the
    /// selected unit, or a smaller, dim one under the unit whose turn it
    /// is while nothing is selected — so the current unit reads from the
    /// ground alone.
    fn draw_current_mark(&self, ctx: &mut FrameContext<'_, Board>) {
        let (color, scale) = if self.selected {
            (CURRENT_MARK, CURRENT_MARK_SCALE)
        } else {
            (TURN_MARK, TURN_MARK_SCALE)
        };
        let center = tile_center(self.current().tile) + Vec3::Y * REACHABLE_MARK_LIFT;
        ctx.draw(
            Plane
                .at(Transform::from_scale_rotation_translation(
                    Vec3::new(TILE_SIZE * scale, 1.0, TILE_SIZE * scale),
                    Quat::IDENTITY,
                    center,
                ))
                .material(Material::color(color)),
        );
    }

examples/breakout-game.rs (line 675)

    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 = NoSurfaceStyles;
    type PostEffects = NoPostEffects;

    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);
    }

examples/ui-fonts.rs (line 668)

    fn draw_station(&self, ctx: &mut FrameContext<'_, Self>, station: StationKind) {
        let look = station.look();
        let center = station.center();
        let front_offset =
            STATION_SIZE.z * 0.5 - STATION_FRONT_SIZE.z * 0.5 + STATION_FRONT_OUTWARD;
        let front = center - Vec3::new(0.0, 0.0, front_offset);
        for (size, position, material) in [
            (STATION_SIZE, center, Material::lit(look.color)),
            (
                STATION_FRONT_SIZE,
                front,
                Material::color(Color::BLACK).emissive(look.glow),
            ),
        ] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    size,
                    Quat::IDENTITY,
                    position,
                ))
                .material(material),
            );
        }
    }

examples/post-effects.rs (line 108)

    fn draw_scene(&self, ctx: &mut FrameContext<'_, Self>) {
        ctx.light(Light::directional(SUN_DIRECTION, SUN_COLOR).shadow());

        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR)),
        );
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::splat(GLOW_SIZE),
                Quat::IDENTITY,
                GLOW_POSITION,
            ))
            .material(Material::color(Color::BLACK).emissive(GLOW_COLOR)),
        );
        for position in SPHERE_POSITIONS {
            ctx.draw(
                Sphere {
                    subdivisions: SPHERE_SUBDIVISIONS,
                }
                .at(position)
                .material(Material::lit(SPHERE_COLOR)),
            );
        }
    }

Additional examples can be found in:

• examples/sound-lab.rs
• examples/animation.rs

pub const fn lit(color: Color) -> Self

A color fully lit by the frame’s lights.

Examples found in repository

examples/material-playground.rs (line 292)

fn shading_material() -> Material {
    Material::lit(SHADING_TINT).roughness(0.5).metallic(0.5)
}

fn relief_material() -> Material {
    Material::lit(RELIEF_TINT).roughness(0.35)
}

fn emissive_material() -> Material {
    Material::color(EMISSIVE_BASE).emissive(EMISSIVE_GLOW)
}

/// A shading map whose checker goes between low occlusion, roughness and
/// metallic and full occlusion, roughness and metallic, so all three read
/// apart across [`ShadingMapped`].
fn shading_checker() -> ShadingData {
    ShadingData::rgba8(
        MAP_SIZE,
        checker_pixels(MAP_SIZE, SHADING_CELL, SHADING_LOW, SHADING_HIGH),
    )
}

/// An emissive map whose checker goes between full glow and none, so
/// [`EMISSIVE_GLOW`] shapes across [`EmissiveMapped`] instead of casting
/// whole.
fn emissive_checker() -> TextureData {
    TextureData::rgba8(
        MAP_SIZE,
        checker_pixels(MAP_SIZE, EMISSIVE_CELL, [0, 0, 0], [255, 255, 255]),
    )
}

fn checker_pixels(size: UVec2, cell: u32, low: [u8; 3], high: [u8; 3]) -> Vec<u8> {
    let mut pixels = Vec::with_capacity((size.x * size.y * 4) as usize);
    for y in 0..size.y {
        for x in 0..size.x {
            let on = ((x / cell) + (y / cell)).is_multiple_of(2);
            let [red, green, blue] = if on { high } else { low };
            pixels.extend_from_slice(&[red, green, blue, u8::MAX]);
        }
    }
    pixels
}

/// A relief whose normals turn across a wave that repeats over the map:
/// each texel's slope comes from the partial derivatives of a
/// `sin(u) * sin(v)` height field at `BUMP_SLOPE`'s peak, computed at that
/// texel and not sampled from any other.
fn relief_bumps() -> ReliefData {
    let size = MAP_SIZE;
    let turns = core::f32::consts::TAU * BUMP_WAVES;
    let mut pixels = Vec::with_capacity((size.x * size.y * 4) as usize);
    for y in 0..size.y {
        for x in 0..size.x {
            let u = (x as f32 + 0.5) / size.x as f32;
            let v = (y as f32 + 0.5) / size.y as f32;
            let slope_u = BUMP_SLOPE * (turns * u).cos() * (turns * v).sin();
            let slope_v = BUMP_SLOPE * (turns * u).sin() * (turns * v).cos();
            let normal = Vec3::new(-slope_u, -slope_v, 1.0).normalize();
            let encode = |signed: f32| ((signed * 0.5 + 0.5) * 255.0).round() as u8;
            pixels.extend_from_slice(&[encode(normal.x), encode(normal.y), encode(normal.z), 0]);
        }
    }
    ReliefData::normals(size, pixels)
}

/// `BannerCloth`'s vertices and indices, built twice over: the columns as
/// authored, facing `+Z`, and the same columns again facing `-Z`, their
/// triangles in the other order so both draw front side out.
fn banner_mesh() -> MeshData {
    let mut vertices = Vec::with_capacity(((BANNER_COLUMNS + 1) * 4) as usize);
    for normal in [Vec3::Z, Vec3::NEG_Z] {
        for column in 0..=BANNER_COLUMNS {
            let u = column as f32 / BANNER_COLUMNS as f32;
            let x = u * BANNER_WIDTH;
            for v in [0.0, 1.0] {
                vertices.push(Vertex::new(
                    Vec3::new(x, -v * BANNER_HEIGHT, 0.0),
                    normal,
                    Vec2::new(u, v),
                ));
            }
        }
    }

    let side = BANNER_COLUMNS + 1;
    let mut indices = Vec::with_capacity((BANNER_COLUMNS * 12) as usize);
    for column in 0..BANNER_COLUMNS {
        let top_left = column * 2;
        let bottom_left = top_left + 1;
        let top_right = top_left + 2;
        let bottom_right = top_left + 3;
        indices.extend([
            bottom_left,
            bottom_right,
            top_right,
            bottom_left,
            top_right,
            top_left,
        ]);

        let back = side * 2;
        indices.extend([
            back + top_right,
            back + bottom_right,
            back + bottom_left,
            back + top_left,
            back + top_right,
            back + bottom_left,
        ]);
    }

    MeshData::new(vertices, indices)
}

/// Displaced by a wave that grows away from its `x = 0` edge; casts the
/// shadow of where it was placed, unmoved by its own wave. Its one value
/// is the clock its wave slides on.
#[derive(Default, ShaderValues)]
struct Banner {
    time: f32,
}

impl SurfaceStyle for Banner {
    const PASS: DrawPass = DrawPass::Opaque;
    const DISPLACE: Option<&'static str> = Some(include_str!("material_playground_banner.wgsl"));
}

/// A surface that reads no light of the scene's own: it draws its own
/// pulsing tint, added over what is behind it, through the color it pulses
/// through and the clock the pulse is timed by.
#[derive(Default, ShaderValues)]
struct Field {
    tint: Color,
    time: f32,
}

impl SurfaceStyle for Field {
    const PASS: DrawPass = DrawPass::Additive;
    const SURFACE: Option<&'static str> = Some(include_str!("material_playground_field.wgsl"));
}

surface_styles! { enum Looks { Banner, Field } }

/// A whole scene lighting choice: it names a sky and, kept with it, the
/// sun that lights the scene, so a choice cannot leave the two apart.
/// `Dawn`, `Noon`, `Dusk` and `Night` each pair a gradient with a sun of
/// its own color and direction; `Clear`, `Classic`, `ImageDawn` and
/// `Sinister` each pair a loaded image with a sun that fits it, and
/// `LightBlueStars` and `BlueStars` pair a loaded space image with none;
/// `Default` is the engine's own grey sky and white sun.
///
/// [`Skyboxes`] proves every value at startup, so it must be [`Eq`] and
/// [`Hash`] over a fixed [`Skyboxes::catalog`] — a sky and sun a player
/// set to any color and direction live could never meet, since `f32` is
/// neither. This fixed, named set is the shape this file chose in its
/// place: the side area offers it as one row, and shows the chosen sky's
/// own light and its sun's own strength as text, read only, rather than
/// controls a game could not build from. See this example's report for
/// what that choice costs.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
enum Sky {
    Dawn,
    Noon,
    Dusk,
    Night,
    Clear,
    Classic,
    ImageDawn,
    Sinister,
    LightBlueStars,
    BlueStars,
    Default,
}

impl Sky {
    const ALL: [Sky; 11] = [
        Self::Dawn,
        Self::Noon,
        Self::Dusk,
        Self::Night,
        Self::Clear,
        Self::Classic,
        Self::ImageDawn,
        Self::Sinister,
        Self::LightBlueStars,
        Self::BlueStars,
        Self::Default,
    ];

    fn name(self) -> &'static str {
        match self {
            Self::Dawn => "dawn",
            Self::Noon => "noon",
            Self::Dusk => "dusk",
            Self::Night => "night",
            Self::Clear => "clear day",
            Self::Classic => "classic",
            Self::ImageDawn => "dawn image",
            Self::Sinister => "sinister night",
            Self::LightBlueStars => "light blue stars",
            Self::BlueStars => "blue stars",
            Self::Default => "default",
        }
    }

    /// The fraction of its own light this sky lands and reflects, through
    /// [`SkyboxData::lit_by`]: fixed per choice, so a bright one does not
    /// read too bright, and a dark one does not read too dark, under the
    /// frame's own lights.
    fn light(self) -> f32 {
        match self {
            Self::Dawn => 0.4,
            Self::Noon => 0.5,
            Self::Dusk => 0.35,
            Self::Night => 0.3,
            Self::Clear => CLEAR_SKY_LIGHT,
            Self::Classic => CLASSIC_SKY_LIGHT,
            Self::ImageDawn => DAWN_SKY_LIGHT,
            Self::Sinister => SINISTER_SKY_LIGHT,
            Self::LightBlueStars => LIGHT_BLUE_STARS_LIGHT,
            Self::BlueStars => BLUE_STARS_LIGHT,
            Self::Default => 1.0,
        }
    }

    /// The sun this choice pairs with its sky: direction, color and
    /// strength resolved together, so a choice cannot leave them apart.
    /// `None` for the two space images, which pair with no sun at all.
    fn sun(self) -> Option<(Vec3, Color, f32)> {
        match self {
            Self::Dawn => Some((
                Vec3::new(-1.0, -0.15, 0.05),
                Color::rgb(1.0, 0.7, 0.45),
                1.4,
            )),
            Self::Noon => Some((
                Vec3::new(-0.15, -1.0, -0.1),
                Color::rgb(1.0, 1.0, 0.98),
                1.6,
            )),
            Self::Dusk => Some((
                Vec3::new(1.0, -0.15, 0.05),
                Color::rgb(1.0, 0.55, 0.25),
                1.2,
            )),
            Self::Night => Some((
                Vec3::new(-0.3, -0.7, -0.6),
                Color::rgb(0.55, 0.65, 0.85),
                0.15,
            )),
            Self::Clear => Some((
                Vec3::new(-0.2, -1.0, -0.15),
                Color::rgb(1.0, 0.98, 0.9),
                1.5,
            )),
            Self::Classic => Some((
                Vec3::new(-0.4, -0.9, -0.2),
                Color::rgb(1.0, 0.95, 0.85),
                1.3,
            )),
            Self::ImageDawn => Some((Vec3::new(-1.0, -0.2, 0.1), Color::rgb(1.0, 0.75, 0.5), 1.1)),
            Self::Sinister => Some((Vec3::new(0.4, -0.5, -0.7), Color::rgb(0.4, 0.5, 0.75), 0.1)),
            Self::LightBlueStars | Self::BlueStars => None,
            Self::Default => Some((Vec3::new(-0.4, -1.0, -0.6), Color::WHITE, 1.0)),
        }
    }

    /// The color the sky reads under the horizon, through
    /// [`SkyboxData::with_ground`]: the floor as lit under this choice's own
    /// sun and [`Self::light`], so it moves with them, not only with the
    /// image. `None` for the gradient skies and `Default`, which need no
    /// ground, and for the two space images, which hold space below the
    /// horizon as well.
    fn ground(self) -> Option<Color> {
        match self {
            Self::Clear => Some(Color::rgb(0.501, 0.517, 0.449)),
            Self::Classic => Some(Color::rgb(0.420, 0.405, 0.379)),
            Self::ImageDawn => Some(Color::rgb(0.073, 0.053, 0.032)),
            Self::Sinister => Some(Color::rgb(0.012, 0.014, 0.020)),
            Self::Dawn
            | Self::Noon
            | Self::Dusk
            | Self::Night
            | Self::LightBlueStars
            | Self::BlueStars
            | Self::Default => None,
        }
    }
}

impl Catalog for Sky {
    fn catalog() -> Vec<Self> {
        Self::ALL.to_vec()
    }
}

impl Skyboxes for Sky {
    fn build(&self, assets: &Assets) -> SkyboxData {
        let sky = match self {
            Self::Dawn => SkyboxData::gradient(
                Color::rgb(0.55, 0.55, 0.75),
                Color::rgb(0.95, 0.6, 0.35),
                Color::rgb(0.12, 0.08, 0.06),
            ),
            Self::Noon => SkyboxData::gradient(
                Color::rgb(0.2, 0.45, 0.85),
                Color::rgb(0.75, 0.82, 0.9),
                Color::rgb(0.3, 0.3, 0.28),
            ),
            Self::Dusk => SkyboxData::gradient(
                Color::rgb(0.18, 0.1, 0.3),
                Color::rgb(0.85, 0.35, 0.2),
                Color::rgb(0.03, 0.02, 0.03),
            ),
            Self::Night => SkyboxData::gradient(
                Color::rgb(0.02, 0.02, 0.06),
                Color::rgb(0.05, 0.05, 0.1),
                Color::rgb(0.0, 0.0, 0.0),
            ),
            Self::Clear => assets.skybox("sky-clear"),
            Self::Classic => assets.skybox("sky-classic"),
            Self::ImageDawn => assets.skybox("sky-dawn"),
            Self::Sinister => assets.skybox("sky-sinister"),
            Self::LightBlueStars => assets.skybox("sky-stars-lightblue"),
            Self::BlueStars => assets.skybox("sky-stars-blue"),
            Self::Default => SkyboxData::gradient(DEFAULT_SKY, DEFAULT_SKY, DEFAULT_SKY),
        };
        let sky = match self.ground() {
            Some(ground) => sky.with_ground(ground),
            None => sky,
        };

        sky.lit_by(self.light())
    }
}

/// `color` scaled by `strength`, the value a [`Light`] reads.
fn scaled(color: Color, strength: f32) -> Color {
    Color::rgb(
        color.red * strength,
        color.green * strength,
        color.blue * strength,
    )
}

/// One light's color and strength, held apart from the position that
/// names it, plus whether it casts.
#[derive(Clone, Copy)]
struct Glow {
    color: Color,
    strength: f32,
    shadow: bool,
}

impl Glow {
    /// `color` scaled by `strength`, the value a [`Light`] reads.
    fn scaled(self) -> Color {
        scaled(self.color, self.strength)
    }
}

/// Every key and button this game reads apart from the UI: held, `Look`
/// turns the camera by the pointer's own motion, `Forward`/`Back`/
/// `Left`/`Right` move it along the view and to its side, and `Up`/
/// `Down` move it along the world's own up.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Move {
    Forward,
    Back,
    Left,
    Right,
    Up,
    Down,
    Look,
}

impl InputButtonAction for Move {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Self::Forward => vec![Key::W.into()],
            Self::Back => vec![Key::S.into()],
            Self::Left => vec![Key::A.into()],
            Self::Right => vec![Key::D.into()],
            Self::Up => vec![Key::Space.into()],
            Self::Down => vec![Key::LeftShift.into()],
            Self::Look => vec![MouseButton::Right.into()],
        }
    }
}

/// The pointer's own motion, read only while [`Move::Look`] is held.
#[derive(InputAxis2Action, Clone, Copy, PartialEq)]
enum Turn {
    Look,
}

impl InputAxis2Action for Turn {
    fn bindings(&self) -> Vec<Axis2Binding> {
        match self {
            Self::Look => vec![Axis2Binding::pointer().scale(LOOK_SENSITIVITY)],
        }
    }
}

/// How far the wheel moved this frame, read to scale the move speed.
#[derive(InputAxisAction, Clone, Copy, PartialEq)]
enum Speed {
    Wheel,
}

impl InputAxisAction for Speed {
    fn bindings(&self) -> Vec<AxisBinding> {
        match self {
            Self::Wheel => vec![AxisBinding::from(WheelDelta::Up).scale(4.0)],
        }
    }
}

struct Controls;

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

struct Playground {
    eye: Vec3,
    yaw: f32,
    pitch: f32,
    speed_scale: f32,

    sky: Sky,
    sun_shadow: bool,

    lamp: Glow,
    spotlight: Glow,

    front_tint: Color,
    front_roughness: f32,
    front_metallic: f32,
    shading_map_on: bool,
    relief_map_on: bool,
    emissive_map_on: bool,

    exposure: f32,
    bloom: f32,
}

impl Playground {
    fn init(ctx: &mut InitContext<'_, Self>) -> Result<Self, Error> {
        let _ = ctx;
        Ok(Self {
            eye: START_EYE,
            yaw: START_YAW,
            pitch: START_PITCH,
            speed_scale: 1.0,

            sky: Sky::Default,
            sun_shadow: true,

            lamp: Glow {
                color: Color::rgb(0.9, 0.55, 0.3),
                strength: 3.0,
                shadow: false,
            },
            spotlight: Glow {
                color: Color::rgb(0.4, 0.6, 1.0),
                strength: 6.0,
                shadow: true,
            },

            front_tint: Color::rgb(0.7, 0.25, 0.2),
            front_roughness: 0.4,
            front_metallic: 0.0,
            shading_map_on: true,
            relief_map_on: true,
            emissive_map_on: true,

            exposure: START_EXPOSURE,
            bloom: START_BLOOM,
        })
    }

    /// This frame's forward direction, from `yaw` (turning around the
    /// world's own up) and `pitch` (turning up or down).
    fn forward(&self) -> Vec3 {
        Vec3::new(
            -self.pitch.cos() * self.yaw.sin(),
            self.pitch.sin(),
            -self.pitch.cos() * self.yaw.cos(),
        )
    }

    /// The camera this frame draws from: `eye` looking along `forward`.
    fn camera(&self) -> Camera {
        Camera::new(
            View::look_at(self.eye, self.eye + self.forward()),
            Projection::perspective(CAMERA_FOV),
        )
    }

    /// A held `Move::Look` (the right mouse button) turns the camera by
    /// the pointer's own motion, the same way it moves: dragging right
    /// turns the view right and left turns it left, dragging down turns
    /// it to look further down at the scene, dragging up back toward the
    /// horizon. `W`/`A`/`S`/`D` move along the view and to its side,
    /// `Space`/`Left Shift` up and down, and the wheel scales how far
    /// each move goes. The `eye` is held above the ground plane wherever
    /// it moves.
    fn fly_camera(&mut self, ctx: &mut FrameContext<'_, Self>) {
        if !ctx.ui_wants_pointer() && ctx.down(Move::Look) {
            let look = ctx.axis2(Turn::Look);
            self.yaw -= look.x;
            self.pitch = (self.pitch + look.y).clamp(-PITCH_LIMIT, PITCH_LIMIT);
        }

        let wheel = ctx.axis(Speed::Wheel);
        if !ctx.ui_wants_pointer() && wheel != 0.0 {
            self.speed_scale =
                (self.speed_scale * SPEED_STEP.powf(wheel)).clamp(MIN_SPEED_SCALE, MAX_SPEED_SCALE);
        }

        let forward = self.forward();
        let right = Vec3::new(self.yaw.cos(), 0.0, -self.yaw.sin());
        let mut move_by = Vec3::ZERO;
        if ctx.down(Move::Forward) {
            move_by += forward;
        }
        if ctx.down(Move::Back) {
            move_by -= forward;
        }
        if ctx.down(Move::Right) {
            move_by += right;
        }
        if ctx.down(Move::Left) {
            move_by -= right;
        }
        if ctx.down(Move::Up) {
            move_by += Vec3::Y;
        }
        if ctx.down(Move::Down) {
            move_by -= Vec3::Y;
        }
        if move_by.length_squared() > 1.0 {
            move_by = move_by.normalize();
        }

        self.eye += move_by * MOVE_SPEED * self.speed_scale * ctx.dt().as_secs_f32();
        self.eye.y = self.eye.y.max(MIN_EYE_HEIGHT);
    }

    /// The material [`Front`] draws with, resolved new from its sliders
    /// every frame — the override [`Instance::material`] takes, in place
    /// of a baked one.
    fn front_material(&self) -> Material {
        Material::lit(self.front_tint)
            .roughness(self.front_roughness)
            .metallic(self.front_metallic)
    }

    /// Every draw this game makes: the ground, each map pair, the front
    /// sphere, the reflection row and the pillars beside it.
    fn draw_scene(&self, ctx: &mut FrameContext<'_, Self>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR).roughness(0.9)),
        );

        Self::draw_pair(
            ctx,
            SHADING_Z,
            SPHERE_RADIUS,
            ShadingPlain.at(Vec3::ZERO).into_set(),
            ShadingMapped.at(Vec3::ZERO).into_set(),
            self.shading_map_on,
        );
        Self::draw_pair(
            ctx,
            RELIEF_Z,
            SPHERE_RADIUS,
            ReliefPlain.at(Vec3::ZERO).into_set(),
            ReliefMapped.at(Vec3::ZERO).into_set(),
            self.relief_map_on,
        );
        Self::draw_pair(
            ctx,
            EMISSIVE_Z,
            CUBE_SIZE / 2.0,
            EmissivePlain.at(Vec3::ZERO).into_set(),
            EmissiveMapped.at(Vec3::ZERO).into_set(),
            self.emissive_map_on,
        );

        ctx.draw(
            Front
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FRONT_SCALE),
                    Quat::IDENTITY,
                    FRONT_POSITION,
                ))
                .material(self.front_material()),
        );

        self.draw_reflect_row(ctx);
        self.draw_outpost(ctx);
    }

    /// One pair at depth `z`, its centers `height` above the ground: `plain`
    /// on the left always, and on the right `mapped` where `mapped_on` is
    /// set, `plain` again where it is not — the same position drawing the
    /// same base material with and without the map.
    fn draw_pair(
        ctx: &mut FrameContext<'_, Self>,
        z: f32,
        height: f32,
        plain: Instance<Shape, Looks>,
        mapped: Instance<Shape, Looks>,
        mapped_on: bool,
    ) {
        ctx.draw(plain.clone().at(Vec3::new(-PAIR_HALF_SPACING, height, z)));
        let right = if mapped_on { mapped } else { plain };
        ctx.draw(right.at(Vec3::new(PAIR_HALF_SPACING, height, z)));
    }

    /// A row of built-in `Sphere` draws at rising roughness, each
    /// `metallic(1.0)` with its tint white, so what draws is the sky's own
    /// reflection alone.
    fn draw_reflect_row(&self, ctx: &mut FrameContext<'_, Self>) {
        let start = -REFLECT_ROW_SPACING * (REFLECT_ROW_COUNT as f32 - 1.0) / 2.0;
        for index in 0..REFLECT_ROW_COUNT {
            let x = start + index as f32 * REFLECT_ROW_SPACING;
            let roughness = index as f32 / (REFLECT_ROW_COUNT as f32 - 1.0);
            ctx.draw(
                Sphere {
                    subdivisions: SPHERE_SUBDIVISIONS,
                }
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(REFLECT_ROW_RADIUS * 2.0),
                    Quat::IDENTITY,
                    Vec3::new(x, REFLECT_ROW_RADIUS, REFLECT_ROW_Z),
                ))
                .material(
                    Material::lit(Color::WHITE)
                        .roughness(roughness)
                        .metallic(1.0),
                ),
            );
        }
    }

    /// Three pillars and a pole a light can shadow, beside `Banner`'s
    /// displaced cloth and `Field`'s pulsing sphere — [`OUTPOST`] moves the
    /// whole group clear of the rest of the scene.
    fn draw_outpost(&self, ctx: &mut FrameContext<'_, Self>) {
        let clock = ctx.elapsed().as_secs_f32();

        for &(position, scale) in &PILLARS {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    scale,
                    Quat::IDENTITY,
                    OUTPOST + position,
                ))
                .material(Material::lit(Color::rgb(0.55, 0.5, 0.45))),
            );
        }

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                POLE_SCALE,
                Quat::IDENTITY,
                OUTPOST + POLE_POSITION,
            ))
            .material(Material::lit(Color::rgb(0.3, 0.24, 0.18))),
        );

        ctx.set_surface_style(Banner { time: clock });
        ctx.draw(
            BannerCloth
                .at(Transform::from_translation(OUTPOST + BANNER_MOUNT))
                .material(Material::lit(Color::rgb(0.75, 0.12, 0.12)))
                .surface_style::<Banner>(),
        );

        ctx.set_surface_style(Field {
            tint: Color::rgb(0.25, 0.75, 1.0),
            time: clock,
        });
        ctx.draw(
            Sphere { subdivisions: 2 }
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FIELD_ORB_SCALE),
                    Quat::IDENTITY,
                    OUTPOST + FIELD_ORB_POSITION,
                ))
                .material(Material::color(Color::BLACK))
                .surface_style::<Field>(),
        );
    }

examples/sprite-adventure.rs (line 586)

    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(POND_SHEET).pixelated())
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A crate prop, its texture drawn over a cube.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Crate;

impl Mesh for Crate {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(CRATE_TEXTURE).pixelated())
    }
}

/// The well's rim.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Well;

impl Mesh for Well {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(WELL_SHEET).pixelated())
    }
}

/// The well's mouth, laid flat over the rim's top face.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct WellMouth;

impl Mesh for WellMouth {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(WELL_SHEET).pixelated())
    }
}

/// A stone box: the mouth's pillars and lintel.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Stone;

impl Mesh for Stone {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(STONE_SHEET).pixelated())
    }
}

/// A bush sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Bush;

impl Mesh for Bush {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(BUSH_SPRITE).pixelated())
            .with_relief(assets.relief(BUSH_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A rock sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Rock;

impl Mesh for Rock {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(ROCK_SPRITE).pixelated())
            .with_relief(assets.relief(ROCK_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A torch's post sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Torch;

impl Mesh for Torch {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(TORCH_SPRITE).pixelated())
            .with_relief(assets.relief(TORCH_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A torch's flame sprite, added over the dark rather than lit.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Flame;

impl Mesh for Flame {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(FLAME_SHEET).pixelated())
            .with_material(Material::color(FLAME_TINT).additive())
    }
}

/// The player's sprite, cutout with its own relief, its sheet shared
/// with `examples/isometric-board.rs`.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Walker;

impl Mesh for Walker {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(WALKER_SHEET).pixelated())
            .with_relief(assets.relief(WALKER_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }

examples/stress-preview.rs (line 399)

    fn draw_ground(ctx: &mut FrameContext<'_, Self>) {
        let side = (FIELD_RADIUS + FIELD_INNER_RADIUS) * 2.2;
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(side, 1.0, side)))
                .material(Material::lit(GROUND_COLOR).roughness(0.9)),
        );
    }

    fn draw_field(&self, ctx: &mut FrameContext<'_, Self>, elapsed: f32) {
        for entry in &self.field {
            let yaw = if self.settings.moving && entry.moving {
                entry.phase + elapsed * MOVING_SPEED
            } else {
                entry.phase
            };
            ctx.draw(
                Rock { seed: entry.seed }.at(Transform::from_scale_rotation_translation(
                    Vec3::ONE,
                    Quat::from_rotation_y(yaw),
                    entry.position,
                )),
            );
        }
    }

    /// How many field items lie in the camera's view at `window_size`:
    /// every item where the field holds at most [`MAX_IN_VIEW_SAMPLES`],
    /// otherwise one item stepped at a time and the count scaled back up
    /// to the whole field; `true` in the second place where the count
    /// came from such a step.
    ///
    /// Each item is tested on the engine's own workers: a parallel iterator
    /// reaches them with nothing configured for it.
    fn count_in_view(&self, camera: &Camera, window_size: UVec2) -> (usize, bool) {
        let stride = (self.field.len() as u32 / MAX_IN_VIEW_SAMPLES).max(1) as usize;
        let tested = self.field.par_iter().step_by(stride);
        let tested_count = self.field.len().div_ceil(stride);
        let in_view = tested
            .filter(|entry| Self::in_view(camera, entry.position, window_size))
            .count();
        let estimate = in_view
            .checked_mul(self.field.len())
            .and_then(|scaled| scaled.checked_div(tested_count))
            .unwrap_or(in_view);
        (estimate, stride > 1)
    }

    /// Whether `position` draws inside `window_size`, the frame's own
    /// bound of what the camera's view holds.
    fn in_view(camera: &Camera, position: Vec3, window_size: UVec2) -> bool {
        camera.pixel_of(position, window_size).is_some_and(|pixel| {
            pixel.x >= 0.0
                && pixel.y >= 0.0
                && pixel.x < window_size.x as f32
                && pixel.y < window_size.y as f32
        })
    }

    /// The load controls, and this frame's own cost, reported below them.
    fn controls(&mut self, ctx: &mut FrameContext<'_, Self>, camera: &Camera) {
        let submitted = self.field.len();
        let seeds = self.applied_seed_count;
        let average_ms = self.frame_times.average_ms();
        let fps = if average_ms > 0.0 {
            1000.0 / average_ms
        } else {
            0.0
        };
        let elapsed = ctx.elapsed().as_secs_f32();
        let (in_view, sampled) = self.count_in_view(camera, ctx.window_size());

        ctx.ui(|ui| {
            egui::Frame::new()
                .fill(egui::Color32::from_gray(24))
                .inner_margin(PANEL_PADDING)
                .corner_radius(f32::from(PANEL_PADDING))
                .show(ui, |ui| {
                    ui.add(
                        egui::Slider::new(
                            &mut self.settings.instance_count,
                            MIN_INSTANCE_COUNT..=MAX_INSTANCE_COUNT,
                        )
                        .text("instance count"),
                    );
                    ui.add(
                        egui::Slider::new(
                            &mut self.settings.seed_count,
                            MIN_SEED_COUNT..=MAX_SEED_COUNT,
                        )
                        .text("distinct seeds"),
                    );
                    ui.checkbox(&mut self.settings.sun_shadow, "sun shadow");
                    ui.checkbox(&mut self.settings.moving, "moving fraction");
                    ui.separator();
                    ui.label(format!("instances submitted {submitted}"));
                    if sampled {
                        ui.label(format!("in view, sampled {in_view}"));
                    } else {
                        ui.label(format!("instances in view {in_view}"));
                    }
                    ui.label(format!("distinct seeds {seeds}"));
                    ui.label(format!("frame time {average_ms:.2}ms, {fps:.0} fps"));
                    ui.label(format!("elapsed {elapsed:.1}s"));
                });
        });
    }
}

/// `instance_count` field values, each drawing one of `seed_count`
/// distinct seed values in a cycle, and scattered from
/// [`FIELD_INNER_RADIUS`] out to [`FIELD_RADIUS`]; each built from an
/// integer-hash of its own index.
fn build_field(instance_count: u32, seed_count: u32) -> Vec<FieldEntry> {
    (0..instance_count)
        .map(|index| {
            let angle = hash_unit(index, 0) * core::f32::consts::TAU;
            let spread = hash_unit(index, 1).sqrt();
            let distance = FIELD_INNER_RADIUS + spread * (FIELD_RADIUS - FIELD_INNER_RADIUS);
            FieldEntry {
                seed: index % seed_count,
                position: Vec3::new(angle.cos() * distance, 0.0, angle.sin() * distance),
                phase: hash_unit(index, 2) * core::f32::consts::TAU,
                moving: index % MOVING_STRIDE == 0,
            }
        })
        .collect()
}

/// A rock built from `seed`: a cone of [`ROCK_SIDES`] sides, each base
/// corner and the apex height displaced by an integer-hash of `seed`.
fn build_rock(seed: u32) -> MeshData {
    let height = ROCK_HEIGHT * (1.0 + hash_signed(seed, ROCK_SIDES) * ROCK_HEIGHT_DISPLACEMENT);
    let apex = Vec3::Y * height;
    let base: Vec<Vec3> = (0..ROCK_SIDES)
        .map(|corner| {
            let angle = core::f32::consts::TAU * corner as f32 / ROCK_SIDES as f32;
            let radius =
                ROCK_BASE_RADIUS * (1.0 + hash_signed(seed, corner) * ROCK_RADIAL_DISPLACEMENT);
            Vec3::new(angle.cos() * radius, 0.0, angle.sin() * radius)
        })
        .collect();

    let mut vertices = Vec::with_capacity(base.len() * 6);
    let mut indices = Vec::with_capacity(base.len() * 6);
    for corner in 0..base.len() {
        let next = (corner + 1) % base.len();
        push_face(&mut vertices, &mut indices, base[corner], apex, base[next]);
        push_face(
            &mut vertices,
            &mut indices,
            base[corner],
            base[next],
            Vec3::ZERO,
        );
    }

    MeshData::new(vertices, indices).with_material(Material::lit(ROCK_COLOR))
}

examples/flock-parallelism.rs (line 668)

    fn draw_ground(ctx: &mut FrameContext<'_, Self>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR).roughness(0.9)),
        );
    }

    /// Every butterfly at its own scale, turned to face its velocity, posed
    /// by the flap machine of its own group and tinted its own color.
    fn draw_butterflies(&self, ctx: &mut FrameContext<'_, Self>) {
        for (position, velocity, kind) in self.butterflies.each() {
            let rotation = Quat::from_rotation_arc(Vec3::Z, Vec3::from(velocity).normalize());
            ctx.draw(
                Butterfly
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(BUTTERFLY_SCALE),
                        rotation,
                        Vec3::from(position),
                    ))
                    .posed(&self.flaps[usize::from(kind.flap)])
                    .material(Material::lit(TINTS[usize::from(kind.tint)])),
            );
        }
    }

examples/breakout-game.rs (line 601)

    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)),
        );
    }

examples/ui-fonts.rs (line 664)

    fn draw_station(&self, ctx: &mut FrameContext<'_, Self>, station: StationKind) {
        let look = station.look();
        let center = station.center();
        let front_offset =
            STATION_SIZE.z * 0.5 - STATION_FRONT_SIZE.z * 0.5 + STATION_FRONT_OUTWARD;
        let front = center - Vec3::new(0.0, 0.0, front_offset);
        for (size, position, material) in [
            (STATION_SIZE, center, Material::lit(look.color)),
            (
                STATION_FRONT_SIZE,
                front,
                Material::color(Color::BLACK).emissive(look.glow),
            ),
        ] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    size,
                    Quat::IDENTITY,
                    position,
                ))
                .material(material),
            );
        }
    }

    fn draw_bracket(&self, ctx: &mut FrameContext<'_, Self>, camera: Camera, station: StationKind) {
        let top = station.center() + Vec3::Y * (STATION_SIZE.y * 0.5);
        let window_size = ctx.window_size();
        let Some(pixel) = camera.pixel_of(top, window_size) else {
            return;
        };
        let at = logical(pixel, ctx.pixels_per_point());

        let name = ctx.text_layout(station.look().name, egui::FontId::proportional(BODY_SIZE));
        let (reading_text, number_text) = station.reading(self.elapsed.as_secs_f32());
        let reading = ctx.text_layout(&reading_text, egui::FontId::monospace(BODY_SIZE));
        let number = ctx.text_layout(
            &number_text,
            egui::FontId::new(NUMBER_SIZE, egui::FontFamily::Name(DISPLAY_FAMILY.into())),
        );

        ctx.ui(|ui| bracket(ui.painter(), at, name, reading, number));
    }

    /// A `Prompt` for `Trigger::Hail`, above every `StationKind` but
    /// `hovered`: what a player presses to reach one, apart from a hover.
    fn draw_prompts(
        &self,
        ctx: &mut FrameContext<'_, Self>,
        camera: Camera,
        hovered: Option<StationKind>,
    ) {
        let Some(binding) = ctx.bindings(Trigger::Hail).into_iter().next() else {
            return;
        };
        let hint = prompt(&binding);
        let glyph = ctx.text_layout(&hint.text(), egui::FontId::new(PROMPT_SIZE, hint.family()));
        let window_size = ctx.window_size();
        let pixels_per_point = ctx.pixels_per_point();

        ctx.ui(|ui| {
            let painter = ui.painter();
            for station in StationKind::ALL {
                if Some(station) == hovered {
                    continue;
                }
                let top = station.center() + Vec3::Y * (STATION_SIZE.y * 0.5);
                let Some(pixel) = camera.pixel_of(top, window_size) else {
                    continue;
                };
                let at = logical(pixel, pixels_per_point);
                let at = egui::pos2(at.x, at.y - PROMPT_LIFT);
                prompt_at(painter, at, glyph.clone());
            }
        });
    }

    /// The title, a line and the reading, each in a font this game loaded
    /// rather than egui's own.
    fn panel(&self, ctx: &mut FrameContext<'_, Self>) {
        ctx.ui(|ui| {
            ui.label(styled(
                "a game's own fonts",
                egui::FontId::proportional(HEADING_SIZE),
            ));
            ui.label(styled(
                "drawn in Pixel Operator, the game's proportional font",
                egui::FontId::proportional(BODY_SIZE),
            ));
            ui.label(styled(
                "the readings above each station in Pixel Operator Mono",
                egui::FontId::monospace(BODY_SIZE),
            ));
        });
    }

    fn draw_dialogue(&self, ctx: &mut FrameContext<'_, Self>) {
        let Some(dialogue) = &self.dialogue else {
            return;
        };
        let whole = ctx.text_layout(
            dialogue.current_line(),
            egui::FontId::proportional(BODY_SIZE),
        );
        let size = whole.size();
        ctx.ui(|ui| dialogue.draw(ui, size));
    }

    /// The `StationKind` under the pointer, `None` while the UI holds it.
    fn hovered(ctx: &FrameContext<'_, Self>) -> Option<StationKind> {
        if ctx.ui_wants_pointer() {
            return None;
        }
        hit_station(
            ctx.last_camera()
                .ray_through(ctx.pointer(), ctx.window_size()),
        )
    }

    /// A held [`Trigger::Hail`] turns the camera by the pointer's own
    /// motion; the wheel zooms it.
    fn steer(&mut self, ctx: &mut FrameContext<'_, Self>) {
        if !ctx.ui_wants_pointer() && ctx.down(Trigger::Hail) {
            self.orbit.turn(ctx.axis2(Turn::Look));
        }
        let wheel = ctx.axis(Zoom::Wheel);
        if !ctx.ui_wants_pointer() && wheel != 0.0 {
            self.orbit.zoom(ZOOM_STEP.powf(wheel));
        }
    }
}

impl Game for WatchRoom {
    type Meshes = Shape;
    type Sounds = NoSounds;
    type InputActions = Controls;
    type Skyboxes = Sky;
    type SurfaceStyles = NoSurfaceStyles;
    type PostEffects = NoPostEffects;

    fn tick(&mut self, ctx: &mut TickContext<'_, Self>) {
        self.elapsed += ctx.dt();
        self.orbit.yaw += AUTO_TURN_RATE * ctx.dt().as_secs_f32();

        if let Some(dialogue) = &mut self.dialogue {
            dialogue.tick();
        }
        if ctx.pressed(Trigger::Close) {
            self.dialogue = None;
            self.hailed = None;
        }
        if ctx.pressed(Trigger::Sheet) {
            self.sheet_open = !self.sheet_open;
        }
        if ctx.pressed(Trigger::Hail) && !ctx.ui_wants_pointer() {
            self.handle_hail(ctx);
        }
    }

    fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
        self.steer(ctx);

        let camera = self.orbit.camera();
        ctx.set_camera(camera);
        ctx.set_skybox(Sky::Dusk);
        ctx.light(Light::directional(SUN_DIRECTION, SUN_COLOR).shadow());

        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    PLATFORM_SIZE,
                    1.0,
                    PLATFORM_SIZE,
                )))
                .material(Material::lit(PLATFORM_COLOR)),
        );
        for station in StationKind::ALL {
            self.draw_station(ctx, station);
        }

        let hovered = Self::hovered(ctx);
        if !self.sheet_open {
            if let Some(station) = hovered {
                ctx.set_cursor(Cursor::Pointer);
                self.draw_bracket(ctx, camera, station);
            }
            self.draw_prompts(ctx, camera, hovered);
        }
        if self.dialogue.is_some() {
            self.draw_dialogue(ctx);
        }
        if self.sheet_open {
            ctx.ui(sheet);
        }
        self.panel(ctx);
    }

Additional examples can be found in:

• examples/post-effects.rs
• examples/isometric-board.rs
• examples/sound-lab.rs
• examples/animation.rs

pub fn shaded(color: Color, litness: f32) -> Self

A color between flat and lit by litness, a fraction clamped to 0.0..=1.0.

Examples found in repository

examples/breakout-game.rs (line 654)

    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)),
            );
        }
    }

examples/sprite-adventure.rs (line 1305)

    fn draw_pond(&self, ctx: &mut FrameContext<'_, Keep>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(POND_WATER_HALF * 2.0),
                    Quat::IDENTITY,
                    POND_CENTER,
                ))
                .material(Material::shaded(WATER_COLOR, WATER_LITNESS))
                .surface_style::<Water>(),
        );
        ctx.draw(
            Shore
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(POND_HALF * 2.0),
                    Quat::IDENTITY,
                    Vec3::new(POND_CENTER.x, 0.0, POND_CENTER.z),
                ))
                .frame(Sheet::new(UVec2::new(POND_CELLS, 1)).cell(POND_SHORE_CELL)),
        );
    }

    fn draw_crates(&self, ctx: &mut FrameContext<'_, Keep>) {
        for &(x, z, turn) in &CRATE_POSITIONS {
            ctx.draw(Crate.at(Transform::from_scale_rotation_translation(
                Vec3::splat(CRATE_SIZE),
                Quat::from_rotation_y(turn),
                Vec3::new(x, CRATE_SIZE * 0.5, z),
            )));
        }
    }

    /// The well: its rim in grey masonry, and the mouth cell laid over the
    /// rim's top face.
    fn draw_well(&self, ctx: &mut FrameContext<'_, Keep>) {
        let cells = Sheet::new(UVec2::new(WELL_CELLS, 1));
        ctx.draw(
            Well.at(Transform::from_scale_rotation_translation(
                WELL_SIZE,
                Quat::IDENTITY,
                WELL_POSITION + Vec3::Y * (WELL_SIZE.y * 0.5),
            ))
            .frame(cells.cell(WELL_RIM_CELL)),
        );
        ctx.draw(
            WellMouth
                .at(Transform::from_scale_rotation_translation(
                    Vec3::new(WELL_SIZE.x, 1.0, WELL_SIZE.z),
                    Quat::IDENTITY,
                    WELL_POSITION + Vec3::Y * (WELL_SIZE.y + WELL_MOUTH_LIFT),
                ))
                .frame(cells.cell(WELL_MOUTH_CELL)),
        );
    }

    fn draw_flora(&self, ctx: &mut FrameContext<'_, Keep>) {
        for &(x, z, rock) in &FLORA {
            let (width, height) = if rock {
                (ROCK_WIDTH, ROCK_HEIGHT)
            } else {
                (BUSH_WIDTH, BUSH_HEIGHT)
            };
            let standing = Transform::from_scale_rotation_translation(
                Vec3::new(width, height, width),
                Quat::IDENTITY,
                Vec3::new(x, height * 0.5, z),
            );
            let flora: Instance<Shape, _> = if rock {
                Rock.at(standing).into_set()
            } else {
                Bush.at(standing).into_set()
            };
            ctx.draw(flora.upright());
        }
    }

    /// One stone box drawn on the ground at `at`, `size` across, sampling
    /// the part of the sheet `frame` covers.
    fn draw_stone(ctx: &mut FrameContext<'_, Keep>, at: Vec3, size: Vec3, frame: Frame) {
        ctx.draw(
            Stone
                .at(Transform::from_scale_rotation_translation(
                    size,
                    Quat::IDENTITY,
                    at + Vec3::Y * (size.y * 0.5),
                ))
                .frame(frame),
        );
    }

    /// Two stone pillars drawn where `mouth` blocks the player, each a
    /// capital over its own course of masonry, and, on the one the camera
    /// looks into, the lintel across their tops and the dark filling
    /// the opening under it.
    fn draw_mouth(ctx: &mut FrameContext<'_, Keep>, mouth: Mouth) {
        for at in mouth.pillars() {
            Self::draw_stone(ctx, at, MOUTH_PILLAR_SIZE, Frame::default());
        }
        if !mouth.looked_into() {
            return;
        }

        Self::draw_stone(
            ctx,
            mouth.at + Vec3::Y * MOUTH_PILLAR_SIZE.y,
            MOUTH_LINTEL_SIZE,
            masonry(MOUTH_LINTEL_TILES),
        );
        ctx.draw(
            Quad.at(Transform::from_scale_rotation_translation(
                Vec3::new(MOUTH_PILLAR_OFFSET * 2.0, MOUTH_DARK_HEIGHT, 1.0),
                Quat::IDENTITY,
                mouth.at + Vec3::Y * (MOUTH_DARK_HEIGHT * 0.5),
            ))
            .material(Material::color(Color::BLACK)),
        );
    }

    fn draw_cave_floor(&self, ctx: &mut FrameContext<'_, Keep>) {
        let half = CAVE_HALF_WIDTH as i32;
        let near = CAVE_NEAR_Z as i32;
        let far = CAVE_FAR_Z as i32;
        for col in -half..=half {
            for row in far..=near {
                let variant = (col * 13 + row * 7).rem_euclid(CAVE_COLUMNS as i32) as u32;
                ctx.draw(
                    CaveFloor
                        .at(Vec3::new(
                            col as f32 * TILE_SIZE,
                            0.0,
                            row as f32 * TILE_SIZE,
                        ))
                        .frame(
                            Sheet::new(UVec2::new(CAVE_COLUMNS, CAVE_ROWS))
                                .cell_at(UVec2::new(variant, CAVE_FLOOR_ROW)),
                        ),
                );
            }
        }
    }

    /// The wall drawn at `at` over the meters `standing`, in courses
    /// [`WALL_HEIGHT`] tall from the floor up, each cut to the part of it the
    /// span leaves; its faces are picked by `seed` and its stone faded to
    /// `fade`, which is `1.0` wherever it is solid.
    fn draw_wall(
        ctx: &mut FrameContext<'_, Keep>,
        at: Vec2,
        standing: Range<f32>,
        seed: i32,
        fade: f32,
    ) {
        for course in 0..WALL_COURSES {
            let base = course as f32 * WALL_HEIGHT;
            let low = (standing.start - base).max(0.0);
            let high = (standing.end - base).min(WALL_HEIGHT);
            if high <= low {
                continue;
            }

            let variant = (seed + course).rem_euclid(CAVE_COLUMNS as i32) as u32;
            ctx.draw(
                CaveWall
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::new(TILE_SIZE, high - low, TILE_SIZE),
                        Quat::IDENTITY,
                        Vec3::new(at.x, base + (low + high) * 0.5, at.y),
                    ))
                    .frame(cave_wall_face(variant, low..high))
                    .faded(fade),
            );
        }
    }

    /// The room's two side walls and its back wall, full height, and the low
    /// wall closing its near end between the side walls and the mouth. The
    /// back wall stops short of the corners the side walls already fill, and
    /// the near one leaves the mouth's own tile open.
    fn draw_cave_walls(&self, ctx: &mut FrameContext<'_, Keep>) {
        let half = CAVE_HALF_WIDTH as i32 + 1;
        let near = CAVE_NEAR_Z as i32;
        let far = CAVE_FAR_Z as i32;

        for row in far..=near {
            let z = row as f32 * TILE_SIZE;
            let west = Vec2::new(-half as f32 * TILE_SIZE, z);
            let east = Vec2::new(half as f32 * TILE_SIZE, z);
            Self::draw_wall(ctx, west, 0.0..WALL_TOP, row * 5, SOLID);
            Self::draw_wall(ctx, east, 0.0..WALL_TOP, row * 5 + 1, SOLID);
        }
        for col in (-half + 1)..half {
            let x = col as f32 * TILE_SIZE;
            let back = Vec2::new(x, far as f32 * TILE_SIZE);
            Self::draw_wall(ctx, back, 0.0..WALL_TOP, col * 5 + 2, SOLID);
            if col != 0 {
                let lip = Vec2::new(x, CAVE_LIP_Z);
                Self::draw_wall(ctx, lip, 0.0..CAVE_LIP_HEIGHT, col * 5 + 4, SOLID);
            }
        }
    }

    /// The wall the door hangs in, run across the room between the side walls
    /// with one tile left open on the room's axis for the doorway and stone
    /// filling the column over the door. A player behind the wall is drawn
    /// through the stacks between them and the camera, at `seen_through`,
    /// faded by `ghost`; the rest of it stays solid, and keeps casting.
    fn draw_door_wall(ctx: &mut FrameContext<'_, Keep>, seen_through: Option<f32>, ghost: f32) {
        let stone = |x: f32| match seen_through {
            Some(at) if (x - at).abs() < GHOST_CORRIDOR_HALF => ghost_alpha(ghost),
            _ => SOLID,
        };
        let half = CAVE_HALF_WIDTH as i32;

        for col in (-half..=half).filter(|&col| col != 0) {
            let x = col as f32 * TILE_SIZE;
            Self::draw_wall(
                ctx,
                Vec2::new(x, DOOR_Z),
                0.0..WALL_TOP,
                col * 5 + 3,
                stone(x),
            );
        }
        Self::draw_wall(
            ctx,
            Vec2::new(0.0, DOOR_Z),
            DOOR_HEIGHT..WALL_TOP,
            3,
            stone(0.0),
        );
    }

    /// The two torches: an upright cutout post apiece, the flame's loop
    /// burning over its binding, and the light that flame casts.
    fn draw_torches(&self, ctx: &mut FrameContext<'_, Keep>) {
        let elapsed = self.simulated.as_secs_f32();
        let loop_cells = Sheet::new(UVec2::new(FLAME_CELLS, 1));

        for (index, &(x, z)) in TORCH_POSITIONS.iter().enumerate() {
            let base = Vec3::new(x, 0.0, z);
            ctx.draw(
                Torch
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::new(TORCH_SPRITE_WIDTH, TORCH_STAND_HEIGHT, 1.0),
                        Quat::IDENTITY,
                        base + Vec3::Y * (TORCH_STAND_HEIGHT * 0.5),
                    ))
                    .upright(),
            );

            let phase = index as f32 * 2.1;
            let flicker = (elapsed * FLAME_FLICKER_SPEED + phase).sin();
            let flame_pos =
                base + Vec3::Y * (TORCH_STAND_HEIGHT + FLAME_LIFT + flicker * FLAME_BOB);

            let light_pos = flame_pos + Vec3::new(0.0, TORCH_LIGHT_LIFT, TORCH_LIGHT_STANDOFF);
            ctx.light(Light::point(light_pos, TORCH_LIGHT_COLOR, TORCH_LIGHT_RANGE).shadow());
            // The pair burn an even share of the loop apart.
            let offset = index as u32 * FLAME_CELLS / TORCH_POSITIONS.len() as u32;
            ctx.draw(
                Flame
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(FLAME_SIZE),
                        Quat::IDENTITY,
                        flame_pos,
                    ))
                    .billboard()
                    .roll(flicker * FLAME_ROLL)
                    .frame(loop_cells.cell((elapsed * FLAME_RATE) as u32 + offset)),
            );
        }
    }

    /// The door at its hinge — swung back against the wall once opened —
    /// drawn through alongside its wall, faded by `ghost`.
    fn draw_door(&self, ctx: &mut FrameContext<'_, Keep>, ghost: f32) {
        let fade = ghost_alpha(ghost);
        let swung = if self.door_opening {
            Quat::from_rotation_y(core::f32::consts::FRAC_PI_2)
        } else {
            Quat::IDENTITY
        };

        ctx.draw(
            Door.at(Transform::from_rotation_translation(swung, DOOR_HINGE))
                .material(Material::shaded(DOOR_COLOR, DOOR_LITNESS))
                .faded(fade),
        );
    }

    /// The posts and lintel framing the doorway, in a color the stone never
    /// is, standing clear of the wall so the opening reads as a door from
    /// across the chamber. Glowing of their own while the door is closed and
    /// within [`INTERACT_RADIUS`], the cue that it opens.
    fn draw_door_frame(&self, ctx: &mut FrameContext<'_, Keep>, ghost: f32) {
        let reachable =
            !self.door_opening && self.position.distance(INTERACT_POINT) < INTERACT_RADIUS;
        let material =
            Material::shaded(DOOR_FRAME_COLOR, DOOR_FRAME_LITNESS).emissive(if reachable {
                DOOR_FRAME_GLOW
            } else {
                Color::BLACK
            });
        let fade = ghost_alpha(ghost);
        let z = DOOR_WALL_NEAR_Z + DOOR_FRAME_STANDOFF;
        let jamb_height = DOOR_HEIGHT + DOOR_FRAME_THICKNESS;

        for side in SIDES {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::new(DOOR_FRAME_THICKNESS, jamb_height, DOOR_FRAME_THICKNESS),
                    Quat::IDENTITY,
                    Vec3::new(
                        side * (DOORWAY_HALF + DOOR_FRAME_THICKNESS * 0.5),
                        jamb_height * 0.5,
                        z,
                    ),
                ))
                .material(material)
                .faded(fade),
            );
        }
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(
                    DOOR_WIDTH + DOOR_FRAME_THICKNESS * 2.0,
                    DOOR_FRAME_THICKNESS,
                    DOOR_FRAME_THICKNESS,
                ),
                Quat::IDENTITY,
                Vec3::new(0.0, DOOR_HEIGHT + DOOR_FRAME_THICKNESS * 0.5, z),
            ))
            .material(material)
            .faded(fade),
        );
    }

    /// A world prompt over the door: what opens it while the player is
    /// within [`INTERACT_RADIUS`] and it is closed, and that it swings while
    /// it does; gone once it has swung [`DOOR_SWING_TICKS`]. Laid out and
    /// placed like `examples/animation.rs`'s own prompt.
    fn draw_door_prompt(&self, ctx: &mut FrameContext<'_, Keep>, camera: Camera) {
        let near = self.position.distance(INTERACT_POINT) < INTERACT_RADIUS;
        let swinging = self.door_opening && self.swing_ticks < DOOR_SWING_TICKS;
        let text = if swinging {
            "opening"
        } else if near && !self.door_opening {
            "e opens the door"
        } else {
            return;
        };

        let galley = ctx.text_layout(text, egui::FontId::proportional(DOOR_PROMPT_SIZE));
        let point = INTERACT_POINT + Vec3::Y * (DOOR_HEIGHT + DOOR_PROMPT_LIFT);
        let window_size = ctx.window_size();
        let pixels_per_point = ctx.pixels_per_point();
        let Some(pixel) = camera.pixel_of(point, window_size) else {
            return;
        };

        ctx.ui(|ui| {
            let painter = ui.painter();
            let at = logical(pixel, pixels_per_point);
            let ink = galley.mesh_bounds;
            let pos = egui::pos2(at.x - ink.center().x, at.y - ink.center().y);
            let backdrop = egui::Rect::from_center_size(
                at,
                ink.size() + egui::Vec2::splat(DOOR_PROMPT_PADDING * 2.0),
            );
            painter.rect_filled(
                backdrop,
                DOOR_PROMPT_PADDING,
                egui::Color32::from_black_alpha(DOOR_PROMPT_BACKDROP),
            );
            painter.galley(pos, galley, DOOR_PROMPT_COLOR);
        });
    }

    /// The gem, spinning and bobbing over the chamber's floor, and the light
    /// it casts over it.
    fn draw_gem(&self, ctx: &mut FrameContext<'_, Keep>) {
        let t = self.simulated.as_secs_f32();
        let bob = (t * 2.0).sin() * GEM_BOB_HEIGHT;
        ctx.light(
            Light::point(
                GEM_POSITION + Vec3::Y * (bob + GEM_LIGHT_LIFT),
                GEM_LIGHT_COLOR,
                GEM_LIGHT_RANGE,
            )
            .shadow(),
        );
        ctx.draw(
            Gem.at(Transform::from_scale_rotation_translation(
                Vec3::ONE,
                Quat::from_rotation_y(t * GEM_SPIN_SPEED),
                GEM_POSITION + Vec3::Y * bob,
            ))
            .material(Material::shaded(GEM_COLOR, 0.7).emissive(GEM_COLOR.dimmed(1.6))),
        );
    }

examples/sound-lab.rs (line 577)

    fn draw_sources(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        for (index, source) in self.sources.iter().enumerate() {
            let color = SOURCE_COLORS[index];
            let picked_up = self.dragging == Some(index);
            let scale = if picked_up { 1.3 } else { 1.0 };
            let emissive = if source.enabled {
                Color::rgb(color.red * 3.0, color.green * 3.0, color.blue * 3.0)
            } else {
                color.dimmed(0.15)
            };

            for (radius, ring_color) in [
                (source.range, RANGE_COLOR),
                (source.reference, REFERENCE_COLOR),
            ] {
                ctx.draw(
                    Ring.at(Transform::from_scale_rotation_translation(
                        Vec3::new(radius, 1.0, radius),
                        Quat::IDENTITY,
                        Vec3::new(source.position.x, 0.01, source.position.z),
                    ))
                    .material(Material::color(ring_color)),
                );
            }
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0 * scale),
                    Quat::IDENTITY,
                    source.position,
                ))
                .material(Material::shaded(color, 0.6).emissive(emissive)),
            );
        }
    }

pub const fn emissive(self, color: Color) -> Self

Adds light of its own to the surface; Color::BLACK by default.

Required if you want a surface bright on its own: values past 1.0 are what FrameContext::set_bloom spreads. In the transparent pass the tint’s alpha scales everything the surface draws, this light too — fade one or the other, not both.

Examples found in repository

examples/material-playground.rs (line 300)

fn emissive_material() -> Material {
    Material::color(EMISSIVE_BASE).emissive(EMISSIVE_GLOW)
}

examples/breakout-game.rs (line 601)

    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 = NoSurfaceStyles;
    type PostEffects = NoPostEffects;

    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);
    }

examples/ui-fonts.rs (line 668)

    fn draw_station(&self, ctx: &mut FrameContext<'_, Self>, station: StationKind) {
        let look = station.look();
        let center = station.center();
        let front_offset =
            STATION_SIZE.z * 0.5 - STATION_FRONT_SIZE.z * 0.5 + STATION_FRONT_OUTWARD;
        let front = center - Vec3::new(0.0, 0.0, front_offset);
        for (size, position, material) in [
            (STATION_SIZE, center, Material::lit(look.color)),
            (
                STATION_FRONT_SIZE,
                front,
                Material::color(Color::BLACK).emissive(look.glow),
            ),
        ] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    size,
                    Quat::IDENTITY,
                    position,
                ))
                .material(material),
            );
        }
    }

examples/isometric-board.rs (line 604)

    fn draw_sprite(&self, ctx: &mut FrameContext<'_, Board>, hover: Hover) {
        let position = self.sprite.previous.lerp(self.sprite.position, ctx.alpha());
        let current = self.turn == Turn::Sprite;
        let (tint, glow) = if current && self.selected {
            (SELECTED_TINT, SELECTED_GLOW)
        } else if current && hover == Hover::CurrentUnit {
            (HOVER_TINT, HOVER_GLOW)
        } else if current {
            (TURN_TINT, TURN_GLOW)
        } else {
            (Color::WHITE, Color::BLACK)
        };
        ctx.draw(
            Sprite
                .at(Transform::from_scale_rotation_translation(
                    Vec3::new(SPRITE_WIDTH, SPRITE_HEIGHT, 1.0),
                    Quat::IDENTITY,
                    position,
                ))
                .upright()
                .frame(sprite_frame(self.sprite.facing_right))
                .material(Material::lit(tint).cutout().emissive(glow)),
        );
    }

    fn draw_block(&self, ctx: &mut FrameContext<'_, Board>, hover: Hover) {
        let position = self.block.previous.lerp(self.block.position, ctx.alpha());
        let current = self.turn == Turn::Block;
        let (color, glow) = if current && self.selected {
            (SELECTED_TINT, SELECTED_GLOW)
        } else if current && hover == Hover::CurrentUnit {
            (HOVER_TINT, HOVER_GLOW)
        } else if current {
            (BLOCK_TURN, TURN_GLOW)
        } else {
            (BLOCK_IDLE, Color::BLACK)
        };
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::splat(BLOCK_SIZE),
                Quat::IDENTITY,
                position,
            ))
            .material(Material::lit(color).emissive(glow)),
        );
    }

examples/post-effects.rs (line 108)

    fn draw_scene(&self, ctx: &mut FrameContext<'_, Self>) {
        ctx.light(Light::directional(SUN_DIRECTION, SUN_COLOR).shadow());

        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR)),
        );
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::splat(GLOW_SIZE),
                Quat::IDENTITY,
                GLOW_POSITION,
            ))
            .material(Material::color(Color::BLACK).emissive(GLOW_COLOR)),
        );
        for position in SPHERE_POSITIONS {
            ctx.draw(
                Sphere {
                    subdivisions: SPHERE_SUBDIVISIONS,
                }
                .at(position)
                .material(Material::lit(SPHERE_COLOR)),
            );
        }
    }

examples/sound-lab.rs (line 577)

    fn draw_sources(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        for (index, source) in self.sources.iter().enumerate() {
            let color = SOURCE_COLORS[index];
            let picked_up = self.dragging == Some(index);
            let scale = if picked_up { 1.3 } else { 1.0 };
            let emissive = if source.enabled {
                Color::rgb(color.red * 3.0, color.green * 3.0, color.blue * 3.0)
            } else {
                color.dimmed(0.15)
            };

            for (radius, ring_color) in [
                (source.range, RANGE_COLOR),
                (source.reference, REFERENCE_COLOR),
            ] {
                ctx.draw(
                    Ring.at(Transform::from_scale_rotation_translation(
                        Vec3::new(radius, 1.0, radius),
                        Quat::IDENTITY,
                        Vec3::new(source.position.x, 0.01, source.position.z),
                    ))
                    .material(Material::color(ring_color)),
                );
            }
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0 * scale),
                    Quat::IDENTITY,
                    source.position,
                ))
                .material(Material::shaded(color, 0.6).emissive(emissive)),
            );
        }
    }

Additional examples can be found in:

• examples/sprite-adventure.rs
• examples/animation.rs

pub fn roughness(self, roughness: f32) -> Self

The surface’s roughness, a fraction clamped to 0.0..=1.0 and 1.0 by default: the factor a .glb material declares, held per draw.

Examples found in repository

examples/material-playground.rs (line 292)

fn shading_material() -> Material {
    Material::lit(SHADING_TINT).roughness(0.5).metallic(0.5)
}

fn relief_material() -> Material {
    Material::lit(RELIEF_TINT).roughness(0.35)
}

fn emissive_material() -> Material {
    Material::color(EMISSIVE_BASE).emissive(EMISSIVE_GLOW)
}

/// A shading map whose checker goes between low occlusion, roughness and
/// metallic and full occlusion, roughness and metallic, so all three read
/// apart across [`ShadingMapped`].
fn shading_checker() -> ShadingData {
    ShadingData::rgba8(
        MAP_SIZE,
        checker_pixels(MAP_SIZE, SHADING_CELL, SHADING_LOW, SHADING_HIGH),
    )
}

/// An emissive map whose checker goes between full glow and none, so
/// [`EMISSIVE_GLOW`] shapes across [`EmissiveMapped`] instead of casting
/// whole.
fn emissive_checker() -> TextureData {
    TextureData::rgba8(
        MAP_SIZE,
        checker_pixels(MAP_SIZE, EMISSIVE_CELL, [0, 0, 0], [255, 255, 255]),
    )
}

fn checker_pixels(size: UVec2, cell: u32, low: [u8; 3], high: [u8; 3]) -> Vec<u8> {
    let mut pixels = Vec::with_capacity((size.x * size.y * 4) as usize);
    for y in 0..size.y {
        for x in 0..size.x {
            let on = ((x / cell) + (y / cell)).is_multiple_of(2);
            let [red, green, blue] = if on { high } else { low };
            pixels.extend_from_slice(&[red, green, blue, u8::MAX]);
        }
    }
    pixels
}

/// A relief whose normals turn across a wave that repeats over the map:
/// each texel's slope comes from the partial derivatives of a
/// `sin(u) * sin(v)` height field at `BUMP_SLOPE`'s peak, computed at that
/// texel and not sampled from any other.
fn relief_bumps() -> ReliefData {
    let size = MAP_SIZE;
    let turns = core::f32::consts::TAU * BUMP_WAVES;
    let mut pixels = Vec::with_capacity((size.x * size.y * 4) as usize);
    for y in 0..size.y {
        for x in 0..size.x {
            let u = (x as f32 + 0.5) / size.x as f32;
            let v = (y as f32 + 0.5) / size.y as f32;
            let slope_u = BUMP_SLOPE * (turns * u).cos() * (turns * v).sin();
            let slope_v = BUMP_SLOPE * (turns * u).sin() * (turns * v).cos();
            let normal = Vec3::new(-slope_u, -slope_v, 1.0).normalize();
            let encode = |signed: f32| ((signed * 0.5 + 0.5) * 255.0).round() as u8;
            pixels.extend_from_slice(&[encode(normal.x), encode(normal.y), encode(normal.z), 0]);
        }
    }
    ReliefData::normals(size, pixels)
}

/// `BannerCloth`'s vertices and indices, built twice over: the columns as
/// authored, facing `+Z`, and the same columns again facing `-Z`, their
/// triangles in the other order so both draw front side out.
fn banner_mesh() -> MeshData {
    let mut vertices = Vec::with_capacity(((BANNER_COLUMNS + 1) * 4) as usize);
    for normal in [Vec3::Z, Vec3::NEG_Z] {
        for column in 0..=BANNER_COLUMNS {
            let u = column as f32 / BANNER_COLUMNS as f32;
            let x = u * BANNER_WIDTH;
            for v in [0.0, 1.0] {
                vertices.push(Vertex::new(
                    Vec3::new(x, -v * BANNER_HEIGHT, 0.0),
                    normal,
                    Vec2::new(u, v),
                ));
            }
        }
    }

    let side = BANNER_COLUMNS + 1;
    let mut indices = Vec::with_capacity((BANNER_COLUMNS * 12) as usize);
    for column in 0..BANNER_COLUMNS {
        let top_left = column * 2;
        let bottom_left = top_left + 1;
        let top_right = top_left + 2;
        let bottom_right = top_left + 3;
        indices.extend([
            bottom_left,
            bottom_right,
            top_right,
            bottom_left,
            top_right,
            top_left,
        ]);

        let back = side * 2;
        indices.extend([
            back + top_right,
            back + bottom_right,
            back + bottom_left,
            back + top_left,
            back + top_right,
            back + bottom_left,
        ]);
    }

    MeshData::new(vertices, indices)
}

/// Displaced by a wave that grows away from its `x = 0` edge; casts the
/// shadow of where it was placed, unmoved by its own wave. Its one value
/// is the clock its wave slides on.
#[derive(Default, ShaderValues)]
struct Banner {
    time: f32,
}

impl SurfaceStyle for Banner {
    const PASS: DrawPass = DrawPass::Opaque;
    const DISPLACE: Option<&'static str> = Some(include_str!("material_playground_banner.wgsl"));
}

/// A surface that reads no light of the scene's own: it draws its own
/// pulsing tint, added over what is behind it, through the color it pulses
/// through and the clock the pulse is timed by.
#[derive(Default, ShaderValues)]
struct Field {
    tint: Color,
    time: f32,
}

impl SurfaceStyle for Field {
    const PASS: DrawPass = DrawPass::Additive;
    const SURFACE: Option<&'static str> = Some(include_str!("material_playground_field.wgsl"));
}

surface_styles! { enum Looks { Banner, Field } }

/// A whole scene lighting choice: it names a sky and, kept with it, the
/// sun that lights the scene, so a choice cannot leave the two apart.
/// `Dawn`, `Noon`, `Dusk` and `Night` each pair a gradient with a sun of
/// its own color and direction; `Clear`, `Classic`, `ImageDawn` and
/// `Sinister` each pair a loaded image with a sun that fits it, and
/// `LightBlueStars` and `BlueStars` pair a loaded space image with none;
/// `Default` is the engine's own grey sky and white sun.
///
/// [`Skyboxes`] proves every value at startup, so it must be [`Eq`] and
/// [`Hash`] over a fixed [`Skyboxes::catalog`] — a sky and sun a player
/// set to any color and direction live could never meet, since `f32` is
/// neither. This fixed, named set is the shape this file chose in its
/// place: the side area offers it as one row, and shows the chosen sky's
/// own light and its sun's own strength as text, read only, rather than
/// controls a game could not build from. See this example's report for
/// what that choice costs.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
enum Sky {
    Dawn,
    Noon,
    Dusk,
    Night,
    Clear,
    Classic,
    ImageDawn,
    Sinister,
    LightBlueStars,
    BlueStars,
    Default,
}

impl Sky {
    const ALL: [Sky; 11] = [
        Self::Dawn,
        Self::Noon,
        Self::Dusk,
        Self::Night,
        Self::Clear,
        Self::Classic,
        Self::ImageDawn,
        Self::Sinister,
        Self::LightBlueStars,
        Self::BlueStars,
        Self::Default,
    ];

    fn name(self) -> &'static str {
        match self {
            Self::Dawn => "dawn",
            Self::Noon => "noon",
            Self::Dusk => "dusk",
            Self::Night => "night",
            Self::Clear => "clear day",
            Self::Classic => "classic",
            Self::ImageDawn => "dawn image",
            Self::Sinister => "sinister night",
            Self::LightBlueStars => "light blue stars",
            Self::BlueStars => "blue stars",
            Self::Default => "default",
        }
    }

    /// The fraction of its own light this sky lands and reflects, through
    /// [`SkyboxData::lit_by`]: fixed per choice, so a bright one does not
    /// read too bright, and a dark one does not read too dark, under the
    /// frame's own lights.
    fn light(self) -> f32 {
        match self {
            Self::Dawn => 0.4,
            Self::Noon => 0.5,
            Self::Dusk => 0.35,
            Self::Night => 0.3,
            Self::Clear => CLEAR_SKY_LIGHT,
            Self::Classic => CLASSIC_SKY_LIGHT,
            Self::ImageDawn => DAWN_SKY_LIGHT,
            Self::Sinister => SINISTER_SKY_LIGHT,
            Self::LightBlueStars => LIGHT_BLUE_STARS_LIGHT,
            Self::BlueStars => BLUE_STARS_LIGHT,
            Self::Default => 1.0,
        }
    }

    /// The sun this choice pairs with its sky: direction, color and
    /// strength resolved together, so a choice cannot leave them apart.
    /// `None` for the two space images, which pair with no sun at all.
    fn sun(self) -> Option<(Vec3, Color, f32)> {
        match self {
            Self::Dawn => Some((
                Vec3::new(-1.0, -0.15, 0.05),
                Color::rgb(1.0, 0.7, 0.45),
                1.4,
            )),
            Self::Noon => Some((
                Vec3::new(-0.15, -1.0, -0.1),
                Color::rgb(1.0, 1.0, 0.98),
                1.6,
            )),
            Self::Dusk => Some((
                Vec3::new(1.0, -0.15, 0.05),
                Color::rgb(1.0, 0.55, 0.25),
                1.2,
            )),
            Self::Night => Some((
                Vec3::new(-0.3, -0.7, -0.6),
                Color::rgb(0.55, 0.65, 0.85),
                0.15,
            )),
            Self::Clear => Some((
                Vec3::new(-0.2, -1.0, -0.15),
                Color::rgb(1.0, 0.98, 0.9),
                1.5,
            )),
            Self::Classic => Some((
                Vec3::new(-0.4, -0.9, -0.2),
                Color::rgb(1.0, 0.95, 0.85),
                1.3,
            )),
            Self::ImageDawn => Some((Vec3::new(-1.0, -0.2, 0.1), Color::rgb(1.0, 0.75, 0.5), 1.1)),
            Self::Sinister => Some((Vec3::new(0.4, -0.5, -0.7), Color::rgb(0.4, 0.5, 0.75), 0.1)),
            Self::LightBlueStars | Self::BlueStars => None,
            Self::Default => Some((Vec3::new(-0.4, -1.0, -0.6), Color::WHITE, 1.0)),
        }
    }

    /// The color the sky reads under the horizon, through
    /// [`SkyboxData::with_ground`]: the floor as lit under this choice's own
    /// sun and [`Self::light`], so it moves with them, not only with the
    /// image. `None` for the gradient skies and `Default`, which need no
    /// ground, and for the two space images, which hold space below the
    /// horizon as well.
    fn ground(self) -> Option<Color> {
        match self {
            Self::Clear => Some(Color::rgb(0.501, 0.517, 0.449)),
            Self::Classic => Some(Color::rgb(0.420, 0.405, 0.379)),
            Self::ImageDawn => Some(Color::rgb(0.073, 0.053, 0.032)),
            Self::Sinister => Some(Color::rgb(0.012, 0.014, 0.020)),
            Self::Dawn
            | Self::Noon
            | Self::Dusk
            | Self::Night
            | Self::LightBlueStars
            | Self::BlueStars
            | Self::Default => None,
        }
    }
}

impl Catalog for Sky {
    fn catalog() -> Vec<Self> {
        Self::ALL.to_vec()
    }
}

impl Skyboxes for Sky {
    fn build(&self, assets: &Assets) -> SkyboxData {
        let sky = match self {
            Self::Dawn => SkyboxData::gradient(
                Color::rgb(0.55, 0.55, 0.75),
                Color::rgb(0.95, 0.6, 0.35),
                Color::rgb(0.12, 0.08, 0.06),
            ),
            Self::Noon => SkyboxData::gradient(
                Color::rgb(0.2, 0.45, 0.85),
                Color::rgb(0.75, 0.82, 0.9),
                Color::rgb(0.3, 0.3, 0.28),
            ),
            Self::Dusk => SkyboxData::gradient(
                Color::rgb(0.18, 0.1, 0.3),
                Color::rgb(0.85, 0.35, 0.2),
                Color::rgb(0.03, 0.02, 0.03),
            ),
            Self::Night => SkyboxData::gradient(
                Color::rgb(0.02, 0.02, 0.06),
                Color::rgb(0.05, 0.05, 0.1),
                Color::rgb(0.0, 0.0, 0.0),
            ),
            Self::Clear => assets.skybox("sky-clear"),
            Self::Classic => assets.skybox("sky-classic"),
            Self::ImageDawn => assets.skybox("sky-dawn"),
            Self::Sinister => assets.skybox("sky-sinister"),
            Self::LightBlueStars => assets.skybox("sky-stars-lightblue"),
            Self::BlueStars => assets.skybox("sky-stars-blue"),
            Self::Default => SkyboxData::gradient(DEFAULT_SKY, DEFAULT_SKY, DEFAULT_SKY),
        };
        let sky = match self.ground() {
            Some(ground) => sky.with_ground(ground),
            None => sky,
        };

        sky.lit_by(self.light())
    }
}

/// `color` scaled by `strength`, the value a [`Light`] reads.
fn scaled(color: Color, strength: f32) -> Color {
    Color::rgb(
        color.red * strength,
        color.green * strength,
        color.blue * strength,
    )
}

/// One light's color and strength, held apart from the position that
/// names it, plus whether it casts.
#[derive(Clone, Copy)]
struct Glow {
    color: Color,
    strength: f32,
    shadow: bool,
}

impl Glow {
    /// `color` scaled by `strength`, the value a [`Light`] reads.
    fn scaled(self) -> Color {
        scaled(self.color, self.strength)
    }
}

/// Every key and button this game reads apart from the UI: held, `Look`
/// turns the camera by the pointer's own motion, `Forward`/`Back`/
/// `Left`/`Right` move it along the view and to its side, and `Up`/
/// `Down` move it along the world's own up.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Move {
    Forward,
    Back,
    Left,
    Right,
    Up,
    Down,
    Look,
}

impl InputButtonAction for Move {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Self::Forward => vec![Key::W.into()],
            Self::Back => vec![Key::S.into()],
            Self::Left => vec![Key::A.into()],
            Self::Right => vec![Key::D.into()],
            Self::Up => vec![Key::Space.into()],
            Self::Down => vec![Key::LeftShift.into()],
            Self::Look => vec![MouseButton::Right.into()],
        }
    }
}

/// The pointer's own motion, read only while [`Move::Look`] is held.
#[derive(InputAxis2Action, Clone, Copy, PartialEq)]
enum Turn {
    Look,
}

impl InputAxis2Action for Turn {
    fn bindings(&self) -> Vec<Axis2Binding> {
        match self {
            Self::Look => vec![Axis2Binding::pointer().scale(LOOK_SENSITIVITY)],
        }
    }
}

/// How far the wheel moved this frame, read to scale the move speed.
#[derive(InputAxisAction, Clone, Copy, PartialEq)]
enum Speed {
    Wheel,
}

impl InputAxisAction for Speed {
    fn bindings(&self) -> Vec<AxisBinding> {
        match self {
            Self::Wheel => vec![AxisBinding::from(WheelDelta::Up).scale(4.0)],
        }
    }
}

struct Controls;

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

struct Playground {
    eye: Vec3,
    yaw: f32,
    pitch: f32,
    speed_scale: f32,

    sky: Sky,
    sun_shadow: bool,

    lamp: Glow,
    spotlight: Glow,

    front_tint: Color,
    front_roughness: f32,
    front_metallic: f32,
    shading_map_on: bool,
    relief_map_on: bool,
    emissive_map_on: bool,

    exposure: f32,
    bloom: f32,
}

impl Playground {
    fn init(ctx: &mut InitContext<'_, Self>) -> Result<Self, Error> {
        let _ = ctx;
        Ok(Self {
            eye: START_EYE,
            yaw: START_YAW,
            pitch: START_PITCH,
            speed_scale: 1.0,

            sky: Sky::Default,
            sun_shadow: true,

            lamp: Glow {
                color: Color::rgb(0.9, 0.55, 0.3),
                strength: 3.0,
                shadow: false,
            },
            spotlight: Glow {
                color: Color::rgb(0.4, 0.6, 1.0),
                strength: 6.0,
                shadow: true,
            },

            front_tint: Color::rgb(0.7, 0.25, 0.2),
            front_roughness: 0.4,
            front_metallic: 0.0,
            shading_map_on: true,
            relief_map_on: true,
            emissive_map_on: true,

            exposure: START_EXPOSURE,
            bloom: START_BLOOM,
        })
    }

    /// This frame's forward direction, from `yaw` (turning around the
    /// world's own up) and `pitch` (turning up or down).
    fn forward(&self) -> Vec3 {
        Vec3::new(
            -self.pitch.cos() * self.yaw.sin(),
            self.pitch.sin(),
            -self.pitch.cos() * self.yaw.cos(),
        )
    }

    /// The camera this frame draws from: `eye` looking along `forward`.
    fn camera(&self) -> Camera {
        Camera::new(
            View::look_at(self.eye, self.eye + self.forward()),
            Projection::perspective(CAMERA_FOV),
        )
    }

    /// A held `Move::Look` (the right mouse button) turns the camera by
    /// the pointer's own motion, the same way it moves: dragging right
    /// turns the view right and left turns it left, dragging down turns
    /// it to look further down at the scene, dragging up back toward the
    /// horizon. `W`/`A`/`S`/`D` move along the view and to its side,
    /// `Space`/`Left Shift` up and down, and the wheel scales how far
    /// each move goes. The `eye` is held above the ground plane wherever
    /// it moves.
    fn fly_camera(&mut self, ctx: &mut FrameContext<'_, Self>) {
        if !ctx.ui_wants_pointer() && ctx.down(Move::Look) {
            let look = ctx.axis2(Turn::Look);
            self.yaw -= look.x;
            self.pitch = (self.pitch + look.y).clamp(-PITCH_LIMIT, PITCH_LIMIT);
        }

        let wheel = ctx.axis(Speed::Wheel);
        if !ctx.ui_wants_pointer() && wheel != 0.0 {
            self.speed_scale =
                (self.speed_scale * SPEED_STEP.powf(wheel)).clamp(MIN_SPEED_SCALE, MAX_SPEED_SCALE);
        }

        let forward = self.forward();
        let right = Vec3::new(self.yaw.cos(), 0.0, -self.yaw.sin());
        let mut move_by = Vec3::ZERO;
        if ctx.down(Move::Forward) {
            move_by += forward;
        }
        if ctx.down(Move::Back) {
            move_by -= forward;
        }
        if ctx.down(Move::Right) {
            move_by += right;
        }
        if ctx.down(Move::Left) {
            move_by -= right;
        }
        if ctx.down(Move::Up) {
            move_by += Vec3::Y;
        }
        if ctx.down(Move::Down) {
            move_by -= Vec3::Y;
        }
        if move_by.length_squared() > 1.0 {
            move_by = move_by.normalize();
        }

        self.eye += move_by * MOVE_SPEED * self.speed_scale * ctx.dt().as_secs_f32();
        self.eye.y = self.eye.y.max(MIN_EYE_HEIGHT);
    }

    /// The material [`Front`] draws with, resolved new from its sliders
    /// every frame — the override [`Instance::material`] takes, in place
    /// of a baked one.
    fn front_material(&self) -> Material {
        Material::lit(self.front_tint)
            .roughness(self.front_roughness)
            .metallic(self.front_metallic)
    }

    /// Every draw this game makes: the ground, each map pair, the front
    /// sphere, the reflection row and the pillars beside it.
    fn draw_scene(&self, ctx: &mut FrameContext<'_, Self>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR).roughness(0.9)),
        );

        Self::draw_pair(
            ctx,
            SHADING_Z,
            SPHERE_RADIUS,
            ShadingPlain.at(Vec3::ZERO).into_set(),
            ShadingMapped.at(Vec3::ZERO).into_set(),
            self.shading_map_on,
        );
        Self::draw_pair(
            ctx,
            RELIEF_Z,
            SPHERE_RADIUS,
            ReliefPlain.at(Vec3::ZERO).into_set(),
            ReliefMapped.at(Vec3::ZERO).into_set(),
            self.relief_map_on,
        );
        Self::draw_pair(
            ctx,
            EMISSIVE_Z,
            CUBE_SIZE / 2.0,
            EmissivePlain.at(Vec3::ZERO).into_set(),
            EmissiveMapped.at(Vec3::ZERO).into_set(),
            self.emissive_map_on,
        );

        ctx.draw(
            Front
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FRONT_SCALE),
                    Quat::IDENTITY,
                    FRONT_POSITION,
                ))
                .material(self.front_material()),
        );

        self.draw_reflect_row(ctx);
        self.draw_outpost(ctx);
    }

    /// One pair at depth `z`, its centers `height` above the ground: `plain`
    /// on the left always, and on the right `mapped` where `mapped_on` is
    /// set, `plain` again where it is not — the same position drawing the
    /// same base material with and without the map.
    fn draw_pair(
        ctx: &mut FrameContext<'_, Self>,
        z: f32,
        height: f32,
        plain: Instance<Shape, Looks>,
        mapped: Instance<Shape, Looks>,
        mapped_on: bool,
    ) {
        ctx.draw(plain.clone().at(Vec3::new(-PAIR_HALF_SPACING, height, z)));
        let right = if mapped_on { mapped } else { plain };
        ctx.draw(right.at(Vec3::new(PAIR_HALF_SPACING, height, z)));
    }

    /// A row of built-in `Sphere` draws at rising roughness, each
    /// `metallic(1.0)` with its tint white, so what draws is the sky's own
    /// reflection alone.
    fn draw_reflect_row(&self, ctx: &mut FrameContext<'_, Self>) {
        let start = -REFLECT_ROW_SPACING * (REFLECT_ROW_COUNT as f32 - 1.0) / 2.0;
        for index in 0..REFLECT_ROW_COUNT {
            let x = start + index as f32 * REFLECT_ROW_SPACING;
            let roughness = index as f32 / (REFLECT_ROW_COUNT as f32 - 1.0);
            ctx.draw(
                Sphere {
                    subdivisions: SPHERE_SUBDIVISIONS,
                }
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(REFLECT_ROW_RADIUS * 2.0),
                    Quat::IDENTITY,
                    Vec3::new(x, REFLECT_ROW_RADIUS, REFLECT_ROW_Z),
                ))
                .material(
                    Material::lit(Color::WHITE)
                        .roughness(roughness)
                        .metallic(1.0),
                ),
            );
        }
    }

examples/stress-preview.rs (line 399)

    fn draw_ground(ctx: &mut FrameContext<'_, Self>) {
        let side = (FIELD_RADIUS + FIELD_INNER_RADIUS) * 2.2;
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(side, 1.0, side)))
                .material(Material::lit(GROUND_COLOR).roughness(0.9)),
        );
    }

examples/flock-parallelism.rs (line 668)

    fn draw_ground(ctx: &mut FrameContext<'_, Self>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR).roughness(0.9)),
        );
    }

pub fn metallic(self, metallic: f32) -> Self

The surface’s metallic, a fraction clamped to 0.0..=1.0 and 0.0 by default: the factor a .glb material declares, held per draw.

Examples found in repository

examples/material-playground.rs (line 292)

fn shading_material() -> Material {
    Material::lit(SHADING_TINT).roughness(0.5).metallic(0.5)
}

fn relief_material() -> Material {
    Material::lit(RELIEF_TINT).roughness(0.35)
}

fn emissive_material() -> Material {
    Material::color(EMISSIVE_BASE).emissive(EMISSIVE_GLOW)
}

/// A shading map whose checker goes between low occlusion, roughness and
/// metallic and full occlusion, roughness and metallic, so all three read
/// apart across [`ShadingMapped`].
fn shading_checker() -> ShadingData {
    ShadingData::rgba8(
        MAP_SIZE,
        checker_pixels(MAP_SIZE, SHADING_CELL, SHADING_LOW, SHADING_HIGH),
    )
}

/// An emissive map whose checker goes between full glow and none, so
/// [`EMISSIVE_GLOW`] shapes across [`EmissiveMapped`] instead of casting
/// whole.
fn emissive_checker() -> TextureData {
    TextureData::rgba8(
        MAP_SIZE,
        checker_pixels(MAP_SIZE, EMISSIVE_CELL, [0, 0, 0], [255, 255, 255]),
    )
}

fn checker_pixels(size: UVec2, cell: u32, low: [u8; 3], high: [u8; 3]) -> Vec<u8> {
    let mut pixels = Vec::with_capacity((size.x * size.y * 4) as usize);
    for y in 0..size.y {
        for x in 0..size.x {
            let on = ((x / cell) + (y / cell)).is_multiple_of(2);
            let [red, green, blue] = if on { high } else { low };
            pixels.extend_from_slice(&[red, green, blue, u8::MAX]);
        }
    }
    pixels
}

/// A relief whose normals turn across a wave that repeats over the map:
/// each texel's slope comes from the partial derivatives of a
/// `sin(u) * sin(v)` height field at `BUMP_SLOPE`'s peak, computed at that
/// texel and not sampled from any other.
fn relief_bumps() -> ReliefData {
    let size = MAP_SIZE;
    let turns = core::f32::consts::TAU * BUMP_WAVES;
    let mut pixels = Vec::with_capacity((size.x * size.y * 4) as usize);
    for y in 0..size.y {
        for x in 0..size.x {
            let u = (x as f32 + 0.5) / size.x as f32;
            let v = (y as f32 + 0.5) / size.y as f32;
            let slope_u = BUMP_SLOPE * (turns * u).cos() * (turns * v).sin();
            let slope_v = BUMP_SLOPE * (turns * u).sin() * (turns * v).cos();
            let normal = Vec3::new(-slope_u, -slope_v, 1.0).normalize();
            let encode = |signed: f32| ((signed * 0.5 + 0.5) * 255.0).round() as u8;
            pixels.extend_from_slice(&[encode(normal.x), encode(normal.y), encode(normal.z), 0]);
        }
    }
    ReliefData::normals(size, pixels)
}

/// `BannerCloth`'s vertices and indices, built twice over: the columns as
/// authored, facing `+Z`, and the same columns again facing `-Z`, their
/// triangles in the other order so both draw front side out.
fn banner_mesh() -> MeshData {
    let mut vertices = Vec::with_capacity(((BANNER_COLUMNS + 1) * 4) as usize);
    for normal in [Vec3::Z, Vec3::NEG_Z] {
        for column in 0..=BANNER_COLUMNS {
            let u = column as f32 / BANNER_COLUMNS as f32;
            let x = u * BANNER_WIDTH;
            for v in [0.0, 1.0] {
                vertices.push(Vertex::new(
                    Vec3::new(x, -v * BANNER_HEIGHT, 0.0),
                    normal,
                    Vec2::new(u, v),
                ));
            }
        }
    }

    let side = BANNER_COLUMNS + 1;
    let mut indices = Vec::with_capacity((BANNER_COLUMNS * 12) as usize);
    for column in 0..BANNER_COLUMNS {
        let top_left = column * 2;
        let bottom_left = top_left + 1;
        let top_right = top_left + 2;
        let bottom_right = top_left + 3;
        indices.extend([
            bottom_left,
            bottom_right,
            top_right,
            bottom_left,
            top_right,
            top_left,
        ]);

        let back = side * 2;
        indices.extend([
            back + top_right,
            back + bottom_right,
            back + bottom_left,
            back + top_left,
            back + top_right,
            back + bottom_left,
        ]);
    }

    MeshData::new(vertices, indices)
}

/// Displaced by a wave that grows away from its `x = 0` edge; casts the
/// shadow of where it was placed, unmoved by its own wave. Its one value
/// is the clock its wave slides on.
#[derive(Default, ShaderValues)]
struct Banner {
    time: f32,
}

impl SurfaceStyle for Banner {
    const PASS: DrawPass = DrawPass::Opaque;
    const DISPLACE: Option<&'static str> = Some(include_str!("material_playground_banner.wgsl"));
}

/// A surface that reads no light of the scene's own: it draws its own
/// pulsing tint, added over what is behind it, through the color it pulses
/// through and the clock the pulse is timed by.
#[derive(Default, ShaderValues)]
struct Field {
    tint: Color,
    time: f32,
}

impl SurfaceStyle for Field {
    const PASS: DrawPass = DrawPass::Additive;
    const SURFACE: Option<&'static str> = Some(include_str!("material_playground_field.wgsl"));
}

surface_styles! { enum Looks { Banner, Field } }

/// A whole scene lighting choice: it names a sky and, kept with it, the
/// sun that lights the scene, so a choice cannot leave the two apart.
/// `Dawn`, `Noon`, `Dusk` and `Night` each pair a gradient with a sun of
/// its own color and direction; `Clear`, `Classic`, `ImageDawn` and
/// `Sinister` each pair a loaded image with a sun that fits it, and
/// `LightBlueStars` and `BlueStars` pair a loaded space image with none;
/// `Default` is the engine's own grey sky and white sun.
///
/// [`Skyboxes`] proves every value at startup, so it must be [`Eq`] and
/// [`Hash`] over a fixed [`Skyboxes::catalog`] — a sky and sun a player
/// set to any color and direction live could never meet, since `f32` is
/// neither. This fixed, named set is the shape this file chose in its
/// place: the side area offers it as one row, and shows the chosen sky's
/// own light and its sun's own strength as text, read only, rather than
/// controls a game could not build from. See this example's report for
/// what that choice costs.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
enum Sky {
    Dawn,
    Noon,
    Dusk,
    Night,
    Clear,
    Classic,
    ImageDawn,
    Sinister,
    LightBlueStars,
    BlueStars,
    Default,
}

impl Sky {
    const ALL: [Sky; 11] = [
        Self::Dawn,
        Self::Noon,
        Self::Dusk,
        Self::Night,
        Self::Clear,
        Self::Classic,
        Self::ImageDawn,
        Self::Sinister,
        Self::LightBlueStars,
        Self::BlueStars,
        Self::Default,
    ];

    fn name(self) -> &'static str {
        match self {
            Self::Dawn => "dawn",
            Self::Noon => "noon",
            Self::Dusk => "dusk",
            Self::Night => "night",
            Self::Clear => "clear day",
            Self::Classic => "classic",
            Self::ImageDawn => "dawn image",
            Self::Sinister => "sinister night",
            Self::LightBlueStars => "light blue stars",
            Self::BlueStars => "blue stars",
            Self::Default => "default",
        }
    }

    /// The fraction of its own light this sky lands and reflects, through
    /// [`SkyboxData::lit_by`]: fixed per choice, so a bright one does not
    /// read too bright, and a dark one does not read too dark, under the
    /// frame's own lights.
    fn light(self) -> f32 {
        match self {
            Self::Dawn => 0.4,
            Self::Noon => 0.5,
            Self::Dusk => 0.35,
            Self::Night => 0.3,
            Self::Clear => CLEAR_SKY_LIGHT,
            Self::Classic => CLASSIC_SKY_LIGHT,
            Self::ImageDawn => DAWN_SKY_LIGHT,
            Self::Sinister => SINISTER_SKY_LIGHT,
            Self::LightBlueStars => LIGHT_BLUE_STARS_LIGHT,
            Self::BlueStars => BLUE_STARS_LIGHT,
            Self::Default => 1.0,
        }
    }

    /// The sun this choice pairs with its sky: direction, color and
    /// strength resolved together, so a choice cannot leave them apart.
    /// `None` for the two space images, which pair with no sun at all.
    fn sun(self) -> Option<(Vec3, Color, f32)> {
        match self {
            Self::Dawn => Some((
                Vec3::new(-1.0, -0.15, 0.05),
                Color::rgb(1.0, 0.7, 0.45),
                1.4,
            )),
            Self::Noon => Some((
                Vec3::new(-0.15, -1.0, -0.1),
                Color::rgb(1.0, 1.0, 0.98),
                1.6,
            )),
            Self::Dusk => Some((
                Vec3::new(1.0, -0.15, 0.05),
                Color::rgb(1.0, 0.55, 0.25),
                1.2,
            )),
            Self::Night => Some((
                Vec3::new(-0.3, -0.7, -0.6),
                Color::rgb(0.55, 0.65, 0.85),
                0.15,
            )),
            Self::Clear => Some((
                Vec3::new(-0.2, -1.0, -0.15),
                Color::rgb(1.0, 0.98, 0.9),
                1.5,
            )),
            Self::Classic => Some((
                Vec3::new(-0.4, -0.9, -0.2),
                Color::rgb(1.0, 0.95, 0.85),
                1.3,
            )),
            Self::ImageDawn => Some((Vec3::new(-1.0, -0.2, 0.1), Color::rgb(1.0, 0.75, 0.5), 1.1)),
            Self::Sinister => Some((Vec3::new(0.4, -0.5, -0.7), Color::rgb(0.4, 0.5, 0.75), 0.1)),
            Self::LightBlueStars | Self::BlueStars => None,
            Self::Default => Some((Vec3::new(-0.4, -1.0, -0.6), Color::WHITE, 1.0)),
        }
    }

    /// The color the sky reads under the horizon, through
    /// [`SkyboxData::with_ground`]: the floor as lit under this choice's own
    /// sun and [`Self::light`], so it moves with them, not only with the
    /// image. `None` for the gradient skies and `Default`, which need no
    /// ground, and for the two space images, which hold space below the
    /// horizon as well.
    fn ground(self) -> Option<Color> {
        match self {
            Self::Clear => Some(Color::rgb(0.501, 0.517, 0.449)),
            Self::Classic => Some(Color::rgb(0.420, 0.405, 0.379)),
            Self::ImageDawn => Some(Color::rgb(0.073, 0.053, 0.032)),
            Self::Sinister => Some(Color::rgb(0.012, 0.014, 0.020)),
            Self::Dawn
            | Self::Noon
            | Self::Dusk
            | Self::Night
            | Self::LightBlueStars
            | Self::BlueStars
            | Self::Default => None,
        }
    }
}

impl Catalog for Sky {
    fn catalog() -> Vec<Self> {
        Self::ALL.to_vec()
    }
}

impl Skyboxes for Sky {
    fn build(&self, assets: &Assets) -> SkyboxData {
        let sky = match self {
            Self::Dawn => SkyboxData::gradient(
                Color::rgb(0.55, 0.55, 0.75),
                Color::rgb(0.95, 0.6, 0.35),
                Color::rgb(0.12, 0.08, 0.06),
            ),
            Self::Noon => SkyboxData::gradient(
                Color::rgb(0.2, 0.45, 0.85),
                Color::rgb(0.75, 0.82, 0.9),
                Color::rgb(0.3, 0.3, 0.28),
            ),
            Self::Dusk => SkyboxData::gradient(
                Color::rgb(0.18, 0.1, 0.3),
                Color::rgb(0.85, 0.35, 0.2),
                Color::rgb(0.03, 0.02, 0.03),
            ),
            Self::Night => SkyboxData::gradient(
                Color::rgb(0.02, 0.02, 0.06),
                Color::rgb(0.05, 0.05, 0.1),
                Color::rgb(0.0, 0.0, 0.0),
            ),
            Self::Clear => assets.skybox("sky-clear"),
            Self::Classic => assets.skybox("sky-classic"),
            Self::ImageDawn => assets.skybox("sky-dawn"),
            Self::Sinister => assets.skybox("sky-sinister"),
            Self::LightBlueStars => assets.skybox("sky-stars-lightblue"),
            Self::BlueStars => assets.skybox("sky-stars-blue"),
            Self::Default => SkyboxData::gradient(DEFAULT_SKY, DEFAULT_SKY, DEFAULT_SKY),
        };
        let sky = match self.ground() {
            Some(ground) => sky.with_ground(ground),
            None => sky,
        };

        sky.lit_by(self.light())
    }
}

/// `color` scaled by `strength`, the value a [`Light`] reads.
fn scaled(color: Color, strength: f32) -> Color {
    Color::rgb(
        color.red * strength,
        color.green * strength,
        color.blue * strength,
    )
}

/// One light's color and strength, held apart from the position that
/// names it, plus whether it casts.
#[derive(Clone, Copy)]
struct Glow {
    color: Color,
    strength: f32,
    shadow: bool,
}

impl Glow {
    /// `color` scaled by `strength`, the value a [`Light`] reads.
    fn scaled(self) -> Color {
        scaled(self.color, self.strength)
    }
}

/// Every key and button this game reads apart from the UI: held, `Look`
/// turns the camera by the pointer's own motion, `Forward`/`Back`/
/// `Left`/`Right` move it along the view and to its side, and `Up`/
/// `Down` move it along the world's own up.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Move {
    Forward,
    Back,
    Left,
    Right,
    Up,
    Down,
    Look,
}

impl InputButtonAction for Move {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Self::Forward => vec![Key::W.into()],
            Self::Back => vec![Key::S.into()],
            Self::Left => vec![Key::A.into()],
            Self::Right => vec![Key::D.into()],
            Self::Up => vec![Key::Space.into()],
            Self::Down => vec![Key::LeftShift.into()],
            Self::Look => vec![MouseButton::Right.into()],
        }
    }
}

/// The pointer's own motion, read only while [`Move::Look`] is held.
#[derive(InputAxis2Action, Clone, Copy, PartialEq)]
enum Turn {
    Look,
}

impl InputAxis2Action for Turn {
    fn bindings(&self) -> Vec<Axis2Binding> {
        match self {
            Self::Look => vec![Axis2Binding::pointer().scale(LOOK_SENSITIVITY)],
        }
    }
}

/// How far the wheel moved this frame, read to scale the move speed.
#[derive(InputAxisAction, Clone, Copy, PartialEq)]
enum Speed {
    Wheel,
}

impl InputAxisAction for Speed {
    fn bindings(&self) -> Vec<AxisBinding> {
        match self {
            Self::Wheel => vec![AxisBinding::from(WheelDelta::Up).scale(4.0)],
        }
    }
}

struct Controls;

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

struct Playground {
    eye: Vec3,
    yaw: f32,
    pitch: f32,
    speed_scale: f32,

    sky: Sky,
    sun_shadow: bool,

    lamp: Glow,
    spotlight: Glow,

    front_tint: Color,
    front_roughness: f32,
    front_metallic: f32,
    shading_map_on: bool,
    relief_map_on: bool,
    emissive_map_on: bool,

    exposure: f32,
    bloom: f32,
}

impl Playground {
    fn init(ctx: &mut InitContext<'_, Self>) -> Result<Self, Error> {
        let _ = ctx;
        Ok(Self {
            eye: START_EYE,
            yaw: START_YAW,
            pitch: START_PITCH,
            speed_scale: 1.0,

            sky: Sky::Default,
            sun_shadow: true,

            lamp: Glow {
                color: Color::rgb(0.9, 0.55, 0.3),
                strength: 3.0,
                shadow: false,
            },
            spotlight: Glow {
                color: Color::rgb(0.4, 0.6, 1.0),
                strength: 6.0,
                shadow: true,
            },

            front_tint: Color::rgb(0.7, 0.25, 0.2),
            front_roughness: 0.4,
            front_metallic: 0.0,
            shading_map_on: true,
            relief_map_on: true,
            emissive_map_on: true,

            exposure: START_EXPOSURE,
            bloom: START_BLOOM,
        })
    }

    /// This frame's forward direction, from `yaw` (turning around the
    /// world's own up) and `pitch` (turning up or down).
    fn forward(&self) -> Vec3 {
        Vec3::new(
            -self.pitch.cos() * self.yaw.sin(),
            self.pitch.sin(),
            -self.pitch.cos() * self.yaw.cos(),
        )
    }

    /// The camera this frame draws from: `eye` looking along `forward`.
    fn camera(&self) -> Camera {
        Camera::new(
            View::look_at(self.eye, self.eye + self.forward()),
            Projection::perspective(CAMERA_FOV),
        )
    }

    /// A held `Move::Look` (the right mouse button) turns the camera by
    /// the pointer's own motion, the same way it moves: dragging right
    /// turns the view right and left turns it left, dragging down turns
    /// it to look further down at the scene, dragging up back toward the
    /// horizon. `W`/`A`/`S`/`D` move along the view and to its side,
    /// `Space`/`Left Shift` up and down, and the wheel scales how far
    /// each move goes. The `eye` is held above the ground plane wherever
    /// it moves.
    fn fly_camera(&mut self, ctx: &mut FrameContext<'_, Self>) {
        if !ctx.ui_wants_pointer() && ctx.down(Move::Look) {
            let look = ctx.axis2(Turn::Look);
            self.yaw -= look.x;
            self.pitch = (self.pitch + look.y).clamp(-PITCH_LIMIT, PITCH_LIMIT);
        }

        let wheel = ctx.axis(Speed::Wheel);
        if !ctx.ui_wants_pointer() && wheel != 0.0 {
            self.speed_scale =
                (self.speed_scale * SPEED_STEP.powf(wheel)).clamp(MIN_SPEED_SCALE, MAX_SPEED_SCALE);
        }

        let forward = self.forward();
        let right = Vec3::new(self.yaw.cos(), 0.0, -self.yaw.sin());
        let mut move_by = Vec3::ZERO;
        if ctx.down(Move::Forward) {
            move_by += forward;
        }
        if ctx.down(Move::Back) {
            move_by -= forward;
        }
        if ctx.down(Move::Right) {
            move_by += right;
        }
        if ctx.down(Move::Left) {
            move_by -= right;
        }
        if ctx.down(Move::Up) {
            move_by += Vec3::Y;
        }
        if ctx.down(Move::Down) {
            move_by -= Vec3::Y;
        }
        if move_by.length_squared() > 1.0 {
            move_by = move_by.normalize();
        }

        self.eye += move_by * MOVE_SPEED * self.speed_scale * ctx.dt().as_secs_f32();
        self.eye.y = self.eye.y.max(MIN_EYE_HEIGHT);
    }

    /// The material [`Front`] draws with, resolved new from its sliders
    /// every frame — the override [`Instance::material`] takes, in place
    /// of a baked one.
    fn front_material(&self) -> Material {
        Material::lit(self.front_tint)
            .roughness(self.front_roughness)
            .metallic(self.front_metallic)
    }

    /// Every draw this game makes: the ground, each map pair, the front
    /// sphere, the reflection row and the pillars beside it.
    fn draw_scene(&self, ctx: &mut FrameContext<'_, Self>) {
        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR).roughness(0.9)),
        );

        Self::draw_pair(
            ctx,
            SHADING_Z,
            SPHERE_RADIUS,
            ShadingPlain.at(Vec3::ZERO).into_set(),
            ShadingMapped.at(Vec3::ZERO).into_set(),
            self.shading_map_on,
        );
        Self::draw_pair(
            ctx,
            RELIEF_Z,
            SPHERE_RADIUS,
            ReliefPlain.at(Vec3::ZERO).into_set(),
            ReliefMapped.at(Vec3::ZERO).into_set(),
            self.relief_map_on,
        );
        Self::draw_pair(
            ctx,
            EMISSIVE_Z,
            CUBE_SIZE / 2.0,
            EmissivePlain.at(Vec3::ZERO).into_set(),
            EmissiveMapped.at(Vec3::ZERO).into_set(),
            self.emissive_map_on,
        );

        ctx.draw(
            Front
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FRONT_SCALE),
                    Quat::IDENTITY,
                    FRONT_POSITION,
                ))
                .material(self.front_material()),
        );

        self.draw_reflect_row(ctx);
        self.draw_outpost(ctx);
    }

    /// One pair at depth `z`, its centers `height` above the ground: `plain`
    /// on the left always, and on the right `mapped` where `mapped_on` is
    /// set, `plain` again where it is not — the same position drawing the
    /// same base material with and without the map.
    fn draw_pair(
        ctx: &mut FrameContext<'_, Self>,
        z: f32,
        height: f32,
        plain: Instance<Shape, Looks>,
        mapped: Instance<Shape, Looks>,
        mapped_on: bool,
    ) {
        ctx.draw(plain.clone().at(Vec3::new(-PAIR_HALF_SPACING, height, z)));
        let right = if mapped_on { mapped } else { plain };
        ctx.draw(right.at(Vec3::new(PAIR_HALF_SPACING, height, z)));
    }

    /// A row of built-in `Sphere` draws at rising roughness, each
    /// `metallic(1.0)` with its tint white, so what draws is the sky's own
    /// reflection alone.
    fn draw_reflect_row(&self, ctx: &mut FrameContext<'_, Self>) {
        let start = -REFLECT_ROW_SPACING * (REFLECT_ROW_COUNT as f32 - 1.0) / 2.0;
        for index in 0..REFLECT_ROW_COUNT {
            let x = start + index as f32 * REFLECT_ROW_SPACING;
            let roughness = index as f32 / (REFLECT_ROW_COUNT as f32 - 1.0);
            ctx.draw(
                Sphere {
                    subdivisions: SPHERE_SUBDIVISIONS,
                }
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(REFLECT_ROW_RADIUS * 2.0),
                    Quat::IDENTITY,
                    Vec3::new(x, REFLECT_ROW_RADIUS, REFLECT_ROW_Z),
                ))
                .material(
                    Material::lit(Color::WHITE)
                        .roughness(roughness)
                        .metallic(1.0),
                ),
            );
        }
    }

pub const fn cutout(self) -> Self

Drops the texels where tint × texture alpha lands under 0.5, and draws the rest as opaque.

Required if you want a sprite drawn with no blending at its edges: a cutout draw writes depth and is not sorted. A tint alpha under 1.0 still draws it in the transparent pass, where the same texels are dropped.

Examples found in repository

examples/sprite-adventure.rs (line 586)

    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(POND_SHEET).pixelated())
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A crate prop, its texture drawn over a cube.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Crate;

impl Mesh for Crate {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(CRATE_TEXTURE).pixelated())
    }
}

/// The well's rim.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Well;

impl Mesh for Well {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(WELL_SHEET).pixelated())
    }
}

/// The well's mouth, laid flat over the rim's top face.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct WellMouth;

impl Mesh for WellMouth {
    fn build(&self, assets: &Assets) -> MeshData {
        Plane
            .build(assets)
            .with_texture(assets.texture(WELL_SHEET).pixelated())
    }
}

/// A stone box: the mouth's pillars and lintel.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Stone;

impl Mesh for Stone {
    fn build(&self, assets: &Assets) -> MeshData {
        Cube.build(assets)
            .with_texture(assets.texture(STONE_SHEET).pixelated())
    }
}

/// A bush sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Bush;

impl Mesh for Bush {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(BUSH_SPRITE).pixelated())
            .with_relief(assets.relief(BUSH_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A rock sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Rock;

impl Mesh for Rock {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(ROCK_SPRITE).pixelated())
            .with_relief(assets.relief(ROCK_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A torch's post sprite, cutout with its own relief.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Torch;

impl Mesh for Torch {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(TORCH_SPRITE).pixelated())
            .with_relief(assets.relief(TORCH_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }
}

/// A torch's flame sprite, added over the dark rather than lit.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Flame;

impl Mesh for Flame {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(FLAME_SHEET).pixelated())
            .with_material(Material::color(FLAME_TINT).additive())
    }
}

/// The player's sprite, cutout with its own relief, its sheet shared
/// with `examples/isometric-board.rs`.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Walker;

impl Mesh for Walker {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(WALKER_SHEET).pixelated())
            .with_relief(assets.relief(WALKER_RELIEF))
            .with_material(Material::lit(Color::WHITE).cutout())
    }

examples/isometric-board.rs (line 604)

    fn draw_sprite(&self, ctx: &mut FrameContext<'_, Board>, hover: Hover) {
        let position = self.sprite.previous.lerp(self.sprite.position, ctx.alpha());
        let current = self.turn == Turn::Sprite;
        let (tint, glow) = if current && self.selected {
            (SELECTED_TINT, SELECTED_GLOW)
        } else if current && hover == Hover::CurrentUnit {
            (HOVER_TINT, HOVER_GLOW)
        } else if current {
            (TURN_TINT, TURN_GLOW)
        } else {
            (Color::WHITE, Color::BLACK)
        };
        ctx.draw(
            Sprite
                .at(Transform::from_scale_rotation_translation(
                    Vec3::new(SPRITE_WIDTH, SPRITE_HEIGHT, 1.0),
                    Quat::IDENTITY,
                    position,
                ))
                .upright()
                .frame(sprite_frame(self.sprite.facing_right))
                .material(Material::lit(tint).cutout().emissive(glow)),
        );
    }

pub const fn additive(self) -> Self

Adds what the draw would be to what is behind it, instead of drawing over it.

Required if you want a draw that only ever adds light and never darkens what it covers: it is drawn after the transparent pass, in the order it was submitted, is never written to depth, and casts no shadow. The tint’s alpha scales everything it adds — the emissive light too: fade one or the other, not both. The texture’s alpha scales each texel the same way: an empty texel adds nothing, and one half covered adds half of what it holds. A tint past 1.0 scales what the texture holds past it: the draw adds light in the shape and color of its own texture. A flat emissive adds one color over every texel instead. A material that also set cutout drops nothing.

Examples found in repository

examples/sprite-adventure.rs (line 682)

    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(FLAME_SHEET).pixelated())
            .with_material(Material::color(FLAME_TINT).additive())
    }

examples/breakout-game.rs (line 677)

    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 = NoSurfaceStyles;
    type PostEffects = NoPostEffects;

    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);
    }

pub const fn tint(&self) -> Color

The color shading multiplies the lighting by.

pub const fn litness(&self) -> f32

The fraction of lit shading applied: 0.0 flat, 1.0 fully lit.

pub const fn emission(&self) -> Color

The light the surface adds of its own.

pub const fn rough(&self) -> f32

The surface’s roughness, a fraction.

pub const fn metal(&self) -> f32

The surface’s metallic, a fraction.

Trait Implementations

impl Clone for Material

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Material

impl Debug for Material

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Material

fn default() -> Self

Lit white.

impl PartialEq for Material

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Material