Struct Vec3 

#[repr(C)]
pub struct Vec3 {
    pub x: f32,
    pub y: f32,
    pub z: f32,
}

A 3-dimensional vector.

Fields

x: f32

y: f32

z: f32

Implementations

impl Vec3

pub const ZERO: Vec3

All zeroes.

pub const ONE: Vec3

All ones.

pub const NEG_ONE: Vec3

All negative ones.

pub const MIN: Vec3

All f32::MIN.

pub const MAX: Vec3

All f32::MAX.

pub const NAN: Vec3

All f32::NAN.

pub const INFINITY: Vec3

All f32::INFINITY.

pub const NEG_INFINITY: Vec3

All f32::NEG_INFINITY.

pub const X: Vec3

A unit vector pointing along the positive X axis.

pub const Y: Vec3

A unit vector pointing along the positive Y axis.

pub const Z: Vec3

A unit vector pointing along the positive Z axis.

pub const NEG_X: Vec3

A unit vector pointing along the negative X axis.

pub const NEG_Y: Vec3

A unit vector pointing along the negative Y axis.

pub const NEG_Z: Vec3

A unit vector pointing along the negative Z axis.

pub const AXES: [Vec3; 3]

The unit axes.

pub const USES_CORE_SIMD: bool = false

Vec3 uses Rust Portable SIMD

pub const USES_NEON: bool = false

Vec3 uses Arm NEON

pub const USES_SCALAR_MATH: bool = true

Vec3 uses scalar math

pub const USES_SSE2: bool = false

Vec3 uses Intel SSE2

pub const USES_WASM_SIMD: bool = false

Vec3 uses WebAssembly 128-bit SIMD

pub const USES_WASM32_SIMD: bool = false

👎Deprecated since 0.31.0:

Renamed to USES_WASM_SIMD

pub const fn new(x: f32, y: f32, z: f32) -> Vec3

Creates a new vector.

Examples found in repository

examples/animation.rs (line 80)

const ELF_START: Vec3 = Vec3::new(-3.0, 0.0, 4.0);

/// Ground positions of the three hurt patches, and their radius.
const HURT_PATCHES: [Vec3; 3] = [
    Vec3::new(1.5, 0.0, -1.0),
    Vec3::new(-1.5, 0.0, -3.5),
    Vec3::new(3.0, 0.0, 2.0),
];
const HURT_RADIUS: f32 = 0.9;
/// Hits it takes before the elf reads `Death` instead of `Hit`.
const FATAL_HITS: u32 = 3;

/// The seat's position, at the ground, and its footprint: measured on the
/// asset, `sit_down` lowers the pelvis from `0.77` meters to `0.47` meters
/// and moves it `0.29` meters toward the seat, the feet staying where they
/// stood, so a block this tall under that landing puts the pelvis on its
/// top face.
const SEAT_POSITION: Vec3 = Vec3::new(-3.5, 0.0, -3.0);
const SEAT_FOOTPRINT: f32 = 1.0;
const SEAT_HEIGHT: f32 = 0.45;
/// How tall the figure sits, from the seat's top to its head.
const SEATED_HEIGHT: f32 = 0.75;
/// Height from the ground to the seated elf's head.
const SEAT_HEAD_HEIGHT: f32 = SEAT_HEIGHT + SEATED_HEIGHT;
/// The gap in front of the seat's own face the elf stands at.
const SEAT_STAND_CLEARANCE: f32 = 0.05;
/// Where the elf stands to sit on the seat, at its front face plus
/// [`SEAT_STAND_CLEARANCE`], and which way it faces there: away from the
/// seat, so `sit_down` moves the pelvis back onto it.
const SEAT_SPOT: Vec3 = Vec3::new(
    SEAT_POSITION.x,
    0.0,
    SEAT_POSITION.z + SEAT_FOOTPRINT * 0.5 + SEAT_STAND_CLEARANCE,
);
const SEAT_FACING: f32 = 0.0;
/// The least distance from [`SEAT_POSITION`] `Button::Interact` sits the
/// elf down at.
const SEAT_INTERACT_RADIUS: f32 = 1.6;

/// The second elf's fixed position, under a machine scrubbed by its
/// distance from the first.
const SCRUBBED_ELF_POSITION: Vec3 = Vec3::new(3.5, 0.0, 4.0);
/// The distance at and under which the scrubbed elf reads fully seated.
const SCRUB_NEAR: f32 = 1.5;
/// The distance at and past which it reads fully standing.
const SCRUB_FAR: f32 = 5.0;

/// The lamp post's own position, near the seat and its stand.
const LAMP_POST_POSITION: Vec3 = Vec3::new(-4.9, 0.0, -2.0);
const LAMP_POST_HEIGHT: f32 = 2.2;
const LAMP_POST_THICKNESS: f32 = 0.16;
const LAMP_POST_COLOR: Color = Color::rgb(0.16, 0.14, 0.12);
/// The lamp's own head, on top of the post, emissive in [`LAMP_LIGHT_COLOR`].
const LAMP_HEAD_SIZE: f32 = 0.34;
/// The gap left between the post's own top and the head's bottom face, so
/// the light sits clear of both meshes rather than inside the head it
/// would then cast no light from.
const LAMP_HEAD_GAP: f32 = 0.06;
/// Past `1.0`, so its glow lands on the ground near it, visible against
/// the sky, and the head reads bright once bloom spreads it.
const LAMP_LIGHT_COLOR: Color = Color::rgb(5.5, 4.2, 2.2);
const LAMP_LIGHT_RANGE: f32 = 6.0;

/// Centered over the three [`HURT_PATCHES`], tall enough for one cone to
/// reach all of them.
const SPOT_POSITION: Vec3 = Vec3::new(1.0, 6.0, -0.83);
const SPOT_DIRECTION: Vec3 = Vec3::NEG_Y;
/// Past `1.0`, so the cone is visible on the ground against the sky, and
/// bright enough that a patch inside it reads well past a patch outside.
const SPOT_COLOR: Color = Color::rgb(11.0, 9.8, 8.2);
const SPOT_RANGE: f32 = 9.0;
const SPOT_ANGLE: f32 = 0.85;
/// The fixture's own edge length, drawn where the cone starts.
const SPOT_FIXTURE_SIZE: f32 = 0.22;
const SPOT_FIXTURE_COLOR: Color = Color::rgb(0.2, 0.2, 0.22);

/// The butterfly's own source, next to the other example assets.
const BUTTERFLY_SOURCE: &str = "examples/assets/butterfly.glb";
/// The root node the source names the butterfly under.
const BUTTERFLY_ROOT: &str = "Butterfly";
/// The point halfway between [`SEAT_POSITION`] and [`LAMP_POST_POSITION`],
/// the closed path's own center.
const BUTTERFLY_CENTER: Vec3 = Vec3::new(-4.2, 0.0, -2.5);
/// The closed path's radius along `x` and `z`, wide enough to loop around
/// both the seat and the lamp.
const BUTTERFLY_RADIUS: Vec2 = Vec2::new(1.8, 1.4);
/// About the lamp's own height.
const BUTTERFLY_HEIGHT: f32 = LAMP_POST_HEIGHT;
/// Radians a second around the path; a full loop takes about 14 seconds.
const BUTTERFLY_ANGULAR_SPEED: f32 = TAU / 14.0;
/// Past `1.0`, so its glow lands on the ground and the lamp post it passes.
const BUTTERFLY_LIGHT_COLOR: Color = Color::rgb(1.8, 5.5, 5.0);
const BUTTERFLY_LIGHT_RANGE: f32 = 3.0;
/// The butterfly's own small emissive, so it reads bright rather than
/// dark against the glow it casts.
const BUTTERFLY_EMISSIVE: Color = Color::rgb(0.6, 1.8, 1.6);

const GROUND_SIZE: f32 = 400.0;
const GROUND_COLOR: Color = Color::rgb(0.24, 0.30, 0.22);
const HURT_COLOR: Color = Color::rgb(0.75, 0.12, 0.10);
const SEAT_COLOR: Color = Color::rgb(0.5, 0.42, 0.3);
/// Low, near the horizon, and dim.
const SUN_DIRECTION: Vec3 = Vec3::new(-0.85, -0.18, -0.5);
const SUN_COLOR: Color = Color::rgb(0.55, 0.32, 0.22);
const SKY_ZENITH: Color = Color::rgb(0.06, 0.07, 0.2);
const SKY_HORIZON: Color = Color::rgb(0.55, 0.35, 0.28);
const SKY_NADIR: Color = Color::rgb(0.05, 0.05, 0.07);
/// The fraction of its own light the sky lands and reflects: dim, so the
/// lamp, spotlight and butterfly lights read against it.
const SKY_LIGHT: f32 = 0.15;

/// The orbit camera's distance behind and height above its target.
const CAMERA_BACK: f32 = 3.4;
const CAMERA_UP: f32 = 1.7;
/// Height above the ground the camera looks at, framing the whole figure.
const CAMERA_LOOK_HEIGHT: f32 = 0.8;
const CAMERA_FOV: f32 = 50.0;
/// Radians the camera orbits, or tilts, per pixel the pointer moves,
/// chosen so a drag the width, or the height, of the window turns it by
/// [`CAMERA_YAW_PER_DRAG`], or [`CAMERA_PITCH_PER_DRAG`].
const CAMERA_YAW_PER_DRAG: f32 = core::f32::consts::PI;
const CAMERA_PITCH_PER_DRAG: f32 = core::f32::consts::FRAC_PI_3;
const CAMERA_YAW_SCALE: f32 = CAMERA_YAW_PER_DRAG / WINDOW_WIDTH as f32;
const CAMERA_PITCH_SCALE: f32 = CAMERA_PITCH_PER_DRAG / WINDOW_HEIGHT as f32;
/// The range the camera's tilt is held inside, in radians: short of
/// looking flat along the ground or straight down, either of which would
/// stop framing the figure.
const CAMERA_PITCH_RANGE: Range<f32> = -0.4..0.9;

/// The panel's controls, a key and what it does.
const CONTROLS: [(&str, &str); 10] = [
    ("mouse", "turns the camera"),
    ("click", "locks the pointer"),
    ("escape", "frees the pointer"),
    ("wasd or arrows", "walk"),
    ("left shift", "runs"),
    ("f", "attacks, chains on a second press"),
    ("space", "jumps"),
    ("n", "dances while idle"),
    ("e", "sits on the seat and stands back up"),
    ("r", "starts a new elf"),
];

/// The UI's own text color, read over the ground and the sky both.
const PANEL_TEXT_COLOR: egui::Color32 = egui::Color32::from_gray(230);
/// How much dark a panel or a prompt's own backdrop puts behind its text.
const PANEL_BACKDROP: u8 = 190;
/// The panel's own inner margin, around its labels.
const PANEL_PADDING: i8 = 8;
/// The size a world-space prompt reads at, in logical points.
const PROMPT_SIZE: f32 = 15.0;
/// Height a world-space prompt is lifted over the point it names.
const PROMPT_LIFT: f32 = 0.35;
/// Margin a prompt's own backdrop keeps past its galley, in logical points.
const PROMPT_PADDING: f32 = 4.0;

meshes! { enum Shape { Plane, Cube, Elf, Butterfly } }

/// The one sky this game draws, a gradient set each frame.
#[derive(Catalog, Clone, Copy, Debug, Eq, Hash, PartialEq)]
enum Sky {
    Day,
}

impl Skyboxes for Sky {
    fn build(&self, _assets: &Assets) -> SkyboxData {
        match self {
            Self::Day => SkyboxData::gradient(SKY_ZENITH, SKY_HORIZON, SKY_NADIR).lit_by(SKY_LIGHT),
        }
    }
}

#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Elf;

/// The clips `ElfState` and `ScrubbedState` play, named as the source
/// names them.
#[derive(Clip, Clone, Debug, PartialEq, Eq, Hash)]
enum ElfClip {
    #[clip("idle")]
    Idle,
    #[clip("walk")]
    Walk,
    #[clip("jog")]
    Jog,
    #[clip("attack")]
    Attack,
    #[clip("hit")]
    Hit,
    #[clip("death")]
    Death,
    #[clip("sit_down")]
    SitDown,
    #[clip("sit")]
    Sit,
    #[clip("stand_up")]
    StandUp,
    #[clip("jump")]
    Jump,
    #[clip("dance")]
    Dance,
}

impl Mesh<NoParts, ElfClip> for Elf {
    fn build(&self, assets: &Assets) -> MeshData<NoParts, ElfClip> {
        assets.model(ELF_ROOT)
    }
}

/// What the game fills each tick to move `ElfState` on.
#[derive(Default)]
struct ElfInput {
    /// The elf's speed this tick, a fraction of [`ELF_SPEED`].
    speed: f32,
    attack: bool,
    /// True the tick a hurt patch is stepped onto and [`FATAL_HITS`] have
    /// not yet landed.
    hit: bool,
    /// True the tick a hurt patch is stepped onto the third time, which
    /// [`FATAL_HITS`] counts.
    dying: bool,
    jump: bool,
    /// True the tick `Jump`'s own height curve returns the elf to the
    /// ground after it launches.
    landed: bool,
    dance: bool,
    /// `Button::Interact`, read as sitting down, standing back up, or
    /// nothing, by the state it reaches.
    interact: bool,
    /// Whether the elf stands close enough to the cube to sit on it.
    near_seat: bool,
}

#[derive(Clone, Copy, Eq, PartialEq, Debug)]
enum ElfState {
    Idle,
    Locomotion,
    Attack,
    Hit,
    Death,
    SitDown,
    Sit,
    StandUp,
    Jump,
    Dance,
}

impl ElfState {
    /// Whether the elf is on the seat, or on its way onto or off it.
    fn seated(self) -> bool {
        matches!(self, Self::SitDown | Self::Sit | Self::StandUp)
    }

    /// `Locomotion` where `input` reads a walk or a run, `Idle` at rest:
    /// where a grounded state returns once whatever interrupted it ends.
    fn grounded(input: &ElfInput) -> Self {
        match input.speed > WALK_THRESHOLD {
            true => Self::Locomotion,
            false => Self::Idle,
        }
    }
}

impl AnimationStates for ElfState {
    type Clip = ElfClip;
    type Input = ElfInput;

    fn entry() -> Self {
        Self::Idle
    }

    fn motion(&self, input: &ElfInput) -> Motion<ElfClip> {
        match self {
            Self::Idle => Motion::looping(ElfClip::Idle),
            Self::Locomotion => {
                Motion::blend(ElfClip::Walk, ElfClip::Jog, input.speed).paced(input.speed)
            }
            Self::Attack => Motion::once(ElfClip::Attack),
            Self::Hit => Motion::once(ElfClip::Hit),
            Self::Death => Motion::once(ElfClip::Death),
            Self::SitDown => Motion::once(ElfClip::SitDown),
            Self::Sit => Motion::looping(ElfClip::Sit),
            Self::StandUp => Motion::once(ElfClip::StandUp),
            Self::Jump => Motion::once(ElfClip::Jump),
            Self::Dance => Motion::looping(ElfClip::Dance),
        }
    }

    fn next(&self, input: &ElfInput, at: Progress) -> Option<Transition<Self>> {
        match (self, input) {
            (Self::Death, _) => None,
            (_, ElfInput { dying: true, .. }) => Some(Self::Death.fade(DEATH_FADE)),
            (_, ElfInput { hit: true, .. }) if *self != Self::Hit => {
                Some(Self::Hit.fade(HIT_ENTER_FADE))
            }
            (Self::Hit, _) if at.ended() => Some(ElfState::grounded(input).fade(HIT_EXIT_FADE)),
            (Self::Attack, ElfInput { attack: true, .. }) if at.past(ATTACK_RELEASE) => Some(
                Self::Attack
                    .restarted()
                    .entering_at(ATTACK_CHAIN_ENTRY)
                    .fade(ATTACK_CHAIN_FADE),
            ),
            (Self::Attack, _) if at.past(ATTACK_RELEASE) => {
                Some(ElfState::grounded(input).fade(ATTACK_EXIT_FADE))
            }
            (Self::SitDown | Self::Sit | Self::StandUp, i) if i.speed > WALK_THRESHOLD => {
                Some(Self::Locomotion.fade(STAND_EXIT_FADE))
            }
            (Self::SitDown | Self::Sit | Self::StandUp, ElfInput { attack: true, .. }) => {
                Some(Self::Attack.fade(ATTACK_ENTER_FADE))
            }
            (Self::SitDown | Self::Sit | Self::StandUp, ElfInput { jump: true, .. }) => {
                Some(Self::Jump.fade(JUMP_ENTER_FADE))
            }
            (Self::SitDown, _) if at.ended() => Some(Self::Sit.at_once()),
            (Self::Sit, ElfInput { interact: true, .. }) => Some(Self::StandUp.fade(STAND_UP_FADE)),
            (Self::StandUp, _) if at.ended() => Some(Self::Idle.fade(STAND_EXIT_FADE)),
            (Self::Jump, ElfInput { landed: true, .. }) => {
                Some(ElfState::grounded(input).fade(JUMP_EXIT_FADE))
            }
            (Self::Jump, _) if at.ended() => Some(ElfState::grounded(input).fade(JUMP_EXIT_FADE)),
            (
                Self::Idle | Self::Locomotion,
                ElfInput {
                    interact: true,
                    near_seat: true,
                    ..
                },
            ) => Some(Self::SitDown.fade(SIT_DOWN_FADE)),
            (Self::Idle | Self::Locomotion, ElfInput { attack: true, .. }) => {
                Some(Self::Attack.fade(ATTACK_ENTER_FADE))
            }
            (Self::Idle | Self::Locomotion, ElfInput { jump: true, .. }) => {
                Some(Self::Jump.fade(JUMP_ENTER_FADE))
            }
            (Self::Idle, ElfInput { dance: true, .. }) => Some(Self::Dance.fade(DANCE_FADE)),
            (Self::Dance, i) if i.speed > WALK_THRESHOLD => {
                Some(Self::Locomotion.fade(IDLE_LOCOMOTION_FADE))
            }
            (Self::Idle, i) if i.speed > WALK_THRESHOLD => {
                Some(Self::Locomotion.fade(IDLE_LOCOMOTION_FADE))
            }
            (Self::Locomotion, i) if i.speed <= WALK_THRESHOLD => {
                Some(Self::Idle.fade(IDLE_LOCOMOTION_FADE))
            }
            _ => None,
        }
    }
}

/// A machine of one state, posed by nothing but the value it scrubs.
#[derive(Clone, Copy, Eq, PartialEq, Debug)]
enum ScrubbedState {
    SitDown,
}

/// What the game fills each tick to move `ScrubbedState` on.
#[derive(Default)]
struct ScrubbedInput {
    /// How far into sitting down the second elf reads, a fraction in
    /// `0.0..=1.0`.
    settled: f32,
}

impl AnimationStates for ScrubbedState {
    type Clip = ElfClip;
    type Input = ScrubbedInput;

    fn entry() -> Self {
        Self::SitDown
    }

    fn motion(&self, input: &ScrubbedInput) -> Motion<ElfClip> {
        Motion::scrubbed(ElfClip::SitDown, input.settled)
    }

    fn next(&self, _input: &ScrubbedInput, _at: Progress) -> Option<Transition<Self>> {
        None
    }
}

#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Butterfly;

/// The one clip `FlyingState` plays, named as the source names it.
#[derive(Clip, Clone, Debug, PartialEq, Eq, Hash)]
enum ButterflyClip {
    #[clip("fly")]
    Fly,
}

impl Mesh<NoParts, ButterflyClip> for Butterfly {
    fn build(&self, assets: &Assets) -> MeshData<NoParts, ButterflyClip> {
        assets.model(BUTTERFLY_ROOT)
    }
}

/// A machine of one state, looping the butterfly's only clip.
#[derive(Clone, Copy, Eq, PartialEq, Debug)]
enum FlyingState {
    Flying,
}

impl AnimationStates for FlyingState {
    type Clip = ButterflyClip;
    type Input = ();

    fn entry() -> Self {
        Self::Flying
    }

    fn motion(&self, _input: &()) -> Motion<ButterflyClip> {
        Motion::looping(ButterflyClip::Fly)
    }

    fn next(&self, _input: &(), _at: Progress) -> Option<Transition<Self>> {
        None
    }
}

/// The butterfly's position and the `yaw` it faces, `t` seconds into its
/// closed loop around [`BUTTERFLY_CENTER`].
fn butterfly_pose(t: f32) -> (Vec3, f32) {
    let angle = t * BUTTERFLY_ANGULAR_SPEED;
    let position = BUTTERFLY_CENTER
        + Vec3::new(
            BUTTERFLY_RADIUS.x * angle.cos(),
            BUTTERFLY_HEIGHT,
            BUTTERFLY_RADIUS.y * angle.sin(),
        );
    let direction = Vec3::new(
        -BUTTERFLY_RADIUS.x * angle.sin(),
        0.0,
        BUTTERFLY_RADIUS.y * angle.cos(),
    );
    (position, direction.x.atan2(direction.z))
}

/// How far into sitting down the second elf reads at `distance` from the
/// first.
fn settled_at(distance: f32) -> f32 {
    1.0 - (distance - SCRUB_NEAR) / (SCRUB_FAR - SCRUB_NEAR)
}

/// A camera [`CAMERA_BACK`] behind and [`CAMERA_UP`] above `target`, tilted
/// `pitch` radians and turned `yaw` radians around it, looking at a point
/// [`CAMERA_LOOK_HEIGHT`] above `target`.
fn orbit_camera(target: Vec3, yaw: f32, pitch: f32) -> Camera {
    let look_at = target + Vec3::Y * CAMERA_LOOK_HEIGHT;
    let base = Vec3::new(0.0, CAMERA_UP, CAMERA_BACK);
    let offset = Quat::from_rotation_y(yaw) * (Quat::from_rotation_x(pitch) * base);
    Camera::new(
        View::look_at(look_at + offset, look_at),
        Projection::perspective(CAMERA_FOV),
    )
}

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

#[derive(InputButtonAction, Clone, Copy)]
enum Button {
    Run,
    Attack,
    Jump,
    Dance,
    Interact,
    Restart,
    Hold,
    Release,
}

impl InputButtonAction for Button {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Button::Run => vec![Key::LeftShift.into()],
            Button::Attack => vec![Key::F.into()],
            Button::Jump => vec![Key::Space.into()],
            Button::Dance => vec![Key::N.into()],
            Button::Interact => vec![Key::E.into()],
            Button::Restart => vec![Key::R.into()],
            Button::Hold => vec![MouseButton::Left.into()],
            Button::Release => vec![Key::Escape.into()],
        }
    }
}

/// The camera's own controls: turned and tilted by how far the pointer
/// moves sideways and upward each tick.
#[derive(InputAxisAction, Clone, Copy)]
enum Axis {
    CameraYaw,
    CameraPitch,
}

impl InputAxisAction for Axis {
    fn bindings(&self) -> Vec<AxisBinding> {
        match self {
            Axis::CameraYaw => {
                vec![AxisBinding::pointer_delta(PointerDelta::Sideways).scale(CAMERA_YAW_SCALE)]
            }
            Axis::CameraPitch => {
                vec![AxisBinding::pointer_delta(PointerDelta::Up).scale(CAMERA_PITCH_SCALE)]
            }
        }
    }
}

#[derive(InputAxis2Action, Clone, Copy)]
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,
                }),
            ],
        }
    }
}

struct Controls;

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

/// `text` in [`PANEL_TEXT_COLOR`].
fn panel_text(text: impl Into<String>) -> egui::RichText {
    egui::RichText::new(text.into()).color(PANEL_TEXT_COLOR)
}

struct Scene {
    elf_pos: Vec3,
    elf_prev: Vec3,
    elf_yaw: f32,
    /// Height the elf is lifted over the ground while off the ground,
    /// integrated in [`Game::tick`] from [`Self::jump_speed`].
    elf_height: f32,
    elf_height_prev: f32,
    /// The elf's own vertical speed while off the ground, in meters a
    /// second, positive upward.
    jump_speed: f32,
    elf_input: ElfInput,
    elf_animator: Animator<Elf, ElfState>,
    scrubbed_animator: Animator<Elf, ScrubbedState>,
    butterfly_animator: Animator<Butterfly, FlyingState>,
    hits: u32,
    /// True while a hurt patch already held the elf, so leaving and
    /// returning to the same patch counts as a new hit.
    in_patch: bool,
    /// Whether the pointer is held; a click takes it, escape frees it.
    holding: bool,
    /// The camera's turn around the elf, and its tilt, both in radians.
    camera_yaw: f32,
    camera_pitch: f32,
    /// The last state change the panel names.
    last_event: &'static str,
}

impl Scene {
    fn init(_ctx: &mut InitContext<'_, Scene>) -> Result<Self, Error> {
        Ok(Self {
            elf_pos: ELF_START,
            elf_prev: ELF_START,
            elf_yaw: 0.0,
            elf_height: 0.0,
            elf_height_prev: 0.0,
            jump_speed: 0.0,
            elf_input: ElfInput::default(),
            elf_animator: Animator::new(),
            scrubbed_animator: Animator::new(),
            butterfly_animator: Animator::new(),
            hits: 0,
            in_patch: false,
            holding: false,
            camera_yaw: 0.0,
            camera_pitch: 0.0,
            last_event: "none yet",
        })
    }

    /// Turns the camera by how far the pointer moves sideways and upward,
    /// [`CAMERA_PITCH_RANGE`] holding how far it tilts.
    fn steer_camera(&mut self, ctx: &mut FrameContext<'_, Scene>) {
        self.camera_yaw -= ctx.axis(Axis::CameraYaw);
        self.camera_pitch = (self.camera_pitch + ctx.axis(Axis::CameraPitch))
            .clamp(CAMERA_PITCH_RANGE.start, CAMERA_PITCH_RANGE.end);
    }

    /// Turns `elf_yaw` toward the heading `ctx` reads, relative to the
    /// camera's own turn, and moves `elf_pos` along it; the speed it moves
    /// at, a fraction of [`ELF_SPEED`], held at [`WALK_CAP`] until
    /// `Button::Run` is held.
    fn advance(&mut self, ctx: &mut TickContext<'_, Scene>) -> f32 {
        let control = ctx.axis2(Move::Walk).clamp_length_max(1.0);
        let turn = Quat::from_rotation_y(self.camera_yaw);
        let heading = turn * Vec3::X * control.x + turn * Vec3::NEG_Z * control.y;
        let dt = ctx.dt().as_secs_f32();
        if let Some(direction) = heading.try_normalize() {
            let wanted = direction.x.atan2(direction.z);
            let turn = (wanted - self.elf_yaw + core::f32::consts::PI).rem_euclid(TAU)
                - core::f32::consts::PI;
            self.elf_yaw += turn.clamp(-TURN_RATE * dt, TURN_RATE * dt);
        }
        let cap = if ctx.down(Button::Run) { 1.0 } else { WALK_CAP };
        self.elf_pos += heading * cap * ELF_SPEED * dt;
        heading.length() * cap
    }

    /// Integrates [`Self::elf_height`] under [`GRAVITY`] from
    /// [`Self::jump_speed`], held at the ground; `true` the tick it
    /// returns there from above it.
    fn fall(&mut self, dt: f32) -> bool {
        let off_ground = self.elf_height > 0.0;
        self.jump_speed -= GRAVITY * dt;
        self.elf_height = (self.elf_height + self.jump_speed * dt).max(0.0);
        if self.elf_height == 0.0 {
            self.jump_speed = 0.0;
        }
        off_ground && self.elf_height == 0.0
    }

