Build a game #
In which we build a cube you steer round a floor, picking up three marks. About a hundred and seventy lines, and it ends with a test that holds the frame against a picture of it.
Rust 1.87 or newer.
cargo new rover
cd rover
cargo add blitzkit glam
The trait is the whole interface #
Game is what you implement and start() is what you call. Four of its
methods have no default and the rest do, so the smallest game that opens a
window is this:
impl Game for Rover {
fn initialize(&mut self, _g: &mut Geometry, _t: &mut TextRenderer,
_s: &SoundSystem, _size: (f32, f32)) {}
fn update(&mut self, dt: f32, _g: &mut Geometry, _t: &mut TextRenderer,
_s: &SoundSystem) {}
fn process_keyboard(&mut self, input: KeyboardInput) {}
fn is_quitting(&self) -> bool { self.quitting }
fn focus_changed(&mut self, focus: bool) {}
}
fn main() {
start("rover", Box::new(Rover::new()));
}
start opens the window, makes the device and runs the loop. Nothing else
in your program touches wgpu.
Meshes are uploaded once #
load is called once, before anything is drawn, and it is where meshes go
up. Keep the MeshId it hands back.
fn load(&mut self, renderer: &mut Renderer) {
self.cube = Some(renderer.add_mesh(&MeshData::cube()));
self.floor = Some(renderer.add_mesh(&MeshData::plane()));
}
cube() is a unit cube on the origin and plane() is a unit square on the
xz plane facing up. There are also sphere(), an OBJ loader, and
surface(), which builds a mesh from a formula.
The scene is thrown away every frame #
draw hands you a Scene and a Camera. Fill the scene, say where the
camera is, and both are emptied before the next frame. There is nothing to
free and nothing to keep in step.
let mut wide = Transform::at(vec3(0.0, 0.0, 0.0));
wide.scale = vec3(EDGE * 2.0, 1.0, EDGE * 2.0);
scene.push_colored(floor, &wide, vec4(0.22, 0.24, 0.28, 1.0));
scene.push_colored(cube, &Transform::at(self.at), vec4(0.3, 0.7, 0.9, 1.0));
camera.position = self.at + vec3(0.0, 6.0, 9.0);
camera.target = self.at;
One mesh drawn twenty times is one upload and twenty transforms. The floor and every mark here are the same two meshes pushed again.
Light it #
A sun that comes from a direction, and lamps that come from a place.
scene.light.direction = vec3(-0.3, -1.0, -0.4);
scene.push_light(PointLight::new(
self.at + vec3(0.0, 2.5, 0.0),
vec3(1.0, 0.9, 0.7),
1.4,
9.0,
));
The lamp rides above the rover, so the pool of light moves with it. Add
.casting() and it throws a shadow, which two lamps at a time can afford.
Keys say what is held, not what to do #
process_keyboard fires on the edge, once down and once up. Movement
belongs in update, which is given the seconds since the last frame.
fn process_keyboard(&mut self, input: KeyboardInput) {
let down = input.state == KeyboardKeyState::Pressed;
match input.key {
KeyboardKey::Up => self.held[0] = down,
KeyboardKey::Down => self.held[1] = down,
KeyboardKey::Left => self.held[2] = down,
KeyboardKey::Right => self.held[3] = down,
KeyboardKey::Escape => self.quitting = down,
_ => {}
}
}
Then in update, self.at += self.wish() * SPEED * dt. Multiplying by dt
is what makes the rover cross the floor at the same speed on a fast machine
and a slow one.
Give it something to do #
The marks are a list, and taking one is removing it. Nothing has to be drawn to be taken, and the drawing reads the same list, so the two cannot disagree about where a mark is.
let at = self.at;
let before = self.marks.len();
self.marks.retain(|mark| at.distance(*mark) > REACH);
self.taken += before - self.marks.len();
Say something #
Text and quads are the 2D half, and they are filled in update rather than
draw.
text.push_render_text(RenderText {
position: vec2(20.0, 20.0),
color: vec4(1.0, 1.0, 1.0, 1.0),
text: said,
size: 20.0,
..Default::default()
});
The engine empties the text and the quads between frames, so a line pushed every frame stays one line.
Hold it against a picture #
This is the part no window can do for you. One call draws a frame with no window open and holds it against a committed picture.
#[test]
fn the_floor_from_the_start_looks_right() {
let reference = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("tests/pictures/from-the-start.png");
blitzkit::picture::drawn_looks_right(&reference, blitzkit::picture::SIZE, |renderer| {
let mut game = Rover::new();
let mut geometry = Geometry::new();
let mut text = TextRenderer::new();
let sound = SoundSystem::new();
let mut scene = Scene::new();
let mut camera = Camera::new();
game.load(renderer);
game.initialize(&mut geometry, &mut text, &sound, (320.0, 240.0));
game.update(0.0, &mut geometry, &mut text, &sound);
game.draw(&mut scene, &mut camera);
(scene, camera)
});
}
mkdir -p tests/pictures and run it. The first run writes the reference
rather than comparing, so look at what it wrote before you commit it. After
that, move one mark a metre and the test fails on 0.7% of its pixels, names
the frame it drew and writes the difference beside it.
A dt of nought is what makes this repeatable. Nothing moves between the
staging and the shutter.
Testing a game has the rest of it: the
tolerances, BLESS, and what happens on a machine with no adapter.
The whole thing #
//! rover: a cube you steer round a floor, picking up three marks.
use blitzkit::camera::Camera;
use blitzkit::geometry::Geometry;
use blitzkit::keyboard::{KeyboardInput, KeyboardKey, KeyboardKeyState};
use blitzkit::lighting::PointLight;
use blitzkit::mesh::{MeshData, Transform};
use blitzkit::renderer::render_text::{RenderText, TextRenderer};
use blitzkit::renderer::scene::{MeshId, Scene};
use blitzkit::renderer::Renderer;
use blitzkit::sound::SoundSystem;
use blitzkit::{start, Game};
use glam::{vec2, vec3, vec4, Vec3};
/// Half the floor's width, so the rover is kept inside this either way.
const EDGE: f32 = 7.0;
/// Metres a second.
const SPEED: f32 = 5.0;
/// How near counts as reaching a mark.
const REACH: f32 = 0.9;
/// Where the three marks sit. Written once and read by both the drawing and
/// the taking, so the two can never disagree about where a mark is.
fn marks() -> Vec<Vec3> {
vec![
vec3(-4.5, 0.25, -3.0),
vec3(4.0, 0.25, 1.5),
vec3(-1.0, 0.25, 5.0),
]
}
struct Rover {
at: Vec3,
/// north, south, west, east
held: [bool; 4],
marks: Vec<Vec3>,
taken: usize,
cube: Option<MeshId>,
floor: Option<MeshId>,
quitting: bool,
}
impl Rover {
fn new() -> Self {
Self {
at: vec3(0.0, 0.5, 0.0),
held: [false; 4],
marks: marks(),
taken: 0,
cube: None,
floor: None,
quitting: false,
}
}
/// Which way the keys are asking to go, as a unit vector or nothing.
fn wish(&self) -> Vec3 {
let north = self.held[0] as i32 as f32;
let south = self.held[1] as i32 as f32;
let west = self.held[2] as i32 as f32;
let east = self.held[3] as i32 as f32;
let wish = vec3(east - west, 0.0, south - north);
if wish.length() > 0.0 {
wish.normalize()
} else {
Vec3::ZERO
}
}
}
impl Game for Rover {
fn load(&mut self, renderer: &mut Renderer) {
self.cube = Some(renderer.add_mesh(&MeshData::cube()));
self.floor = Some(renderer.add_mesh(&MeshData::plane()));
}
fn initialize(
&mut self,
_geometry: &mut Geometry,
_text: &mut TextRenderer,
_sound: &SoundSystem,
_size: (f32, f32),
) {
}
fn update(
&mut self,
dt: f32,
_geometry: &mut Geometry,
text: &mut TextRenderer,
_sound: &SoundSystem,
) {
self.at += self.wish() * SPEED * dt;
self.at.x = self.at.x.clamp(-EDGE, EDGE);
self.at.z = self.at.z.clamp(-EDGE, EDGE);
// A mark is taken by being reached, and the list is what says which
// are left, so nothing has to be drawn to be taken.
let at = self.at;
let before = self.marks.len();
self.marks.retain(|mark| at.distance(*mark) > REACH);
self.taken += before - self.marks.len();
let said = if self.marks.is_empty() {
"all three. Escape quits".to_string()
} else {
format!("{} of 3. Arrow keys drive, escape quits", self.taken)
};
text.push_render_text(RenderText {
position: vec2(20.0, 20.0),
color: vec4(1.0, 1.0, 1.0, 1.0),
text: said,
size: 20.0,
..Default::default()
});
}
fn draw(&mut self, scene: &mut Scene, camera: &mut Camera) {
let (Some(cube), Some(floor)) = (self.cube, self.floor) else {
return;
};
let mut wide = Transform::at(vec3(0.0, 0.0, 0.0));
wide.scale = vec3(EDGE * 2.0, 1.0, EDGE * 2.0);
scene.push_colored(floor, &wide, vec4(0.22, 0.24, 0.28, 1.0));
for mark in &self.marks {
let mut small = Transform::at(*mark);
small.scale = Vec3::splat(0.5);
scene.push_colored(cube, &small, vec4(0.95, 0.75, 0.2, 1.0));
}
scene.push_colored(cube, &Transform::at(self.at), vec4(0.3, 0.7, 0.9, 1.0));
scene.light.direction = vec3(-0.3, -1.0, -0.4);
scene.push_light(PointLight::new(
self.at + vec3(0.0, 2.5, 0.0),
vec3(1.0, 0.9, 0.7),
1.4,
9.0,
));
// behind and above the rover, looking at it
camera.position = self.at + vec3(0.0, 6.0, 9.0);
camera.target = self.at;
}
fn process_keyboard(&mut self, input: KeyboardInput) {
let down = input.state == KeyboardKeyState::Pressed;
match input.key {
KeyboardKey::Up => self.held[0] = down,
KeyboardKey::Down => self.held[1] = down,
KeyboardKey::Left => self.held[2] = down,
KeyboardKey::Right => self.held[3] = down,
KeyboardKey::Escape => self.quitting = down,
_ => {}
}
}
fn is_quitting(&self) -> bool {
self.quitting
}
fn focus_changed(&mut self, _focus: bool) {}
}
fn main() {
start("rover", Box::new(Rover::new()));
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_floor_from_the_start_looks_right() {
let reference = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("tests/pictures/from-the-start.png");
blitzkit::picture::drawn_looks_right(
&reference,
blitzkit::picture::SIZE,
|renderer| {
let mut game = Rover::new();
let mut geometry = Geometry::new();
let mut text = TextRenderer::new();
let sound = SoundSystem::new();
let mut scene = Scene::new();
let mut camera = Camera::new();
game.load(renderer);
game.initialize(&mut geometry, &mut text, &sound, (320.0, 240.0));
game.update(0.0, &mut geometry, &mut text, &sound);
game.draw(&mut scene, &mut camera);
(scene, camera)
},
);
}
}
Where to go next #
The examples are single files, each small enough to read in one sitting. The games are whole programs with their own repos. Signatures are on docs.rs.