mirage_engine/

lib.rs

//! An immediate-mode `3D` engine for simple games: implement [`Game`] and
//! start the engine with [`run`]. See `examples/breakout-game.rs`.
//!
//! Coordinates are right-handed with `+Y` up and cameras looking down `−Z`;
//! time is seconds, and colors are linear `f32`, encoded to sRGB on screen.

#![warn(missing_docs)]

use core::fmt;
use core::time::Duration;

pub use glam as math;

/// The UI toolkit [`FrameContext::ui`] builds with; games never declare a
/// version of it themselves.
#[cfg(feature = "ui")]
pub use egui;

pub use animation::{AnimationStates, Animator, Motion, Progress, Transition};
pub use assets::{Assets, ReliefData, ShadingData, TextureData};
pub use camera::{Camera, Lens, Projection, View};
pub use catalog::Catalog;
pub use color::Color;
pub use context::{FrameContext, InitContext, Startup, TickContext};
pub use holds::Holds;
pub use input::{
    Axis2Binding, AxisBinding, ButtonAxis, ButtonAxis2, ButtonBinding, Cursor, InputAction,
    InputActions, InputAxis2Action, InputAxisAction, InputButtonAction, JoystickControl, Key,
    MouseButton, NoInputActions, NoInputAxes, NoInputAxes2, NoInputButtons, Pad, PadAxis,
    PointerDelta, Stick, WheelDelta,
};
pub use light::{Light, MAX_LIGHTS, MAX_SHADOWS, Spot};
pub use material::Material;
pub use mesh::{Clip, Mesh, Meshes, NoClips, NoParts, Part, Slot};
pub use mirage_engine_derive::{
    Catalog, Clip, InputAxis2Action, InputAxisAction, InputButtonAction, Part, Saves, ShaderValues,
};
/// A point in time a run reads on either target: `std`'s `Instant` on the
/// desktop, `web-time`'s in the browser, spelled the same either way.
/// Required if a game times its own work on both targets.
///
/// One `Instant` minus another is a [`Duration`].
pub use platform::Instant;
pub use post_effect::{EffectStage, PostEffect, PostEffects};
pub use ray::Ray;
pub use save::{SaveKey, SaveValue, Saves};
pub use skybox::{NoSkyboxes, SkyboxData, Skyboxes};
pub use sound::{MAX_VOICES, NoSounds, SoundCue, SoundData, Sounds};
pub use surface_style::{DrawPass, SurfaceStyle, SurfaceStyles};
pub use tonemap::Tonemap;
pub use transform::Transform;

pub use shader_values::ShaderValues;

#[doc(hidden)]
pub use post_effect::Declarations as PostEffectDeclarations;
#[doc(hidden)]
pub use shader_values::Sealed;
#[doc(hidden)]
pub use surface_style::Declarations as SurfaceStyleDeclarations;

use math::UVec2;
use renderer::{mesh_cache, shadows};

// `#[derive(ShaderValues)]` names the engine by its own name, which the engine
// is not to itself without this.
extern crate self as mirage_engine;