    /// The hurt patch `elf_pos` stands inside, if any.
    fn patch_underfoot(&self) -> Option<Vec3> {
        HURT_PATCHES
            .into_iter()
            .find(|&patch| self.elf_pos.distance(patch) < HURT_RADIUS)
    }

    /// Reads the controls and moves the elf, filling [`Self::elf_input`]
    /// for [`ElfState`] to read.
    fn tick_elf(&mut self, ctx: &mut TickContext<'_, Scene>) {
        let grounded = matches!(
            self.elf_animator.state(),
            ElfState::Idle | ElfState::Locomotion
        );

        self.elf_input.speed = self.advance(ctx);
        self.elf_input.attack = ctx.pressed(Button::Attack);
        self.elf_input.jump = ctx.pressed(Button::Jump);
        self.elf_input.dance = ctx.pressed(Button::Dance);

        self.elf_input.near_seat = self.elf_pos.distance(SEAT_POSITION) < SEAT_INTERACT_RADIUS;
        self.elf_input.interact = ctx.pressed(Button::Interact);
        if self.elf_input.interact && grounded && self.elf_input.near_seat {
            self.elf_pos = SEAT_SPOT;
            self.elf_yaw = SEAT_FACING;
        }

        let underfoot = self.patch_underfoot();
        let entered_patch = underfoot.is_some() && !self.in_patch;
        self.in_patch = underfoot.is_some();
        self.hits += u32::from(entered_patch);
        self.elf_input.hit = entered_patch && self.hits < FATAL_HITS;
        self.elf_input.dying = entered_patch && self.hits >= FATAL_HITS;
        if entered_patch {
            self.last_event = match self.elf_input.dying {
                true => "elf died",
                false => "elf hit",
            };
        }
    }

    /// Starts a new [`Animator`] over the elf's own state, its position and
    /// hit count reset with it.
    fn restart_elf(&mut self) {
        self.elf_animator = Animator::new();
        self.elf_pos = ELF_START;
        self.elf_prev = ELF_START;
        self.elf_yaw = 0.0;
        self.elf_height = 0.0;
        self.elf_height_prev = 0.0;
        self.jump_speed = 0.0;
        self.elf_input = ElfInput::default();
        self.hits = 0;
        self.in_patch = false;
        self.last_event = "new elf started";
    }

    fn panel(&self, ctx: &mut FrameContext<'_, Scene>) {
        let state = match self.elf_animator.state() {
            ElfState::Idle => "idle",
            ElfState::Locomotion if self.elf_input.speed > WALK_CAP => "running",
            ElfState::Locomotion => "walking",
            ElfState::Attack => "attacking",
            ElfState::Hit => "hit",
            ElfState::Death => "dead",
            ElfState::SitDown => "sitting down",
            ElfState::Sit => "sitting",
            ElfState::StandUp => "standing up",
            ElfState::Jump => "jumping",
            ElfState::Dance => "dancing",
        };
        ctx.ui(|ui| {
            egui::Frame::new()
                .fill(egui::Color32::from_black_alpha(PANEL_BACKDROP))
                .inner_margin(PANEL_PADDING)
                .corner_radius(f32::from(PANEL_PADDING))
                .show(ui, |ui| {
                    ui.heading(panel_text(format!("elf is {state}")));
                    ui.label(panel_text(format!(
                        "hits taken {} of the {} red patches hurt for, {}",
                        self.hits, FATAL_HITS, self.last_event
                    )));
                    ui.label(panel_text(match self.elf_animator.transitioning() {
                        true => "fading between clips",
                        false => "one clip playing",
                    }));
                    ui.add_space(f32::from(PANEL_PADDING));
                    egui::Grid::new("controls").show(ui, |ui| {
                        for (key, does) in CONTROLS {
                            ui.label(panel_text(key));
                            ui.label(panel_text(does));
                            ui.end_row();
                        }
                    });
                });
        });
    }

    /// A prompt over the seat, each hurt patch, and the scrubbed elf,
    /// naming what a player finds there; the seat's own prompt names the
    /// live binding of `Button::Interact` by its own name, not one fixed
    /// in the code, and is absent while the elf sits on it.
    fn draw_prompts(&self, ctx: &mut FrameContext<'_, Scene>, camera: Camera) {
        let sit_key = ctx
            .bindings(Button::Interact)
            .into_iter()
            .next()
            .map_or_else(|| "interact".to_owned(), |binding| binding.to_string());
        let sit = ctx.text_layout(
            &format!("{sit_key} sits"),
            egui::FontId::proportional(PROMPT_SIZE),
        );
        let hurts = ctx.text_layout("hurts", egui::FontId::proportional(PROMPT_SIZE));
        let walk_closer = ctx.text_layout("walk closer", egui::FontId::proportional(PROMPT_SIZE));

        let mut prompts = vec![(
            SCRUBBED_ELF_POSITION + Vec3::Y * (ELF_HEIGHT + PROMPT_LIFT),
            walk_closer,
        )];
        if !self.elf_animator.state().seated() {
            prompts.push((
                SEAT_POSITION + Vec3::Y * (SEAT_HEAD_HEIGHT + PROMPT_LIFT),
                sit,
            ));
        }
        prompts.extend(HURT_PATCHES.map(|patch| (patch + Vec3::Y * PROMPT_LIFT, hurts.clone())));

        let window_size = ctx.window_size();
        let pixels_per_point = ctx.pixels_per_point();
        ctx.ui(|ui| {
            let painter = ui.painter();
            for (point, galley) in prompts {
                let Some(pixel) = camera.pixel_of(point, window_size) else {
                    continue;
                };
                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(PROMPT_PADDING * 2.0),
                );
                painter.rect_filled(
                    backdrop,
                    PROMPT_PADDING,
                    egui::Color32::from_black_alpha(PANEL_BACKDROP),
                );
                painter.galley(pos, galley, PANEL_TEXT_COLOR);
            }
        });
    }
}

impl Game for Scene {
    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<'_, Scene>) {
        self.elf_prev = self.elf_pos;
        self.elf_height_prev = self.elf_height;

        if ctx.pressed(Button::Restart) {
            self.restart_elf();
        }
        if ctx.pressed(Button::Hold) {
            self.holding = true;
        }
        if ctx.pressed(Button::Release) {
            self.holding = false;
        }

        self.elf_input.landed = self.fall(ctx.dt().as_secs_f32());
        self.tick_elf(ctx);
        ctx.animate(Elf, &mut self.elf_animator, &self.elf_input);

        if self.elf_animator.entered(ElfState::Jump) {
            self.jump_speed = JUMP_LAUNCH_SPEED;
        }
        if self.elf_animator.left(ElfState::StandUp) {
            self.last_event = "elf stood up";
        }
        if self.elf_animator.entered(ElfState::Sit) {
            self.last_event = "elf sat down";
        }
        if self.elf_animator.entered(ElfState::Death) {
            self.last_event = "elf died";
        }

        let scrubbed_input = ScrubbedInput {
            settled: settled_at(self.elf_pos.distance(SCRUBBED_ELF_POSITION)),
        };
        ctx.animate(Elf, &mut self.scrubbed_animator, &scrubbed_input);
        ctx.animate(Butterfly, &mut self.butterfly_animator, &());
    }

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

        let alpha = ctx.alpha();
        let elf_pos = self.elf_prev.lerp(self.elf_pos, alpha);
        let elf_height = self.elf_height_prev + (self.elf_height - self.elf_height_prev) * alpha;
        let (butterfly_pos, butterfly_yaw) = butterfly_pose(ctx.elapsed().as_secs_f32());

        let camera = orbit_camera(elf_pos, self.camera_yaw, self.camera_pitch);
        ctx.set_camera(camera);
        ctx.set_cursor(if self.holding {
            Cursor::Held
        } else {
            Cursor::Arrow
        });
        ctx.set_skybox(Sky::Day);
        ctx.set_exposure(3.0);
        ctx.set_bloom(0.2);
        ctx.light(Light::directional(SUN_DIRECTION, SUN_COLOR).shadow());
        ctx.light(
            Light::point(
                LAMP_POST_POSITION + Vec3::Y * (LAMP_POST_HEIGHT + LAMP_HEAD_GAP * 0.5),
                LAMP_LIGHT_COLOR,
                LAMP_LIGHT_RANGE,
            )
            .shadow(),
        );
        ctx.light(
            Light::spot(Spot {
                position: SPOT_POSITION,
                direction: SPOT_DIRECTION,
                color: SPOT_COLOR,
                range: SPOT_RANGE,
                angle: SPOT_ANGLE,
            })
            .shadow(),
        );
        ctx.light(
            Light::point(butterfly_pos, BUTTERFLY_LIGHT_COLOR, BUTTERFLY_LIGHT_RANGE).shadow(),
        );

        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR)),
        );
        for patch in HURT_PATCHES {
            ctx.draw(
                Plane
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(HURT_RADIUS * 2.0),
                        Quat::IDENTITY,
                        patch,
                    ))
                    .material(Material::lit(HURT_COLOR)),
            );
        }
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(SEAT_FOOTPRINT, SEAT_HEIGHT, SEAT_FOOTPRINT),
                Quat::IDENTITY,
                SEAT_POSITION + Vec3::Y * SEAT_HEIGHT * 0.5,
            ))
            .material(Material::lit(SEAT_COLOR)),
        );
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(LAMP_POST_THICKNESS, LAMP_POST_HEIGHT, LAMP_POST_THICKNESS),
                Quat::IDENTITY,
                LAMP_POST_POSITION + Vec3::Y * LAMP_POST_HEIGHT * 0.5,
            ))
            .material(Material::lit(LAMP_POST_COLOR)),
        );
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::splat(LAMP_HEAD_SIZE),
                Quat::IDENTITY,
                LAMP_POST_POSITION
                    + Vec3::Y * (LAMP_POST_HEIGHT + LAMP_HEAD_GAP + LAMP_HEAD_SIZE * 0.5),
            ))
            .material(Material::color(Color::BLACK).emissive(LAMP_LIGHT_COLOR)),
        );
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::splat(SPOT_FIXTURE_SIZE),
                Quat::IDENTITY,
                SPOT_POSITION + Vec3::Y * SPOT_FIXTURE_SIZE * 0.5,
            ))
            .material(Material::lit(SPOT_FIXTURE_COLOR)),
        );

        ctx.draw(
            Elf.at(Transform::from_rotation_translation(
                Quat::from_rotation_y(self.elf_yaw),
                elf_pos + Vec3::Y * elf_height,
            ))
            .posed(&self.elf_animator),
        );
        ctx.draw(
            Elf.at(Transform::from_rotation_translation(
                Quat::from_rotation_y(core::f32::consts::PI),
                SCRUBBED_ELF_POSITION,
            ))
            .posed(&self.scrubbed_animator),
        );
        ctx.draw(
            Butterfly
                .at(Transform::from_rotation_translation(
                    Quat::from_rotation_y(butterfly_yaw),
                    butterfly_pos,
                ))
                .posed(&self.butterfly_animator)
                .material(Material::lit(Color::WHITE).emissive(BUTTERFLY_EMISSIVE)),
        );

        self.draw_prompts(ctx, camera);
        self.panel(ctx);
    }

examples/sprite-adventure.rs (line 152)

const PLAYER_SPAWN: Vec3 = Vec3::new(0.0, 0.0, 5.0);
const CAVE_MOUTH: Vec3 = Vec3::new(0.0, 0.0, -6.0);
/// Landing position for a return from the cave: past the [`ENTRANCE`] band,
/// so the return does not count as another step through the mouth.
const RETURN_SPAWN: Vec3 = Vec3::new(
    CAVE_MOUTH.x,
    0.0,
    CAVE_MOUTH.z + MOUTH_CROSSING_INSET + PORTAL_CLEARANCE,
);

/// The pond's position and half the side of it: the shoreline sprite is
/// three meters square, the sixteen texels to the meter the game keeps. The
/// styled water is drawn barely off the ground, clear of z-fighting with it; the
/// shore draws at the ground's own `y` instead, submitted after it, so
/// submission order alone separates the two and the shore never shadows the
/// ground it lies on.
const POND_CENTER: Vec3 = Vec3::new(4.2, 0.01, -1.5);
const POND_HALF: f32 = 1.5;
/// Half the open water that sprite's shoreline rings — the middle three
/// fifths of its side, both drawn styled and blocking the player: the square
/// stops well inside the shore, so its own edges never show.
const POND_WATER_HALF: f32 = POND_HALF * 0.6;
const WATER_COLOR: Color = Color::rgba(0.06, 0.20, 0.27, 0.92);
const WATER_LITNESS: f32 = 0.45;

/// Footprint and turn of the two crates beside the spawn: far enough apart
/// that neither turned box overlaps the other, and clear of the path's verge.
const CRATE_POSITIONS: [(f32, f32, f32); 2] = [(-2.7, 3.5, 0.5), (-1.2, 2.6, -0.3)];
const CRATE_SIZE: f32 = 1.0;
const WELL_POSITION: Vec3 = Vec3::new(2.6, 0.0, 3.2);
/// The well's rim: width, height, depth in meters, as wide as the two tiles
/// its mouth is drawn from.
const WELL_SIZE: Vec3 = Vec3::new(2.0, 0.6, 2.0);
/// Mouth lift over the rim's top face, clear of z-fighting.
const WELL_MOUTH_LIFT: f32 = 0.01;

/// Flora position: `x, z`, and whether it is a rock rather than a bush.
const FLORA: [(f32, f32, bool); 6] = [
    (-4.2, 1.4, false),
    (-4.8, -1.8, true),
    (5.8, 2.6, false),
    (6.6, -1.0, false),
    (3.2, -4.8, true),
    (-2.2, -5.0, true),
];
/// Both sprites are two tiles wide — the tileset's own sixteen texels to
/// the meter, as the ground and player. Height matches each one's own
/// cropped sheet, so its visible size stays the same.
const BUSH_WIDTH: f32 = 2.0;
const BUSH_HEIGHT: f32 = 1.9375;
const ROCK_WIDTH: f32 = 2.0;
const ROCK_HEIGHT: f32 = 1.875;
/// Each one's block: the base under the sprite, well inside the two meters
/// it is drawn across — a bush's stems, a rock's foot.
const BUSH_FOOTPRINT: f32 = 0.6;
const ROCK_FOOTPRINT: f32 = 0.8;

/// The bush rows that ring the clearing, hiding where the ground tiles stop:
/// an inner and an outer half-extent in meters, the step along each side,
/// and the gap left either side of the path.
const HEDGE_INNER_HALF: f32 = 10.4;
const HEDGE_OUTER_HALF: f32 = 11.8;
const HEDGE_STEP: f32 = 1.4;
const HEDGE_GATE_HALF: f32 = 2.2;

/// Walkable extent of the clearing: to the inner hedge row's near face, so
/// the bushes the player can see are the wall.
const CLEARING_HALF: f32 = HEDGE_INNER_HALF - BUSH_WIDTH * 0.5;

/// The mouth's flanking pillars, half this far either side of its center,
/// and the dark opening drawn between them.
const MOUTH_PILLAR_OFFSET: f32 = 1.1;
/// Width, height and depth of each of those pillars: the whole stone sheet
/// at its own texels to the meter, so the capital lands where a capital
/// goes.
const MOUTH_PILLAR_SIZE: Vec3 = Vec3::new(1.0, STONE_ROWS as f32 * TILE_SIZE, 1.0);
/// Whole tiles the stone across the pillars runs: enough to end
/// past both of them, so no face of it lands in either pillar, and a
/// whole number so its masonry repeats without a part course.
const MOUTH_LINTEL_TILES: f32 = 4.0;
/// That stone's own size: those tiles across, one course tall, and deeper
/// than the pillars.
const MOUTH_LINTEL_SIZE: Vec3 = Vec3::new(
    MOUTH_LINTEL_TILES * TILE_SIZE,
    TILE_SIZE,
    MOUTH_PILLAR_SIZE.z + 0.1,
);
/// Height of the dark between the pillars, drawn up into the lintel, so a
/// camera looking down finds stone over it rather than the ground behind.
const MOUTH_DARK_HEIGHT: f32 = MOUTH_PILLAR_SIZE.y + MOUTH_LINTEL_SIZE.y * 0.5;
/// Half the clear opening between the pillars' inner faces.
const MOUTH_OPENING_HALF: f32 = MOUTH_PILLAR_OFFSET - MOUTH_PILLAR_SIZE.x * 0.5;
/// Distance in front of a mouth for the plane that stepping through its
/// opening crosses.
const MOUTH_CROSSING_INSET: f32 = 0.1;
/// Distance past that plane a portal lands the player.
const PORTAL_CLEARANCE: f32 = 0.8;

/// The overworld's mouth into the cave, and the one at the cave's near end
/// that leads back out.
const ENTRANCE: Mouth = Mouth {
    at: CAVE_MOUTH,
    room_side: 1.0,
};
const EXIT: Mouth = Mouth {
    at: CAVE_EXIT,
    room_side: -1.0,
};

const SUN_COLOR: Color = Color::rgb(0.92, 0.87, 0.72);
/// The sun's direction: low enough that props cast shadows about their own
/// length, and from over the player's left shoulder, which is where the
/// tileset's own sprites are shaded from.
const SUN_DIRECTION: Vec3 = Vec3::new(0.6, -0.75, 0.4);

// ---------------------------------------------------------------------
// Cave layout
// ---------------------------------------------------------------------

const CAVE_HALF_WIDTH: f32 = 4.0;
/// Room tiling and walls toward the camera, past the wall closing it: under
/// the bottom corners of the frame, wherever the player walks.
const CAVE_NEAR_Z: f32 = 10.0;
const CAVE_FAR_Z: f32 = -6.0;
/// Walkable extent of the room at its far end: the back wall's inner face,
/// less the player's own half-width, so the sprite stops flush against
/// stone.
const CAVE_WALK_FAR_Z: f32 = CAVE_FAR_Z + TILE_SIZE * 0.5 + WALKER_WIDTH * 0.5;
/// Walkable extent at the room's near end: past the plane stepping out
/// crosses, so the last step through the mouth is never clamped away. The
/// near wall itself is what keeps the player from the ledge beyond.
const CAVE_WALK_NEAR_Z: f32 = CAVE_EXIT.z + PLAYER_RADIUS;
/// As many meters as the wall face is tiles tall, so it samples the sheet
/// at the floor's own texels to the meter.
const WALL_HEIGHT: f32 = 3.0;
/// Wall height: over the camera, so it neither looks over them nor down onto
/// their tops.
const WALL_TOP: f32 = CAVE_CAMERA_OFFSET.y + TILE_SIZE * 0.5;
/// Courses that takes; the last one is cut to what is left of it.
const WALL_COURSES: i32 = (WALL_TOP / WALL_HEIGHT) as i32 + 1;
/// The tile row the room's near end is closed along, from each side wall to
/// the mouth in it.
const CAVE_LIP_Z: f32 = 5.0;
/// Height of that wall: one tile, so its top face is at the floor's own
/// texels to the meter, and low enough that it never hides the player.
const CAVE_LIP_HEIGHT: f32 = TILE_SIZE;
/// The cave's own mouth position: in the near wall, its pillars half their
/// depth past it.
const CAVE_EXIT: Vec3 = Vec3::new(0.0, 0.0, CAVE_LIP_Z + MOUTH_PILLAR_SIZE.z * 0.5);
/// Landing position for an entry into the cave: past the [`EXIT`] band, so
/// the entry does not count as another step through the mouth.
const CAVE_SPAWN: Vec3 = Vec3::new(
    CAVE_EXIT.x,
    0.0,
    CAVE_EXIT.z - MOUTH_CROSSING_INSET - PORTAL_CLEARANCE,
);

const DOOR_Z: f32 = 0.0;
/// The near face of the wall the door hangs in: past it the wall is
/// between the camera and the player, and is drawn through.
const DOOR_WALL_NEAR_Z: f32 = DOOR_Z + TILE_SIZE * 0.5;
/// Alpha for that wall and its door once the player has been behind them
/// for [`GHOST_RAMP_TICKS`]: opaque enough for stone in a dark room,
/// translucent enough for the chamber and the player to show through.
const GHOST_ALPHA: f32 = 0.6;
/// The fade of a draw nothing is seen through.
const SOLID: f32 = 1.0;
/// Ticks the wall and door take to fade between [`SOLID`] and
/// [`GHOST_ALPHA`].
const GHOST_RAMP_TICKS: u32 = 6;
/// Span either side of the player the wall is drawn through: wide enough for
/// the sight line to the player, no wider, so no more of the light the
/// stone holds off the chamber passes through it than that line needs.
const GHOST_CORRIDOR_HALF: f32 = 1.5;
/// The door's hinge: `tools/keep_fixture.py`'s box is hinged at its own
/// local origin and spans [`DOOR_WIDTH`] along local `+X`.
const DOOR_HINGE: Vec3 = Vec3::new(-DOOR_WIDTH * 0.5, 0.0, DOOR_Z);
/// Width of that box, as the fixture builds it.
const DOOR_WIDTH: f32 = 1.0;
/// Thickness of it, as the fixture builds it.
const DOOR_THICKNESS: f32 = 0.12;
/// Height of it, as the fixture builds it: the stone over the doorway starts
/// here.
const DOOR_HEIGHT: f32 = 1.9;
/// Half the doorway the door hangs in: one tile wide, on the room's axis.
const DOORWAY_HALF: f32 = TILE_SIZE * 0.5;
/// Span from that axis of the wall the door hangs in: to the side walls'
/// inner faces.
const DOOR_WALL_END: f32 = CAVE_HALF_WIDTH + TILE_SIZE * 0.5;
const INTERACT_POINT: Vec3 = Vec3::new(0.0, 0.0, DOOR_Z);
const INTERACT_RADIUS: f32 = 1.8;

/// The door slab's own color, a deep red the cave's grey stone never is, so
/// the slab reads as a door rather than more wall.
const DOOR_COLOR: Color = Color::rgb(0.58, 0.16, 0.09);
const DOOR_LITNESS: f32 = 0.85;
/// Thickness of the posts and lintel framing the doorway, and how far in
/// front of the wall face they stand, clear of z-fighting with it.
const DOOR_FRAME_THICKNESS: f32 = 0.14;
const DOOR_FRAME_STANDOFF: f32 = 0.03;
/// The frame's own color, visible from the cave's own spawn well before a
/// torch reaches the doorway.
const DOOR_FRAME_COLOR: Color = Color::rgb(0.85, 0.55, 0.2);
const DOOR_FRAME_LITNESS: f32 = 0.9;
/// The frame's own light while the door is closed and within
/// [`INTERACT_RADIUS`]: the cue that it can be opened.
const DOOR_FRAME_GLOW: Color = Color::rgb(1.6, 0.9, 0.35);

const GEM_POSITION: Vec3 = Vec3::new(0.0, 0.5, -4.6);
const GEM_BOB_HEIGHT: f32 = 0.12;
const GEM_SPIN_SPEED: f32 = 1.4;
const PICKUP_RADIUS: f32 = 1.0;
const GEM_COLOR: Color = Color::rgb(0.35, 0.95, 0.85);
/// The gem's own light: what lights the chamber until the door opens on the
/// torches, and gone with the gem once it is taken.
const GEM_LIGHT_COLOR: Color = Color::rgb(0.3, 0.85, 0.78);
/// Reach of it: short of the door wall, so what the wall casts never depends
/// on the gem.
const GEM_LIGHT_RANGE: f32 = 4.0;
/// Lift over the gem, clear of the gem's own facets, which would otherwise
/// shadow the chamber from inside it.
const GEM_LIGHT_LIFT: f32 = 0.7;

/// The two torches' position, `x, z`: flanking the doorway on the near side
/// of the wall, the side the player arrives on.
const TORCH_POSITIONS: [(f32, f32); 2] = [(-3.0, 0.6), (3.0, 0.6)];
const TORCH_STAND_HEIGHT: f32 = 2.0;
/// Thickness of a torch's post: the four texels the sprite draws it as,
/// which is also what it blocks the player as.
const TORCH_STAND_WIDTH: f32 = 0.25;
/// Width of the sprite around that post: its canvas is twice the post,
/// transparent either side.
const TORCH_SPRITE_WIDTH: f32 = TORCH_STAND_WIDTH * 2.0;
const TORCH_LIGHT_RANGE: f32 = 10.0;
/// Height above its flame a torch's light is placed, and how far it is
/// offset from the post toward the room: straight over the post, its own face
/// turns edge-on to the light and goes dark.
const TORCH_LIGHT_LIFT: f32 = 0.7;
const TORCH_LIGHT_STANDOFF: f32 = 0.8;
const TORCH_LIGHT_COLOR: Color = Color::rgb(1.0, 0.6, 0.28);
/// Size of one cell of the flame's loop: a tile, as everything else the
/// tilesets draw.
const FLAME_SIZE: f32 = TILE_SIZE;
/// Lift of the flame's center over the post's top: its own half-height, less
/// the overlap that keeps the two from parting.
const FLAME_LIFT: f32 = FLAME_SIZE * 0.5 - 0.1;
/// The flame's tint, past `1.0`: an additive draw's tint scales its sampled
/// texel, so this lifts the flame's own lit texels out of the cave's dark
/// without a flat color added over its dark, unlit base.
const FLAME_TINT: Color = Color::rgb(2.2, 1.5, 0.7);
/// Speed the loop runs, in cells a second.
const FLAME_RATE: f32 = 12.0;
/// Speed the flicker runs, and how far it lifts and rolls the flame.
const FLAME_FLICKER_SPEED: f32 = 9.0;
const FLAME_BOB: f32 = 0.03;
const FLAME_ROLL: f32 = 0.12;

/// How much dark the overlay puts behind its lines, and how far that dark
/// extends past them — the ground under it is bright enough to hide bare text
/// without it.
const HUD_BACKDROP: u8 = 200;
const HUD_PADDING: i8 = 8;

/// Ticks the door's own world prompt still reads as it swings once opened,
/// after which it is taken as open and the prompt drops.
const DOOR_SWING_TICKS: u32 = 24;
/// Size the door's world prompt reads at, in logical points, and how far
/// over the doorway it is lifted.
const DOOR_PROMPT_SIZE: f32 = 15.0;
const DOOR_PROMPT_LIFT: f32 = 0.3;
/// Margin the prompt's own backdrop keeps past its galley, in logical
/// points, and how much dark that backdrop puts behind the text.
const DOOR_PROMPT_PADDING: f32 = 4.0;
const DOOR_PROMPT_BACKDROP: u8 = 190;
const DOOR_PROMPT_COLOR: egui::Color32 = egui::Color32::from_gray(230);

const CAMERA_FOV: f32 = 45.0;
/// Both cameras look down about forty degrees: shallow enough that the
/// upright sprites keep close to their full height on screen.
const OVERWORLD_CAMERA_OFFSET: Vec3 = Vec3::new(0.0, 9.0, 11.0);
const CAVE_CAMERA_OFFSET: Vec3 = Vec3::new(0.0, 6.5, 7.5);

// ---------------------------------------------------------------------
// Collision footprints
// ---------------------------------------------------------------------

/// Excess reach of a square box turned `turn` about `+Y`, along either
/// ground axis, as a factor of its side.
fn turned_span(turn: f32) -> f32 {
    turn.cos().abs() + turn.sin().abs()
}

/// One drawn prop's block: its footprint in the `x, z` the player walks.
///
/// Everything drawn on the ground is one — a box at its own extents,
/// an upright sprite at the base under it. Pickups, flames, and whatever a
/// clamp already holds — the hedgerow, the cave's own walls — are not.
#[derive(Clone, Copy)]
struct Obstacle {
    center: Vec2,
    half: Vec2,
}

