sprite_adventure/

sprite-adventure.rs

//! A small top-down adventure across two areas: a grass overworld around a
//! pond drawn in a custom water style, and a cave of its own tileset. Either
//! area is left through the opening between a mouth's
//! two pillars. A wall across the cave holds a torch-lit door the player
//! interacts beside, with a gem drawn behind it. The current area, whether
//! the gem is taken, and the
//! position where the player last moved between the two or took the gem are
//! saved across runs. Movement is fixed-step in `tick`, with the upright
//! player shared with `examples/isometric-board.rs`, pushed out of
//! whatever it walks into; drawing interpolates between the last two steps.

use core::ops::Range;
use core::time::Duration;

use mirage_engine::prelude::*;

// ---------------------------------------------------------------------
// Assets
// ---------------------------------------------------------------------

/// The player's sprite sheet, shared with `examples/isometric-board.rs`.
/// Cropped of its 5 empty bottom texel rows per cell and then moved cell by cell onto
/// its own drawn bottom, so every frame's feet land on the sheet's own bottom edge
/// and none of them hovers a texel over its shadow:
/// `trim examples/assets/walker.png --cells 4x4 --baseline`.
const WALKER_SOURCE: &str = "examples/assets/walker.png";
const WALKER_SHEET: &str = "walker";
/// The player's relief, generated from its own sheet at `--detail 0`,
/// which keeps its lit color round instead of a bright band across it.
/// `--strength 16` shades more rows than the default `4` does in the
/// engine's own draw, measured off the sheet's own mirrored center
/// column, where every strength shades the same single color:
/// `spritemaps examples/assets/walker.png --cells 4x4 --dome 0.8 --detail 0.0 --strength 16.0 --out examples/assets/walker-relief.png`.
const WALKER_RELIEF_SOURCE: &str = "examples/assets/walker-relief.png";
const WALKER_RELIEF: &str = "walker-relief";
const WALKER_COLUMNS: u32 = 4;
const WALKER_ROWS: u32 = 4;
const WALKER_WIDTH: f32 = 1.0;
/// The cropped sheet's own `16x27` cell aspect at the tileset's sixteen
/// texels to the meter: `2.0 * 27 / 32` keeps its visible size at what it
/// was before.
const WALKER_HEIGHT: f32 = 1.6875;
const WALK_SPEED: f32 = 4.0;
const TICKS_PER_WALK_FRAME: u32 = 8;

/// The overworld's ground tiles, cropped from the owner's tileset: row `0`
/// is four grass variants, row `1` the path — its west verge, two dirt
/// variants, then its east verge, in that column order.
const GROUND_SOURCE: &str = "examples/assets/keep-ground.png";
const GROUND_SHEET: &str = "keep-ground";
const GROUND_COLUMNS: u32 = 4;
const GROUND_ROWS: u32 = 2;
const GRASS_ROW: u32 = 0;
const PATH_ROW: u32 = 1;
const PATH_WEST_VERGE: u32 = 0;
/// The first of the path row's two dirt columns; the second follows it.
const PATH_DIRT: u32 = 1;
const PATH_EAST_VERGE: u32 = 3;

/// Cropped of its 1 empty bottom texel row:
/// `trim examples/assets/keep-bush.png --cells 1x1`.
const BUSH_SOURCE: &str = "examples/assets/keep-bush.png";
const BUSH_SPRITE: &str = "keep-bush";
/// The bush's relief, generated from its own sprite:
/// `spritemaps examples/assets/keep-bush.png --cells 1x1 --out examples/assets/keep-bush-relief.png`.
const BUSH_RELIEF_SOURCE: &str = "examples/assets/keep-bush-relief.png";
const BUSH_RELIEF: &str = "keep-bush-relief";
/// Cropped of its 2 empty bottom texel rows:
/// `trim examples/assets/keep-rock.png --cells 1x1`.
const ROCK_SOURCE: &str = "examples/assets/keep-rock.png";
const ROCK_SPRITE: &str = "keep-rock";
/// The rock's relief, generated from its own sprite:
/// `spritemaps examples/assets/keep-rock.png --cells 1x1 --out examples/assets/keep-rock-relief.png`.
const ROCK_RELIEF_SOURCE: &str = "examples/assets/keep-rock-relief.png";
const ROCK_RELIEF: &str = "keep-rock-relief";