/// A game driven by the engine, which owns it for the whole run.
///
/// A vocabulary is a type of the game's own, usually an enum, whose values
/// name everything of one kind the game may use; the contexts are typed by
/// it. Six of them state what this game may draw, play, read, set its sky,
/// style, and pass its frame through, and each has an empty one for a game
/// with none of that kind, so every call in a tick or a frame takes a value
/// of this game's own vocabulary and no other.
///
/// ```
/// use mirage_engine::prelude::*;
///
/// meshes! { enum Shape { Cube } }
///
/// struct Hello;
///
/// impl Game for Hello {
///     type Meshes = Shape;
///     type Sounds = NoSounds;
///     type InputActions = NoInputActions;
///     type Skyboxes = NoSkyboxes;
///     type SurfaceStyles = ();
///     type PostEffects = ();
///
///     fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {}
///
///     fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
///         ctx.draw(Cube.at(Vec3::ZERO));
///     }
/// }
/// ```
pub trait Game: Sized + 'static {
    /// The set of every mesh this game draws — the enum [`meshes!`] writes,
    /// one variant per mesh type — or `()` for a game that draws nothing.
    ///
    /// Startup builds every value the set's types catalog, and
    /// [`FrameContext::draw`] takes a mesh the set holds and no other.
    type Meshes: Meshes + 'static;

    /// The values naming the sounds this game plays, usually an enum, or
    /// [`NoSounds`] for a game with none.
    ///
    /// Startup builds every value of it, and the contexts are typed by it, so
    /// [`FrameContext::play`] takes a value of this type and no other.
    type Sounds: Sounds + 'static;

    /// The three vocabularies naming what the player can do, usually enums,
    /// or [`NoInputActions`] for a game that reads no input; [`Key`] for a
    /// prototype that binds each key to itself.
    ///
    /// Startup materializes these into the table a player rebinds, and their
    /// names are what a rebind is kept under. The contexts are typed by the
    /// set, so [`FrameContext::down`] and every other query take an action
    /// it seats and no other.
    type InputActions: InputActions + 'static;

    /// The set of every style this game draws with — the enum
    /// [`surface_styles!`] writes — or `()` for a game that draws with the
    /// built-in look alone.
    ///
    /// Startup compiles each of them into a pipeline of its own, and stops
    /// the game where any of their WGSL does not compile.
    type SurfaceStyles: SurfaceStyles + 'static;

    /// The values naming the skies this game draws and is lit by, usually
    /// an enum, or [`NoSkyboxes`] for a game under the default sky.
    ///
    /// Startup builds every value of it, and the contexts are typed by it,
    /// so [`FrameContext::set_skybox`] takes a value of this type and no
    /// other.
    type Skyboxes: Skyboxes + 'static;

    /// The set of every post effect this game passes its frame through — the
    /// enum [`post_effects!`] writes — or `()` for a game that draws the
    /// frame as the post chain leaves it.
    ///
    /// The post chain is the passes that take a drawn frame to the window,
    /// and [`EffectStage`] states where in it an effect runs. Startup
    /// compiles each effect into a pipeline of its own, and stops the game
    /// where any of their WGSL does not compile.
    type PostEffects: PostEffects + 'static;

    /// Moves the simulation by one fixed step.
    ///
    /// Called zero or more times per drawn frame, one per
    /// [`Config::tick_interval`] of elapsed time.
    fn tick(&mut self, ctx: &mut TickContext<'_, Self>);

    /// Runs the game's logic for one drawn frame, drawing as it goes.
    fn frame(&mut self, ctx: &mut FrameContext<'_, Self>);
}

/// Opens the window and runs the game `init` builds until it is closed.
///
/// `init` runs once the GPU exists; returning `Err` aborts startup.
///
/// Blocks on the desktop; passes control to the browser's event loop and returns
/// there. Errors that stop startup are reported to the standard error
/// stream, or to the console and a page overlay in the browser.
pub fn run<G: Game>(
    config: Config,
    init: impl FnOnce(&mut InitContext<'_, G>) -> Result<G, Error> + 'static,
) {
    platform::run::<G>(config, init);
}

/// Presentation settings for a game.
#[derive(Clone, Debug)]
pub struct Config {
    title: String,
    size: UVec2,
    tick_interval: Duration,
    canvas_id: Option<String>,
    asset_sources: Vec<String>,
    antialiasing: bool,
    tonemap: Tonemap,
    shadow_resolution: u32,
    mesh_memory: usize,
    /// What a game set for itself, or nothing to count by whatever the
    /// platform states.
    double_click_interval: Option<Duration>,
}

impl Config {
    /// The window size used when none is set, in logical pixels.
    pub const DEFAULT_SIZE: UVec2 = UVec2::new(1280, 720);

    /// The simulation step used when none is set: a sixtieth of a second.
    pub const DEFAULT_TICK_INTERVAL: Duration = Duration::from_nanos(16_666_667);

    /// A configuration with `title` and the engine's other defaults.
    pub fn new(title: impl Into<String>) -> Self {
        Self {
            title: title.into(),
            size: Self::DEFAULT_SIZE,
            tick_interval: Self::DEFAULT_TICK_INTERVAL,
            double_click_interval: None,
            canvas_id: None,
            asset_sources: Vec::new(),
            antialiasing: true,
            tonemap: Tonemap::default(),
            shadow_resolution: shadows::DEFAULT_RESOLUTION,
            mesh_memory: mesh_cache::DEFAULT_MEMORY,
        }
    }

    /// Loads these sources before the game starts, into the [`Assets`] its
    /// meshes build from.
    ///
    /// Sources are file paths on the desktop, relative to the working
    /// directory the game runs in, and URLs relative to the page in the
    /// browser. Anything that fails to load, decode, or match a cataloged
    /// mesh's slots stops startup with an error.
    #[must_use]
    pub fn with_assets(mut self, sources: impl IntoIterator<Item = impl Into<String>>) -> Self {
        self.asset_sources = sources.into_iter().map(Into::into).collect();
        self
    }

    /// Requests an initial window size in logical pixels.
    ///
    /// The browser ignores it: the canvas fills the page, so the page sizes
    /// the game.
    #[must_use]
    pub fn with_size(mut self, width: u32, height: u32) -> Self {
        self.size = UVec2::new(width, height);
        self
    }

    /// Draws edges smoothly, over four samples per pixel; on by default.
    ///
    /// Off draws one sample per pixel, which is less work.
    #[must_use]
    pub fn with_antialiasing(mut self, antialiasing: bool) -> Self {
        self.antialiasing = antialiasing;
        self
    }

    /// Sets the curve the frame is drawn to the screen through;
    /// [`Tonemap::Neutral`] by default.
    #[must_use]
    pub fn with_tonemap(mut self, tonemap: Tonemap) -> Self {
        self.tonemap = tonemap;
        self
    }

    /// Sets the side of the depth map a light flagged with
    /// [`Light::shadow`] draws into, in texels; `2048` by default.
    ///
    /// Held within `256..=4096`. A larger map has denser shadow edges and
    /// costs more memory; each of a point light's six faces is half this
    /// side. The maps live in arrays that grow to the most a frame ever
    /// requested and never give it back — casting lights hold the most
    /// memory they ever took for the whole run.
    #[must_use]
    pub fn with_shadow_resolution(mut self, texels: u32) -> Self {
        // A side below this is not dense enough for a shadow edge, and one
        // above it costs more than a simple game should spend.
        self.shadow_resolution =
            texels.clamp(shadows::SMALLEST_RESOLUTION, shadows::LARGEST_RESOLUTION);
        self
    }

    /// Sets the memory the engine keeps built mesh data in, in bytes; `256`
    /// MB by default.
    ///
    /// Past it the engine drops the copies used least and builds them again
    /// when the game draws those meshes; a game whose meshes fit never
    /// builds one twice. It bounds the system memory the copies hold, not
    /// what the meshes take on the GPU. A mesh built through
    /// [`prepare`](InitContext::prepare) is held like any other: past the cap
    /// it too can be dropped and built again.
    #[must_use]
    pub fn with_mesh_memory(mut self, bytes: usize) -> Self {
        self.mesh_memory = bytes;
        self
    }

    /// Sets the simulated time one [`Game::tick`] covers, held to at least
    /// `Duration::from_micros(1)`; [`Config::DEFAULT_TICK_INTERVAL`] by
    /// default.
    #[must_use]
    pub fn with_tick_interval(mut self, interval: Duration) -> Self {
        self.tick_interval = interval.max(time::MIN_TICK_INTERVAL);
        self
    }

    /// Sets how long after a press a second one still counts as a double
    /// click, which [`FrameContext::clicks`] counts by.
    ///
    /// Without this the engine counts by what the desktop states, and by
    /// `400` milliseconds where the desktop states none; no browser states
    /// one. A windowless session counts by those `400` milliseconds until
    /// this sets another.
    #[must_use]
    pub fn with_double_click_interval(mut self, interval: Duration) -> Self {
        self.double_click_interval = Some(interval);
        self
    }

    /// Draws into the page's `<canvas>` with this id, instead of the one the
    /// engine creates to fill the viewport.
    ///
    /// Ignored outside the browser; startup fails if the page has no such
    /// canvas.
    #[must_use]
    pub fn with_canvas_id(mut self, id: impl Into<String>) -> Self {
        self.canvas_id = Some(id.into());
        self
    }

    /// The window title.
    pub fn title(&self) -> &str {
        &self.title
    }

    /// The requested initial window size, in logical pixels.
    pub fn size(&self) -> UVec2 {
        self.size
    }

    /// Simulated time one [`Game::tick`] covers.
    pub fn tick_interval(&self) -> Duration {
        self.tick_interval
    }

    /// How long after a press a second one still counts as a double click,
    /// where the game set it: `None` to count by what the platform states.
    pub(crate) fn double_click_interval(&self) -> Option<Duration> {
        self.double_click_interval
    }

    /// The page canvas to draw into, if the game named one.
    pub fn canvas_id(&self) -> Option<&str> {
        self.canvas_id.as_deref()
    }

    /// The asset sources loaded before the game starts, in load order.
    pub fn asset_sources(&self) -> &[String] {
        &self.asset_sources
    }

    /// Whether edges are drawn smoothly.
    pub fn antialiasing(&self) -> bool {
        self.antialiasing
    }

    /// The curve the frame is drawn to the screen through.
    pub fn tonemap(&self) -> Tonemap {
        self.tonemap
    }

    /// The side of one light's depth map, in texels.
    pub fn shadow_resolution(&self) -> u32 {
        self.shadow_resolution
    }

    /// Memory the engine keeps built mesh data in, in bytes.
    pub fn mesh_memory(&self) -> usize {
        self.mesh_memory
    }
}

/// Something the engine could not do.
///
/// Only the edges of the API (startup and asset decoding) produce one, so
/// code that runs each frame never handles an error.
#[derive(Clone, Debug)]
pub struct Error {
    msg: String,
}

impl Error {
    /// An error described by `msg`.
    pub fn msg(msg: impl Into<String>) -> Self {
        Self { msg: msg.into() }
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.msg)
    }
}

impl std::error::Error for Error {}

mod assets;
mod camera;
mod catalog;
mod color;
mod context;
mod gpu;
mod holds;
mod light;
mod material;
mod overrun;
mod platform;
mod renderer;
mod skybox;
mod time;
mod tonemap;
mod transform;
mod ui;

pub mod animation;
pub mod input;
pub mod mesh;
pub mod post_effect;
pub mod ray;
pub mod save;
pub mod shader_values;
pub mod sound;
pub mod surface_style;

#[cfg(all(feature = "offscreen", not(target_arch = "wasm32")))]
pub mod headless;

#[doc(hidden)]
pub mod doctests {
    //! `compile_fail` checks for what the type system holds; hidden from
    //! the public docs, run by `cargo test`.
    //!
    //! The README's own code is compiled here too, so that it cannot go
    //! stale: see [`readme`].
    //!
    //! A `Catalog` variant with fields:
    //!
    //! ```compile_fail
    //! #[derive(mirage_engine::Catalog, Clone, Eq, Hash, PartialEq)]
    //! enum Shape {
    //!     Asteroid { seed: u32 },
    //! }
    //! ```
    //!
    //! A `Catalog` type under two attributes:
    //!
    //! ```compile_fail
    //! #[derive(mirage_engine::Catalog, Hash, PartialEq, Eq, Clone)]
    //! #[catalog(Self { seed: 0 })]
    //! #[catalog(Self { seed: 1 })]
    //! struct Asteroid { seed: u32 }
    //! ```
    //!
    //! A `Catalog` attribute naming no value:
    //!
    //! ```compile_fail
    //! #[derive(mirage_engine::Catalog, Hash, PartialEq, Eq, Clone)]
    //! #[catalog()]
    //! struct Asteroid { seed: u32 }
    //! ```
    //!
    //! A `Part` variant with fields:
    //!
    //! ```compile_fail
    //! #[derive(mirage_engine::Part, Clone, Debug, Eq, Hash, PartialEq)]
    //! enum HullPart {
    //!     Plating { layer: u32 },
    //! }
    //! ```
    //!
    //! A `Clip` variant with fields:
    //!
    //! ```compile_fail
    //! #[derive(mirage_engine::Clip, Clone, Debug, Eq, Hash, PartialEq)]
    //! enum Pace {
    //!     Walk { speed: u32 },
    //! }
    //! ```
    //!
    //! A part of one mesh on a draw of another:
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! #[derive(Catalog, Clone, Eq, Hash, PartialEq)]
    //! struct Paddle;
    //!
    //! #[derive(Part, Clone, Debug, Eq, Hash, PartialEq)]
    //! enum PaddlePart {
    //!     Face,
    //! }
    //!
    //! impl Mesh<PaddlePart> for Paddle {
    //!     fn build(&self, assets: &Assets) -> MeshData<PaddlePart> {
    //!         assets.mesh("paddle")
    //!     }
    //! }
    //!
    //! let _ = Cube.at::<()>(Vec3::ZERO).material_of(PaddlePart::Face, Material::default());
    //! ```
    //!
    //! A draw of a mesh the game does not name in its
    //! [`Meshes`](crate::Game::Meshes):
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! meshes! { enum Shape { Cube } }
    //!
    //! struct Spheres;
    //!
    //! impl Game for Spheres {
    //!     type Meshes = Shape;
    //!     type Sounds = NoSounds;
    //!     type InputActions = NoInputActions;
    //!     type Skyboxes = NoSkyboxes;
    //!     type SurfaceStyles = ();
    //!     type PostEffects = ();
    //!
    //!     fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {}
    //!
    //!     fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
    //!         ctx.draw(Sphere { subdivisions: 1 }.at(Vec3::ZERO));
    //!     }
    //! }
    //! ```
    //!
    //! A set naming one mesh type twice:
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! meshes! { enum Shape { Cube, Cube } }
    //! ```
    //!
    //! An action with fields:
    //!
    //! ```compile_fail
    //! #[derive(mirage_engine::InputButtonAction, Clone, Copy)]
    //! enum Verb {
    //!     Fire { rounds: u32 },
    //! }
    //! ```
    //!
    //! A save key with fields:
    //!
    //! ```compile_fail
    //! #[derive(mirage_engine::Saves, Clone, Copy)]
    //! enum Progress {
    //!     Level { number: u32 },
    //! }
    //! ```
    //!
    //! A sound of a vocabulary the game does not name as its
    //! [`Sounds`](crate::Game::Sounds):
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! meshes! { enum Only { Cube } }
    //!
    //! #[derive(Catalog, Clone, Eq, Hash, PartialEq)]
    //! enum Music {
    //!     Theme,
    //! }
    //!
    //! impl Sounds for Music {
    //!     fn build(&self, assets: &Assets) -> SoundData {
    //!         assets.sound("theme")
    //!     }
    //! }
    //!
    //! struct Quiet;
    //!
    //! impl Game for Quiet {
    //!     type Meshes = Only;
    //!     type Sounds = NoSounds;
    //!     type InputActions = NoInputActions;
    //!     type Skyboxes = NoSkyboxes;
    //!     type SurfaceStyles = ();
    //!     type PostEffects = ();
    //!
    //!     fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {}
    //!
    //!     fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
    //!         ctx.play(Music::Theme);
    //!     }
    //! }
    //! ```
    //!
    //! A sky of a vocabulary the game does not name as its
    //! [`Skyboxes`](crate::Game::Skyboxes):
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! meshes! { enum Only { Cube } }
    //!
    //! #[derive(Catalog, Clone, Debug, Eq, Hash, PartialEq)]
    //! enum Weather {
    //!     Clear,
    //!     Storm,
    //! }
    //!
    //! impl Skyboxes for Weather {
    //!     fn build(&self, assets: &Assets) -> SkyboxData {
    //!         assets.skybox("sky")
    //!     }
    //! }
    //!
    //! struct Outdoors;
    //!
    //! impl Game for Outdoors {
    //!     type Meshes = Only;
    //!     type Sounds = NoSounds;
    //!     type InputActions = NoInputActions;
    //!     type Skyboxes = NoSkyboxes;
    //!     type SurfaceStyles = ();
    //!     type PostEffects = ();
    //!
    //!     fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {}
    //!
    //!     fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
    //!         ctx.set_skybox(Weather::Storm);
    //!     }
    //! }
    //! ```
    //!
    //! An action of a vocabulary the game does not name as its
    //! [`InputActions`](crate::Game::InputActions):
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! meshes! { enum Only { Cube } }
    //!
    //! #[derive(InputButtonAction, Clone, Copy)]
    //! enum Verb {
    //!     Jump,
    //! }
    //!
    //! impl InputButtonAction for Verb {
    //!     fn bindings(&self) -> Vec<ButtonBinding> {
    //!         vec![Key::Space.into()]
    //!     }
    //! }
    //!
    //! struct Controls;
    //!
    //! impl InputActions for Controls {
    //!     type Button = Verb;
    //!     type Axis = NoInputAxes;
    //!     type Axis2 = NoInputAxes2;
    //! }
    //!
    //! struct Jumper;
    //!
    //! impl Game for Jumper {
    //!     type Meshes = Only;
    //!     type Sounds = NoSounds;
    //!     type InputActions = Controls;
    //!     type Skyboxes = NoSkyboxes;
    //!     type SurfaceStyles = ();
    //!     type PostEffects = ();
    //!
    //!     fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {}
    //!
    //!     fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
    //!         let _ = ctx.pressed(Key::Escape);
    //!     }
    //! }
    //! ```
    //!
    //! A draw with a style the game does not name in its
    //! [`SurfaceStyles`](crate::Game::SurfaceStyles):
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! meshes! { enum Only { Cube } }
    //!
    //! #[derive(Default, ShaderValues)]
    //! struct Water;
    //!
    //! impl SurfaceStyle for Water {
    //!     const PASS: DrawPass = DrawPass::Translucent;
    //! }
    //!
    //! #[derive(Default, ShaderValues)]
    //! struct Foam;
    //!
    //! impl SurfaceStyle for Foam {
    //!     const PASS: DrawPass = DrawPass::Translucent;
    //! }
    //!
    //! #[derive(Default, ShaderValues)]
    //! struct Ripple;
    //!
    //! impl SurfaceStyle for Ripple {
    //!     const PASS: DrawPass = DrawPass::Opaque;
    //! }
    //!
    //! surface_styles! { enum Looks { Water, Foam } }
    //!
    //! struct Pond;
    //!
    //! impl Game for Pond {
    //!     type Meshes = Only;
    //!     type Sounds = NoSounds;
    //!     type InputActions = NoInputActions;
    //!     type Skyboxes = NoSkyboxes;
    //!     type SurfaceStyles = Looks;
    //!     type PostEffects = ();
    //!
    //!     fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {}
    //!
    //!     fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
    //!         ctx.draw(Cube.at(Vec3::ZERO).surface_style::<Ripple>());
    //!     }
    //! }
    //! ```
    //!
    //! The values of a style the game does not name in its
    //! [`SurfaceStyles`](crate::Game::SurfaceStyles):
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! meshes! { enum Only { Cube } }
    //!
    //! #[derive(Default, ShaderValues)]
    //! struct Water;
    //!
    //! impl SurfaceStyle for Water {
    //!     const PASS: DrawPass = DrawPass::Translucent;
    //! }
    //!
    //! #[derive(Default, ShaderValues)]
    //! struct Foam;
    //!
    //! impl SurfaceStyle for Foam {
    //!     const PASS: DrawPass = DrawPass::Translucent;
    //! }
    //!
    //! #[derive(Default, ShaderValues)]
    //! struct Ripple;
    //!
    //! impl SurfaceStyle for Ripple {
    //!     const PASS: DrawPass = DrawPass::Opaque;
    //! }
    //!
    //! surface_styles! { enum Looks { Water, Foam } }
    //!
    //! struct Pond;
    //!
    //! impl Game for Pond {
    //!     type Meshes = Only;
    //!     type Sounds = NoSounds;
    //!     type InputActions = NoInputActions;
    //!     type Skyboxes = NoSkyboxes;
    //!     type SurfaceStyles = Looks;
    //!     type PostEffects = ();
    //!
    //!     fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {}
    //!
    //!     fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
    //!         ctx.set_surface_style(Ripple);
    //!     }
    //! }
    //! ```
    //!
    //! A post effect the game does not name in its
    //! [`PostEffects`](crate::Game::PostEffects):
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! meshes! { enum Only { Cube } }
    //!
    //! #[derive(ShaderValues)]
    //! struct Vignette;
    //!
    //! impl PostEffect for Vignette {
    //!     const STAGE: EffectStage = EffectStage::ToneMapped;
    //!     const SHADER: &'static str = "fn draw(pixel: Pixel) -> vec4<f32> { return pixel.color; }";
    //! }
    //!
    //! #[derive(ShaderValues)]
    //! struct Scanlines;
    //!
    //! impl PostEffect for Scanlines {
    //!     const STAGE: EffectStage = EffectStage::ToneMapped;
    //!     const SHADER: &'static str = "fn draw(pixel: Pixel) -> vec4<f32> { return pixel.color; }";
    //! }
    //!
    //! #[derive(ShaderValues)]
    //! struct Grain;
    //!
    //! impl PostEffect for Grain {
    //!     const STAGE: EffectStage = EffectStage::ToneMapped;
    //!     const SHADER: &'static str = "fn draw(pixel: Pixel) -> vec4<f32> { return pixel.color; }";
    //! }
    //!
    //! post_effects! { enum Look { Vignette, Scanlines } }
    //!
    //! struct Space;
    //!
    //! impl Game for Space {
    //!     type Meshes = Only;
    //!     type Sounds = NoSounds;
    //!     type InputActions = NoInputActions;
    //!     type Skyboxes = NoSkyboxes;
    //!     type SurfaceStyles = ();
    //!     type PostEffects = Look;
    //!
    //!     fn tick(&mut self, _ctx: &mut TickContext<'_, Self>) {}
    //!
    //!     fn frame(&mut self, ctx: &mut FrameContext<'_, Self>) {
    //!         ctx.set_post_effect(Grain);
    //!     }
    //! }
    //! ```
    //!
    //! A set naming one style twice, and one naming an effect twice:
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! #[derive(Default, ShaderValues)]
    //! struct Water;
    //!
    //! impl SurfaceStyle for Water {
    //!     const PASS: DrawPass = DrawPass::Translucent;
    //! }
    //!
    //! surface_styles! { enum Looks { Water, Water } }
    //! ```
    //!
    //! ```compile_fail
    //! use mirage_engine::prelude::*;
    //!
    //! #[derive(ShaderValues)]
    //! struct Grain;
    //!
    //! impl PostEffect for Grain {
    //!     const STAGE: EffectStage = EffectStage::ToneMapped;
    //!     const SHADER: &'static str = "fn draw(pixel: Pixel) -> vec4<f32> { return pixel.color; }";
    //! }
    //!
    //! post_effects! { enum Look { Grain, Grain } }
    //! ```
    //!
    //! A value of a kind no shader lane holds:
    //!
    //! ```compile_fail
    //! #[derive(mirage_engine::ShaderValues)]
    //! struct Ripples {
    //!     steps: bool,
    //! }
    //! ```
    //!
    //! Values a shader could not read by name:
    //!
    //! ```compile_fail
    //! #[derive(mirage_engine::ShaderValues)]
    //! struct Ripples(f32);
    //! ```
    //!
    //! A relief, and the same call given a sampler of its own:
    //!
    //! ```
    //! use mirage_engine::{ReliefData, math::UVec2};
    //!
    //! ReliefData::rgba8(UVec2::ONE, vec![128, 128, 255, 0]);
    //! ```
    //!
    //! ```compile_fail
    //! use mirage_engine::{ReliefData, math::UVec2};
    //!
    //! ReliefData::rgba8(UVec2::ONE, vec![128, 128, 255, 0]).pixelated();
    //! ```
    //!
    //! A shading map given a sampler of its own:
    //!
    //! ```compile_fail
    //! use mirage_engine::{ShadingData, math::UVec2};
    //!
    //! ShadingData::rgba8(UVec2::ONE, vec![255, 255, 255, 255]).pixelated();
    //! ```
    //!
    //! A vocabulary of one kind declaring the bindings of another:
    //!
    //! ```compile_fail
    //! #[derive(mirage_engine::InputAxisAction, Clone, Copy)]
    //! enum Lever {
    //!     Throttle,
    //! }
    //!
    //! impl mirage_engine::InputButtonAction for Lever {
    //!     fn bindings(&self) -> Vec<mirage_engine::ButtonBinding> {
    //!         Vec::new()
    //!     }
    //! }
    //! ```
    #[doc = include_str!("../README.md")]
    pub mod readme {}
}

/// The items of the public API most games use.
pub mod prelude {
    #[cfg(feature = "ui")]
    pub use crate::egui;
    pub use crate::math::*;
    pub use crate::mesh::{
        Cube, Frame, Instance, Mesh, MeshData, Meshes, NoClips, NoParts, Plane, Quad, Sheet, Slot,
        Sphere, Vertex,
    };
    pub use crate::{
        AnimationStates, Animator, Assets, Axis2Binding, AxisBinding, ButtonAxis, ButtonAxis2,
        ButtonBinding, Camera, Catalog, Clip, Color, Config, Cursor, DrawPass, EffectStage, Error,
        FrameContext, Game, Holds, InitContext, InputAction, InputActions, InputAxis2Action,
        InputAxisAction, InputButtonAction, Instant, JoystickControl, Key, Light, Material, Motion,
        MouseButton, NoInputActions, NoInputAxes, NoInputAxes2, NoInputButtons, NoSkyboxes,
        NoSounds, Pad, PadAxis, Part, PointerDelta, PostEffect, PostEffects, Progress, Projection,
        Ray, ReliefData, SaveKey, SaveValue, Saves, ShaderValues, ShadingData, SkyboxData,
        Skyboxes, SoundCue, SoundData, Sounds, Spot, Startup, Stick, SurfaceStyle, SurfaceStyles,
        TextureData, TickContext, Tonemap, Transform, Transition, View, WheelDelta, run,
    };
    pub use crate::{meshes, post_effects, surface_styles};
}