impl Obstacle {
    /// The footprint of a box `size` across centered on `at`, both
    /// in the `x, z` the player walks.
    fn footprint(at: Vec2, size: Vec2) -> Self {
        Self {
            center: at,
            half: size * 0.5,
        }
    }

    /// The footprint that just covers `corners` — what a prop the game turns
    /// blocks the player as.
    fn over(corners: [Vec2; 4]) -> Self {
        let [first, rest @ ..] = corners;
        let low = rest.iter().fold(first, |low, &corner| low.min(corner));
        let high = rest.iter().fold(first, |high, &corner| high.max(corner));

        Self {
            center: (low + high) * 0.5,
            half: (high - low) * 0.5,
        }
    }

    /// Result of pushing a circle of `radius` at `point` out of this obstacle
    /// the shortest way; `point` itself when it is already clear.
    fn push_out(self, point: Vec2, radius: f32) -> Vec2 {
        let delta = point - self.center;
        let escape = self.half + Vec2::splat(radius) - delta.abs();

        if escape.min_element() <= 0.0 {
            point
        } else if escape.x < escape.y {
            let x = self.center.x + delta.x.signum() * (self.half.x + radius);
            Vec2::new(x, point.y)
        } else {
            let z = self.center.y + delta.y.signum() * (self.half.y + radius);
            Vec2::new(point.x, z)
        }
    }
}

/// A cave mouth's opening: where it is, and which way along `Z` the room
/// it leads out of lies.
#[derive(Clone, Copy)]
struct Mouth {
    at: Vec3,
    room_side: f32,
}

impl Mouth {
    /// True where `position` lies between the pillars and past the plane
    /// in front of the opening — where the only two outcomes are stepping
    /// through and being held.
    fn holds(&self, position: Vec3) -> bool {
        let plane = self.at.z + self.room_side * MOUTH_CROSSING_INSET;

        (position.x - self.at.x).abs() < MOUTH_OPENING_HALF
            && (plane - position.z) * self.room_side > 0.0
    }

    /// Position of each of the two pillars flanking the opening.
    fn pillars(&self) -> impl Iterator<Item = Vec3> + Clone {
        let at = self.at;

        SIDES
            .into_iter()
            .map(move |side| at + Vec3::X * (side * MOUTH_PILLAR_OFFSET))
    }

    /// True when the camera looks into this mouth: it always lies on `+Z`
    /// of the player, so the mouth whose room lies that way is the one seen
    /// from the room's side, and the one to fill with a lintel and the dark
    /// under it. The other is looked through from behind, and leaves its
    /// opening clear for the room to show through.
    fn looked_into(&self) -> bool {
        self.room_side > 0.0
    }
}

// ---------------------------------------------------------------------
// The water style
// ---------------------------------------------------------------------

/// The pond's whole look, over the one value it reads: how far its ripple
/// has traveled.
#[derive(Default, ShaderValues)]
struct Water {
    time: f32,
}

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

surface_styles! { enum Looks { Water } }

// ---------------------------------------------------------------------
// Meshes
// ---------------------------------------------------------------------

/// The player's current area; never both drawn in one frame.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Area {
    Overworld,
    Cave,
}

/// The overworld's ground tile, its texture the only thing that separates a
/// draw of it from another.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Ground;

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

/// The shoreline sprite laid over the pond's styled water, cutout so the
/// water shows through its cleared middle.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Shore;

impl Mesh for Shore {
    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())
    }
}

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

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

    /// The player: upright so it always faces the camera about `+Y`,
    /// windowed to its facing's row and the walk cycle's current frame.
    fn draw_walker(&self, ctx: &mut FrameContext<'_, Keep>, ground: Vec3) {
        let step = if self.walk_ticks > 0 {
            (self.walk_ticks / TICKS_PER_WALK_FRAME) % WALKER_COLUMNS
        } else {
            0
        };
        let cell = Sheet::new(UVec2::new(WALKER_COLUMNS, WALKER_ROWS))
            .cell_at(UVec2::new(step, self.facing as u32));
        let size = Vec2::new(WALKER_WIDTH, WALKER_HEIGHT);

        ctx.draw(
            Walker
                .at(Transform::from_scale_rotation_translation(
                    size.extend(1.0),
                    Quat::IDENTITY,
                    ground + Vec3::Y * (WALKER_HEIGHT * 0.5),
                ))
                .upright()
                .frame(cell),
        );
    }

    fn frame_overworld(&mut self, ctx: &mut FrameContext<'_, Keep>) {
        let drawn_at = self.previous.lerp(self.position, ctx.alpha());
        ctx.set_camera(Self::camera(drawn_at, OVERWORLD_CAMERA_OFFSET));
        ctx.light(Light::directional(SUN_DIRECTION, SUN_COLOR).shadow());

        self.draw_ground(ctx);
        self.draw_hedgerow(ctx);
        self.draw_pond(ctx);
        self.draw_crates(ctx);
        self.draw_well(ctx);
        self.draw_flora(ctx);
        Self::draw_mouth(ctx, ENTRANCE);
        self.draw_walker(ctx, drawn_at);
    }

    fn frame_cave(&mut self, ctx: &mut FrameContext<'_, Keep>) {
        let drawn_at = self.previous.lerp(self.position, ctx.alpha());
        let camera = Self::camera(drawn_at, CAVE_CAMERA_OFFSET);
        ctx.set_camera(camera);

        self.draw_cave_floor(ctx);
        self.draw_cave_walls(ctx);
        Self::draw_door_wall(ctx, (self.ghost > 0.0).then_some(drawn_at.x), self.ghost);
        Self::draw_mouth(ctx, EXIT);
        self.draw_torches(ctx);
        self.draw_door(ctx, self.ghost);
        self.draw_door_frame(ctx, self.ghost);
        if !self.gem_taken {
            self.draw_gem(ctx);
        }
        self.draw_walker(ctx, drawn_at);
        self.draw_door_prompt(ctx, camera);
    }

    /// Instructions and the door's interact hint — gathered before `ctx.ui`,
    /// which cannot read `ctx`.
    fn overlay(&mut self, ctx: &mut FrameContext<'_, Keep>) {
        let near_door = self.area == Area::Cave
            && !self.door_opening
            && self.position.distance(INTERACT_POINT) < INTERACT_RADIUS;
        let gem_taken = self.area == Area::Cave && self.gem_taken;
        let mut reset_clicked = false;

        ctx.ui(|ui| {
            egui::Frame::new()
                .fill(egui::Color32::from_black_alpha(HUD_BACKDROP))
                .inner_margin(HUD_PADDING)
                .corner_radius(f32::from(HUD_PADDING))
                .show(ui, |ui| {
                    ui.visuals_mut().override_text_color = Some(egui::Color32::WHITE);
                    ui.label("wasd / arrows / stick to walk");
                    if near_door {
                        ui.label("e / west button to open the door");
                    }
                    if gem_taken {
                        ui.label("gem recovered");
                    }
                    ui.label("kept between runs: position, gem, cave");
                    ui.label("r to reset world");
                    if ui.button("reset world").clicked() {
                        reset_clicked = true;
                    }
                });
        });

        if reset_clicked {
            self.reset_requested = true;
        }
    }
}

impl Game for Keep {
    type Meshes = Shape;
    type Sounds = Sound;
    type InputActions = Controls;
    type Skyboxes = NoSkyboxes;
    type SurfaceStyles = Looks;
    type PostEffects = NoPostEffects;

    fn tick(&mut self, ctx: &mut TickContext<'_, Keep>) {
        self.previous = self.position;

        if self.reset_requested || ctx.pressed(Button::Reset) {
            self.reset_requested = false;
            self.reset(ctx);
            return;
        }

        let heading = if ctx.ui_wants_keyboard() {
            Vec2::ZERO
        } else {
            ctx.axis2(Move::Walk)
        };
        match Facing::from_heading(heading) {
            Some(facing) => {
                self.facing = facing;
                self.walk_ticks += 1;
            }
            None => self.walk_ticks = 0,
        }
        let stride = Vec3::new(heading.x, 0.0, -heading.y) * WALK_SPEED * ctx.dt().as_secs_f32();
        self.position += stride;
        self.simulated += ctx.dt();

        match self.area {
            Area::Overworld => self.tick_overworld(ctx),
            Area::Cave => self.tick_cave(ctx),
        }
    }

examples/ui-fonts.rs (line 42)

const STATION_SIZE: Vec3 = Vec3::new(0.6, 0.9, 0.5);
/// The emissive cube set against the `STATION_SIZE` cube's own `-Z` side.
const STATION_FRONT_SIZE: Vec3 = Vec3::new(0.42, 0.5, 0.06);
/// The distance past the `STATION_SIZE` cube's own face the emissive
/// cube's front keeps, in meters, so the two stay flush at a shallow
/// angle.
const STATION_FRONT_OUTWARD: f32 = 0.005;

const RADAR_SWEEP_RATE: f32 = 40.0;
const REACTOR_RATE: f32 = 0.5;
const REACTOR_BASE: f32 = 55.0;
const REACTOR_SWING: f32 = 35.0;

const SUN_DIRECTION: Vec3 = Vec3::new(0.4, -1.0, -0.3);
const SUN_COLOR: Color = Color::rgb(0.6, 0.62, 0.7);

const CAMERA_FOV: f32 = 42.0;
const CAMERA_TARGET: Vec3 = Vec3::new(0.0, STATION_SIZE.y * 0.5, 0.0);
const START_YAW: f32 = 0.4;
const START_PITCH: f32 = 0.35;
/// How far short of straight up or down the pitch may turn, in radians.
const PITCH_LIMIT: f32 = 0.9;
const START_DISTANCE: f32 = 8.0;
const MIN_DISTANCE: f32 = 3.0;
const MAX_DISTANCE: f32 = 14.0;
/// Radians the camera turns by on its own, per second.
const AUTO_TURN_RATE: f32 = 0.12;
/// Radians the pointer's own motion turns the view by, per physical pixel
/// it crosses, while [`Trigger::Hail`] is held.
const TURN_SENSITIVITY: f32 = core::f32::consts::FRAC_PI_2 / 1280.0;
/// The factor one full wheel step divides the distance to the target by.
const ZOOM_STEP: f32 = 1.12;

const BRACKET_MARGIN: f32 = 10.0;
const BRACKET_STROKE: f32 = 2.0;
const BRACKET_CORNER: f32 = 7.0;
/// The gap kept past the line above's own full line height, so a glyph
/// whose `mesh_bounds` reaches past that height still clears the line
/// below.
const STACK_GAP: f32 = 4.0;

/// The gap between a `StationKind`'s own top and the `Prompt` drawn above
/// it, in logical points.
const PROMPT_LIFT: f32 = 20.0;

const DIALOGUE_PADDING_X: f32 = 28.0;
const DIALOGUE_PADDING_Y: f32 = 20.0;
const DIALOGUE_MARGIN: f32 = 24.0;

/// A sample the pixel font holds no glyph for, so `Proportional` falls
/// back to egui's own font and `pixel-only` shows the missing glyph box.
const FALLBACK_SAMPLE: &str = "café λ";
/// Different widths of glyph together, so a family's own advance shows.
const FAMILY_SAMPLE: &str = "mill and wall";
const GRID_SAMPLE: &str = "the quick fox";

meshes! { enum Shape { Cube, Plane } }

/// This game's own sky: a dark, dim gradient, so each `StationKind`'s own
/// emissive glow still reads as the platform's brightest color.
#[derive(Catalog, Clone, Copy, Debug, PartialEq, Eq, Hash)]
enum Sky {
    Dusk,
}

impl Skyboxes for Sky {
    fn build(&self, _assets: &Assets) -> SkyboxData {
        SkyboxData::gradient(
            Color::rgb(0.05, 0.06, 0.12),
            Color::rgb(0.18, 0.12, 0.16),
            Color::rgb(0.01, 0.01, 0.02),
        )
        .lit_by(0.25)
    }
}

/// What one `StationKind` is drawn and named as.
struct StationLook {
    name: &'static str,
    color: Color,
    glow: Color,
    lines: [&'static str; 2],
}

#[derive(Clone, Copy, PartialEq, Eq)]
enum StationKind {
    Radar,
    Reactor,
    Clock,
}

impl StationKind {
    const ALL: [Self; 3] = [Self::Radar, Self::Reactor, Self::Clock];

    fn index(self) -> usize {
        self as usize
    }

    fn look(self) -> StationLook {
        match self {
            Self::Radar => StationLook {
                name: "radar",
                color: Color::rgb(0.22, 0.26, 0.30),
                glow: Color::rgb(0.3, 1.4, 1.1),
                lines: [
                    "the radar sweeps the dark past the platform for anything that moves",
                    "nothing answers back tonight",
                ],
            },
            Self::Reactor => StationLook {
                name: "reactor",
                color: Color::rgb(0.30, 0.22, 0.18),
                glow: Color::rgb(1.6, 0.7, 0.2),
                lines: [
                    "the reactor gauge holds steady at a comfortable idle",
                    "plenty of power left for the long watch ahead",
                ],
            },
            Self::Clock => StationLook {
                name: "clock",
                color: Color::rgb(0.20, 0.24, 0.22),
                glow: Color::rgb(0.8, 0.9, 1.6),
                lines: [
                    "the clock keeps the same count it always has",
                    "the watch ends when it says so and not before",
                ],
            },
        }
    }

    /// This `StationKind`'s own center, on the platform's edge.
    fn center(self) -> Vec3 {
        let angle = self.index() as f32 / Self::ALL.len() as f32 * core::f32::consts::TAU;
        Vec3::new(
            STATION_RADIUS * angle.cos(),
            STATION_SIZE.y * 0.5,
            STATION_RADIUS * angle.sin(),
        )
    }

    fn aabb(self) -> (Vec3, Vec3) {
        let half = STATION_SIZE * 0.5;
        (self.center() - half, self.center() + half)
    }

    /// The reading a `bracket` shows through `Monospace`, and the one
    /// large number it shows through the `display` family, both from
    /// `elapsed` seconds.
    fn reading(self, elapsed: f32) -> (String, String) {
        match self {
            Self::Radar => {
                let bearing = (elapsed * RADAR_SWEEP_RATE).rem_euclid(360.0);
                (
                    format!("{bearing:.0} degrees bearing"),
                    format!("{bearing:03.0}"),
                )
            }
            Self::Reactor => {
                let percent = REACTOR_BASE + REACTOR_SWING * (elapsed * REACTOR_RATE).sin();
                (
                    format!("{percent:.0} percent output"),
                    format!("{percent:.0}%"),
                )
            }
            Self::Clock => {
                let seconds = elapsed.rem_euclid(60.0);
                (
                    format!("{seconds:.1} seconds this minute"),
                    format!("{seconds:04.1}"),
                )
            }
        }
    }
}

/// The `StationKind` `ray` lies nearest along, if any.
fn hit_station(ray: Ray) -> Option<StationKind> {
    StationKind::ALL
        .into_iter()
        .filter_map(|station| {
            let (min, max) = station.aabb();
            ray.hit_aabb(min, max).map(|distance| (distance, station))
        })
        .min_by(|(a, _), (b, _)| a.total_cmp(b))
        .map(|(_, station)| station)
}

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

/// `text` at `font`, in this game's own text color.
fn styled(text: impl Into<String>, font: egui::FontId) -> egui::RichText {
    egui::RichText::new(text.into())
        .font(font)
        .color(TEXT_COLOR)
}

/// The position that draws `galley` with its `mesh_bounds` centered on
/// `center_x` and its `mesh_bounds`'s own bottom at `bottom`.
fn ink_bottom_at(galley: &egui::Galley, center_x: f32, bottom: f32) -> egui::Pos2 {
    let ink = galley.mesh_bounds;
    egui::pos2(center_x - ink.center().x, bottom - ink.max.y)
}

/// How a control reads to a player: a glyph the `prompts` family draws,
/// or a control's own name in the `Proportional` font.
enum Prompt {
    Glyph(char),
    Text(String),
}

impl Prompt {
    fn text(&self) -> String {
        match self {
            Self::Glyph(glyph) => glyph.to_string(),
            Self::Text(text) => text.clone(),
        }
    }

    fn family(&self) -> egui::FontFamily {
        match self {
            Self::Glyph(_) => egui::FontFamily::Name(PROMPT_FAMILY.into()),
            Self::Text(_) => egui::FontFamily::Proportional,
        }
    }
}

/// `binding` read for a player: a mouse glyph for its left or right
/// button, or its own `Display` text otherwise, so a key reads as `E`
/// and a pad button as its name.
fn prompt(binding: &ButtonBinding) -> Prompt {
    match binding {
        ButtonBinding::Mouse(MouseButton::Left) => Prompt::Glyph('\u{E0EC}'),
        ButtonBinding::Mouse(MouseButton::Right) => Prompt::Glyph('\u{E0F0}'),
        other => Prompt::Text(other.to_string()),
    }
}

/// A name in `corners`, a reading and a number, placed one above the
/// other upward from `at`, which sits right above a `StationKind`'s top,
/// one line height clear of it: the name boxed and nearest `at`, the
/// reading a full line height above it, the number a full line height
/// above that, so no two lines and no line and the box ever overlap.
///
/// Each gap is measured in the line below's own full line height, not its
/// smaller `mesh_bounds`, so a glyph whose `mesh_bounds` reaches past that
/// height still clears the line above it. The name's own frame is sized to
/// its `mesh_bounds`, margin included, and the name centers inside it on
/// every side. The caller measures every `Galley`; this only draws. Lifts
/// into another game unchanged.
fn bracket(
    painter: &egui::Painter,
    at: egui::Pos2,
    name: Arc<egui::Galley>,
    reading: Arc<egui::Galley>,
    number: Arc<egui::Galley>,
) {
    let frame_bottom = at.y - name.rect.height();
    let name_ink = name.mesh_bounds;
    let frame_height = name_ink.height() + BRACKET_MARGIN * 2.0;
    let frame = egui::Rect::from_min_size(
        egui::pos2(
            at.x - name_ink.width() * 0.5 - BRACKET_MARGIN,
            frame_bottom - frame_height,
        ),
        egui::vec2(name_ink.width() + BRACKET_MARGIN * 2.0, frame_height),
    );
    let name_pos = ink_bottom_at(&name, at.x, frame_bottom - BRACKET_MARGIN);

    let reading_bottom = frame.top() - STACK_GAP;
    let reading_pos = ink_bottom_at(&reading, at.x, reading_bottom);

    let number_bottom = reading_pos.y - reading.rect.height() - STACK_GAP;
    let number_pos = ink_bottom_at(&number, at.x, number_bottom);

    corners(painter, frame);
    painter.galley(name_pos, name, TEXT_COLOR);
    painter.galley(reading_pos, reading, TEXT_COLOR);
    painter.galley(number_pos, number, TEXT_COLOR);
}

/// `glyph`, its `mesh_bounds` centered on `at`. Lifts into another game
/// unchanged.
fn prompt_at(painter: &egui::Painter, at: egui::Pos2, glyph: Arc<egui::Galley>) {
    let ink = glyph.mesh_bounds;
    let pos = egui::pos2(at.x - ink.center().x, at.y - ink.center().y);
    painter.galley(pos, glyph, TEXT_COLOR);
}

/// Four short lines at `rect`'s own corners, in place of its sides.
fn corners(painter: &egui::Painter, rect: egui::Rect) {
    let stroke = egui::Stroke::new(BRACKET_STROKE, TEXT_COLOR);
    for (corner, inward) in [
        (rect.left_top(), egui::vec2(1.0, 1.0)),
        (rect.right_top(), egui::vec2(-1.0, 1.0)),
        (rect.left_bottom(), egui::vec2(1.0, -1.0)),
        (rect.right_bottom(), egui::vec2(-1.0, -1.0)),
    ] {
        painter.line_segment(
            [corner, corner + egui::vec2(inward.x * BRACKET_CORNER, 0.0)],
            stroke,
        );
        painter.line_segment(
            [corner, corner + egui::vec2(0.0, inward.y * BRACKET_CORNER)],
            stroke,
        );
    }
}

/// A name shown large and one line typed a glyph a tick, over two lines a
/// click steps through. Holds no `StationKind` of its own, so it lifts
/// into another game unchanged.
struct Dialogue {
    name: String,
    lines: [String; 2],
    line: usize,
    revealed: usize,
}

impl Dialogue {
    fn start(name: impl Into<String>, lines: [String; 2]) -> Self {
        Self {
            name: name.into(),
            lines,
            line: 0,
            revealed: 0,
        }
    }

    fn current_line(&self) -> &str {
        &self.lines[self.line]
    }

    /// Shows one more glyph of the current line, up to its whole length.
    fn tick(&mut self) {
        let len = self.current_line().chars().count();
        self.revealed = (self.revealed + 1).min(len);
    }

    /// Steps to the next line; `false` where the last line was already
    /// shown, for the caller to close instead.
    fn advance(&mut self) -> bool {
        if self.line + 1 < self.lines.len() {
            self.line += 1;
            self.revealed = 0;
            true
        } else {
            false
        }
    }

    /// Draws the box at a size `whole_line` set, so it never grows as the
    /// glyphs of the same line arrive: `set_min_size` inside the window
    /// holds that size from the frame this window first draws, rather
    /// than egui's own resize state, which only grows a window to match
    /// what the frame before it drew.
    fn draw(&self, ui: &mut egui::Ui, whole_line: egui::Vec2) {
        let display = egui::FontFamily::Name(DISPLAY_FAMILY.into());
        let box_size = egui::vec2(
            whole_line.x + DIALOGUE_PADDING_X,
            whole_line.y + HEADING_SIZE + DIALOGUE_PADDING_Y,
        );
        egui::Window::new("hail")
            .title_bar(false)
            .resizable(false)
            .collapsible(false)
            .anchor(
                egui::Align2::CENTER_BOTTOM,
                egui::vec2(0.0, -DIALOGUE_MARGIN),
            )
            .show(ui.ctx(), |ui| {
                ui.set_min_size(box_size);
                ui.label(styled(&self.name, egui::FontId::new(HEADING_SIZE, display)));
                let shown: String = self.current_line().chars().take(self.revealed).collect();
                ui.label(styled(shown, egui::FontId::proportional(BODY_SIZE)));
            });
    }
}

/// Every family this game loaded, its name at `16` points beside a sample
/// at `32` in that family; the same sample under `Proportional`, where
/// egui's own fonts back what the pixel font holds no glyph for, beside
/// it again under a family that holds only the pixel font; and the pixel
/// font at `16` points beside itself at `17`, where its own grid stops
/// holding it crisp.
fn sheet(ui: &mut egui::Ui) {
    egui::Window::new("font sheet")
        .anchor(egui::Align2::CENTER_CENTER, egui::Vec2::ZERO)
        .collapsible(false)
        .resizable(false)
        .show(ui.ctx(), |ui| {
            egui::Grid::new("font sheet grid").show(ui, |ui| {
                for (label, family) in [
                    ("proportional", egui::FontFamily::Proportional),
                    ("monospace", egui::FontFamily::Monospace),
                    ("display", egui::FontFamily::Name(DISPLAY_FAMILY.into())),
                ] {
                    ui.label(styled(label, egui::FontId::proportional(BODY_SIZE)));
                    ui.label(styled(
                        FAMILY_SAMPLE,
                        egui::FontId::new(HEADING_SIZE, family),
                    ));
                    ui.end_row();
                }

                let pixel_only = egui::FontFamily::Name(PIXEL_ONLY_FAMILY.into());
                for (label, family) in [
                    ("egui's fonts behind", egui::FontFamily::Proportional),
                    ("pixel font alone", pixel_only),
                ] {
                    ui.label(styled(label, egui::FontId::proportional(BODY_SIZE)));
                    ui.label(styled(
                        FALLBACK_SAMPLE,
                        egui::FontId::new(BODY_SIZE, family),
                    ));
                    ui.end_row();
                }

                for (label, size) in [("16 points", 16.0), ("17 points", 17.0)] {
                    ui.label(styled(label, egui::FontId::proportional(BODY_SIZE)));
                    ui.label(styled(GRID_SAMPLE, egui::FontId::proportional(size)));
                    ui.end_row();
                }
            });
        });
}

#[derive(InputButtonAction, Clone, Copy)]
enum Trigger {
    Hail,
    Sheet,
    Close,
}

impl InputButtonAction for Trigger {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Self::Hail => vec![MouseButton::Left.into()],
            Self::Sheet => vec![Key::Tab.into()],
            Self::Close => vec![Key::Escape.into()],
        }
    }
}

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

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

#[derive(InputAxisAction, Clone, Copy)]
enum Zoom {
    Wheel,
}

impl InputAxisAction for Zoom {
    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 = Trigger;
    type Axis = Zoom;
    type Axis2 = Turn;
}

/// Reads every name in `names` and adds them under `family`, front to
/// back in the order given, ahead of whatever `family` already held.
fn install_family(
    fonts: &mut egui::FontDefinitions,
    startup: &mut Startup,
    family: egui::FontFamily,
    names: &[&str],
) -> Result<(), Error> {
    for &name in names {
        if !fonts.font_data.contains_key(name) {
            fonts
                .font_data
                .insert(name.to_owned(), startup.font(name)?.into());
        }
    }
    let list = fonts.families.entry(family).or_default();
    for &name in names.iter().rev() {
        list.insert(0, name.to_owned());
    }
    Ok(())
}

/// The camera around [`CAMERA_TARGET`], its own distance clamped between
/// [`MIN_DISTANCE`] and [`MAX_DISTANCE`], `yaw` free and `pitch` held to
/// [`PITCH_LIMIT`]. Holds nothing of the game, so it copies into another
/// one with its own values.
struct Orbit {
    yaw: f32,
    pitch: f32,
    distance: f32,
}

impl Default for Orbit {
    fn default() -> Self {
        Self {
            yaw: START_YAW,
            pitch: START_PITCH,
            distance: START_DISTANCE,
        }
    }
}

impl Orbit {
    fn camera(&self) -> Camera {
        let direction = Vec3::new(
            self.pitch.cos() * self.yaw.sin(),
            self.pitch.sin(),
            self.pitch.cos() * self.yaw.cos(),
        );
        Camera::new(
            View::look_at(CAMERA_TARGET + direction * self.distance, CAMERA_TARGET),
            Projection::perspective(CAMERA_FOV),
        )
    }

    /// Turns `yaw` by `-by.x` and `pitch` by `by.y`, `pitch` held to its
    /// limit.
    fn turn(&mut self, by: Vec2) {
        self.yaw -= by.x;
        self.pitch = (self.pitch + by.y).clamp(-PITCH_LIMIT, PITCH_LIMIT);
    }

    /// Divides the distance to [`CAMERA_TARGET`] by `factor`, held to its
    /// own least and most.
    fn zoom(&mut self, factor: f32) {
        self.distance = (self.distance / factor).clamp(MIN_DISTANCE, MAX_DISTANCE);
    }
}

struct WatchRoom {
    elapsed: Duration,
    orbit: Orbit,
    hailed: Option<StationKind>,
    dialogue: Option<Dialogue>,
    sheet_open: bool,
}

impl WatchRoom {
    fn init(ctx: &mut InitContext<'_, Self>) -> Result<Self, Error> {
        let startup = ctx.startup();
        let mut fonts = egui::FontDefinitions::default();
        for (family, names) in [
            (egui::FontFamily::Proportional, &[PROPORTIONAL_FONT][..]),
            (egui::FontFamily::Monospace, &[MONOSPACE_FONT][..]),
            (
                egui::FontFamily::Name(DISPLAY_FAMILY.into()),
                &[DISPLAY_FONT][..],
            ),
            (
                egui::FontFamily::Name(PIXEL_ONLY_FAMILY.into()),
                &[PROPORTIONAL_FONT][..],
            ),
            (
                egui::FontFamily::Name(PROMPT_FAMILY.into()),
                &[PROMPT_FONT, PROPORTIONAL_FONT][..],
            ),
        ] {
            install_family(&mut fonts, startup, family, names)?;
        }
        startup.set_fonts(fonts)?;

        Ok(Self {
            elapsed: Duration::ZERO,
            orbit: Orbit::default(),
            hailed: None,
            dialogue: None,
            sheet_open: false,
        })
    }