const CRATE_SOURCE: &str = "examples/assets/keep-crate.png";
const CRATE_TEXTURE: &str = "keep-crate";

/// The well's two cells, side by side: grey masonry for the rim, then the
/// mouth — a stone ring around a dark hole.
const WELL_SOURCE: &str = "examples/assets/keep-well.png";
const WELL_SHEET: &str = "keep-well";
const WELL_CELLS: u32 = 2;
const WELL_RIM_CELL: u32 = 0;
const WELL_MOUTH_CELL: u32 = 1;

/// The mouth's stone, one column of cells: a capital over the plain coursed
/// masonry under it.
const STONE_SOURCE: &str = "examples/assets/keep-stone.png";
const STONE_SHEET: &str = "keep-stone";
const STONE_ROWS: u32 = 2;

/// The pond's two cells: the whole sprite, then the same shoreline with its
/// water cleared away, which is the one drawn over the styled water.
const POND_SOURCE: &str = "examples/assets/keep-pond.png";
const POND_SHEET: &str = "keep-pond";
const POND_CELLS: u32 = 2;
const POND_SHORE_CELL: u32 = 1;

/// A torch's post, drawn as a cutout sprite like the flora: its four lit
/// texels of binding are what the flame is drawn over.
/// `trim examples/assets/keep-torch.png --cells 1x1` measures no empty
/// bottom row, so it stays as it was.
const TORCH_SOURCE: &str = "examples/assets/keep-torch.png";
const TORCH_SPRITE: &str = "keep-torch";
/// The post's relief, generated from its own sprite:
/// `spritemaps examples/assets/keep-torch.png --cells 1x1 --out examples/assets/keep-torch-relief.png`.
const TORCH_RELIEF_SOURCE: &str = "examples/assets/keep-torch-relief.png";
const TORCH_RELIEF: &str = "keep-torch-relief";
/// The flame's loop, one row of cells. It has no relief: the flame is
/// drawn unlit and added, so a normal changes nothing it draws.
const FLAME_SOURCE: &str = "examples/assets/keep-flame.png";
const FLAME_SHEET: &str = "keep-flame";
const FLAME_CELLS: u32 = 7;

/// The cave's tileset. Columns are a variant; row `0` is the floor and the
/// three under it are one wall face, drawn as tall as it is in the tileset.
const CAVE_SOURCE: &str = "examples/assets/keep-cave.png";
const CAVE_SHEET: &str = "keep-cave";
const CAVE_COLUMNS: u32 = 4;
const CAVE_ROWS: u32 = 4;
const CAVE_FLOOR_ROW: u32 = 0;

/// The door and gem, built by `tools/keep_fixture.py`.
const MODEL: &str = "examples/assets/keep.glb";
const DOOR_MESH: &str = "door";
const GEM_MESH: &str = "gem";

const INTERACT_SOUND: &str = "examples/assets/click.ogg";
const GEM_SOUND: &str = "examples/assets/win.ogg";

// ---------------------------------------------------------------------
// Overworld layout
// ---------------------------------------------------------------------

const TILE_SIZE: f32 = 1.0;
/// Half the ground tiling's width and depth, in tiles: past the farthest
/// ground the camera frames from anywhere in the clearing, which is just
/// over thirty meters out at the frame's top corners.
const GROUND_DRAW_HALF: i32 = 31;
/// The two sides a pair is placed on: `-1.0` or `1.0` along the axis
/// they straddle.
const SIDES: [f32; 2] = [-1.0, 1.0];
/// Player width for collision: a circle this radius at their feet, narrower
/// than the sprite so a one-tile doorway stays walkable.
const PLAYER_RADIUS: f32 = 0.3;
/// The tile column the dirt path runs along; its verges edge the two
/// beside it.
const PATH_COLUMN: i32 = 0;

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

    fn frame(&mut self, ctx: &mut FrameContext<'_, Keep>) {
        ctx.set_surface_style(Water {
            time: self.simulated.as_secs_f32(),
        });

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

        self.overlay(ctx);
    }
}