Crate mirage_engine 

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.

Re-exports

pub use animation::AnimationStates;

pub use animation::Animator;

pub use animation::Motion;

pub use animation::Progress;

pub use animation::Transition;

pub use input::Axis2Binding;

pub use input::AxisBinding;

pub use input::ButtonAxis;

pub use input::ButtonAxis2;

pub use input::ButtonBinding;

pub use input::Cursor;

pub use input::InputAction;

pub use input::InputActions;

pub use input::InputAxis2Action;

pub use input::InputAxisAction;

pub use input::InputButtonAction;

pub use input::JoystickControl;

pub use input::Key;

pub use input::MouseButton;

pub use input::NoInputActions;

pub use input::NoInputAxes;

pub use input::NoInputAxes2;

pub use input::NoInputButtons;

pub use input::Pad;

pub use input::PadAxis;

pub use input::PointerDelta;

pub use input::Stick;

pub use input::WheelDelta;

pub use mesh::Clip;

pub use mesh::Mesh;

pub use mesh::Meshes;

pub use mesh::NoClips;

pub use mesh::NoMeshes;

pub use mesh::NoParts;

pub use mesh::Part;

pub use mesh::Slot;

pub use post_effect::EffectStage;

pub use post_effect::NoPostEffects;

pub use post_effect::PostEffect;

pub use post_effect::PostEffects;

pub use ray::Ray;

pub use save::SaveKey;

pub use save::SaveValue;

pub use save::Saves;

pub use sound::MAX_VOICES;

pub use sound::NoSounds;

pub use sound::SoundCue;

pub use sound::SoundData;

pub use sound::Sounds;

pub use surface_style::DrawPass;

pub use surface_style::NoSurfaceStyles;

pub use surface_style::SurfaceStyle;

pub use surface_style::SurfaceStyles;

pub use shader_values::ShaderValues;

pub use glam as math;

pub use rayon;

pub use egui;

Modules

animation

The machine a game poses a draw with: the states it moves between, what each of them plays, and how far along that is.

headless

Running a game with no window, for tools and tests.

input

Actions: what a player can do, and the controls bound to each one.

mesh

Meshes: the two traits a game’s mesh types implement, the data they build, the draws of them, and the set of every mesh a game draws.

post_effect

Full-screen passes a game writes in WGSL, run over the frame the engine drew.

prelude

The items of the public API most games use.

ray

The ray a pixel lies on, and the shapes a game can hit with it.

save

Every value a game keeps between runs: what an earlier run stored, and whatever this one has saved over it.

shader_values

The values a style’s or a post effect’s WGSL reads, and the WGSL struct it reads them through.

sound

Sounds, and the trait that builds them from a game’s values.

surface_style

Surface styles: WGSL of a game’s own, compiled into the engine’s forward shader.

Macros

meshes

Writes the set of every mesh a game draws: an enum with one variant wrapping each named type, which Game::Meshes names.

post_effects

Writes the set of every post effect a game passes its frame through: an enum with one variant wrapping each named type, which Game::PostEffects names.

surface_styles

Writes the set of every style a game draws with: an enum with one variant wrapping each named type, which Game::SurfaceStyles names.

Structs

Assets

Everything Config::with_assets loaded, by name across all sources.

Camera

A View and a Projection: where a frame is viewed from, and how that view is projected.

Color

A red, green, blue, and opacity color, each a linear value the engine encodes to sRGB on its way to the window.

Config

Presentation settings for a game.

Error

Something the engine could not do.

FrameContext

The work Game::frame may do.

InitContext

The work the startup closure run takes may do.

Instant

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.

Light

One light for one frame.

Material

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

Projection

Screen extent of the world, and its foreshortening by depth.

ReliefData

The relief a mesh slot reads: 8-bit RGBA holding a normal and, where the constructor declares one, a depth per texel in place of color, row by row from the top left.

ShadingData

The shading a mesh slot reads: 8-bit RGBA holding a texel’s occlusion, roughness and metallic in R, G and B in place of color, row by row from the top left.

SkyboxData

The sky one value of a game’s vocabulary is drawn and lit from: one of two kinds, an image of the whole sky or a gradient between three colors, the fraction of its own light it lands on a surface, and the ground color under its horizon where a game states one.

Spot

The values Light::spot builds one light from.

Startup

The part of InitContext that is typed by no vocabulary of the game’s own, which InitContext::startup returns.

TextureData

The texture a mesh slot is sampled from: 8-bit RGBA, sRGB-encoded, row by row from the top left.

TickContext

The work Game::tick may do: simulate, never draw.

Transform

A draw’s position, turn, and size.

View

The world’s viewpoint.

Enums

Lens

The shape a projection applies to depth, and the number shaping it.

NoSkyboxes

The vocabulary of a game with no sky of its own to name.

Tonemap

The curve a frame is drawn to the screen through.

Constants

MAX_LIGHTS

Light cap per frame; excess is ignored — warned the first frame, a debug log after.

MAX_SHADOWS

Cap on casting lights per frame (see Light::shadow); excess is ignored — warned the first frame, a debug log after.

Traits

Catalog

Every value the engine proves it can build before the first frame.

Game

A game driven by the engine, which owns it for the whole run.

Holds

Proves that a set holds T, and turns a T into it.

Seats

Proves that one of an InputActions set’s three kinds seats A.

Skyboxes

Turns a game’s value into a skybox.

Functions

run

Opens the window and runs the game init builds until it is closed.

Derive Macros

Catalog

Derives Catalog for a mesh vocabulary: every value the engine builds before the game’s startup closure runs, to prove the assets it names are loaded.

Clip

Derives Clip for a vocabulary of the clips a mesh is posed by: each fieldless variant (and a unit struct) is named by what it is called in code, or by #[clip("...")] when the loaded animation name cannot be written as one — repeat the attribute for other spellings. The variants are numbered in order.

InputAxis2Action

Derives the engine’s view of a vocabulary of actions whose value is a vector, whose bindings are declared by hand in the InputAxis2Action trait; see InputButtonAction.

InputAxisAction

Derives the engine’s view of a vocabulary of actions whose value is a number, whose bindings are declared by hand in the InputAxisAction trait; see InputButtonAction.

InputButtonAction

Derives the engine’s view of a vocabulary of actions whose value is held or not: its values, and the names a rebind of one is kept under.

Part

Derives Part for a vocabulary of mesh parts: each fieldless variant (and a unit struct) is named by what it is called in code, or by #[part("...")] when the loaded material name cannot be written as one — repeat the attribute for other spellings. The variants are numbered in order, which is the position a draw’s override of one is stored at.

Saves

Derives the engine’s view of a vocabulary of keys a game keeps between runs: its values, and the name the store keeps each of them under — the vocabulary’s own name, ., and the value’s name.

ShaderValues

Derives ShaderValues for the values a style’s or an effect’s WGSL reads: the WGSL struct declaring them, and the layout writing each of them where that struct reads it.