    fn handle_hail(&mut self, ctx: &mut TickContext<'_, Self>) {
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());
        let Some(station) = hit_station(ray) else {
            return;
        };

        if self.hailed != Some(station) {
            self.hailed = Some(station);
            let look = station.look();
            self.dialogue = Some(Dialogue::start(look.name, look.lines.map(str::to_owned)));
            return;
        }
        let Some(dialogue) = &mut self.dialogue else {
            return;
        };
        if !dialogue.advance() {
            self.dialogue = None;
            self.hailed = None;
        }
    }

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

examples/post-effects.rs (line 13)

const GLOW_POSITION: Vec3 = Vec3::new(0.0, 0.6, 0.0);
const GLOW_SIZE: f32 = 0.9;
const GLOW_COLOR: Color = Color::rgb(4.0, 2.2, 0.6);

/// A sphere either side of the glowing cube, and its radius.
const SPHERE_POSITIONS: [Vec3; 2] = [Vec3::new(-1.6, 0.5, 0.4), Vec3::new(1.6, 0.5, -0.4)];
const SPHERE_SUBDIVISIONS: u32 = 3;

const SUN_DIRECTION: Vec3 = Vec3::new(0.5, -1.0, -0.3);
const SUN_COLOR: Color = Color::rgb(0.85, 0.8, 0.7);

const GROUND_COLOR: Color = Color::rgb(0.16, 0.17, 0.15);
const SPHERE_COLOR: Color = Color::rgb(0.5, 0.52, 0.55);

/// Bloom the frame draws at, so [`GLOW_COLOR`] past `1.0` scatters.
const SCENE_BLOOM: f32 = 0.5;

meshes! { enum Shape { Plane, Cube, Sphere } }

/// The values the WGSL `Vignette` reads: how far it darkens toward the
/// frame's corners.
#[derive(ShaderValues)]
struct Vignette {
    strength: f32,
}

impl PostEffect for Vignette {
    const STAGE: EffectStage = EffectStage::ToneMapped;
    const SHADER: &'static str = include_str!("post_effects_vignette.wgsl");
}

/// The values the WGSL `Grain` reads: how much grain it draws, and the
/// seed its integer-hash is drawn from.
#[derive(ShaderValues)]
struct Grain {
    strength: f32,
    seed: u32,
}

impl PostEffect for Grain {
    const STAGE: EffectStage = EffectStage::ToneMapped;
    const SHADER: &'static str = include_str!("post_effects_grain.wgsl");
}

/// The values the WGSL `Scanlines` reads: how far it darkens every other
/// pixel row.
#[derive(ShaderValues)]
struct Scanlines {
    strength: f32,
}

impl PostEffect for Scanlines {
    const STAGE: EffectStage = EffectStage::ToneMapped;
    const SHADER: &'static str = include_str!("post_effects_scanlines.wgsl");
}

post_effects! { enum Look { Vignette, Grain, Scanlines } }

struct PostEffectEffects {
    ticks: u32,
    vignette: f32,
    grain: f32,
    scanlines: f32,
}

impl PostEffectEffects {
    fn init(_ctx: &mut InitContext<'_, Self>) -> Result<Self, Error> {
        Ok(Self {
            ticks: 0,
            vignette: 0.5,
            grain: 0.08,
            scanlines: 0.3,
        })
    }

    /// The scene every frame draws: a sun over a ground plane, a glowing
    /// cube bloom scatters from, and a sphere either side of it.
    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)),
            );
        }
    }

    /// A slider per effect, and the effects themselves run at the values
    /// they hold — `Grain`'s seed is [`Self::ticks`], so the frame it
    /// draws stays repeatable.
    fn panel(&mut self, ctx: &mut FrameContext<'_, Self>) {
        ctx.ui(|ui| {
            ui.add(egui::Slider::new(&mut self.vignette, 0.0..=1.0).text("vignette"));
            ui.add(egui::Slider::new(&mut self.grain, 0.0..=1.0).text("grain"));
            ui.add(egui::Slider::new(&mut self.scanlines, 0.0..=1.0).text("scanlines"));
        });

        ctx.set_post_effect(Vignette {
            strength: self.vignette,
        });
        ctx.set_post_effect(Grain {
            strength: self.grain,
            seed: self.ticks,
        });
        ctx.set_post_effect(Scanlines {
            strength: self.scanlines,
        });
    }
}

impl Game for PostEffectEffects {
    type Meshes = Shape;
    type Sounds = NoSounds;
    type InputActions = Key;
    type Skyboxes = NoSkyboxes;
    type SurfaceStyles = NoSurfaceStyles;
    type PostEffects = Look;

    fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {
        self.ticks += 1;
    }

    fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
        ctx.set_camera(Camera::new(
            View::look_at(Vec3::new(0.0, 3.4, 4.6), Vec3::new(0.0, 0.2, 0.0)),
            Projection::perspective(45.0),
        ));
        ctx.set_bloom(SCENE_BLOOM);

        self.draw_scene(ctx);
        self.panel(ctx);
    }

examples/material-playground.rs (line 45)

const FRONT_POSITION: Vec3 = Vec3::new(0.0, 0.7, -1.6);
const FRONT_SCALE: f32 = 1.4;

/// Sphere density every built sphere in this scene shares.
const SPHERE_SUBDIVISIONS: u32 = 3;

/// How many draws the reflection row makes, and the meters between their
/// centers.
const REFLECT_ROW_COUNT: usize = 5;
const REFLECT_ROW_SPACING: f32 = 1.5;
const REFLECT_ROW_Z: f32 = -1.6;
const REFLECT_ROW_RADIUS: f32 = 0.55;

const GROUND_COLOR: Color = Color::rgb(0.24, 0.25, 0.22);
const SHADING_TINT: Color = Color::rgb(0.55, 0.55, 0.6);
const RELIEF_TINT: Color = Color::rgb(0.5, 0.45, 0.35);
const EMISSIVE_BASE: Color = Color::rgb(0.04, 0.04, 0.05);
const EMISSIVE_GLOW: Color = Color::rgb(3.2, 2.2, 0.7);

/// Texel side length of every generated map: coarse enough that each
/// checker cell reads as a distinct part on a sphere or a cube face.
const MAP_SIZE: UVec2 = UVec2::new(64, 64);

/// Checker cell width, in texels, for the shading map.
const SHADING_CELL: u32 = 8;
/// The shading checker's two states: occlusion, roughness and metallic —
/// one square low across all three, the other full across all three.
const SHADING_LOW: [u8; 3] = [70, 40, 15];
const SHADING_HIGH: [u8; 3] = [255, 225, 235];

/// Checker cell width, in texels, for the emissive map.
const EMISSIVE_CELL: u32 = 6;

/// Wave count the relief's texture repeats across its map, and the peak
/// slope of its surface, in height over distance.
const BUMP_WAVES: f32 = 6.0;
const BUMP_SLOPE: f32 = 1.15;

/// `BannerCloth`'s width and height, in meters.
const BANNER_WIDTH: f32 = 1.1;
const BANNER_HEIGHT: f32 = 0.7;

/// Columns `BannerCloth` splits into, so its wave curves smoothly.
const BANNER_COLUMNS: u32 = 10;

/// Where the pillars, the pole, the cloth and the pulsing sphere are
/// placed, added to every one of their own positions: apart from the
/// pairs and the reflection row, so a light's shadow has clear ground to
/// land on.
const OUTPOST: Vec3 = Vec3::new(-4.6, 0.0, -0.8);

const PILLARS: [(Vec3, Vec3); 3] = [
    (Vec3::new(-1.8, 0.6, -0.6), Vec3::new(0.6, 1.2, 0.6)),
    (Vec3::new(0.4, 0.4, -1.6), Vec3::new(0.5, 0.8, 0.5)),
    (Vec3::new(1.7, 0.9, 0.4), Vec3::new(0.55, 1.8, 0.55)),
];

const POLE_POSITION: Vec3 = Vec3::new(-2.6, 1.0, 0.4);
const POLE_SCALE: Vec3 = Vec3::new(0.12, 2.0, 0.12);
const BANNER_MOUNT: Vec3 = Vec3::new(-2.54, 1.55, 0.46);

const FIELD_ORB_POSITION: Vec3 = Vec3::new(1.3, 1.1, 1.6);
const FIELD_ORB_SCALE: f32 = 0.7;

/// The lamp's fixed position and reach, in meters.
const LAMP_POSITION: Vec3 = Vec3::new(2.4, 1.4, -3.0);
const LAMP_RANGE: f32 = 5.0;

/// The spotlight's fixed placement: where it is placed, which way its
/// cone points, its reach in meters and its width in radians.
const SPOT_POSITION: Vec3 = Vec3::new(-3.4, 3.0, 1.6);
const SPOT_DIRECTION: Vec3 = Vec3::new(0.55, -1.0, -1.0);
const SPOT_RANGE: f32 = 7.0;
const SPOT_ANGLE: f32 = 0.5;

/// The camera's vertical field of view, in degrees.
const CAMERA_FOV: f32 = 46.0;
/// Where the camera starts, and the `yaw` and the pitch, in radians, it
/// starts turned to.
const START_EYE: Vec3 = Vec3::new(-0.6, 2.2, 9.0);
const START_YAW: f32 = 0.0;
const START_PITCH: f32 = -0.15;
/// How far short of straight up or down the pitch may turn, in radians,
/// where a turn alone reads as nothing.
const PITCH_LIMIT: f32 = 1.5;
/// The `eye`'s least height above the ground plane, in meters: held above
/// zero so a move can never take it below.
const MIN_EYE_HEIGHT: f32 = 0.3;
/// Radians the pointer's own motion turns the view by, per physical
/// pixel it crosses, before the axis it reads through bounds it: a drag
/// across the whole window turns about a quarter turn.
const LOOK_SENSITIVITY: f32 = core::f32::consts::FRAC_PI_2 / 1280.0;
/// Meters a move key covers per second, at [`Playground::speed_scale`]'s
/// own default.
const MOVE_SPEED: f32 = 4.0;
/// The factor one full wheel step multiplies the move speed apart from.
const SPEED_STEP: f32 = 1.5;
/// The move speed's own least and most, as a factor of [`MOVE_SPEED`].
const MIN_SPEED_SCALE: f32 = 0.2;
const MAX_SPEED_SCALE: f32 = 5.0;

/// Bloom this scene starts at, past the engine's own default: enough that
/// [`EMISSIVE_GLOW`] and the brightest lights scatter right away.
const START_BLOOM: f32 = 0.25;
const START_EXPOSURE: f32 = 1.0;

/// The sky a frame that keeps [`Sky::Default`] draws and is lit by: the
/// same flat grey the engine falls back to when a frame sets none.
const DEFAULT_SKY: Color = Color::rgb(0.1, 0.1, 0.1);

/// The fraction of its own light each loaded sky lands and reflects,
/// through [`SkyboxData::lit_by`]: the bright images fixed low, since an
/// image read too bright under the frame's own lights at its default
/// `1.0`; the dim images fixed more, since the scene read too dark under
/// them at the bright images' value.
const CLEAR_SKY_LIGHT: f32 = 0.35;
const CLASSIC_SKY_LIGHT: f32 = 0.35;
const DAWN_SKY_LIGHT: f32 = 0.3;
const SINISTER_SKY_LIGHT: f32 = 0.6;
const LIGHT_BLUE_STARS_LIGHT: f32 = 0.8;
const BLUE_STARS_LIGHT: f32 = 0.8;

/// The shading pair's plain half: a sphere given the shared shading
/// material and no map.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct ShadingPlain;

impl Mesh for ShadingPlain {
    fn build(&self, assets: &Assets) -> MeshData {
        sphere_with_material(assets, shading_material())
    }
}

/// The shading pair's mapped half: the same sphere and material, with its
/// shading map (occlusion, roughness and metallic) baked in.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct ShadingMapped;

impl Mesh for ShadingMapped {
    fn build(&self, assets: &Assets) -> MeshData {
        sphere_with_material(assets, shading_material()).with_shading(shading_checker())
    }
}

/// The relief pair's plain half.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct ReliefPlain;

impl Mesh for ReliefPlain {
    fn build(&self, assets: &Assets) -> MeshData {
        sphere_with_material(assets, relief_material())
    }
}

/// The relief pair's mapped half: the same sphere and material, with its
/// relief map baked in.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct ReliefMapped;

impl Mesh for ReliefMapped {
    fn build(&self, assets: &Assets) -> MeshData {
        sphere_with_material(assets, relief_material()).with_relief(relief_bumps())
    }
}

/// The emissive pair's plain half.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct EmissivePlain;

impl Mesh for EmissivePlain {
    fn build(&self, assets: &Assets) -> MeshData {
        cube_with_material(assets, emissive_material())
    }
}

/// The emissive pair's mapped half: the same cube and material, with its
/// emissive map baked in.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct EmissiveMapped;

impl Mesh for EmissiveMapped {
    fn build(&self, assets: &Assets) -> MeshData {
        cube_with_material(assets, emissive_material()).with_emissive_map(emissive_checker())
    }
}

/// The front sphere: a draw overrides its material new every frame, in
/// place of a baked one.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct Front;

impl Mesh for Front {
    fn build(&self, assets: &Assets) -> MeshData {
        Sphere {
            subdivisions: SPHERE_SUBDIVISIONS,
        }
        .build(assets)
    }
}

/// `BannerCloth`: a mesh split into columns along its span and placed at
/// its `x = 0` edge, so `Banner`'s wave curves it, not a single flat
/// quad. Its triangles are built twice: once as authored and once in the
/// other order, with the normal turned around, so the cloth draws from
/// both sides however its wave curves it.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
struct BannerCloth;

impl Mesh for BannerCloth {
    fn build(&self, _: &Assets) -> MeshData {
        banner_mesh()
    }
}

// Everything this game draws: the ground plane, each map pair's plain and
// mapped half, the front sphere with its own live material, the built-in
// primitives the reflection row and the pillars beside it place per draw,
// and the displaced cloth.
meshes! {
    enum Shape {
        Plane,
        Sphere,
        Cube,
        ShadingPlain,
        ShadingMapped,
        ReliefPlain,
        ReliefMapped,
        EmissivePlain,
        EmissiveMapped,
        Front,
        BannerCloth,
    }
}

fn sphere_with_material(assets: &Assets, material: Material) -> MeshData {
    Sphere {
        subdivisions: SPHERE_SUBDIVISIONS,
    }
    .build(assets)
    .with_material(material)
}

fn cube_with_material(assets: &Assets, material: Material) -> MeshData {
    Cube.build(assets).with_material(material)
}

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/flock-parallelism.rs (line 102)

const SUN_DIRECTION: Vec3 = Vec3::new(-0.8, -0.55, -0.5);
const SUN_COLOR: Color = Color::rgb(0.95, 0.92, 0.85);

const SKY_ZENITH: Color = Color::rgb(0.15, 0.22, 0.42);
const SKY_HORIZON: Color = Color::rgb(0.7, 0.48, 0.34);
const SKY_NADIR: Color = Color::rgb(0.2, 0.16, 0.14);
const SKY_LIGHT: f32 = 0.65;
/// The sky's own color under the horizon, so a butterfly's own underside and
/// the ground reflect light from the sky instead of reading black.
const SKY_GROUND: Color = Color::rgb(0.42, 0.34, 0.28);

/// The camera's height above and distance from the flock's center, each a
/// fraction of the flock's own radius, so the view frames every size.
const CAMERA_HEIGHT_FRACTION: f32 = 0.45;
const CAMERA_DISTANCE_FRACTION: f32 = 2.2;
/// How far above the flock's center the camera looks, as a fraction of
/// the flock's own radius, so the flock sits below the panel.
const CAMERA_AIM_LIFT_FRACTION: f32 = 0.25;
const CAMERA_FOV: f32 = 75.0;
/// Radians the camera turns about the flock's center per second.
const CAMERA_ANGULAR_SPEED: f32 = 0.08;

/// Butterflies a chunk of [`Butterflies::center`]'s fold sums at a time, so the sum
/// reads the same bits at any worker count.
const CENTER_CHUNK_SIZE: usize = 1024;

const PANEL_PADDING: i8 = 8;

meshes! { enum Shape { Butterfly, Plane } }

/// The one sky this game draws, a gradient set each frame.
#[derive(Catalog, Clone, Copy, Debug, Eq, Hash, PartialEq)]
enum Sky {
    Day,
}

impl Skyboxes for Sky {
    fn build(&self, _assets: &Assets) -> SkyboxData {
        match self {
            Self::Day => SkyboxData::gradient(SKY_ZENITH, SKY_HORIZON, SKY_NADIR)
                .lit_by(SKY_LIGHT)
                .with_ground(SKY_GROUND),
        }
    }
}

#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Butterfly;

/// The one clip a butterfly is posed by, named as the source names it.
#[derive(Clip, Clone, Debug, PartialEq, Eq, Hash)]
enum ButterflyClip {
    #[clip("fly")]
    Fly,
}

impl Mesh<NoParts, ButterflyClip> for Butterfly {
    fn build(&self, assets: &Assets) -> MeshData<NoParts, ButterflyClip> {
        assets
            .model(BUTTERFLY_ROOT)
            .with_texture(greyed(&assets.texture(BUTTERFLY_SKIN)))
    }
}

/// `skin` with every texel at its own grey level, its alpha kept, so a tint
/// colors it whole.
fn greyed(skin: &TextureData) -> TextureData {
    let pixels = skin
        .pixels()
        .chunks_exact(4)
        .flat_map(|texel| {
            let [red, green, blue, alpha] = [texel[0], texel[1], texel[2], texel[3]];
            let grey =
                (0.2126 * f32::from(red) + 0.7152 * f32::from(green) + 0.0722 * f32::from(blue))
                    .round() as u8;
            [grey, grey, grey, alpha]
        })
        .collect();
    TextureData::rgba8(skin.size(), pixels)
}

/// What one butterfly looks like: the flap group that poses it and the tint
/// it is drawn in, both its own for the whole run.
#[derive(Clone, Copy, Default)]
struct Kind {
    flap: u8,
    tint: u8,
}

impl Kind {
    /// The kind butterfly `index` is given, by its own integer-hash.
    fn of(index: u32) -> Self {
        Self {
            flap: (hash(index, 4) % FLAP_GROUPS as u32) as u8,
            tint: (hash(index, 5) % TINTS.len() as u32) as u8,
        }
    }
}

/// A machine of one state, holding the flap at the phase it is given: one
/// machine per flap group poses every butterfly of that group.
#[derive(Clone, Copy, Eq, PartialEq, Debug)]
enum FlapState {
    Flapping,
}

impl AnimationStates for FlapState {
    type Clip = ButterflyClip;
    type Input = f32;

    fn entry() -> Self {
        Self::Flapping
    }

    fn motion(&self, phase: &f32) -> Motion<ButterflyClip> {
        Motion::scrubbed(ButterflyClip::Fly, *phase)
    }

    fn next(&self, _phase: &f32, _at: Progress) -> Option<Transition<Self>> {
        None
    }
}

/// The phase flap group `group` holds `flown` seconds into the run: the
/// flaps its own rate has run, spread about [`FLAP_RATE`] by
/// [`FLAP_RATE_SPREAD`], the rate rising and falling by [`FLAP_WAVES`] at
/// the group's own offsets, from the group's own start. The count is the
/// sum of the rate over the seconds `flown`, taken whole rather than tick by
/// tick, so no step adds up an error.
fn flap_phase(group: usize, flown: f32) -> f32 {
    let share = group as f32 / FLAP_GROUPS as f32;
    let rate = FLAP_RATE * (1.0 + FLAP_RATE_SPREAD * (share - 0.5));
    let waved: f32 = FLAP_WAVES
        .iter()
        .enumerate()
        .map(|(wave, &(depth, period))| {
            let angular = TAU / period;
            let offset = hash_unit(group as u32, 6 + wave as u32) * TAU;
            -depth / angular * (angular * flown + offset).cos()
        })
        .sum();
    (rate * (flown + waved) + share).fract()
}

/// The sphere the flock is bound to: its center, held above the ground by
/// [`FLOCK_CLEARANCE`], and its radius, sized so each butterfly has
/// [`WORLD_VOLUME_PER_BUTTERFLY`].
#[derive(Clone, Copy)]
struct World {
    center: Vec3A,
    radius: f32,
}

impl World {
    fn for_flock(count: u32) -> Self {
        let radius = (count as f32 * WORLD_VOLUME_PER_BUTTERFLY * 3.0 / (4.0 * PI)).cbrt();
        Self {
            center: Vec3A::new(0.0, radius + FLOCK_CLEARANCE, 0.0),
            radius,
        }
    }
}

/// The box of cells the flock is kept in: cubes [`NEIGHBOR_RADIUS`] across,
/// `side` to an axis, from `least` on every axis.
#[derive(Clone, Copy)]
struct Cells {
    side: usize,
    least: Vec3A,
}

impl Cells {
    /// The box over `world`'s sphere and [`BOX_MARGIN`] past it.
    fn covering(world: World) -> Self {
        let reach = world.radius * BOX_MARGIN;
        let side = ((2.0 * reach) / NEIGHBOR_RADIUS).ceil().max(1.0) as usize;
        Self {
            side,
            least: world.center - Vec3A::splat(reach),
        }
    }

    /// How many cells the box holds.
    fn count(self) -> usize {
        self.side * self.side * self.side
    }

    /// The cell `position` lies in, held inside the box on every axis.
    fn of(self, position: Vec3A) -> usize {
        let scaled = (position - self.least) / NEIGHBOR_RADIUS;
        let most = (self.side - 1) as f32;
        let x = scaled.x.clamp(0.0, most) as usize;
        let y = scaled.y.clamp(0.0, most) as usize;
        let z = scaled.z.clamp(0.0, most) as usize;
        (x * self.side + y) * self.side + z
    }

    /// `cell` and every cell beside it, at most 27, inside the box.
    fn around(self, cell: usize) -> impl Iterator<Item = usize> {
        let side = self.side;
        let z = cell % side;
        let y = (cell / side) % side;
        let x = cell / (side * side);
        let span = move |at: usize| at.saturating_sub(1)..(at + 2).min(side);
        span(x).flat_map(move |cx| {
            span(y).flat_map(move |cy| span(z).map(move |cz| (cx * side + cy) * side + cz))
        })
    }
}

/// The flock: every butterfly's position and velocity in cell order, where each
/// cell's butterflies start, and the arrays the next tick is written into.
struct Butterflies {
    cells: Cells,
    /// Where each cell's butterflies start, and one more for the end of the last.
    start: Vec<u32>,
    position: Vec<Vec3A>,
    velocity: Vec<Vec3A>,
    /// Each butterfly's kind, in the same order.
    kind: Vec<Kind>,
    next_position: Vec<Vec3A>,
    next_velocity: Vec<Vec3A>,
    next_kind: Vec<Kind>,
    /// The cell each butterfly of the next arrays lies in.
    next_cell: Vec<u32>,
}

impl Butterflies {
    /// `count` butterflies scattered through `world`'s sphere, each with a level
    /// heading at [`MIN_SPEED`], sorted into cells.
    fn scattered(count: u32, world: World) -> Self {
        let cells = Cells::covering(world);
        let count = count as usize;
        let mut swarm = Self {
            cells,
            start: vec![0; cells.count() + 1],
            position: vec![Vec3A::ZERO; count],
            velocity: vec![Vec3A::ZERO; count],
            kind: vec![Kind::default(); count],
            next_position: Vec::with_capacity(count),
            next_velocity: Vec::with_capacity(count),
            next_kind: Vec::with_capacity(count),
            next_cell: Vec::with_capacity(count),
        };
        for index in 0..count as u32 {
            let radius = world.radius * hash_unit(index, 0).cbrt();
            let inclination = hash_unit(index, 1) * PI;
            let azimuth = hash_unit(index, 2) * TAU;
            let position = world.center
                + Vec3A::new(
                    radius * inclination.sin() * azimuth.cos(),
                    radius * inclination.cos(),
                    radius * inclination.sin() * azimuth.sin(),
                );
            let heading = hash_unit(index, 3) * TAU;
            let velocity = Vec3A::new(heading.cos(), 0.0, heading.sin()) * MIN_SPEED;
            swarm.next_position.push(position);
            swarm.next_velocity.push(velocity);
            swarm.next_kind.push(Kind::of(index));
            swarm.next_cell.push(cells.of(position) as u32);
        }
        swarm.sort();
        swarm
    }

    /// One tick of `dt` seconds: every cell's butterflies steered against the
    /// cells around it into the next arrays, on the engine's workers or one
    /// cell after another, then the next arrays sorted into cells again.
    fn step(&mut self, dt: f32, world: World, sequential: bool) {
        let Self {
            cells,
            start,
            position,
            velocity,
            kind,
            next_position,
            next_velocity,
            next_kind,
            next_cell,
        } = self;
        let flock = Flying {
            cells: *cells,
            start,
            position,
            velocity,
            kind,
        };
        let mut out = CellOut::split(&flock, next_position, next_velocity, next_kind, next_cell);
        let steer = |(cell, out): (usize, &mut CellOut<'_>)| flock.steer(cell, out, dt, world);
        if sequential {
            out.iter_mut().enumerate().for_each(steer);
        } else {
            out.par_iter_mut().enumerate().for_each(steer);
        }
        drop(out);
        self.sort();
    }

    /// Sorts the next arrays into the current ones by cell: a count per
    /// cell, a running total, and a placement in order, so the result reads
    /// the same at any worker count.
    fn sort(&mut self) {
        self.start.iter_mut().for_each(|start| *start = 0);
        for &cell in &self.next_cell {
            self.start[cell as usize + 1] += 1;
        }
        for cell in 0..self.cells.count() {
            self.start[cell + 1] += self.start[cell];
        }
        let mut fill = self.start.clone();
        for (index, &cell) in self.next_cell.iter().enumerate() {
            let at = fill[cell as usize] as usize;
            fill[cell as usize] += 1;
            self.position[at] = self.next_position[index];
            self.velocity[at] = self.next_velocity[index];
            self.kind[at] = self.next_kind[index];
        }
    }

    /// The flock's center: positions summed in fixed chunks and then
    /// folded in order, the fold that `mirage_engine::rayon`'s own docs
    /// show, so it reads the same bits at any worker count.
    fn center(&self) -> Vec3A {
        if self.position.is_empty() {
            return Vec3A::ZERO;
        }
        let sum: Vec3A = self
            .position
            .par_chunks(CENTER_CHUNK_SIZE)
            .map(|chunk| chunk.iter().copied().sum::<Vec3A>())
            .collect::<Vec<Vec3A>>()
            .into_iter()
            .sum();
        sum / self.position.len() as f32
    }

    /// Every butterfly's position, velocity and kind, in cell order.
    fn each(&self) -> impl Iterator<Item = (Vec3A, Vec3A, Kind)> + '_ {
        self.position
            .iter()
            .zip(&self.velocity)
            .zip(&self.kind)
            .map(|((&position, &velocity), &kind)| (position, velocity, kind))
    }
}

/// The flock as one tick reads it: the current arrays and the cells they
/// are sorted by, shared by every cell's step.
struct Flying<'a> {
    cells: Cells,
    start: &'a [u32],
    position: &'a [Vec3A],
    velocity: &'a [Vec3A],
    kind: &'a [Kind],
}

impl Flying<'_> {
    /// The butterflies of `cell`, as a range of the arrays.
    fn range(&self, cell: usize) -> Range<usize> {
        self.start[cell] as usize..self.start[cell + 1] as usize
    }

    /// Steers every butterfly of `cell` by separation, alignment and cohesion
    /// against the butterflies of the cells around it, and back toward the center
    /// once it leaves `world`'s sphere, writing the next state into `out`.
    fn steer(&self, cell: usize, out: &mut CellOut<'_>, dt: f32, world: World) {
        let mut around: [Range<usize>; 27] = core::array::from_fn(|_| 0..0);
        let mut near_count = 0;
        for near in self.cells.around(cell) {
            around[near_count] = self.range(near);
            near_count += 1;
        }
        let around = &around[..near_count];

        for (at, index) in self.range(cell).enumerate() {
            let position = self.position[index];
            let velocity = self.velocity[index];
            let mut separation = Vec3A::ZERO;
            let mut heading_sum = Vec3A::ZERO;
            let mut position_sum = Vec3A::ZERO;
            let mut neighbors = 0u32;

            for near in around {
                for other in near.clone() {
                    if other == index {
                        continue;
                    }
                    let offset = position - self.position[other];
                    let squared = offset.length_squared();
                    if squared > NEIGHBOR_RADIUS * NEIGHBOR_RADIUS || squared <= f32::EPSILON {
                        continue;
                    }
                    if squared < SEPARATION_RADIUS * SEPARATION_RADIUS {
                        separation += offset / squared.sqrt();
                    }
                    heading_sum += self.velocity[other];
                    position_sum += self.position[other];
                    neighbors += 1;
                }
            }

            let mut steering = separation * SEPARATION_WEIGHT;
            if neighbors > 0 {
                let share = 1.0 / neighbors as f32;
                steering += (heading_sum * share - velocity) * ALIGNMENT_WEIGHT
                    + (position_sum * share - position) * COHESION_WEIGHT;
            }
            let from_center = position - world.center;
            if from_center.length() > world.radius {
                steering -= from_center.normalize() * BOUND_WEIGHT;
            }

            let next = velocity + steering * dt;
            let speed = next.length().clamp(MIN_SPEED, MAX_SPEED);
            let next_velocity = next.normalize_or_zero() * speed;
            let next_position = position + next_velocity * dt;
            out.position[at] = next_position;
            out.velocity[at] = next_velocity;
            out.kind[at] = self.kind[index];
            out.cell[at] = self.cells.of(next_position) as u32;
        }
    }
}

/// One cell's share of the next arrays, written by that cell's step alone.
struct CellOut<'a> {
    position: &'a mut [Vec3A],
    velocity: &'a mut [Vec3A],
    kind: &'a mut [Kind],
    cell: &'a mut [u32],
}

impl<'a> CellOut<'a> {
    /// The next arrays split into one share per cell of `flock`, in cell
    /// order, each as long as that cell's range.
    fn split(
        flock: &Flying<'_>,
        position: &'a mut Vec<Vec3A>,
        velocity: &'a mut Vec<Vec3A>,
        kind: &'a mut Vec<Kind>,
        cell: &'a mut Vec<u32>,
    ) -> Vec<Self> {
        let count = flock.position.len();
        position.resize(count, Vec3A::ZERO);
        velocity.resize(count, Vec3A::ZERO);
        kind.resize(count, Kind::default());
        cell.resize(count, 0);
        let mut out = Vec::with_capacity(flock.cells.count());
        let mut position = position.as_mut_slice();
        let mut velocity = velocity.as_mut_slice();
        let mut kind = kind.as_mut_slice();
        let mut cell = cell.as_mut_slice();
        for at in 0..flock.cells.count() {
            let len = flock.range(at).len();
            let (own, rest) = position.split_at_mut(len);
            position = rest;
            let (own_velocity, rest) = velocity.split_at_mut(len);
            velocity = rest;
            let (own_kind, rest) = kind.split_at_mut(len);
            kind = rest;
            let (own_cell, rest) = cell.split_at_mut(len);
            cell = rest;
            out.push(Self {
                position: own,
                velocity: own_velocity,
                kind: own_kind,
                cell: own_cell,
            });
        }
        out
    }
}

/// An integer-hash of `seed` and `salt`.
fn hash(seed: u32, salt: u32) -> u32 {
    let mut x = seed ^ salt.wrapping_mul(0x9E37_79B9);
    x ^= x >> 16;
    x = x.wrapping_mul(0x7FEB_352D);
    x ^= x >> 15;
    x = x.wrapping_mul(0x846C_A68B);
    x ^= x >> 16;
    x
}

/// `hash`, scaled to `0.0..1.0`.
fn hash_unit(seed: u32, salt: u32) -> f32 {
    hash(seed, salt) as f32 / u32::MAX as f32
}

/// The load a player chooses: how many butterflies the flock holds, and whether
/// the step below runs one cell after another instead of on the engine's
/// workers.
struct Settings {
    flock_size: u32,
    sequential: bool,
}

impl Default for Settings {
    fn default() -> Self {
        Self {
            flock_size: DEFAULT_FLOCK_SIZE,
            sequential: false,
        }
    }
}

struct Flock {
    settings: Settings,
    applied_flock_size: u32,
    world: World,
    butterflies: Butterflies,
    flaps: [Animator<Butterfly, FlapState>; FLAP_GROUPS],
    /// Seconds the ticks have run, which paces the flap.
    flown: f32,
    last_tick_ms: f32,
}

impl Flock {
    fn init(_ctx: &mut InitContext<'_, Self>) -> Result<Self, Error> {
        let settings = Settings::default();
        let world = World::for_flock(settings.flock_size);
        Ok(Self {
            applied_flock_size: settings.flock_size,
            butterflies: Butterflies::scattered(settings.flock_size, world),
            settings,
            world,
            flaps: core::array::from_fn(|_| Animator::new()),
            flown: 0.0,
            last_tick_ms: 0.0,
        })
    }

    /// Rebuilds the flock where the chosen size changed since the last
    /// frame.
    fn apply_settings(&mut self) {
        if self.settings.flock_size == self.applied_flock_size {
            return;
        }
        self.world = World::for_flock(self.settings.flock_size);
        self.butterflies = Butterflies::scattered(self.settings.flock_size, self.world);
        self.applied_flock_size = self.settings.flock_size;
    }

    /// The camera at `elapsed`, turning about `center` at
    /// [`CAMERA_HEIGHT_FRACTION`] and [`CAMERA_DISTANCE_FRACTION`] of the
    /// flock's own radius, looking [`CAMERA_AIM_LIFT_FRACTION`] above it.
    fn camera(center: Vec3, world: World, elapsed: f32) -> Camera {
        let angle = elapsed * CAMERA_ANGULAR_SPEED;
        let eye = center
            + Vec3::new(
                angle.cos() * world.radius * CAMERA_DISTANCE_FRACTION,
                world.radius * CAMERA_HEIGHT_FRACTION,
                angle.sin() * world.radius * CAMERA_DISTANCE_FRACTION,
            );
        let aim = center + Vec3::Y * world.radius * CAMERA_AIM_LIFT_FRACTION;
        Camera::new(View::look_at(eye, aim), Projection::perspective(CAMERA_FOV))
    }

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

Additional examples can be found in:

• examples/stress-preview.rs
• examples/sound-lab.rs
• examples/isometric-board.rs
• examples/breakout-game.rs

pub const fn splat(v: f32) -> Vec3

Creates a vector with all elements set to v.

Examples found in repository

examples/isometric-board.rs (line 44)

const BLOCK_HALF_EXTENTS: Vec3 = Vec3::splat(BLOCK_SIZE * 0.5);

/// The name `assets.texture` pulls the sheet under, once loaded.
const SPRITE_TEXTURE: &str = "walker";
const SPRITE_SOURCE: &str = "examples/assets/walker.png";
const CLICK_SOURCE: &str = "examples/assets/click.ogg";

/// The texture's grid: rows top to bottom are toward, right, away, and
/// left; four frames of a walk cycle across each row. The sprite unit
/// draws the right row always, mirrored across its own width for a left
/// order, in place of a left row of its own.
const SPRITE_COLUMNS: u32 = 4;
const SPRITE_ROWS: u32 = 4;
const SPRITE_ROW: u32 = 1;
const SPRITE_COLUMN: u32 = 0;

/// Each rock around the board: position, a `seed` for its mesh, and a
/// scale for the transform that places it.
const ROCKS: [(f32, f32, u32, f32); 5] = [
    (-BOARD_HALF - 1.2, -BOARD_HALF - 0.6, 11, 1.0),
    (-BOARD_HALF - 0.8, BOARD_HALF + 1.0, 37, 0.8),
    (BOARD_HALF + 1.4, -BOARD_HALF - 0.2, 58, 1.3),
    (BOARD_HALF + 1.0, BOARD_HALF + 1.2, 71, 0.9),
    (0.3, BOARD_HALF + 1.6, 94, 1.1),
];

/// How far a rock's corner is displaced from its position on a unit
/// cube, on each axis.
const ROCK_JITTER: f32 = 0.16;

/// Half the ground's width and depth under the board and its rock ring,
/// in meters.
const GROUND_HALF: f32 = BOARD_HALF + 3.0;

/// The ground's surface height, just under the board's own tiles, clear
/// of a z-fighting seam with them.
const GROUND_Y: f32 = -0.01;

const LIGHT_TILE: Color = Color::rgb(0.80, 0.76, 0.64);
const DARK_TILE: Color = Color::rgb(0.55, 0.50, 0.40);
/// A reachable tile's own mark, smaller than the tile itself so the
/// checker tone still shows around its edge.
const REACHABLE_MARK: Color = Color::rgb(0.20, 0.85, 0.35);
/// The fraction of a tile's own footprint the reachable mark draws at,
/// small enough that the tile's own checker tone still shows around it.
const REACHABLE_MARK_SCALE: f32 = 0.45;
/// The reachable mark's own lift over the tile's surface, clear of
/// z-fighting with it.
const REACHABLE_MARK_LIFT: f32 = 0.01;
/// The mark under the selected unit, its own color bright enough to read
/// past the sprite's own tint at a distance.
const CURRENT_MARK: Color = Color::rgb(1.0, 0.2, 0.75);
const CURRENT_MARK_SCALE: f32 = 0.85;
/// The mark under the unit whose turn it is while nothing is selected:
/// smaller and dim next to [`CURRENT_MARK`], a hint rather than a claim.
const TURN_MARK: Color = Color::rgb(0.85, 0.75, 0.15);
const TURN_MARK_SCALE: f32 = 0.5;
/// The tile a hover reads while a unit is selected: reachable, or blocked
/// by the other unit standing there.
const HOVER_REACHABLE_TILE: Color = Color::rgb(0.35, 0.75, 0.68);
const HOVER_BLOCKED_TILE: Color = Color::rgb(0.62, 0.28, 0.26);
const BLOCK_IDLE: Color = Color::rgb(0.32, 0.42, 0.58);
/// `BLOCK_IDLE`, scaled toward white to mark the block unit's own turn.
const BLOCK_TURN: Color = Color::rgb(0.42, 0.54, 0.72);
const GROUND_COLOR: Color = Color::rgb(0.15, 0.16, 0.13);
const ROCK_COLOR: Color = Color::rgb(0.42, 0.40, 0.38);
const SUN_COLOR: Color = Color::rgb(0.95, 0.92, 0.85);

/// The current unit's tint, close to white so the sprite's own texture
/// still reads under it, and the light it adds on its own, low enough
/// that the same texture still reads under its bloom too — distinct from
/// `SELECTED_TINT`, so a hover and a selection never read the same.
const HOVER_TINT: Color = Color::rgb(0.9, 1.15, 1.15);
const HOVER_GLOW: Color = Color::rgb(0.02, 0.15, 0.2);

/// The current unit's tint, close to white with more red where
/// `HOVER_TINT` raises green and blue instead, so the sprite's own
/// texture still reads under it, and the light it adds on its own,
/// scaled down the same way `HOVER_GLOW` is — distinct from `HOVER_TINT`.
const SELECTED_TINT: Color = Color::rgb(1.15, 0.95, 0.85);
const SELECTED_GLOW: Color = Color::rgb(0.22, 0.11, 0.0);

/// The unit whose turn it is shows this tint and glow before any hover or
/// selection, so it reads as the one a click selects.
const TURN_TINT: Color = Color::rgb(1.0, 1.0, 0.82);
const TURN_GLOW: Color = Color::rgb(0.08, 0.08, 0.02);

/// The fraction of the frame `set_bloom` spreads, so `HOVER_GLOW` and
/// `SELECTED_GLOW` read as light around the current unit, not only a
/// larger fill.
const BLOOM: f32 = 0.35;

/// The size a world-space prompt naming a click's effect reads at, in
/// logical points.
const PROMPT_SIZE: f32 = 15.0;
/// Height a prompt is lifted over the tile it names, clear of the tile's
/// own top corner under the diagonal view.
const PROMPT_TILE_LIFT: f32 = 0.55;
/// Height a prompt is lifted over the unit it names, past its own height.
const PROMPT_UNIT_LIFT: f32 = 0.25;
/// Margin a prompt's own backdrop keeps past its galley, in logical points.
const PROMPT_PADDING: f32 = 4.0;
/// How much dark a prompt's own backdrop puts behind its text.
const PROMPT_BACKDROP: u8 = 190;
const PROMPT_TEXT_COLOR: egui::Color32 = egui::Color32::from_gray(230);

/// Thirty steps a second, half the engine's default rate; movement stays
/// smooth through `alpha()` interpolation.
const TICK_INTERVAL: Duration = Duration::from_nanos(33_333_333);

/// Faces of a cube, each a normal with its right and up axes — the same
/// layout `mesh::Cube` builds from, shared so a rock's corners hold the
/// same eight positions between the faces that meet there.
const ROCK_FACES: [(Vec3, Vec3, Vec3); 6] = [
    (Vec3::X, Vec3::NEG_Z, Vec3::Y),
    (Vec3::NEG_X, Vec3::Z, Vec3::Y),
    (Vec3::Y, Vec3::X, Vec3::NEG_Z),
    (Vec3::NEG_Y, Vec3::X, Vec3::Z),
    (Vec3::Z, Vec3::X, Vec3::Y),
    (Vec3::NEG_Z, Vec3::NEG_X, Vec3::Y),
];

const ROCK_TRIANGLES: [u32; 6] = [0, 1, 2, 0, 2, 3];

fn main() {
    run(
        Config::new("Mirage: isometric board")
            .with_size(1280, 720)
            .with_assets([SPRITE_SOURCE, CLICK_SOURCE])
            .with_tick_interval(TICK_INTERVAL),
        Board::init,
    );
}

/// A rock built for its own `seed`; each value is its own mesh.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
#[catalog(Self { seed: 0 })]
struct Rock {
    seed: u32,
}

impl Mesh for Rock {
    fn build(&self, _: &Assets) -> MeshData {
        build_rock(self.seed)
    }
}

/// The sprite unit: a quad windowed to the walk sheet's row facing right.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
struct Sprite;

impl Mesh for Sprite {
    fn build(&self, assets: &Assets) -> MeshData {
        Quad.build(assets)
            .with_texture(assets.texture(SPRITE_TEXTURE).pixelated())
    }
}

// Everything else this game draws: the ground and board tiles are the
// engine's own Plane and Cube, given their color per draw; the block unit
// draws as a plain Cube too.
meshes! { enum Shape { Plane, Cube, Rock, Sprite } }

/// The board's own sky: a dim gradient, so the sun stays the scene's
/// brightest light.
#[derive(Catalog, Clone, Copy, Debug, PartialEq, Eq, Hash)]
enum Sky {
    Day,
}

impl Skyboxes for Sky {
    fn build(&self, _assets: &Assets) -> SkyboxData {
        SkyboxData::gradient(
            Color::rgb(0.55, 0.75, 0.95),
            Color::rgb(0.85, 0.90, 0.95),
            Color::rgb(0.35, 0.33, 0.30),
        )
        .lit_by(0.3)
    }
}

/// The one sound this game plays.
#[derive(Catalog, Clone, PartialEq, Eq, Hash)]
enum Sound {
    Click,
}

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

/// The one control this game reads: a click, which selects the unit whose
/// turn it is or orders it to a tile.
#[derive(InputButtonAction, Clone, Copy)]
enum Button {
    Select,
}

impl InputButtonAction for Button {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Button::Select => vec![MouseButton::Left.into()],
        }
    }
}

struct Controls;

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

/// Whose turn it is: `Sprite` draws the unit with a texture, `Block` the
/// plain one.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Turn {
    Sprite,
    Block,
}

impl Turn {
    fn other(self) -> Self {
        match self {
            Turn::Sprite => Turn::Block,
            Turn::Block => Turn::Sprite,
        }
    }
}

/// One unit's position on the board.
struct Unit {
    tile: (i32, i32),
    position: Vec3,
    previous: Vec3,
    target: Option<Vec3>,
    /// The order the unit last moved along `+X` under, kept while it
    /// stays still.
    facing_right: bool,
}

impl Unit {
    fn resting(tile: (i32, i32), lift: f32) -> Self {
        let position = tile_center(tile) + Vec3::Y * lift;
        Self {
            tile,
            position,
            previous: position,
            target: None,
            facing_right: true,
        }
    }

    /// Steps the unit toward its ordered position by one tick's distance;
    /// returns whether it landed on the position this tick.
    fn advance(&mut self, dt: Duration) -> bool {
        let Some(target) = self.target else {
            return false;
        };
        let to_target = target - self.position;
        let distance = to_target.length();
        let step = UNIT_SPEED * dt.as_secs_f32();
        if distance <= step {
            self.position = target;
            self.target = None;
            true
        } else {
            self.position += to_target * (step / distance);
            false
        }
    }
}

/// The vertical lift from a tile's surface to a unit's center, and the
/// half-extents `Ray::hit_aabb` reads its box by.
fn unit_geometry(turn: Turn) -> (f32, Vec3) {
    match turn {
        Turn::Sprite => (SPRITE_HEIGHT * 0.5, SPRITE_HALF_EXTENTS),
        Turn::Block => (BLOCK_SIZE * 0.5, BLOCK_HALF_EXTENTS),
    }
}

/// The world position a tile's center is at, on the board's surface
/// plane.
fn tile_center((col, row): (i32, i32)) -> Vec3 {
    let half = (BOARD_TILES - 1) as f32 * 0.5;
    Vec3::new(
        (col as f32 - half) * TILE_SIZE,
        0.0,
        (row as f32 - half) * TILE_SIZE,
    )
}

/// The tile `point` falls over, ignoring its height; `None` off the board.
fn tile_at(point: Vec3) -> Option<(i32, i32)> {
    let half = (BOARD_TILES - 1) as f32 * 0.5;
    let col = (point.x / TILE_SIZE + half + 0.5).floor() as i32;
    let row = (point.z / TILE_SIZE + half + 0.5).floor() as i32;
    ((0..BOARD_TILES).contains(&col) && (0..BOARD_TILES).contains(&row)).then_some((col, row))
}

/// Cursor target this frame: nothing, the unit whose turn it is, or a
/// board tile.
#[derive(Clone, Copy, PartialEq)]
enum Hover {
    None,
    CurrentUnit,
    Tile((i32, i32)),
}

struct Board {
    sprite: Unit,
    block: Unit,
    turn: Turn,
    selected: bool,
}

impl Board {
    fn init(ctx: &mut InitContext<'_, Board>) -> Result<Self, Error> {
        for &(_, _, seed, _) in &ROCKS {
            ctx.prepare(Rock { seed });
        }

        let (sprite_lift, _) = unit_geometry(Turn::Sprite);
        let (block_lift, _) = unit_geometry(Turn::Block);
        Ok(Self {
            sprite: Unit::resting((1, 1), sprite_lift),
            block: Unit::resting((BOARD_TILES - 2, BOARD_TILES - 2), block_lift),
            turn: Turn::Sprite,
            selected: false,
        })
    }

    fn camera() -> Camera {
        let eye = Vec3::new(9.0, 9.0, 9.0);
        Camera::new(
            View::look_at(eye, Vec3::ZERO),
            Projection::orthographic(11.0),
        )
    }

    fn current(&self) -> &Unit {
        match self.turn {
            Turn::Sprite => &self.sprite,
            Turn::Block => &self.block,
        }
    }

    fn current_mut(&mut self) -> &mut Unit {
        match self.turn {
            Turn::Sprite => &mut self.sprite,
            Turn::Block => &mut self.block,
        }
    }

    fn other(&self) -> &Unit {
        match self.turn {
            Turn::Sprite => &self.block,
            Turn::Block => &self.sprite,
        }
    }

    /// Resolves a left click: hitting the current unit's box toggles its
    /// selection; while selected, a ground hit that lands on an open tile
    /// orders a move there.
    fn handle_click(&mut self, ctx: &mut TickContext<'_, Board>) {
        if ctx.ui_wants_pointer() || !ctx.pressed(Button::Select) {
            return;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());
        let (lift, half) = unit_geometry(self.turn);

        if self.current().target.is_none() {
            let center = self.current().position;
            if ray.hit_aabb(center - half, center + half).is_some() {
                self.selected = !self.selected;
                return;
            }
        }
        if !self.selected {
            return;
        }

        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return;
        };
        let Some(tile) = tile_at(ray.at(distance)) else {
            return;
        };
        if tile == self.current().tile || tile == self.other().tile {
            return;
        }

        let destination = tile_center(tile) + Vec3::Y * lift;
        let heading = destination.x - self.current().position.x;
        let current = self.current_mut();
        if heading.abs() > f32::EPSILON {
            current.facing_right = heading > 0.0;
        }
        current.target = Some(destination);
        self.selected = false;
        ctx.play(Sound::Click);
    }

    /// Cursor target, `None` while the UI has the pointer.
    fn hovered(&self, ctx: &FrameContext<'_, Board>) -> Hover {
        if ctx.ui_wants_pointer() {
            return Hover::None;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());

        if self.current().target.is_none() {
            let (_, half) = unit_geometry(self.turn);
            let center = self.current().position;
            if ray.hit_aabb(center - half, center + half).is_some() {
                return Hover::CurrentUnit;
            }
        }
        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return Hover::None;
        };
        match tile_at(ray.at(distance)) {
            Some(tile) => Hover::Tile(tile),
            None => Hover::None,
        }
    }

    /// Whether a selected unit could move to `tile`: on the board, and
    /// standing under neither unit.
    fn reachable(&self, tile: (i32, i32)) -> bool {
        tile != self.current().tile && tile != self.other().tile
    }

    fn draw_board(&self, ctx: &mut FrameContext<'_, Board>, hover: Hover) {
        let scale = Vec3::new(TILE_SIZE - TILE_GAP, TILE_THICKNESS, TILE_SIZE - TILE_GAP);
        for col in 0..BOARD_TILES {
            for row in 0..BOARD_TILES {
                let tile = (col, row);
                let center = tile_center(tile) - Vec3::Y * (TILE_THICKNESS * 0.5);
                let reachable = self.selected && self.reachable(tile);
                let hovered = self.selected && hover == Hover::Tile(tile);
                let color = if hovered {
                    if reachable {
                        HOVER_REACHABLE_TILE
                    } else {
                        HOVER_BLOCKED_TILE
                    }
                } else if (col + row) % 2 == 0 {
                    LIGHT_TILE
                } else {
                    DARK_TILE
                };
                ctx.draw(
                    Cube.at(Transform::from_scale_rotation_translation(
                        scale,
                        Quat::IDENTITY,
                        center,
                    ))
                    .material(Material::lit(color)),
                );
                if reachable && !hovered {
                    self.draw_reachable_mark(ctx, tile);
                }
            }
        }
    }

    /// A mark over a reachable tile, its own tone apart from the
    /// checker's tone and the hover tone, so the checker still reads
    /// under it.
    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)),
        );
    }

    fn draw_rocks(&self, ctx: &mut FrameContext<'_, Board>) {
        for &(x, z, seed, scale) in &ROCKS {
            let angle = hash_signed(seed, 99) * core::f32::consts::PI;
            ctx.draw(
                Rock { seed }
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(scale),
                        Quat::from_rotation_y(angle),
                        Vec3::new(x, 0.5 * scale, z),
                    ))
                    .material(Material::lit(ROCK_COLOR)),
            );
        }
    }

    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/flock-parallelism.rs (line 680)

    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/sprite-adventure.rs (line 1301)

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

examples/breakout-game.rs (line 668)

    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/post-effects.rs (line 104)

    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 573)

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

    /// The listener: a cube drawn from the ground up to [`EYE_HEIGHT`],
    /// an ear pair set on ± `view`'s right, and a marker at the front that
    /// shows its fixed `-Z` facing.
    fn draw_listener(&self, ctx: &mut FrameContext<'_, SoundCheck>, view: View) {
        let head = view.eye();
        let ground = Vec3::new(head.x, 0.0, head.z);

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(LISTENER_WIDTH, head.y, LISTENER_DEPTH),
                Quat::IDENTITY,
                ground + Vec3::Y * head.y * 0.5,
            ))
            .material(Material::lit(LISTENER_COLOR)),
        );

        let right = listener_right(view) * EAR_OFFSET;
        for (offset, color) in [(right, RIGHT_EAR_COLOR), (-right, LEFT_EAR_COLOR)] {
            ctx.draw(
                Sphere { subdivisions: 1 }
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(EAR_SIZE),
                        Quat::IDENTITY,
                        head + offset,
                    ))
                    .material(Material::lit(color)),
            );
        }

        ctx.draw(
            Facing
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FACING_MARKER_SIZE),
                    Quat::IDENTITY,
                    head + Vec3::NEG_Z * (FACING_MARKER_SIZE * 0.5),
                ))
                .material(Material::lit(LISTENER_COLOR)),
        );
    }

    fn draw_merge_markers(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.merge_demo {
            return;
        }
        for (position, color) in [(MERGE_POS_A, MERGE_COLOR_A), (MERGE_POS_B, MERGE_COLOR_B)] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0),
                    Quat::IDENTITY,
                    position,
                ))
                .material(Material::lit(color)),
            );
        }
    }

    /// Draws the ring, each cube as dim as the gain its sustain is declared
    /// at.
    fn draw_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let over = 1.0 - nth as f32 / RING_COUNT as f32;
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF),
                    Quat::IDENTITY,
                    ring_place(nth),
                ))
                .material(Material::lit(RING_COLOR.dimmed(over))),
            );
        }
    }

Additional examples can be found in:

• examples/material-playground.rs
• examples/animation.rs

pub fn map<F>(self, f: F) -> Vec3

where F: FnMut(f32) -> f32,

Returns a vector containing each element of self modified by a mapping function f.

pub fn select(mask: BVec3, if_true: Vec3, if_false: Vec3) -> Vec3

Creates a vector from the elements in if_true and if_false, selecting which to use for each element of self.

A true element in the mask uses the corresponding element from if_true, and false uses the element from if_false.

pub const fn from_array(a: [f32; 3]) -> Vec3

Creates a new vector from an array.

pub const fn to_array(&self) -> [f32; 3]

Converts self to [x, y, z]

pub const fn from_slice(slice: &[f32]) -> Vec3

Creates a vector from the first 3 values in slice.

Panics

Panics if slice is less than 3 elements long.

pub fn write_to_slice(self, slice: &mut [f32])

Writes the elements of self to the first 3 elements in slice.

Panics

Panics if slice is less than 3 elements long.

pub fn extend(self, w: f32) -> Vec4

Creates a 4D vector from self and the given w value.

pub fn truncate(self) -> Vec2

Creates a 2D vector from the x and y elements of self, discarding z.

Truncation may also be performed by using self.xy().

pub fn from_homogeneous(v: Vec4) -> Vec3

Projects a homogeneous coordinate to 3D space by performing perspective divide.

Panics

Will panic if v.w is 0 when glam_assert is enabled.

pub fn to_homogeneous(self) -> Vec4

Creates a homogeneous coordinate from self, equivalent to self.extend(1.0).

pub fn to_vec3a(self) -> Vec3A

pub fn with_x(self, x: f32) -> Vec3

Creates a 3D vector from self with the given value of x.

pub fn with_y(self, y: f32) -> Vec3

Creates a 3D vector from self with the given value of y.

pub fn with_z(self, z: f32) -> Vec3

Creates a 3D vector from self with the given value of z.

pub fn dot(self, rhs: Vec3) -> f32

Computes the dot product of self and rhs.

pub fn dot_into_vec(self, rhs: Vec3) -> Vec3

Returns a vector where every component is the dot product of self and rhs.

pub fn cross(self, rhs: Vec3) -> Vec3

Computes the cross product of self and rhs.

Examples found in repository

examples/stress-preview.rs (line 558)

fn push_face(vertices: &mut Vec<Vertex>, indices: &mut Vec<u32>, a: Vec3, b: Vec3, c: Vec3) {
    let normal = (b - a).cross(c - a).normalize();
    let uvs = [
        Vec2::new(0.0, 1.0),
        Vec2::new(0.5, 0.0),
        Vec2::new(1.0, 1.0),
    ];
    let base = vertices.len() as u32;
    for (point, uv) in [a, b, c].into_iter().zip(uvs) {
        vertices.push(Vertex::new(point, normal, uv));
    }
    indices.extend([base, base + 1, base + 2]);
}

examples/sound-lab.rs (line 199)

fn facing_marker() -> MeshData {
    const TIP: Vec3 = Vec3::new(0.0, 0.0, -0.5);
    const BACK: [Vec3; 4] = [
        Vec3::new(-0.5, -0.5, 0.5),
        Vec3::new(0.5, -0.5, 0.5),
        Vec3::new(0.5, 0.5, 0.5),
        Vec3::new(-0.5, 0.5, 0.5),
    ];

    let mut vertices = Vec::with_capacity(BACK.len() * 3);
    for (corner, next) in BACK.iter().zip(BACK.iter().cycle().skip(1)) {
        let normal = (next - corner).cross(TIP - corner).normalize();
        vertices.extend([
            Vertex::new(*corner, normal, Vec2::new(0.0, 1.0)),
            Vertex::new(*next, normal, Vec2::new(1.0, 1.0)),
            Vertex::new(TIP, normal, Vec2::new(0.5, 0.0)),
        ]);
    }
    let indices = (0..vertices.len() as u32).collect();
    MeshData::new(vertices, indices)
}

/// Every sound this game plays. [`Sound::Break`] and [`Sound::Pulse`] read the
/// same source under two names, so sustaining one and playing the other
/// once never share a voice; [`Sound::Theme`] and [`Sound::ThemeDecoded`] do
/// the same for the streamed side against the decoded one, since a clip
/// decodes one way or the other for good, once built.
#[derive(Catalog, Clone, Copy, PartialEq, Eq, Hash)]
enum Sound {
    Bounce,
    Break,
    Serve,
    GameOver,
    Lost,
    Win,
    Click,
    Theme,
    ThemeDecoded,
    MenuTheme,
    Pulse,
}

impl Sound {
    /// The alternatives a one-shot play offers.
    const ONE_SHOTS: [Sound; 7] = [
        Sound::Bounce,
        Sound::Break,
        Sound::Serve,
        Sound::GameOver,
        Sound::Lost,
        Sound::Win,
        Sound::Click,
    ];

    /// The alternatives one source's sustain offers.
    const SOURCE_CHOICES: [Sound; 9] = [
        Sound::Bounce,
        Sound::Break,
        Sound::Serve,
        Sound::GameOver,
        Sound::Lost,
        Sound::Win,
        Sound::Click,
        Sound::Theme,
        Sound::ThemeDecoded,
    ];

    fn label(self) -> &'static str {
        match self {
            Sound::Bounce => "bounce",
            Sound::Break => "break",
            Sound::Serve => "serve",
            Sound::GameOver => "game over",
            Sound::Lost => "lost",
            Sound::Win => "win",
            Sound::Click => "click",
            Sound::Theme => "theme (streamed)",
            Sound::ThemeDecoded => "theme (decoded)",
            Sound::MenuTheme => "menu theme",
            Sound::Pulse => "pulse",
        }
    }
}

impl Sounds for Sound {
    fn build(&self, assets: &Assets) -> SoundData {
        match self {
            Sound::Bounce => assets.sound("bounce"),
            Sound::Break => assets.sound("break"),
            Sound::Serve => assets.sound("serve"),
            Sound::GameOver => assets.sound("gameover"),
            Sound::Lost => assets.sound("lost"),
            Sound::Win => assets.sound("win"),
            Sound::Click => assets.sound("click"),
            Sound::Theme => assets.sound("music").streamed(),
            Sound::ThemeDecoded => assets.sound("music"),
            Sound::MenuTheme => assets.sound("menu_music").streamed(),
            Sound::Pulse => assets.sound("break"),
        }
    }
}

/// The one button this game reads: it holds a source down and moves it.
#[derive(InputButtonAction, Clone, Copy, PartialEq)]
enum Button {
    Select,
}

impl InputButtonAction for Button {
    fn bindings(&self) -> Vec<ButtonBinding> {
        match self {
            Button::Select => vec![MouseButton::Left.into()],
        }
    }
}

/// The listener's walk, in the ground plane.
#[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::stick(Stick::Left),
            ],
        }
    }
}

struct Controls;

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

/// One source a drag moves: a cube on the ground, playing a sustained clip
/// with its own gain, reference, range, and pitch.
struct Source {
    position: Vec3,
    sound: Sound,
    gain: f32,
    reference: f32,
    range: f32,
    pitch: f32,
    /// Whether this source sustains at all; off keeps startup silent.
    enabled: bool,
}

impl Source {
    fn new(x: f32, z: f32, sound: Sound, range: f32, enabled: bool) -> Self {
        Self {
            position: Vec3::new(x, SOURCE_HEIGHT, z),
            sound,
            gain: 0.5,
            reference: SOURCE_REFERENCE,
            range,
            pitch: 1.0,
            enabled,
        }
    }

    /// This source's sustained cue, with the loop point that seeks far
    /// where its choice needs one.
    fn cue(&self) -> SoundCue<Sound> {
        let cue = self
            .sound
            .at(self.position)
            .gain(self.gain)
            .reference(self.reference)
            .range(self.range)
            .pitch(self.pitch);
        match self.sound {
            Sound::Theme | Sound::ThemeDecoded => cue.loop_from(THEME_LOOP_FROM),
            _ => cue,
        }
    }
}

struct SoundCheck {
    master_volume: f32,

    picked: Sound,
    one_shot_gain: f32,
    one_shot_pitch: f32,
    one_shot_fade: f32,
    trim_start: f32,
    trim_end: f32,
    one_shot_loop_from: f32,

    theme_on: bool,
    menu_on: bool,
    pulse_on: bool,
    cue_fade: f32,

    /// Sustains [`Sound::Click`] at [`MERGE_POS_A`] and [`MERGE_POS_B`]
    /// both at the default instance: shows the merge each source's own
    /// instance above keeps clear of.
    merge_demo: bool,

    /// Declares [`RING_COUNT`] sustains at once, more than the engine
    /// plays, so that the cap is heard as it allocates by level.
    ring_demo: bool,

    player: Vec2,
    player_prev: Vec2,
    sources: [Source; 3],
    dragging: Option<usize>,

    /// Every catalog value's length, read once at startup.
    durations: HashMap<Sound, Duration>,
}

impl SoundCheck {
    fn init(ctx: &mut InitContext<'_, SoundCheck>) -> Result<Self, Error> {
        let durations = ctx.durations();

        let picked = Sound::Bounce;
        let trim_end = durations.get(&picked).copied().unwrap_or_default();

        Ok(Self {
            master_volume: 1.0,

            picked,
            one_shot_gain: 1.0,
            one_shot_pitch: 1.0,
            one_shot_fade: SoundCue::<Sound>::DEFAULT_FADE.as_secs_f32(),
            trim_start: 0.0,
            trim_end: trim_end.as_secs_f32(),
            one_shot_loop_from: 0.0,

            theme_on: false,
            menu_on: false,
            pulse_on: false,
            cue_fade: 1.0,

            merge_demo: false,
            ring_demo: false,

            player: Vec2::ZERO,
            player_prev: Vec2::ZERO,
            sources: [
                Source::new(-2.5, -2.0, Sound::Bounce, 4.0, false),
                Source::new(2.5, -2.0, Sound::Serve, 4.0, false),
                Source::new(0.0, 2.8, Sound::Theme, 7.0, true),
            ],
            dragging: None,

            durations,
        })
    }

    fn camera(player: Vec2) -> Camera {
        let ground = Vec3::new(player.x, 0.0, player.y);
        Camera::new(
            View::look_at(
                ground + Vec3::new(0.0, CHASE_UP, CHASE_BACK),
                ground + Vec3::Y * 0.5,
            ),
            Projection::perspective(55.0),
        )
    }

    fn handle_walk(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        self.player_prev = self.player;
        if ctx.ui_wants_keyboard() {
            return;
        }
        let walk = ctx.axis2(Move::Walk);
        let world = Vec2::new(walk.x, -walk.y);
        self.player = (self.player + world * WALK_SPEED * ctx.dt().as_secs_f32())
            .clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
    }

    /// Takes hold of the source a click's ray intersects, moves it across
    /// the floor while the button stays down, and frees it on release.
    fn handle_drag(&mut self, ctx: &mut TickContext<'_, SoundCheck>) {
        // Read before the check below for the UI's own claim on the
        // pointer, so a release over it still frees a source a drag moved
        // there.
        if ctx.released(Button::Select) {
            self.dragging = None;
        }
        if ctx.ui_wants_pointer() {
            return;
        }
        let ray = ctx
            .last_camera()
            .ray_through(ctx.pointer(), ctx.window_size());

        if ctx.pressed(Button::Select) {
            self.dragging = self.sources.iter().position(|source| {
                ray.hit_sphere(source.position, SOURCE_PICK_RADIUS)
                    .is_some()
            });
        }

        let Some(index) = self.dragging else {
            return;
        };
        let Some(distance) = ray.hit_plane(ray::Plane {
            point: Vec3::ZERO,
            normal: Vec3::Y,
        }) else {
            return;
        };
        let hit = ray.at(distance);
        let dropped =
            Vec2::new(hit.x, hit.z).clamp(Vec2::splat(-PLAY_BOUND), Vec2::splat(PLAY_BOUND));
        self.sources[index].position = Vec3::new(dropped.x, SOURCE_HEIGHT, dropped.y);
    }

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

        let side_half = Vec3::new(WALL_THICKNESS * 0.5, WALL_HEIGHT * 0.5, ROOM_HALF);
        for side in [-1.0, 1.0] {
            let x = side * (ROOM_HALF - 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 end_half = Vec3::new(ROOM_HALF, WALL_HEIGHT * 0.5, WALL_THICKNESS * 0.5);
        for side in [-1.0, 1.0] {
            let z = side * (ROOM_HALF - WALL_THICKNESS * 0.5);
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    end_half * 2.0,
                    Quat::IDENTITY,
                    Vec3::new(0.0, end_half.y, z),
                ))
                .material(Material::lit(WALL_COLOR)),
            );
        }
    }

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

    /// The listener: a cube drawn from the ground up to [`EYE_HEIGHT`],
    /// an ear pair set on ± `view`'s right, and a marker at the front that
    /// shows its fixed `-Z` facing.
    fn draw_listener(&self, ctx: &mut FrameContext<'_, SoundCheck>, view: View) {
        let head = view.eye();
        let ground = Vec3::new(head.x, 0.0, head.z);

        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(LISTENER_WIDTH, head.y, LISTENER_DEPTH),
                Quat::IDENTITY,
                ground + Vec3::Y * head.y * 0.5,
            ))
            .material(Material::lit(LISTENER_COLOR)),
        );

        let right = listener_right(view) * EAR_OFFSET;
        for (offset, color) in [(right, RIGHT_EAR_COLOR), (-right, LEFT_EAR_COLOR)] {
            ctx.draw(
                Sphere { subdivisions: 1 }
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(EAR_SIZE),
                        Quat::IDENTITY,
                        head + offset,
                    ))
                    .material(Material::lit(color)),
            );
        }

        ctx.draw(
            Facing
                .at(Transform::from_scale_rotation_translation(
                    Vec3::splat(FACING_MARKER_SIZE),
                    Quat::IDENTITY,
                    head + Vec3::NEG_Z * (FACING_MARKER_SIZE * 0.5),
                ))
                .material(Material::lit(LISTENER_COLOR)),
        );
    }

    fn draw_merge_markers(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.merge_demo {
            return;
        }
        for (position, color) in [(MERGE_POS_A, MERGE_COLOR_A), (MERGE_POS_B, MERGE_COLOR_B)] {
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF * 2.0),
                    Quat::IDENTITY,
                    position,
                ))
                .material(Material::lit(color)),
            );
        }
    }

    /// Draws the ring, each cube as dim as the gain its sustain is declared
    /// at.
    fn draw_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let over = 1.0 - nth as f32 / RING_COUNT as f32;
            ctx.draw(
                Cube.at(Transform::from_scale_rotation_translation(
                    Vec3::splat(SOURCE_HALF),
                    Quat::IDENTITY,
                    ring_place(nth),
                ))
                .material(Material::lit(RING_COLOR.dimmed(over))),
            );
        }
    }

    /// The controls held at the left: master volume, sustained cues, and
    /// each source's own knobs.
    fn side_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) {
        #[cfg(target_arch = "wasm32")]
        let unlocked = ctx.sound_unlocked();

        let master_volume = &mut self.master_volume;
        let theme_on = &mut self.theme_on;
        let menu_on = &mut self.menu_on;
        let pulse_on = &mut self.pulse_on;
        let cue_fade = &mut self.cue_fade;
        let merge_demo = &mut self.merge_demo;
        let ring_demo = &mut self.ring_demo;
        let ring_label = format!("cap demo: sustain {RING_COUNT} sounds at once");
        let ring_note = format!(
            "each one is quieter than the one before it, so the engine plays the loudest {MAX_VOICES} and the rest go silent without stopping"
        );
        let sources = &mut self.sources;

        ctx.ui(|ui| {
            egui::Panel::left("controls").show(ui, |ui| {
                egui::ScrollArea::vertical()
                    .auto_shrink([false, false])
                    .show(ui, |ui| {
                        ui.heading("master");
                        ui.add(egui::Slider::new(master_volume, 0.0..=1.5).text("volume"));
                        #[cfg(target_arch = "wasm32")]
                        if !unlocked {
                            ui.label("audio unlocks on the first click or key in the browser");
                        }

                        ui.separator();
                        ui.heading("cue lab");
                        ui.label("a checked box is the sustain declaration");
                        ui.label("unchecking fades it out and parks it");
                        ui.checkbox(theme_on, Sound::Theme.label());
                        ui.checkbox(menu_on, Sound::MenuTheme.label());
                        ui.checkbox(pulse_on, Sound::Pulse.label());
                        ui.add(egui::Slider::new(cue_fade, 0.0..=3.0).text("fade (seconds)"));

                        ui.separator();
                        ui.heading("spatial lab");
                        ui.label("drag a source's marker on the floor to move it");
                        ui.label(
                            "a source is at full level inside its gold ring and falls to nothing at the white one",
                        );
                        ui.label("red is the right ear (RCA convention), white is the left");
                        ui.label("the point on the listener always faces -Z");
                        for (index, source) in sources.iter_mut().enumerate() {
                            ui.push_id(index, |ui| {
                                ui.separator();
                                ui.label(format!("source {}", index + 1));
                                ui.checkbox(&mut source.enabled, "enabled");
                                egui::ComboBox::from_label("clip")
                                    .selected_text(source.sound.label())
                                    .show_ui(ui, |ui| {
                                        for choice in Sound::SOURCE_CHOICES {
                                            ui.selectable_value(
                                                &mut source.sound,
                                                choice,
                                                choice.label(),
                                            );
                                        }
                                    });
                                ui.add(egui::Slider::new(&mut source.gain, 0.0..=2.0).text("gain"));
                                ui.add(
                                    egui::Slider::new(&mut source.range, 1.0..=12.0).text("range"),
                                );
                                let range = source.range;
                                ui.add(
                                    egui::Slider::new(&mut source.reference, 0.25..=range)
                                        .text("reference"),
                                );
                                ui.add(
                                    egui::Slider::new(&mut source.pitch, 0.5..=2.0).text("pitch"),
                                );
                            });
                        }
                        ui.separator();
                        ui.label(
                            "each enabled source above sustains at its own instance (0, 1, 2 by position), so the same clip can play at every one without merging into one voice",
                        );
                        ui.checkbox(merge_demo, "merge demo: same clip, both at instance 0");
                        ui.label(
                            "both declarations below target the same clip at the default instance",
                        );
                        ui.label(
                            "only the one declared last is heard, proof of what the sources above avoid",
                        );
                        ui.separator();
                        ui.checkbox(ring_demo, &ring_label);
                        ui.label(&ring_note);
                        ui.label(
                            "walk into the ring, or turn a source up, and what is played changes with what is loudest",
                        );
                    });
            });
        });
    }

    /// Reads what the one-shot controls hold, returning whether `play` and
    /// `play x32` were pressed this frame — read inside the closure, applied
    /// after it, since the closure cannot borrow `ctx`.
    fn one_shot_panel(&mut self, ctx: &mut FrameContext<'_, SoundCheck>) -> (bool, bool) {
        let mut play_once = false;
        let mut play_many = false;
        let durations = &self.durations;
        let picked = &mut self.picked;
        let gain = &mut self.one_shot_gain;
        let pitch = &mut self.one_shot_pitch;
        let fade = &mut self.one_shot_fade;
        let trim_start = &mut self.trim_start;
        let trim_end = &mut self.trim_end;
        let loop_from = &mut self.one_shot_loop_from;
        let duration = durations
            .get(picked)
            .copied()
            .unwrap_or_default()
            .as_secs_f32()
            .max(0.001);

        ctx.ui(|ui| {
            egui::Panel::bottom("one-shot").show(ui, |ui| {
                ui.heading("one-shot lab");
                egui::ComboBox::from_label("clip")
                    .selected_text(picked.label())
                    .show_ui(ui, |ui| {
                        for choice in Sound::ONE_SHOTS {
                            if ui
                                .selectable_label(*picked == choice, choice.label())
                                .clicked()
                                && *picked != choice
                            {
                                *picked = choice;
                                *trim_start = 0.0;
                                *trim_end = durations
                                    .get(&choice)
                                    .copied()
                                    .unwrap_or_default()
                                    .as_secs_f32();
                                *loop_from = 0.0;
                            }
                        }
                    });

                ui.add(egui::Slider::new(gain, 0.0..=2.0).text("gain"));
                ui.add(egui::Slider::new(pitch, 0.5..=2.0).text("pitch"));
                ui.add(egui::Slider::new(fade, 0.0..=2.0).text("fade (seconds)"));

                duration_bar(ui, duration, trim_start, trim_end, loop_from);
                ui.label(
                    "the marker sets loop_from, which a one-shot ignores: only sustain reads it",
                );

                ui.horizontal(|ui| {
                    play_once = ui.button("play").clicked();
                    play_many = ui.button("play ×32 (overruns the voice cap)").clicked();
                });
            });
        });

        (play_once, play_many)
    }

    fn one_shot_cue(&self) -> SoundCue<Sound> {
        self.picked
            .gain(self.one_shot_gain)
            .pitch(self.one_shot_pitch)
            .fade(Duration::from_secs_f32(self.one_shot_fade))
            .trim_to(
                Duration::from_secs_f32(self.trim_start),
                Duration::from_secs_f32(self.trim_end),
            )
            .loop_from(Duration::from_secs_f32(self.one_shot_loop_from))
    }

    /// Declares [`RING_COUNT`] sustains on a ring, each less loud than the
    /// one before it, so the engine's cap plays the loudest of them and the
    /// rest hold no voice while their playback goes on.
    fn sustain_ring(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        if !self.ring_demo {
            return;
        }
        for nth in 0..RING_COUNT {
            let gain = RING_GAIN * (1.0 - nth as f32 / RING_COUNT as f32);
            ctx.sustain(
                Sound::Pulse
                    .at(ring_place(nth))
                    .gain(gain)
                    .reference(RING_REFERENCE)
                    .range(RING_RADIUS * 3.0)
                    .instance(nth + 1),
            );
        }
    }

    fn sustain_cues(&self, ctx: &mut FrameContext<'_, SoundCheck>) {
        let fade = Duration::from_secs_f32(self.cue_fade);
        if self.theme_on {
            ctx.sustain(Sound::Theme.gain(0.5).fade(fade));
        }
        if self.menu_on {
            ctx.sustain(Sound::MenuTheme.gain(0.5).fade(fade));
        }
        if self.pulse_on {
            ctx.sustain(Sound::Pulse.gain(0.3).fade(fade));
        }
    }
}

/// Where the `nth` sustain of the ring stands: around the room, starting
/// behind the listener's back.
fn ring_place(nth: u32) -> Vec3 {
    let turn = TAU * nth as f32 / RING_COUNT as f32;

    Vec3::new(
        turn.sin() * RING_RADIUS,
        SOURCE_HEIGHT,
        turn.cos() * RING_RADIUS,
    )
}

/// The direction the ear pair is offset along — the same side the
/// engine's own pan reads.
fn listener_right(view: View) -> Vec3 {
    (view.target() - view.eye())
        .normalize_or_zero()
        .cross(view.up())
}

examples/isometric-board.rs (line 744)

fn build_rock(seed: u32) -> MeshData {
    let corners: [Vec3; 8] = core::array::from_fn(|index| {
        let sign = Vec3::new(
            if index & 1 == 0 { -0.5 } else { 0.5 },
            if index & 2 == 0 { -0.5 } else { 0.5 },
            if index & 4 == 0 { -0.5 } else { 0.5 },
        );
        sign + corner_offset(seed, index as u32)
    });
    let corner_at = |sign: Vec3| corners[corner_index(sign)];

    let mut vertices = Vec::with_capacity(ROCK_FACES.len() * 4);
    let mut indices = Vec::with_capacity(ROCK_FACES.len() * 6);
    for (face, &(normal, right, up)) in ROCK_FACES.iter().enumerate() {
        let quad = [
            corner_at(normal - right - up),
            corner_at(normal + right - up),
            corner_at(normal + right + up),
            corner_at(normal - right + up),
        ];
        let normal = (quad[1] - quad[0]).cross(quad[3] - quad[0]).normalize();
        let uvs = [
            Vec2::new(0.0, 1.0),
            Vec2::new(1.0, 1.0),
            Vec2::new(1.0, 0.0),
            Vec2::new(0.0, 0.0),
        ];
        vertices.extend(
            quad.into_iter()
                .zip(uvs)
                .map(|(corner, uv)| Vertex::new(corner, normal, uv)),
        );
        let base = face as u32 * 4;
        indices.extend(ROCK_TRIANGLES.map(|index| base + index));
    }
    MeshData::new(vertices, indices)
}

pub fn min(self, rhs: Vec3) -> Vec3

Returns a vector containing the minimum values for each element of self and rhs.

In other words this computes [min(x, rhs.x), min(self.y, rhs.y), ..].

NaN propogation does not follow IEEE 754-2008 semantics for minNum and may differ on different SIMD architectures.

pub fn max(self, rhs: Vec3) -> Vec3

Returns a vector containing the maximum values for each element of self and rhs.

In other words this computes [max(self.x, rhs.x), max(self.y, rhs.y), ..].

NaN propogation does not follow IEEE 754-2008 semantics for maxNum and may differ on different SIMD architectures.

pub fn clamp(self, min: Vec3, max: Vec3) -> Vec3

Component-wise clamping of values, similar to f32::clamp.

Each element in min must be less-or-equal to the corresponding element in max.

NaN propogation does not follow IEEE 754-2008 semantics and may differ on different SIMD architectures.

Panics

Will panic if min is greater than max when glam_assert is enabled.

pub fn min_element(self) -> f32

Returns the horizontal minimum of self.

In other words this computes min(x, y, ..).

NaN propogation does not follow IEEE 754-2008 semantics and may differ on different SIMD architectures.

pub fn max_element(self) -> f32

Returns the horizontal maximum of self.

In other words this computes max(x, y, ..).

NaN propogation does not follow IEEE 754-2008 semantics and may differ on different SIMD architectures.

pub fn min_position(self) -> usize

Returns the index of the first minimum element of self.

pub fn max_position(self) -> usize

Returns the index of the first maximum element of self.

pub fn element_sum(self) -> f32

Returns the sum of all elements of self.

In other words, this computes self.x + self.y + ...

pub fn element_product(self) -> f32

Returns the product of all elements of self.

In other words, this computes self.x * self.y * ...

pub fn cmpeq(self, rhs: Vec3) -> BVec3

Returns a vector mask containing the result of a == comparison for each element of self and rhs.

In other words, this computes [self.x == rhs.x, self.y == rhs.y, ..] for all elements.

pub fn cmpne(self, rhs: Vec3) -> BVec3

Returns a vector mask containing the result of a != comparison for each element of self and rhs.

In other words this computes [self.x != rhs.x, self.y != rhs.y, ..] for all elements.

pub fn cmpge(self, rhs: Vec3) -> BVec3

Returns a vector mask containing the result of a >= comparison for each element of self and rhs.

In other words this computes [self.x >= rhs.x, self.y >= rhs.y, ..] for all elements.

pub fn cmpgt(self, rhs: Vec3) -> BVec3

Returns a vector mask containing the result of a > comparison for each element of self and rhs.

In other words this computes [self.x > rhs.x, self.y > rhs.y, ..] for all elements.

pub fn cmple(self, rhs: Vec3) -> BVec3

Returns a vector mask containing the result of a <= comparison for each element of self and rhs.

In other words this computes [self.x <= rhs.x, self.y <= rhs.y, ..] for all elements.

pub fn cmplt(self, rhs: Vec3) -> BVec3

Returns a vector mask containing the result of a < comparison for each element of self and rhs.

In other words this computes [self.x < rhs.x, self.y < rhs.y, ..] for all elements.

pub fn abs(self) -> Vec3

Returns a vector containing the absolute value of each element of self.

pub fn signum(self) -> Vec3

Returns a vector with elements representing the sign of self.

• 1.0 if the number is positive, +0.0 or INFINITY
• -1.0 if the number is negative, -0.0 or NEG_INFINITY
• NAN if the number is NAN

pub fn copysign(self, rhs: Vec3) -> Vec3

Returns a vector with signs of rhs and the magnitudes of self.

pub fn is_negative_bitmask(self) -> u32

Returns a bitmask with the lowest 3 bits set to the sign bits from the elements of self.

A negative element results in a 1 bit and a positive element in a 0 bit. Element x goes into the first lowest bit, element y into the second, etc.

An element is negative if it has a negative sign, including -0.0, NaNs with negative sign bit and negative infinity.

pub fn is_negative_mask(self) -> BVec3

Returns a mask indicating which components are negative.

An element is negative if it has a negative sign, including -0.0, NaNs with negative sign bit and negative infinity.

pub fn is_finite(self) -> bool

Returns true if, and only if, all elements are finite. If any element is either NaN, positive or negative infinity, this will return false.

pub fn is_finite_mask(self) -> BVec3

Performs is_finite on each element of self, returning a vector mask of the results.

In other words, this computes [x.is_finite(), y.is_finite(), ...].

pub fn is_nan(self) -> bool

Returns true if any elements are NaN.

pub fn is_nan_mask(self) -> BVec3

Performs is_nan on each element of self, returning a vector mask of the results.

In other words, this computes [x.is_nan(), y.is_nan(), ...].

pub fn length(self) -> f32

Computes the length of self.

Examples found in repository

examples/isometric-board.rs (line 309)

    fn advance(&mut self, dt: Duration) -> bool {
        let Some(target) = self.target else {
            return false;
        };
        let to_target = target - self.position;
        let distance = to_target.length();
        let step = UNIT_SPEED * dt.as_secs_f32();
        if distance <= step {
            self.position = target;
            self.target = None;
            true
        } else {
            self.position += to_target * (step / distance);
            false
        }
    }

examples/animation.rs (line 705)

    fn advance(&mut self, ctx: &mut TickContext<'_, Scene>) -> f32 {
        let control = ctx.axis2(Move::Walk).clamp_length_max(1.0);
        let turn = Quat::from_rotation_y(self.camera_yaw);
        let heading = turn * Vec3::X * control.x + turn * Vec3::NEG_Z * control.y;
        let dt = ctx.dt().as_secs_f32();
        if let Some(direction) = heading.try_normalize() {
            let wanted = direction.x.atan2(direction.z);
            let turn = (wanted - self.elf_yaw + core::f32::consts::PI).rem_euclid(TAU)
                - core::f32::consts::PI;
            self.elf_yaw += turn.clamp(-TURN_RATE * dt, TURN_RATE * dt);
        }
        let cap = if ctx.down(Button::Run) { 1.0 } else { WALK_CAP };
        self.elf_pos += heading * cap * ELF_SPEED * dt;
        heading.length() * cap
    }

pub fn length_squared(self) -> f32

Computes the squared length of self.

This is faster than length() as it avoids a square root operation.

Examples found in repository

examples/material-playground.rs (line 836)

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

pub fn length_recip(self) -> f32

Computes 1.0 / length().

For valid results, self must not be of length zero.

pub fn distance(self, rhs: Vec3) -> f32

Computes the Euclidean distance between two points in space.

Examples found in repository

examples/animation.rs (line 725)

    fn patch_underfoot(&self) -> Option<Vec3> {
        HURT_PATCHES
            .into_iter()
            .find(|&patch| self.elf_pos.distance(patch) < HURT_RADIUS)
    }

    /// Reads the controls and moves the elf, filling [`Self::elf_input`]
    /// for [`ElfState`] to read.
    fn tick_elf(&mut self, ctx: &mut TickContext<'_, Scene>) {
        let grounded = matches!(
            self.elf_animator.state(),
            ElfState::Idle | ElfState::Locomotion
        );

        self.elf_input.speed = self.advance(ctx);
        self.elf_input.attack = ctx.pressed(Button::Attack);
        self.elf_input.jump = ctx.pressed(Button::Jump);
        self.elf_input.dance = ctx.pressed(Button::Dance);

        self.elf_input.near_seat = self.elf_pos.distance(SEAT_POSITION) < SEAT_INTERACT_RADIUS;
        self.elf_input.interact = ctx.pressed(Button::Interact);
        if self.elf_input.interact && grounded && self.elf_input.near_seat {
            self.elf_pos = SEAT_SPOT;
            self.elf_yaw = SEAT_FACING;
        }

        let underfoot = self.patch_underfoot();
        let entered_patch = underfoot.is_some() && !self.in_patch;
        self.in_patch = underfoot.is_some();
        self.hits += u32::from(entered_patch);
        self.elf_input.hit = entered_patch && self.hits < FATAL_HITS;
        self.elf_input.dying = entered_patch && self.hits >= FATAL_HITS;
        if entered_patch {
            self.last_event = match self.elf_input.dying {
                true => "elf died",
                false => "elf hit",
            };
        }
    }

    /// Starts a new [`Animator`] over the elf's own state, its position and
    /// hit count reset with it.
    fn restart_elf(&mut self) {
        self.elf_animator = Animator::new();
        self.elf_pos = ELF_START;
        self.elf_prev = ELF_START;
        self.elf_yaw = 0.0;
        self.elf_height = 0.0;
        self.elf_height_prev = 0.0;
        self.jump_speed = 0.0;
        self.elf_input = ElfInput::default();
        self.hits = 0;
        self.in_patch = false;
        self.last_event = "new elf started";
    }

    fn panel(&self, ctx: &mut FrameContext<'_, Scene>) {
        let state = match self.elf_animator.state() {
            ElfState::Idle => "idle",
            ElfState::Locomotion if self.elf_input.speed > WALK_CAP => "running",
            ElfState::Locomotion => "walking",
            ElfState::Attack => "attacking",
            ElfState::Hit => "hit",
            ElfState::Death => "dead",
            ElfState::SitDown => "sitting down",
            ElfState::Sit => "sitting",
            ElfState::StandUp => "standing up",
            ElfState::Jump => "jumping",
            ElfState::Dance => "dancing",
        };
        ctx.ui(|ui| {
            egui::Frame::new()
                .fill(egui::Color32::from_black_alpha(PANEL_BACKDROP))
                .inner_margin(PANEL_PADDING)
                .corner_radius(f32::from(PANEL_PADDING))
                .show(ui, |ui| {
                    ui.heading(panel_text(format!("elf is {state}")));
                    ui.label(panel_text(format!(
                        "hits taken {} of the {} red patches hurt for, {}",
                        self.hits, FATAL_HITS, self.last_event
                    )));
                    ui.label(panel_text(match self.elf_animator.transitioning() {
                        true => "fading between clips",
                        false => "one clip playing",
                    }));
                    ui.add_space(f32::from(PANEL_PADDING));
                    egui::Grid::new("controls").show(ui, |ui| {
                        for (key, does) in CONTROLS {
                            ui.label(panel_text(key));
                            ui.label(panel_text(does));
                            ui.end_row();
                        }
                    });
                });
        });
    }

    /// A prompt over the seat, each hurt patch, and the scrubbed elf,
    /// naming what a player finds there; the seat's own prompt names the
    /// live binding of `Button::Interact` by its own name, not one fixed
    /// in the code, and is absent while the elf sits on it.
    fn draw_prompts(&self, ctx: &mut FrameContext<'_, Scene>, camera: Camera) {
        let sit_key = ctx
            .bindings(Button::Interact)
            .into_iter()
            .next()
            .map_or_else(|| "interact".to_owned(), |binding| binding.to_string());
        let sit = ctx.text_layout(
            &format!("{sit_key} sits"),
            egui::FontId::proportional(PROMPT_SIZE),
        );
        let hurts = ctx.text_layout("hurts", egui::FontId::proportional(PROMPT_SIZE));
        let walk_closer = ctx.text_layout("walk closer", egui::FontId::proportional(PROMPT_SIZE));

        let mut prompts = vec![(
            SCRUBBED_ELF_POSITION + Vec3::Y * (ELF_HEIGHT + PROMPT_LIFT),
            walk_closer,
        )];
        if !self.elf_animator.state().seated() {
            prompts.push((
                SEAT_POSITION + Vec3::Y * (SEAT_HEAD_HEIGHT + PROMPT_LIFT),
                sit,
            ));
        }
        prompts.extend(HURT_PATCHES.map(|patch| (patch + Vec3::Y * PROMPT_LIFT, hurts.clone())));

        let window_size = ctx.window_size();
        let pixels_per_point = ctx.pixels_per_point();
        ctx.ui(|ui| {
            let painter = ui.painter();
            for (point, galley) in prompts {
                let Some(pixel) = camera.pixel_of(point, window_size) else {
                    continue;
                };
                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(PROMPT_PADDING * 2.0),
                );
                painter.rect_filled(
                    backdrop,
                    PROMPT_PADDING,
                    egui::Color32::from_black_alpha(PANEL_BACKDROP),
                );
                painter.galley(pos, galley, PANEL_TEXT_COLOR);
            }
        });
    }
}

impl Game for Scene {
    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<'_, Scene>) {
        self.elf_prev = self.elf_pos;
        self.elf_height_prev = self.elf_height;

        if ctx.pressed(Button::Restart) {
            self.restart_elf();
        }
        if ctx.pressed(Button::Hold) {
            self.holding = true;
        }
        if ctx.pressed(Button::Release) {
            self.holding = false;
        }

        self.elf_input.landed = self.fall(ctx.dt().as_secs_f32());
        self.tick_elf(ctx);
        ctx.animate(Elf, &mut self.elf_animator, &self.elf_input);

        if self.elf_animator.entered(ElfState::Jump) {
            self.jump_speed = JUMP_LAUNCH_SPEED;
        }
        if self.elf_animator.left(ElfState::StandUp) {
            self.last_event = "elf stood up";
        }
        if self.elf_animator.entered(ElfState::Sit) {
            self.last_event = "elf sat down";
        }
        if self.elf_animator.entered(ElfState::Death) {
            self.last_event = "elf died";
        }

        let scrubbed_input = ScrubbedInput {
            settled: settled_at(self.elf_pos.distance(SCRUBBED_ELF_POSITION)),
        };
        ctx.animate(Elf, &mut self.scrubbed_animator, &scrubbed_input);
        ctx.animate(Butterfly, &mut self.butterfly_animator, &());
    }

examples/breakout-game.rs (line 696)

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

examples/sprite-adventure.rs (line 1170)

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

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

    /// The player: upright so it always faces the camera about `+Y`,
    /// windowed to its facing's row and the walk cycle's current frame.
    fn draw_walker(&self, ctx: &mut FrameContext<'_, Keep>, ground: Vec3) {
        let step = if self.walk_ticks > 0 {
            (self.walk_ticks / TICKS_PER_WALK_FRAME) % WALKER_COLUMNS
        } else {
            0
        };
        let cell = Sheet::new(UVec2::new(WALKER_COLUMNS, WALKER_ROWS))
            .cell_at(UVec2::new(step, self.facing as u32));
        let size = Vec2::new(WALKER_WIDTH, WALKER_HEIGHT);

        ctx.draw(
            Walker
                .at(Transform::from_scale_rotation_translation(
                    size.extend(1.0),
                    Quat::IDENTITY,
                    ground + Vec3::Y * (WALKER_HEIGHT * 0.5),
                ))
                .upright()
                .frame(cell),
        );
    }

    fn frame_overworld(&mut self, ctx: &mut FrameContext<'_, Keep>) {
        let drawn_at = self.previous.lerp(self.position, ctx.alpha());
        ctx.set_camera(Self::camera(drawn_at, OVERWORLD_CAMERA_OFFSET));
        ctx.light(Light::directional(SUN_DIRECTION, SUN_COLOR).shadow());

        self.draw_ground(ctx);
        self.draw_hedgerow(ctx);
        self.draw_pond(ctx);
        self.draw_crates(ctx);
        self.draw_well(ctx);
        self.draw_flora(ctx);
        Self::draw_mouth(ctx, ENTRANCE);
        self.draw_walker(ctx, drawn_at);
    }

    fn frame_cave(&mut self, ctx: &mut FrameContext<'_, Keep>) {
        let drawn_at = self.previous.lerp(self.position, ctx.alpha());
        let camera = Self::camera(drawn_at, CAVE_CAMERA_OFFSET);
        ctx.set_camera(camera);

        self.draw_cave_floor(ctx);
        self.draw_cave_walls(ctx);
        Self::draw_door_wall(ctx, (self.ghost > 0.0).then_some(drawn_at.x), self.ghost);
        Self::draw_mouth(ctx, EXIT);
        self.draw_torches(ctx);
        self.draw_door(ctx, self.ghost);
        self.draw_door_frame(ctx, self.ghost);
        if !self.gem_taken {
            self.draw_gem(ctx);
        }
        self.draw_walker(ctx, drawn_at);
        self.draw_door_prompt(ctx, camera);
    }

    /// Instructions and the door's interact hint — gathered before `ctx.ui`,
    /// which cannot read `ctx`.
    fn overlay(&mut self, ctx: &mut FrameContext<'_, Keep>) {
        let near_door = self.area == Area::Cave
            && !self.door_opening
            && self.position.distance(INTERACT_POINT) < INTERACT_RADIUS;
        let gem_taken = self.area == Area::Cave && self.gem_taken;
        let mut reset_clicked = false;

        ctx.ui(|ui| {
            egui::Frame::new()
                .fill(egui::Color32::from_black_alpha(HUD_BACKDROP))
                .inner_margin(HUD_PADDING)
                .corner_radius(f32::from(HUD_PADDING))
                .show(ui, |ui| {
                    ui.visuals_mut().override_text_color = Some(egui::Color32::WHITE);
                    ui.label("wasd / arrows / stick to walk");
                    if near_door {
                        ui.label("e / west button to open the door");
                    }
                    if gem_taken {
                        ui.label("gem recovered");
                    }
                    ui.label("kept between runs: position, gem, cave");
                    ui.label("r to reset world");
                    if ui.button("reset world").clicked() {
                        reset_clicked = true;
                    }
                });
        });

        if reset_clicked {
            self.reset_requested = true;
        }
    }

pub fn distance_squared(self, rhs: Vec3) -> f32

Compute the squared euclidean distance between two points in space.

pub fn div_euclid(self, rhs: Vec3) -> Vec3

Returns the element-wise quotient of [Euclidean division] of self by rhs.

pub fn rem_euclid(self, rhs: Vec3) -> Vec3

Returns the element-wise remainder of Euclidean division of self by rhs.

pub fn normalize(self) -> Vec3

Returns self normalized to length 1.0.

For valid results, self must be finite and not of length zero, nor very close to zero.

See also Self::try_normalize() and Self::normalize_or_zero().

Panics

Will panic if the resulting normalized vector is not finite when glam_assert is enabled.

Examples found in repository

examples/breakout-game.rs (line 393)

    fn launch(&mut self) {
        self.ball_vel = Vec3::new(0.35, 0.0, -1.0).normalize() * BALL_SPEED;
        self.phase = Phase::Playing;
    }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

examples/flock-parallelism.rs (line 676)

    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/sound-lab.rs (line 199)

fn facing_marker() -> MeshData {
    const TIP: Vec3 = Vec3::new(0.0, 0.0, -0.5);
    const BACK: [Vec3; 4] = [
        Vec3::new(-0.5, -0.5, 0.5),
        Vec3::new(0.5, -0.5, 0.5),
        Vec3::new(0.5, 0.5, 0.5),
        Vec3::new(-0.5, 0.5, 0.5),
    ];

    let mut vertices = Vec::with_capacity(BACK.len() * 3);
    for (corner, next) in BACK.iter().zip(BACK.iter().cycle().skip(1)) {
        let normal = (next - corner).cross(TIP - corner).normalize();
        vertices.extend([
            Vertex::new(*corner, normal, Vec2::new(0.0, 1.0)),
            Vertex::new(*next, normal, Vec2::new(1.0, 1.0)),
            Vertex::new(TIP, normal, Vec2::new(0.5, 0.0)),
        ]);
    }
    let indices = (0..vertices.len() as u32).collect();
    MeshData::new(vertices, indices)
}

examples/material-playground.rs (line 349)

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

examples/stress-preview.rs (line 376)

    fn handle_camera(&mut self, ctx: &mut FrameContext<'_, Self>, elapsed: f32) {
        if ctx.ui_wants_pointer() || ctx.ui_wants_keyboard() {
            return;
        }
        let pan = ctx.axis2(Motion::Pan);
        let wheel = ctx.axis(Height::Wheel);
        let look = if ctx.down(Drag::Turn) {
            ctx.axis2(Motion::Look)
        } else {
            Vec2::ZERO
        };
        if pan == Vec2::ZERO && wheel == 0.0 && look == Vec2::ZERO {
            return;
        }

        let player = self.player.get_or_insert_with(|| {
            let eye = Self::orbit_eye(elapsed);
            let forward = (Vec3::ZERO - eye).normalize();
            Player {
                eye,
                yaw: (-forward.x).atan2(-forward.z),
                pitch: forward.y.asin(),
            }
        });

        player.yaw -= look.x;
        player.pitch = (player.pitch + look.y).clamp(-PITCH_LIMIT, PITCH_LIMIT);

        let forward = Vec3::new(-player.yaw.sin(), 0.0, -player.yaw.cos());
        let right = Vec3::new(player.yaw.cos(), 0.0, -player.yaw.sin());
        player.eye += (forward * pan.y + right * pan.x) * PAN_SPEED * ctx.dt().as_secs_f32();
        player.eye.y =
            (player.eye.y + wheel * WHEEL_STEP).clamp(MIN_CAMERA_HEIGHT, MAX_CAMERA_HEIGHT);
    }

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

/// One triangle, shaded flat, over `a`, `b`, `c`, in the order that faces
/// outward: counter-clockwise as seen from the side its own normal points
/// to.
fn push_face(vertices: &mut Vec<Vertex>, indices: &mut Vec<u32>, a: Vec3, b: Vec3, c: Vec3) {
    let normal = (b - a).cross(c - a).normalize();
    let uvs = [
        Vec2::new(0.0, 1.0),
        Vec2::new(0.5, 0.0),
        Vec2::new(1.0, 1.0),
    ];
    let base = vertices.len() as u32;
    for (point, uv) in [a, b, c].into_iter().zip(uvs) {
        vertices.push(Vertex::new(point, normal, uv));
    }
    indices.extend([base, base + 1, base + 2]);
}

examples/isometric-board.rs (line 744)

fn build_rock(seed: u32) -> MeshData {
    let corners: [Vec3; 8] = core::array::from_fn(|index| {
        let sign = Vec3::new(
            if index & 1 == 0 { -0.5 } else { 0.5 },
            if index & 2 == 0 { -0.5 } else { 0.5 },
            if index & 4 == 0 { -0.5 } else { 0.5 },
        );
        sign + corner_offset(seed, index as u32)
    });
    let corner_at = |sign: Vec3| corners[corner_index(sign)];

    let mut vertices = Vec::with_capacity(ROCK_FACES.len() * 4);
    let mut indices = Vec::with_capacity(ROCK_FACES.len() * 6);
    for (face, &(normal, right, up)) in ROCK_FACES.iter().enumerate() {
        let quad = [
            corner_at(normal - right - up),
            corner_at(normal + right - up),
            corner_at(normal + right + up),
            corner_at(normal - right + up),
        ];
        let normal = (quad[1] - quad[0]).cross(quad[3] - quad[0]).normalize();
        let uvs = [
            Vec2::new(0.0, 1.0),
            Vec2::new(1.0, 1.0),
            Vec2::new(1.0, 0.0),
            Vec2::new(0.0, 0.0),
        ];
        vertices.extend(
            quad.into_iter()
                .zip(uvs)
                .map(|(corner, uv)| Vertex::new(corner, normal, uv)),
        );
        let base = face as u32 * 4;
        indices.extend(ROCK_TRIANGLES.map(|index| base + index));
    }
    MeshData::new(vertices, indices)
}

pub fn try_normalize(self) -> Option<Vec3>

Returns self normalized to length 1.0 if possible, else returns None.

In particular, if the input is zero (or very close to zero), or non-finite, the result of this operation will be None.

See also Self::normalize_or_zero().

Examples found in repository

examples/animation.rs (line 697)

    fn advance(&mut self, ctx: &mut TickContext<'_, Scene>) -> f32 {
        let control = ctx.axis2(Move::Walk).clamp_length_max(1.0);
        let turn = Quat::from_rotation_y(self.camera_yaw);
        let heading = turn * Vec3::X * control.x + turn * Vec3::NEG_Z * control.y;
        let dt = ctx.dt().as_secs_f32();
        if let Some(direction) = heading.try_normalize() {
            let wanted = direction.x.atan2(direction.z);
            let turn = (wanted - self.elf_yaw + core::f32::consts::PI).rem_euclid(TAU)
                - core::f32::consts::PI;
            self.elf_yaw += turn.clamp(-TURN_RATE * dt, TURN_RATE * dt);
        }
        let cap = if ctx.down(Button::Run) { 1.0 } else { WALK_CAP };
        self.elf_pos += heading * cap * ELF_SPEED * dt;
        heading.length() * cap
    }

pub fn normalize_or(self, fallback: Vec3) -> Vec3

Returns self normalized to length 1.0 if possible, else returns a fallback value.

In particular, if the input is zero (or very close to zero), or non-finite, the result of this operation will be the fallback value.

See also Self::try_normalize().

pub fn normalize_or_zero(self) -> Vec3

Returns self normalized to length 1.0 if possible, else returns zero.

In particular, if the input is zero (or very close to zero), or non-finite, the result of this operation will be zero.

See also Self::try_normalize().

Examples found in repository

examples/sound-lab.rs (line 883)

fn listener_right(view: View) -> Vec3 {
    (view.target() - view.eye())
        .normalize_or_zero()
        .cross(view.up())
}

pub fn normalize_and_length(self) -> (Vec3, f32)

Returns self normalized to length 1.0 and the length of self.

If self is zero length then (Self::X, 0.0) is returned.

pub fn is_normalized(self) -> bool

Returns whether self is length 1.0 or not.

Uses a precision threshold of approximately 1e-4.

pub fn project_onto(self, rhs: Vec3) -> Vec3

Returns the vector projection of self onto rhs.

rhs must be of non-zero length.

Panics

Will panic if rhs is zero length when glam_assert is enabled.

pub fn reject_from(self, rhs: Vec3) -> Vec3

Returns the vector rejection of self from rhs.

The vector rejection is the vector perpendicular to the projection of self onto rhs, in rhs words the result of self - self.project_onto(rhs).

rhs must be of non-zero length.

Panics

Will panic if rhs has a length of zero when glam_assert is enabled.

pub fn project_onto_normalized(self, rhs: Vec3) -> Vec3

Returns the vector projection of self onto rhs.

rhs must be normalized.

Panics

Will panic if rhs is not normalized when glam_assert is enabled.

pub fn reject_from_normalized(self, rhs: Vec3) -> Vec3

Returns the vector rejection of self from rhs.

The vector rejection is the vector perpendicular to the projection of self onto rhs, in rhs words the result of self - self.project_onto(rhs).

rhs must be normalized.

Panics

Will panic if rhs is not normalized when glam_assert is enabled.

pub fn round(self) -> Vec3

Returns a vector containing the nearest integer to a number for each element of self. Round half-way cases away from 0.0.

pub fn floor(self) -> Vec3

Returns a vector containing the largest integer less than or equal to a number for each element of self.

pub fn ceil(self) -> Vec3

Returns a vector containing the smallest integer greater than or equal to a number for each element of self.

pub fn trunc(self) -> Vec3

Returns a vector containing the integer part each element of self. This means numbers are always truncated towards zero.

pub fn step(self, rhs: Vec3) -> Vec3

Returns a vector containing 0.0 if rhs < self and 1.0 otherwise.

Similar to glsl’s step(edge, x), which translates into edge.step(x)

pub fn saturate(self) -> Vec3

Returns a vector containing all elements of self clamped to the range of [0, 1].

pub fn fract(self) -> Vec3

Returns a vector containing the fractional part of the vector as self - self.trunc().

Note that this differs from the GLSL implementation of fract which returns self - self.floor().

Note that this is fast but not precise for large numbers.

pub fn fract_gl(self) -> Vec3

Returns a vector containing the fractional part of the vector as self - self.floor().

Note that this differs from the Rust implementation of fract which returns self - self.trunc().

Note that this is fast but not precise for large numbers.

pub fn exp(self) -> Vec3

Returns a vector containing e^self (the exponential function) for each element of self.

pub fn exp2(self) -> Vec3

Returns a vector containing 2^self for each element of self.

pub fn ln(self) -> Vec3

Returns a vector containing the natural logarithm for each element of self. This returns NaN when the element is negative and negative infinity when the element is zero.

pub fn log2(self) -> Vec3

Returns a vector containing the base 2 logarithm for each element of self. This returns NaN when the element is negative and negative infinity when the element is zero.

pub fn powf(self, n: f32) -> Vec3

Returns a vector containing each element of self raised to the power of n.

pub fn sqrt(self) -> Vec3

Returns a vector containing the square root for each element of self. This returns NaN when the element is negative.

pub fn cos(self) -> Vec3

Returns a vector containing the cosine for each element of self.

pub fn sin(self) -> Vec3

Returns a vector containing the sine for each element of self.

pub fn sin_cos(self) -> (Vec3, Vec3)

Returns a tuple of two vectors containing the sine and cosine for each element of self.

pub fn recip(self) -> Vec3

Returns a vector containing the reciprocal 1.0/n of each element of self.

pub fn lerp(self, rhs: Vec3, s: f32) -> Vec3

Performs a linear interpolation between self and rhs based on the value s.

When s is 0.0, the result will be equal to self. When s is 1.0, the result will be equal to rhs. When s is outside of range [0, 1], the result is linearly extrapolated.

Examples found in repository

examples/sprite-adventure.rs (line 1723)

    fn frame_overworld(&mut self, ctx: &mut FrameContext<'_, Keep>) {
        let drawn_at = self.previous.lerp(self.position, ctx.alpha());
        ctx.set_camera(Self::camera(drawn_at, OVERWORLD_CAMERA_OFFSET));
        ctx.light(Light::directional(SUN_DIRECTION, SUN_COLOR).shadow());

        self.draw_ground(ctx);
        self.draw_hedgerow(ctx);
        self.draw_pond(ctx);
        self.draw_crates(ctx);
        self.draw_well(ctx);
        self.draw_flora(ctx);
        Self::draw_mouth(ctx, ENTRANCE);
        self.draw_walker(ctx, drawn_at);
    }

    fn frame_cave(&mut self, ctx: &mut FrameContext<'_, Keep>) {
        let drawn_at = self.previous.lerp(self.position, ctx.alpha());
        let camera = Self::camera(drawn_at, CAVE_CAMERA_OFFSET);
        ctx.set_camera(camera);

        self.draw_cave_floor(ctx);
        self.draw_cave_walls(ctx);
        Self::draw_door_wall(ctx, (self.ghost > 0.0).then_some(drawn_at.x), self.ghost);
        Self::draw_mouth(ctx, EXIT);
        self.draw_torches(ctx);
        self.draw_door(ctx, self.ghost);
        self.draw_door_frame(ctx, self.ghost);
        if !self.gem_taken {
            self.draw_gem(ctx);
        }
        self.draw_walker(ctx, drawn_at);
        self.draw_door_prompt(ctx, camera);
    }

examples/isometric-board.rs (line 584)

    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/breakout-game.rs (line 690)

    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/animation.rs (line 924)

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

        let alpha = ctx.alpha();
        let elf_pos = self.elf_prev.lerp(self.elf_pos, alpha);
        let elf_height = self.elf_height_prev + (self.elf_height - self.elf_height_prev) * alpha;
        let (butterfly_pos, butterfly_yaw) = butterfly_pose(ctx.elapsed().as_secs_f32());

        let camera = orbit_camera(elf_pos, self.camera_yaw, self.camera_pitch);
        ctx.set_camera(camera);
        ctx.set_cursor(if self.holding {
            Cursor::Held
        } else {
            Cursor::Arrow
        });
        ctx.set_skybox(Sky::Day);
        ctx.set_exposure(3.0);
        ctx.set_bloom(0.2);
        ctx.light(Light::directional(SUN_DIRECTION, SUN_COLOR).shadow());
        ctx.light(
            Light::point(
                LAMP_POST_POSITION + Vec3::Y * (LAMP_POST_HEIGHT + LAMP_HEAD_GAP * 0.5),
                LAMP_LIGHT_COLOR,
                LAMP_LIGHT_RANGE,
            )
            .shadow(),
        );
        ctx.light(
            Light::spot(Spot {
                position: SPOT_POSITION,
                direction: SPOT_DIRECTION,
                color: SPOT_COLOR,
                range: SPOT_RANGE,
                angle: SPOT_ANGLE,
            })
            .shadow(),
        );
        ctx.light(
            Light::point(butterfly_pos, BUTTERFLY_LIGHT_COLOR, BUTTERFLY_LIGHT_RANGE).shadow(),
        );

        ctx.draw(
            Plane
                .at(Transform::from_scale(Vec3::new(
                    GROUND_SIZE,
                    1.0,
                    GROUND_SIZE,
                )))
                .material(Material::lit(GROUND_COLOR)),
        );
        for patch in HURT_PATCHES {
            ctx.draw(
                Plane
                    .at(Transform::from_scale_rotation_translation(
                        Vec3::splat(HURT_RADIUS * 2.0),
                        Quat::IDENTITY,
                        patch,
                    ))
                    .material(Material::lit(HURT_COLOR)),
            );
        }
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(SEAT_FOOTPRINT, SEAT_HEIGHT, SEAT_FOOTPRINT),
                Quat::IDENTITY,
                SEAT_POSITION + Vec3::Y * SEAT_HEIGHT * 0.5,
            ))
            .material(Material::lit(SEAT_COLOR)),
        );
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::new(LAMP_POST_THICKNESS, LAMP_POST_HEIGHT, LAMP_POST_THICKNESS),
                Quat::IDENTITY,
                LAMP_POST_POSITION + Vec3::Y * LAMP_POST_HEIGHT * 0.5,
            ))
            .material(Material::lit(LAMP_POST_COLOR)),
        );
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::splat(LAMP_HEAD_SIZE),
                Quat::IDENTITY,
                LAMP_POST_POSITION
                    + Vec3::Y * (LAMP_POST_HEIGHT + LAMP_HEAD_GAP + LAMP_HEAD_SIZE * 0.5),
            ))
            .material(Material::color(Color::BLACK).emissive(LAMP_LIGHT_COLOR)),
        );
        ctx.draw(
            Cube.at(Transform::from_scale_rotation_translation(
                Vec3::splat(SPOT_FIXTURE_SIZE),
                Quat::IDENTITY,
                SPOT_POSITION + Vec3::Y * SPOT_FIXTURE_SIZE * 0.5,
            ))
            .material(Material::lit(SPOT_FIXTURE_COLOR)),
        );

        ctx.draw(
            Elf.at(Transform::from_rotation_translation(
                Quat::from_rotation_y(self.elf_yaw),
                elf_pos + Vec3::Y * elf_height,
            ))
            .posed(&self.elf_animator),
        );
        ctx.draw(
            Elf.at(Transform::from_rotation_translation(
                Quat::from_rotation_y(core::f32::consts::PI),
                SCRUBBED_ELF_POSITION,
            ))
            .posed(&self.scrubbed_animator),
        );
        ctx.draw(
            Butterfly
                .at(Transform::from_rotation_translation(
                    Quat::from_rotation_y(butterfly_yaw),
                    butterfly_pos,
                ))
                .posed(&self.butterfly_animator)
                .material(Material::lit(Color::WHITE).emissive(BUTTERFLY_EMISSIVE)),
        );

        self.draw_prompts(ctx, camera);
        self.panel(ctx);
    }

pub fn move_towards(self, rhs: Vec3, d: f32) -> Vec3

Moves towards rhs based on the value d.

When d is 0.0, the result will be equal to self. When d is equal to self.distance(rhs), the result will be equal to rhs. Will not go past rhs.

pub fn midpoint(self, rhs: Vec3) -> Vec3

Calculates the midpoint between self and rhs.

The midpoint is the average of, or halfway point between, two vectors. a.midpoint(b) should yield the same result as a.lerp(b, 0.5) while being slightly cheaper to compute.

pub fn abs_diff_eq(self, rhs: Vec3, max_abs_diff: f32) -> bool

Returns true if the absolute difference of all elements between self and rhs is less than or equal to max_abs_diff.

This can be used to compare if two vectors contain similar elements. It works best when comparing with a known value. The max_abs_diff that should be used used depends on the values being compared against.

For more see comparing floating point numbers.

pub fn clamp_length(self, min: f32, max: f32) -> Vec3

Returns a vector with a length no less than min and no more than max.

Panics

Will panic if min is greater than max, or if either min or max is negative, when glam_assert is enabled.

pub fn clamp_length_max(self, max: f32) -> Vec3

Returns a vector with a length no more than max.

Panics

Will panic if max is negative when glam_assert is enabled.

pub fn clamp_length_min(self, min: f32) -> Vec3

Returns a vector with a length no less than min.

Panics

Will panic if min is negative when glam_assert is enabled.

pub fn mul_add(self, a: Vec3, b: Vec3) -> Vec3

Fused multiply-add. Computes (self * a) + b element-wise with only one rounding error, yielding a more accurate result than an unfused multiply-add.

Using mul_add may be more performant than an unfused multiply-add if the target architecture has a dedicated fma CPU instruction. However, this is not always true, and will be heavily dependant on designing algorithms with specific target hardware in mind.

pub fn reflect(self, normal: Vec3) -> Vec3

Returns the reflection vector for a given incident vector self and surface normal normal.

normal must be normalized.

Panics

Will panic if normal is not normalized when glam_assert is enabled.

pub fn refract(self, normal: Vec3, eta: f32) -> Vec3

Returns the refraction direction for a given incident vector self, surface normal normal and ratio of indices of refraction, eta. When total internal reflection occurs, a zero vector will be returned.

self and normal must be normalized.

Panics

Will panic if self or normal is not normalized when glam_assert is enabled.

pub fn angle_between(self, rhs: Vec3) -> f32

Returns the angle (in radians) between two vectors in the range [0, +π].

For the full rotation between two vectors as a quaternion, see Quat::from_rotation_arc.

The inputs do not need to be unit vectors however they must be non-zero.

Panics

Will panic if self or rhs has zero length when glam_assert is enabled.

pub fn angle_to(self, rhs: Vec3, axis: Vec3) -> f32

Returns the signed angle (in radians) from self to rhs around axis in the range [-π, +π].

The axis must be a unit vector. The angle follows the right-hand rule around axis and can be used with Self::rotate_axis, e.g. self.rotate_axis(axis, self.angle_to(rhs, axis)) will be equal to rhs.

For the unsigned angle without a reference axis, see Self::angle_between.

The inputs do not need to be unit vectors however they must be non-zero.

Panics

Will panic if axis is not normalized when glam_assert is enabled. Will panic if self or rhs has zero length when glam_assert is enabled.

pub fn rotate_x(self, angle: f32) -> Vec3

Rotates around the x axis by angle (in radians).

pub fn rotate_y(self, angle: f32) -> Vec3

Rotates around the y axis by angle (in radians).

pub fn rotate_z(self, angle: f32) -> Vec3

Rotates around the z axis by angle (in radians).

pub fn rotate_axis(self, axis: Vec3, angle: f32) -> Vec3

Rotates around axis by angle (in radians).

The axis must be a unit vector.

Panics

Will panic if axis is not normalized when glam_assert is enabled.

pub fn rotate_towards(self, rhs: Vec3, max_angle: f32) -> Vec3

Rotates towards rhs up to max_angle (in radians).

When max_angle is 0.0, the result will be equal to self. When max_angle is equal to self.angle_between(rhs), the result will be parallel to rhs. If max_angle is negative, rotates towards the exact opposite of rhs. Will not go past the target.

pub fn any_orthogonal_vector(self) -> Vec3

Returns some vector that is orthogonal to the given one.

The input vector must be finite and non-zero.

The output vector is not necessarily unit length. For that use Self::any_orthonormal_vector() instead.

pub fn any_orthonormal_vector(self) -> Vec3

Returns any unit vector that is orthogonal to the given one.

The input vector must be unit length.

Panics

Will panic if self is not normalized when glam_assert is enabled.

pub fn any_orthonormal_pair(self) -> (Vec3, Vec3)

Given a unit vector return two other vectors that together form a right-handed orthonormal basis. That is, all three vectors are orthogonal to each other and are normalized.

Panics

Will panic if self is not normalized when glam_assert is enabled.

pub fn slerp(self, rhs: Vec3, s: f32) -> Vec3

Performs a spherical linear interpolation between self and rhs based on the value s.

When s is 0.0, the result will be equal to self. When s is 1.0, the result will be equal to rhs. When s is outside of range [0, 1], the result is linearly extrapolated.

pub fn as_dvec3(self) -> DVec3

Casts all elements of self to f64.

pub fn as_i8vec3(self) -> I8Vec3

Casts all elements of self to i8.

pub fn as_u8vec3(self) -> U8Vec3

Casts all elements of self to u8.

pub fn as_i16vec3(self) -> I16Vec3

Casts all elements of self to i16.

pub fn as_u16vec3(self) -> U16Vec3

Casts all elements of self to u16.

pub fn as_ivec3(self) -> IVec3

Casts all elements of self to i32.

pub fn as_uvec3(self) -> UVec3

Casts all elements of self to u32.

pub fn as_i64vec3(self) -> I64Vec3

Casts all elements of self to i64.

pub fn as_u64vec3(self) -> U64Vec3

Casts all elements of self to u64.

pub fn as_isizevec3(self) -> ISizeVec3

Casts all elements of self to isize.

pub fn as_usizevec3(self) -> USizeVec3

Casts all elements of self to usize.

Trait Implementations

impl Add for Vec3

type Output = Vec3

The resulting type after applying the + operator.

fn add(self, rhs: Vec3) -> Vec3

Performs the + operation.

impl Add<&Vec3> for Vec3

type Output = Vec3

The resulting type after applying the + operator.

fn add(self, rhs: &Vec3) -> Vec3

Performs the + operation.

impl Add<&Vec3> for &Vec3

type Output = Vec3

The resulting type after applying the + operator.

fn add(self, rhs: &Vec3) -> Vec3

Performs the + operation.

impl Add<&f32> for Vec3

type Output = Vec3

The resulting type after applying the + operator.

fn add(self, rhs: &f32) -> Vec3

Performs the + operation.

impl Add<&f32> for &Vec3

type Output = Vec3

The resulting type after applying the + operator.

fn add(self, rhs: &f32) -> Vec3

Performs the + operation.

impl Add<Vec3> for &Vec3

type Output = Vec3

The resulting type after applying the + operator.

fn add(self, rhs: Vec3) -> Vec3

Performs the + operation.

impl Add<f32> for Vec3

type Output = Vec3

The resulting type after applying the + operator.

fn add(self, rhs: f32) -> Vec3

Performs the + operation.

impl Add<f32> for &Vec3

type Output = Vec3

The resulting type after applying the + operator.

fn add(self, rhs: f32) -> Vec3

Performs the + operation.

impl AddAssign for Vec3

fn add_assign(&mut self, rhs: Vec3)

Performs the += operation.

impl AddAssign<&Vec3> for Vec3

fn add_assign(&mut self, rhs: &Vec3)

Performs the += operation.

impl AddAssign<&f32> for Vec3

fn add_assign(&mut self, rhs: &f32)

Performs the += operation.

impl AddAssign<f32> for Vec3

fn add_assign(&mut self, rhs: f32)

Performs the += operation.

impl AsMut<[f32; 3]> for Vec3

fn as_mut(&mut self) -> &mut [f32; 3]

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<[f32; 3]> for Vec3

fn as_ref(&self) -> &[f32; 3]

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Vec3

fn clone(&self) -> Vec3

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Vec3

impl Debug for Vec3

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

Formats the value using the given formatter.

impl Default for Vec3

fn default() -> Vec3

Returns the “default value” for a type.

impl Display for Vec3

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

Formats the value using the given formatter.

impl Div for Vec3

type Output = Vec3

The resulting type after applying the / operator.

fn div(self, rhs: Vec3) -> Vec3

Performs the / operation.

impl Div<&Vec3> for Vec3

type Output = Vec3

The resulting type after applying the / operator.

fn div(self, rhs: &Vec3) -> Vec3

Performs the / operation.

impl Div<&Vec3> for &Vec3

type Output = Vec3

The resulting type after applying the / operator.

fn div(self, rhs: &Vec3) -> Vec3

Performs the / operation.

impl Div<&f32> for Vec3

type Output = Vec3

The resulting type after applying the / operator.

fn div(self, rhs: &f32) -> Vec3

Performs the / operation.

impl Div<&f32> for &Vec3

type Output = Vec3

The resulting type after applying the / operator.

fn div(self, rhs: &f32) -> Vec3

Performs the / operation.

impl Div<Vec3> for &Vec3

type Output = Vec3

The resulting type after applying the / operator.

fn div(self, rhs: Vec3) -> Vec3

Performs the / operation.

impl Div<f32> for Vec3

type Output = Vec3

The resulting type after applying the / operator.

fn div(self, rhs: f32) -> Vec3

Performs the / operation.

impl Div<f32> for &Vec3

type Output = Vec3

The resulting type after applying the / operator.

fn div(self, rhs: f32) -> Vec3

Performs the / operation.

impl DivAssign for Vec3

fn div_assign(&mut self, rhs: Vec3)

Performs the /= operation.

impl DivAssign<&Vec3> for Vec3

fn div_assign(&mut self, rhs: &Vec3)

Performs the /= operation.

impl DivAssign<&f32> for Vec3

fn div_assign(&mut self, rhs: &f32)

Performs the /= operation.

impl DivAssign<f32> for Vec3

fn div_assign(&mut self, rhs: f32)

Performs the /= operation.

impl From<(Vec2, f32)> for Vec3

fn from(_: (Vec2, f32)) -> Vec3

Converts to this type from the input type.

impl From<(f32, f32, f32)> for Vec3

fn from(t: (f32, f32, f32)) -> Vec3

Converts to this type from the input type.

impl From<BVec3> for Vec3

fn from(v: BVec3) -> Vec3

Converts to this type from the input type.

impl From<BVec3A> for Vec3

fn from(v: BVec3A) -> Vec3

Converts to this type from the input type.

impl From<Vec3> for Vec3A

fn from(v: Vec3) -> Vec3A

Converts to this type from the input type.

impl From<Vec3> for DVec3

fn from(v: Vec3) -> DVec3

Converts to this type from the input type.

impl From<Vec3> for Transform

fn from(translation: Vec3) -> Self

A position.

impl From<Vec3A> for Vec3

fn from(v: Vec3A) -> Vec3

Converts to this type from the input type.

impl From<[f32; 3]> for Vec3

fn from(a: [f32; 3]) -> Vec3

Converts to this type from the input type.

impl Index<usize> for Vec3

type Output = f32

The returned type after indexing.

fn index(&self, index: usize) -> &<Vec3 as Index<usize>>::Output

Performs the indexing (container[index]) operation.

impl IndexMut<usize> for Vec3

fn index_mut(&mut self, index: usize) -> &mut <Vec3 as Index<usize>>::Output

Performs the mutable indexing (container[index]) operation.

impl Mul for Vec3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: Vec3) -> Vec3

Performs the * operation.

impl Mul<&Vec3> for Mat3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec3) -> Vec3

Performs the * operation.

impl Mul<&Vec3> for &Mat3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec3) -> Vec3

Performs the * operation.

impl Mul<&Vec3> for Vec3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec3) -> Vec3

Performs the * operation.

impl Mul<&Vec3> for &Vec3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec3) -> Vec3

Performs the * operation.

impl Mul<&Vec3> for Mat3A

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec3) -> Vec3

Performs the * operation.

impl Mul<&Vec3> for &Mat3A

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec3) -> Vec3

Performs the * operation.

impl Mul<&Vec3> for Quat

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec3) -> Vec3

Performs the * operation.

impl Mul<&Vec3> for &Quat

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &Vec3) -> Vec3

Performs the * operation.

impl Mul<&f32> for Vec3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &f32) -> Vec3

Performs the * operation.

impl Mul<&f32> for &Vec3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: &f32) -> Vec3

Performs the * operation.

impl Mul<Vec3> for Mat3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: Vec3) -> <Mat3 as Mul<Vec3>>::Output

Performs the * operation.

impl Mul<Vec3> for &Mat3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: Vec3) -> Vec3

Performs the * operation.

impl Mul<Vec3> for &Vec3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: Vec3) -> Vec3

Performs the * operation.

impl Mul<Vec3> for Mat3A

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: Vec3) -> Vec3

Performs the * operation.

impl Mul<Vec3> for &Mat3A

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: Vec3) -> Vec3

Performs the * operation.

impl Mul<Vec3> for Quat

fn mul(self, rhs: Vec3) -> <Quat as Mul<Vec3>>::Output

Multiplies a quaternion and a 3D vector, returning the rotated vector.

Panics

Will panic if self is not normalized when glam_assert is enabled.

type Output = Vec3

The resulting type after applying the * operator.

impl Mul<Vec3> for &Quat

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: Vec3) -> Vec3

Performs the * operation.

impl Mul<f32> for Vec3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Vec3

Performs the * operation.

impl Mul<f32> for &Vec3

type Output = Vec3

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Vec3

Performs the * operation.

impl MulAssign for Vec3

fn mul_assign(&mut self, rhs: Vec3)

Performs the *= operation.

impl MulAssign<&Vec3> for Vec3

fn mul_assign(&mut self, rhs: &Vec3)

Performs the *= operation.

impl MulAssign<&f32> for Vec3

fn mul_assign(&mut self, rhs: &f32)

Performs the *= operation.

impl MulAssign<f32> for Vec3

fn mul_assign(&mut self, rhs: f32)

Performs the *= operation.

impl Neg for Vec3

type Output = Vec3

The resulting type after applying the - operator.

fn neg(self) -> Vec3

Performs the unary - operation.

impl Neg for &Vec3

type Output = Vec3

The resulting type after applying the - operator.

fn neg(self) -> Vec3

Performs the unary - operation.

impl PartialEq for Vec3

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

Equality operator ==.

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

Inequality operator !=.

impl Pod for Vec3

impl Product for Vec3

fn product<I>(iter: I) -> Vec3

where I: Iterator<Item = Vec3>,

Takes an iterator and generates Self from the elements by multiplying the items.

impl<'a> Product<&'a Vec3> for Vec3

fn product<I>(iter: I) -> Vec3

where I: Iterator<Item = &'a Vec3>,

Takes an iterator and generates Self from the elements by multiplying the items.

impl Rem for Vec3

type Output = Vec3

The resulting type after applying the % operator.

fn rem(self, rhs: Vec3) -> Vec3

Performs the % operation.

impl Rem<&Vec3> for Vec3

type Output = Vec3

The resulting type after applying the % operator.

fn rem(self, rhs: &Vec3) -> Vec3

Performs the % operation.

impl Rem<&Vec3> for &Vec3

type Output = Vec3

The resulting type after applying the % operator.

fn rem(self, rhs: &Vec3) -> Vec3

Performs the % operation.

impl Rem<&f32> for Vec3

type Output = Vec3

The resulting type after applying the % operator.

fn rem(self, rhs: &f32) -> Vec3

Performs the % operation.

impl Rem<&f32> for &Vec3

type Output = Vec3

The resulting type after applying the % operator.

fn rem(self, rhs: &f32) -> Vec3

Performs the % operation.

impl Rem<Vec3> for &Vec3

type Output = Vec3

The resulting type after applying the % operator.

fn rem(self, rhs: Vec3) -> Vec3

Performs the % operation.

impl Rem<f32> for Vec3

type Output = Vec3

The resulting type after applying the % operator.

fn rem(self, rhs: f32) -> Vec3

Performs the % operation.

impl Rem<f32> for &Vec3

type Output = Vec3

The resulting type after applying the % operator.

fn rem(self, rhs: f32) -> Vec3

Performs the % operation.

impl RemAssign for Vec3

fn rem_assign(&mut self, rhs: Vec3)

Performs the %= operation.

impl RemAssign<&Vec3> for Vec3

fn rem_assign(&mut self, rhs: &Vec3)

Performs the %= operation.

impl RemAssign<&f32> for Vec3

fn rem_assign(&mut self, rhs: &f32)

Performs the %= operation.

impl RemAssign<f32> for Vec3

fn rem_assign(&mut self, rhs: f32)

Performs the %= operation.

impl StructuralPartialEq for Vec3

impl Sub for Vec3

type Output = Vec3

The resulting type after applying the - operator.

fn sub(self, rhs: Vec3) -> Vec3

Performs the - operation.

impl Sub<&Vec3> for Vec3

type Output = Vec3

The resulting type after applying the - operator.

fn sub(self, rhs: &Vec3) -> Vec3

Performs the - operation.

impl Sub<&Vec3> for &Vec3

type Output = Vec3

The resulting type after applying the - operator.

fn sub(self, rhs: &Vec3) -> Vec3

Performs the - operation.

impl Sub<&f32> for Vec3

type Output = Vec3

The resulting type after applying the - operator.

fn sub(self, rhs: &f32) -> Vec3

Performs the - operation.

impl Sub<&f32> for &Vec3

type Output = Vec3

The resulting type after applying the - operator.

fn sub(self, rhs: &f32) -> Vec3

Performs the - operation.

impl Sub<Vec3> for &Vec3

type Output = Vec3

The resulting type after applying the - operator.

fn sub(self, rhs: Vec3) -> Vec3

Performs the - operation.

impl Sub<f32> for Vec3

type Output = Vec3

The resulting type after applying the - operator.

fn sub(self, rhs: f32) -> Vec3

Performs the - operation.

impl Sub<f32> for &Vec3

type Output = Vec3

The resulting type after applying the - operator.

fn sub(self, rhs: f32) -> Vec3

Performs the - operation.

impl SubAssign for Vec3

fn sub_assign(&mut self, rhs: Vec3)

Performs the -= operation.

impl SubAssign<&Vec3> for Vec3

fn sub_assign(&mut self, rhs: &Vec3)

Performs the -= operation.

impl SubAssign<&f32> for Vec3

fn sub_assign(&mut self, rhs: &f32)

Performs the -= operation.

impl SubAssign<f32> for Vec3

fn sub_assign(&mut self, rhs: f32)

Performs the -= operation.

impl Sum for Vec3

fn sum<I>(iter: I) -> Vec3

where I: Iterator<Item = Vec3>,

Takes an iterator and generates Self from the elements by “summing up” the items.

impl<'a> Sum<&'a Vec3> for Vec3

fn sum<I>(iter: I) -> Vec3

where I: Iterator<Item = &'a Vec3>,

Takes an iterator and generates Self from the elements by “summing up” the items.

impl Vec3Swizzles for Vec3

type Vec2 = Vec2

type Vec4 = Vec4

fn xx(self) -> Vec2

fn xy(self) -> Vec2

fn with_xy(self, rhs: Vec2) -> Vec3

fn xz(self) -> Vec2

fn with_xz(self, rhs: Vec2) -> Vec3

fn yx(self) -> Vec2

fn with_yx(self, rhs: Vec2) -> Vec3

fn yy(self) -> Vec2

fn yz(self) -> Vec2

fn with_yz(self, rhs: Vec2) -> Vec3

fn zx(self) -> Vec2

fn with_zx(self, rhs: Vec2) -> Vec3

fn zy(self) -> Vec2

fn with_zy(self, rhs: Vec2) -> Vec3

fn zz(self) -> Vec2

fn xxx(self) -> Vec3

fn xxy(self) -> Vec3

fn xxz(self) -> Vec3

fn xyx(self) -> Vec3

fn xyy(self) -> Vec3

fn xzx(self) -> Vec3

fn xzy(self) -> Vec3

fn xzz(self) -> Vec3

fn yxx(self) -> Vec3

fn yxy(self) -> Vec3

fn yxz(self) -> Vec3

fn yyx(self) -> Vec3

fn yyy(self) -> Vec3

fn yyz(self) -> Vec3

fn yzx(self) -> Vec3

fn yzy(self) -> Vec3

fn yzz(self) -> Vec3

fn zxx(self) -> Vec3

fn zxy(self) -> Vec3

fn zxz(self) -> Vec3

fn zyx(self) -> Vec3

fn zyy(self) -> Vec3

fn zyz(self) -> Vec3

fn zzx(self) -> Vec3

fn zzy(self) -> Vec3

fn zzz(self) -> Vec3

fn xxxx(self) -> Vec4

fn xxxy(self) -> Vec4

fn xxxz(self) -> Vec4

fn xxyx(self) -> Vec4

fn xxyy(self) -> Vec4

fn xxyz(self) -> Vec4

fn xxzx(self) -> Vec4

fn xxzy(self) -> Vec4

fn xxzz(self) -> Vec4

fn xyxx(self) -> Vec4

fn xyxy(self) -> Vec4

fn xyxz(self) -> Vec4

fn xyyx(self) -> Vec4

fn xyyy(self) -> Vec4

fn xyyz(self) -> Vec4

fn xyzx(self) -> Vec4

fn xyzy(self) -> Vec4

fn xyzz(self) -> Vec4

fn xzxx(self) -> Vec4

fn xzxy(self) -> Vec4

fn xzxz(self) -> Vec4

fn xzyx(self) -> Vec4

fn xzyy(self) -> Vec4

fn xzyz(self) -> Vec4

fn xzzx(self) -> Vec4

fn xzzy(self) -> Vec4

fn xzzz(self) -> Vec4

fn yxxx(self) -> Vec4

fn yxxy(self) -> Vec4

fn yxxz(self) -> Vec4

fn yxyx(self) -> Vec4

fn yxyy(self) -> Vec4

fn yxyz(self) -> Vec4

fn yxzx(self) -> Vec4

fn yxzy(self) -> Vec4

fn yxzz(self) -> Vec4

fn yyxx(self) -> Vec4

fn yyxy(self) -> Vec4

fn yyxz(self) -> Vec4

fn yyyx(self) -> Vec4

fn yyyy(self) -> Vec4

fn yyyz(self) -> Vec4

fn yyzx(self) -> Vec4

fn yyzy(self) -> Vec4

fn yyzz(self) -> Vec4

fn yzxx(self) -> Vec4

fn yzxy(self) -> Vec4

fn yzxz(self) -> Vec4

fn yzyx(self) -> Vec4

fn yzyy(self) -> Vec4

fn yzyz(self) -> Vec4

fn yzzx(self) -> Vec4

fn yzzy(self) -> Vec4

fn yzzz(self) -> Vec4

fn zxxx(self) -> Vec4

fn zxxy(self) -> Vec4

fn zxxz(self) -> Vec4

fn zxyx(self) -> Vec4

fn zxyy(self) -> Vec4

fn zxyz(self) -> Vec4

fn zxzx(self) -> Vec4

fn zxzy(self) -> Vec4

fn zxzz(self) -> Vec4

fn zyxx(self) -> Vec4

fn zyxy(self) -> Vec4

fn zyxz(self) -> Vec4

fn zyyx(self) -> Vec4

fn zyyy(self) -> Vec4

fn zyyz(self) -> Vec4

fn zyzx(self) -> Vec4

fn zyzy(self) -> Vec4

fn zyzz(self) -> Vec4

fn zzxx(self) -> Vec4

fn zzxy(self) -> Vec4

fn zzxz(self) -> Vec4

fn zzyx(self) -> Vec4

fn zzyy(self) -> Vec4

fn zzyz(self) -> Vec4

fn zzzx(self) -> Vec4

fn zzzy(self) -> Vec4

fn zzzz(self) -> Vec4

fn xyz(self) -> Self

impl Zeroable for Vec3

fn zeroed() -> Self

Calls zeroed.