Today, a browser runs it.

Not a rewrite. Not a port. The same library, with the same twenty-eight tests, compiled for a different machine. The browser gets a handful of operations and a save that is already text. It does not get the rules.

By the end, a web page shows this:

One hour away.
Stage 1 -> 128  Level 1 -> 47  Gold 0 -> 16637

Stage 128 and level 47 are the numbers tests/idle_hour.rs has been checking since the ninth article. Same engine. Same hour. The call came from JavaScript.

Along the way we meet WebAssembly, two tools that do the glue work, and one new rule about what is allowed to cross a border.

Our starting point

This series builds a small idle game: a player clicks to fight slimes, earns gold and XP, and keeps progressing while you are away.

If you are only reading along, skip past this code to "A second machine."

If you are building along, you need the library as it stood at the end of the last article: a project called rustbound-idle with seven source files and two outside tests. (If you kept your project, you already have all of this. The article_10 branch of the companion repository has it too.)

rustbound-idle/
├── Cargo.toml
├── Cargo.lock
├── src/
│   ├── lib.rs
│   ├── main.rs
│   ├── rules.rs
│   ├── enemy.rs
│   ├── player.rs
│   ├── game.rs
│   └── save.rs
└── tests/
    ├── idle_hour.rs
    └── save_and_restore.rs

Cargo.toml:

Cargo.toml

[package]
name = "rustbound-idle"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"

mod enemy;
mod game;
mod player;
mod rules;
mod save;

pub use enemy::Enemy;
pub use game::Game;
pub use player::{Player, PurchaseOutcome};
pub use save::LoadError;

use rustbound_idle::{Game, PurchaseOutcome};

fn main() {
    let mut game = Game::new();
while game.stage <= 3 {
    let stage = game.stage;
    let level = game.player.level;

    game.click();

    if game.stage > stage {
        println!(
            "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
            game.player.gold,
            game.player.xp,
            game.player.xp_needed()
        );

        if game.player.level > level {
            println!(
                "Level up! Now level {}. Click damage: {}",
                game.player.level,
                game.player.click_damage()
            );
        }

        println!(
            "  Next up: {} with {} health.",
            game.enemy.name, game.enemy.health
        );
    }

    match game.buy_click_upgrade() {
        PurchaseOutcome::Purchased => println!(
            "Bought click upgrade {}! Click damage: {}  Gold left: {}",
            game.player.click_upgrade_level,
            game.player.click_damage(),
            game.player.gold
        ),
        PurchaseOutcome::NotEnoughGold => {}
    }
}

let save = game.save_json();
println!("Saved: {save}");

drop(game);

let mut game = match Game::from_saved_json(&save) {
    Ok(game) => game,
    Err(error) => {
        println!("Could not load the save: {error:?}");
        return;
    }
};

println!("Loaded. Stage {}, level {}.", game.stage, game.player.level);

let stage = game.stage;
let level = game.player.level;
let gold = game.player.gold;

game.tick(3600);

println!("One hour away.");
println!(
    "Stage {} -> {}  Level {} -> {}  Gold {} -> {}",
    stage, game.stage, level, game.player.level, gold, game.player.gold
);

}

pub(crate) fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

pub(crate) fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}
pub(crate) fn is_defeated(health: u32) -> bool {
    health == 0
}
pub(crate) fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}
pub(crate) fn gold_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(3)
}
pub(crate) fn xp_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(4)
}
pub(crate) fn xp_to_next_level(level: u32) -> u32 {
    level
        .saturating_sub(1)
        .saturating_mul(15)
        .saturating_add(20)
}
pub(crate) fn base_damage_for_level(level: u32) -> u32 {
    level.saturating_add(4)
}
pub(crate) fn idle_damage_for_level(level: u32) -> u32 {
    level
}
pub(crate) fn click_upgrade_bonus(upgrades: u32) -> u32 {
    upgrades.saturating_mul(2)
}
pub(crate) fn click_upgrade_cost(upgrades: u32) -> u32 {
    upgrades.saturating_add(1).saturating_mul(10)
}
#[cfg(test)]
mod tests {
    use super::*;
#[test]
fn click_damage_adds_base_and_bonus() {
    assert_eq!(click_damage(3, 4), 7);
}

#[test]
fn health_never_drops_below_zero() {
    assert_eq!(health_after_hit(3, 10), 0);
}

#[test]
fn zero_health_is_defeated() {
    assert!(is_defeated(0));
    assert!(!is_defeated(1));
}

#[test]
fn later_stages_have_tougher_enemies() {
    assert_eq!(enemy_health_for_stage(1), 20);
    assert_eq!(enemy_health_for_stage(2), 30);
}

#[test]
fn later_stages_pay_better() {
    assert_eq!(gold_reward_for_stage(1), 5);
    assert_eq!(gold_reward_for_stage(2), 7);
    assert_eq!(xp_reward_for_stage(1), 6);
    assert_eq!(xp_reward_for_stage(2), 8);
}

#[test]
fn levels_need_more_xp_as_they_go() {
    assert_eq!(xp_to_next_level(1), 20);
    assert_eq!(xp_to_next_level(2), 35);
}

#[test]
fn levels_make_the_player_hit_harder() {
    assert_eq!(base_damage_for_level(1), 5);
    assert_eq!(base_damage_for_level(2), 6);
}

#[test]
fn idle_damage_grows_with_level() {
    assert_eq!(idle_damage_for_level(1), 1);
    assert_eq!(idle_damage_for_level(2), 2);
}

#[test]
fn upgrades_cost_more_each_time() {
    assert_eq!(click_upgrade_cost(0), 10);
    assert_eq!(click_upgrade_cost(1), 20);
}

}

use crate::rules::{enemy_health_for_stage, gold_reward_for_stage, xp_reward_for_stage};

pub struct Enemy {
    pub name: String,
    pub health: u32,
    pub(crate) gold_reward: u32,
    pub(crate) xp_reward: u32,
}
impl Enemy {
    pub(crate) fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
            xp_reward: xp_reward_for_stage(stage),
        }
    }
}

use crate::rules::{
    base_damage_for_level, click_damage, click_upgrade_bonus, click_upgrade_cost, xp_to_next_level,
};

pub struct Player {
    pub gold: u32,
    pub xp: u32,
    pub level: u32,
    pub click_upgrade_level: u32,
}
#[derive(Debug, PartialEq)]
pub enum PurchaseOutcome {
    Purchased,
    NotEnoughGold,
}
impl Player {
    pub(crate) fn new() -> Player {
        Player {
            gold: 0,
            xp: 0,
            level: 1,
            click_upgrade_level: 0,
        }
    }
pub(crate) fn add_gold(&mut self, amount: u32) {
    self.gold = self.gold.saturating_add(amount);
}

pub(crate) fn add_xp(&mut self, amount: u32) {
    self.xp = self.xp.saturating_add(amount);

    while self.xp >= self.xp_needed() {
        self.xp -= self.xp_needed();
        self.level = self.level.saturating_add(1);
    }
}

pub fn xp_needed(&self) -> u32 {
    xp_to_next_level(self.level)
}

pub fn click_damage(&self) -> u32 {
    click_damage(self.base_damage(), self.bonus_damage())
}

fn base_damage(&self) -> u32 {
    base_damage_for_level(self.level)
}

fn bonus_damage(&self) -> u32 {
    click_upgrade_bonus(self.click_upgrade_level)
}

pub(crate) fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
    let cost = click_upgrade_cost(self.click_upgrade_level);

    if self.gold < cost {
        return PurchaseOutcome::NotEnoughGold;
    }

    self.gold -= cost;
    self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);

    PurchaseOutcome::Purchased
}

}
#[cfg(test)]
mod tests {
    use super::*;
#[test]
fn leveling_up_keeps_leftover_xp() {
    let mut player = Player::new();

    player.add_xp(25);

    assert_eq!(player.level, 2);
    assert_eq!(player.xp, 5);
}

#[test]
fn a_big_reward_can_skip_levels() {
    let mut player = Player::new();

    player.add_xp(60);

    assert_eq!(player.level, 3);
    assert_eq!(player.xp, 5);
}

#[test]
fn buying_an_upgrade_needs_gold() {
    let mut player = Player::new();

    assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::NotEnoughGold);
    assert_eq!(player.click_upgrade_level, 0);
    assert_eq!(player.bonus_damage(), 0);
}

#[test]
fn buying_an_upgrade_spends_gold() {
    let mut player = Player::new();
    player.gold = 12;

    assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::Purchased);
    assert_eq!(player.gold, 2);
    assert_eq!(player.click_upgrade_level, 1);
    assert_eq!(player.bonus_damage(), 2);
}

}

use crate::enemy::Enemy;
use crate::player::{Player, PurchaseOutcome};
use crate::rules::{health_after_hit, idle_damage_for_level, is_defeated};

pub struct Game {
    pub stage: u32,
    pub player: Player,
    pub enemy: Enemy,
}
impl Game {
    pub fn new() -> Game {
        Game {
            stage: 1,
            player: Player::new(),
            enemy: Enemy::for_stage(1),
        }
    }
pub fn click(&mut self) {
    attack(&self.player, &mut self.enemy);
    self.resolve_hit();
}

pub fn tick(&mut self, seconds: u32) {
    for _ in 0..seconds {
        let damage = idle_damage_for_level(self.player.level);

        self.enemy.health = health_after_hit(self.enemy.health, damage);
        self.resolve_hit();
    }
}

fn resolve_hit(&mut self) {
    if is_defeated(self.enemy.health) {
        self.defeat_enemy();
    }
}

fn defeat_enemy(&mut self) {
    self.player.add_gold(self.enemy.gold_reward);
    self.player.add_xp(self.enemy.xp_reward);

    self.stage = self.stage.saturating_add(1);
    self.enemy = Enemy::for_stage(self.stage);
}

pub fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
    self.player.buy_click_upgrade()
}

}
impl Default for Game {
    fn default() -> Game {
        Game::new()
    }
}
fn attack(player: &Player, enemy: &mut Enemy) {
    enemy.health = health_after_hit(enemy.health, player.click_damage());
}
#[cfg(test)]
mod tests {
    use super::*;
#[test]
fn attack_reduces_enemy_health() {
    let player = Player::new();

    let mut enemy = Enemy::for_stage(1);
    enemy.health = 10;

    attack(&player, &mut enemy);

    assert_eq!(enemy.health, 5);
}

#[test]
fn a_new_game_starts_at_stage_one() {
    let game = Game::new();

    assert_eq!(game.stage, 1);
    assert_eq!(game.enemy.health, 20);
    assert_eq!(game.player.gold, 0);
}

#[test]
fn clicking_damages_the_enemy() {
    let mut game = Game::new();

    game.click();

    assert_eq!(game.enemy.health, 15);
}

#[test]
fn defeating_an_enemy_pays_the_player() {
    let mut game = Game::new();
    game.enemy.health = 1;

    game.click();

    assert_eq!(game.stage, 2);
    assert_eq!(game.enemy.health, 30);
    assert_eq!(game.player.gold, 5);
    assert_eq!(game.player.xp, 6);
}

#[test]
fn one_second_is_one_idle_hit() {
    let mut game = Game::new();

    game.tick(1);

    assert_eq!(game.enemy.health, 19);
}

#[test]
fn zero_seconds_changes_nothing() {
    let mut game = Game::new();

    game.tick(0);

    assert_eq!(game.stage, 1);
    assert_eq!(game.enemy.health, 20);
}

#[test]
fn enough_time_defeats_the_enemy() {
    let mut game = Game::new();

    game.tick(20);

    assert_eq!(game.stage, 2);
    assert_eq!(game.enemy.health, 30);
    assert_eq!(game.player.gold, 5);
    assert_eq!(game.player.xp, 6);
}

#[test]
fn one_long_tick_matches_many_short_ones() {
    let mut long = Game::new();
    let mut short = Game::new();

    long.tick(45);

    for _ in 0..45 {
        short.tick(1);
    }

    assert_eq!(long.stage, short.stage);
    assert_eq!(long.enemy.health, short.enemy.health);
    assert_eq!(long.player.gold, short.player.gold);
    assert_eq!(long.player.xp, short.player.xp);
    assert_eq!(long.player.level, short.player.level);
}

}

use crate::enemy::Enemy;
use crate::game::Game;
use serde::{Deserialize, Serialize};

const SAVE_VERSION: u32 = 1;
#[derive(Debug, PartialEq)]
pub enum LoadError {
    Unreadable,
    UnsupportedVersion(u32),
}
#[derive(Serialize, Deserialize)]
struct PlayerSave {
    gold: u32,
    xp: u32,
    level: u32,
    click_upgrade_level: u32,
}
#[derive(Serialize, Deserialize)]
struct SaveData {
    save_version: u32,
    stage: u32,
    player: PlayerSave,
    enemy_health: u32,
}
impl Game {
    pub fn save_json(&self) -> String {
        let save = SaveData {
            save_version: SAVE_VERSION,
            stage: self.stage,
            player: PlayerSave {
                gold: self.player.gold,
                xp: self.player.xp,
                level: self.player.level,
                click_upgrade_level: self.player.click_upgrade_level,
            },
            enemy_health: self.enemy.health,
        };
    serde_json::to_string(&save).expect("a save made of numbers should always serialize")
}

pub fn from_saved_json(json: &str) -> Result<Game, LoadError> {
    let save: SaveData = match serde_json::from_str(json) {
        Ok(save) => save,
        Err(_) => return Err(LoadError::Unreadable),
    };

    if save.save_version != SAVE_VERSION {
        return Err(LoadError::UnsupportedVersion(save.save_version));
    }

    let mut game = Game::new();

    game.stage = save.stage;
    game.player.gold = save.player.gold;
    game.player.xp = save.player.xp;
    game.player.level = save.player.level;
    game.player.click_upgrade_level = save.player.click_upgrade_level;

    game.enemy = Enemy::for_stage(save.stage);
    game.enemy.health = save.enemy_health;

    Ok(game)
}

}
#[cfg(test)]
mod tests {
    use super::*;
#[test]
fn a_new_game_saves_its_starting_numbers() {
    let json = Game::new().save_json();

    assert_eq!(
        json,
        r#"{"save_version":1,"stage":1,"player":{"gold":0,"xp":0,"level":1,"click_upgrade_level":0},"enemy_health":20}"#
    );
}

#[test]
fn a_loaded_game_rebuilds_the_enemy_from_the_rules() {
    let mut game = Game::new();
    game.tick(600);

    let restored = Game::from_saved_json(&game.save_json()).expect("the save should load");

    assert_eq!(restored.stage, game.stage);
    assert_eq!(restored.enemy.health, game.enemy.health);
    assert_eq!(restored.enemy.gold_reward, game.enemy.gold_reward);
    assert_eq!(restored.enemy.xp_reward, game.enemy.xp_reward);
}

#[test]
fn nonsense_is_not_a_save() {
    assert!(matches!(
        Game::from_saved_json("definitely not a save"),
        Err(LoadError::Unreadable)
    ));
}

#[test]
fn a_save_with_missing_pieces_is_not_a_save() {
    let json = r#"{"save_version":1,"stage":4}"#;

    assert!(matches!(
        Game::from_saved_json(json),
        Err(LoadError::Unreadable)
    ));
}

#[test]
fn a_save_from_another_version_is_refused() {
    let json = r#"{
        "save_version": 99,
        "stage": 1,
        "player": { "gold": 0, "xp": 0, "level": 1, "click_upgrade_level": 0 },
        "enemy_health": 20
    }"#;

    assert!(matches!(
        Game::from_saved_json(json),
        Err(LoadError::UnsupportedVersion(99))
    ));
}

}

use rustbound_idle::Game;

#[test]
fn an_hour_away_moves_the_game_forward() {
    let mut game = Game::new();
game.tick(3600);

assert_eq!(game.stage, 128);
assert_eq!(game.player.level, 47);

}

use rustbound_idle::Game;

#[test]
fn a_restored_game_plays_the_same_hour() {
    let mut original = Game::new();
    original.tick(600);
let mut restored = Game::from_saved_json(&original.save_json()).expect("the save should load");

original.tick(3600);
restored.tick(3600);

assert_eq!(restored.stage, original.stage);
assert_eq!(restored.enemy.health, original.enemy.health);
assert_eq!(restored.player.gold, original.player.gold);
assert_eq!(restored.player.xp, original.player.xp);
assert_eq!(restored.player.level, original.player.level);

}

Run cargo test, and twenty-eight tests pass. Run cargo run, and the player clears three stages, saves, loads, and spends an hour away.

A second machine

Everything we have compiled so far has been for the computer in front of you. cargo build asks Rust to produce a program for this machine: this processor, this operating system.

Rust can produce programs for other machines too. A phone. A server with a different processor. Each one is called a target, and you pick it when you build.

WebAssembly is one of those targets.

It is not a real machine. It is a description of one, agreed on by the people who make browsers, so that every browser can run the same compiled code. Compile Rust for it, and the result is a file a browser can load and run, the way it loads and runs JavaScript.

The target has a long name:

wasm32-unknown-unknown

The three parts are the processor, the vendor, and the operating system. The processor is 32-bit WebAssembly. The other two are unknown, and they mean it.

There is no operating system. No files, no clock, no terminal, no println!. A program compiled for this target can do arithmetic and talk to whoever loaded it, and that is all.

That should sound like a problem.

It is not, and the reason is the wall we built two articles ago. Our library has never opened a file, never asked the time, never printed. It takes numbers and text, and it gives back numbers and text. main.rs does the printing, and main.rs is not coming with us.

Install the target:

rustup target add wasm32-unknown-unknown

That downloads Rust's standard library, compiled for WebAssembly, so that String and Vec and saturating_add all exist on the other side. It takes a moment, and it only happens once.

Question: Why does main.rs stay behind when we compile the library for the browser?

1. WebAssembly can only compile files named lib.rs
2. main.rs prints to a terminal, and this browser target has no terminal
3. JavaScript automatically replaces every Rust main() function

Answer: 2. main.rs prints to a terminal, and this browser target has no terminal

Explanation: The engine only calculates with numbers and text. The terminal-specific printing stays in main.rs on the machine that has a terminal.

Two tools

WebAssembly has one more limitation that matters to us.

At the raw WebAssembly boundary we are using today, values cross as WebAssembly's small built-in types. A Rust String or struct cannot cross as a JavaScript string or object by itself.

Our front door takes a &str and returns a String. Those are not numbers.

Someone has to write the code that turns a Rust String into a JavaScript string, one byte at a time, on both sides of the line. That code is tedious, and it is the same every time, so a tool writes it. Two tools, in fact:

• wasm-bindgen is a Rust crate and a command-line program. The crate gives us an attribute to mark what JavaScript should be able to call. The program reads a compiled .wasm file and writes the JavaScript glue for everything marked.
• wasm-pack runs the whole build: cargo build for the WebAssembly target, then wasm-bindgen, then a shrinking pass, and puts the results in one folder, ready for a web page.

Install wasm-pack:

cargo install wasm-pack

cargo install builds a program from crates.io and puts it on your path. This one takes a couple of minutes.

The other tool comes in through Cargo.toml, the way serde did. Open it and make two changes:

Cargo.toml

[package]
name = "rustbound-idle"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
wasm-bindgen = "0.2"

The dependency is the familiar part.

The [lib] section is new. It tells Cargo what shape to build the library in.

rlib is the shape Rust uses: it is what main.rs and the tests have been linking against all along. cdylib is a shape other languages can load. Think of a front door for the family and a side door for guests. We ask for both, so that cargo run and cargo test keep using the door they know, and wasm-pack gets one it can open.

Build:

cargo build

Cargo downloads wasm-bindgen and a few helpers, compiles them, and finishes with nothing to say. Nothing is marked yet.

Run cargo test too. Twenty-eight.

Do not export the engine

Here is the tempting move: put the wasm-bindgen attribute on Game, on Player, on Enemy, and let JavaScript have everything.

We are not going to do that, for the same reason rules is not on the front door.

Game has never heard of a browser. The moment it carries a browser attribute, it has. Every future change to the engine would have to ask whether JavaScript still likes the shape. And JavaScript would be free to reach past the methods, read the fields, and start doing arithmetic of its own.

So we build an adapter: a small type that holds a Game, and shows JavaScript only what we choose.

It is a separate concern, so it gets a separate module. Create src/web.rs:

src/web.rs

use crate::game::Game;
use wasm_bindgen::prelude::*;

#[wasm_bindgen(js_name = Game)]
pub struct WebGame {
    inner: Game,
}

#[wasm_bindgen(js_class = Game)]
impl WebGame {
    #[wasm_bindgen(constructor)]
    pub fn new() -> WebGame {
        WebGame { inner: Game::new() }
    }

    pub fn click(&mut self) {
        self.inner.click();
    }

    pub fn tick(&mut self, seconds: u32) {
        self.inner.tick(seconds);
    }
}

And register it. In src/lib.rs, add mod web; under mod save;. It does not go on the front door. JavaScript will not come in through lib.rs; it comes in through the glue.

Now read web.rs from the top.

use wasm_bindgen::prelude::*; brings in everything the crate expects us to use. A prelude is a crate's "you will want all of these" list. The * means all of it.

#[wasm_bindgen] is an attribute, like #[derive(...)] and #[test]: a note to the compiler, attached to the thing below it. This one says JavaScript should be able to see this.

WebGame is the adapter. It has one field, inner, holding the real Game. The field is private. JavaScript cannot see inside, and neither can anything outside this file.

js_name = Game on the struct, and js_class = Game on the impl block, say what the type is called on the JavaScript side. In Rust it is WebGame, so the two never collide. In the browser it is Game, because that is what it is.

#[wasm_bindgen(constructor)] marks new() as the thing new Game() runs in JavaScript.

click() and tick() are the smallest methods in the project. They hand the call to inner and that is all. That is what an adapter does. The rules stay on the far side.

Question: Why does WebGame hold a private Game instead of exporting every engine field?

1. Private fields make WebAssembly download faster
2. The adapter keeps JavaScript's interface small and leaves the rules in Rust
3. Rust structs cannot contain public fields

Answer: 2. The adapter keeps JavaScript's interface small and leaves the rules in Rust

Explanation: JavaScript gets a few operations chosen by the adapter. It cannot reach into the engine and start calculating a second version of a rule.

Build it:

cargo build

It compiles with nothing to say. On your own machine, cargo build still reads the attribute and checks that everything it marks could cross to JavaScript, which is about to matter. But it exports nothing. The result is a normal library, which is why cargo test keeps working, and we will lean on that before we are done.

Only some things can cross

buy_click_upgrade() is next. The engine's version returns a PurchaseOutcome. Try handing that straight across. Add this inside the impl WebGame block:

src/web.rs

    #[wasm_bindgen(js_name = buyClickUpgrade)]
    pub fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        self.inner.buy_click_upgrade()
    }

And add use crate::player::PurchaseOutcome; under the first use line.

The js_name attribute works on methods too. Rust calls it buy_click_upgrade, because that is how Rust names things. JavaScript calls it buyClickUpgrade, because that is how JavaScript names things. Each side gets its own convention and neither has to flinch.

Build, and Rust refuses, because this type is not allowed across:

error[E0277]: the trait bound `PurchaseOutcome: IntoWasmAbi` is not satisfied
  --> src/web.rs:10:1
   |
10 | #[wasm_bindgen(js_class = Game)]
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ unsatisfied trait bound
   |
help: the trait `IntoWasmAbi` is not implemented for `PurchaseOutcome`

(There are several of these, and one names a cousin trait, WasmDescribe. They all say the same thing: this type cannot cross.)

IntoWasmAbi is the trait for can be handed to JavaScript. Numbers have it. bool has it. String and &str have it, thanks to the glue. Types marked with #[wasm_bindgen] have it.

PurchaseOutcome does not, and we are not going to mark it, because it belongs to the engine.

So what crosses instead?

false is still not an answer. We settled that in the seventh article, and a border does not change it. What crosses is the name of the answer, as text:

src/web.rs

    #[wasm_bindgen(js_name = buyClickUpgrade)]
    pub fn buy_click_upgrade(&mut self) -> String {
        match self.inner.buy_click_upgrade() {
            PurchaseOutcome::Purchased => String::from("purchased"),
            PurchaseOutcome::NotEnoughGold => String::from("notEnoughGold"),
        }
    }

Replace the version you just wrote with this one.

The match is doing the translating. Rust's enum stays an enum. JavaScript gets a string it can compare against. If a third outcome ever appears, the match refuses to compile until it has a name too, which is the same protection we had before.

Question: What crosses into JavaScript when an upgrade cannot be bought?

1. The whole PurchaseOutcome enum definition
2. false
3. The string "notEnoughGold"

Answer: 3. The string "notEnoughGold"

Explanation: The adapter translates the Rust enum variant into text. The engine keeps the enum, including Rust's exhaustive match check.

Build, and it is quiet again.

A snapshot for the screen

If JavaScript ever computes click damage, there are two programs that know how, and one day they will disagree.

That is the rule this whole section protects.

The browser is going to draw a screen, and a screen needs numbers: the stage, the gold, how much a click does, what the next upgrade costs. Some of those are fields. Some are rules. We could hand JavaScript the fields and let it work out the rest, and that is exactly the thing it must never do.

So the adapter answers all of it at once, as one piece of JSON, and Rust does every bit of arithmetic before the text leaves.

Add this at the bottom of web.rs, after the impl WebGame block:

src/web.rs

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct Snapshot {
    stage: u32,
    gold: u32,
    xp: u32,
    xp_needed: u32,
    level: u32,
    click_damage: u32,
    click_upgrade_level: u32,
    click_upgrade_cost: u32,
    enemy_name: String,
    enemy_health: u32,
    enemy_max_health: u32,
}

impl Snapshot {
    fn of(game: &Game) -> Snapshot {
        Snapshot {
            stage: game.stage,
            gold: game.player.gold,
            xp: game.player.xp,
            xp_needed: game.player.xp_needed(),
            level: game.player.level,
            click_damage: game.player.click_damage(),
            click_upgrade_level: game.player.click_upgrade_level,
            click_upgrade_cost: game.player.click_upgrade_cost(),
            enemy_name: game.enemy.name.clone(),
            enemy_health: game.enemy.health,
            enemy_max_health: enemy_health_for_stage(game.stage),
        }
    }
}

And at the top of the file, two more use lines, under the one for PurchaseOutcome:

src/web.rs

use crate::rules::enemy_health_for_stage;
use serde::Serialize;

A Snapshot is a flat list of everything a screen might want, taken at one moment. It only needs Serialize, not Deserialize, because nobody ever reads a snapshot back in. It is a picture, not a save.

Three lines in of() deserve a look.

xp_needed, click_damage and click_upgrade_cost are not copied. They are asked for. Each one is a rule, applied in Rust, and only the answer goes in the picture.

enemy_max_health is the same idea. The enemy does not store its full health; the rule enemy_health_for_stage() knows it, and the stage is right there.

game.enemy.name.clone() is new. A String owns its text, and two things cannot own the same text at once. The enemy owns that name. The snapshot wants its own, so .clone() makes a second copy. (The u32 fields do not need this. A number is small enough that Rust copies it without asking.)

And the attribute above the struct:

src/web.rs

#[serde(rename_all = "camelCase")]

This is the article where JavaScript finally reads our JSON, so this is the article where the names change shape. Rust writes click_damage. JavaScript expects clickDamage. rename_all tells serde to convert every field name on the way out, and the Rust code stays the way Rust likes it.

The save is not getting this. JavaScript stores a save and hands it back; it never looks inside. Changing the save's field names would be a new save version for the benefit of nobody.

Two small things remain before it builds.

click_upgrade_cost() does not exist on Player yet. The cost has only ever been needed inside a purchase. Now a screen wants to show it. In src/player.rs, add a method under click_damage():

src/player.rs

    pub fn click_upgrade_cost(&self) -> u32 {
        click_upgrade_cost(self.click_upgrade_level)
    }

And since the player can answer that now, buy_click_upgrade() should ask instead of reaching for the rule. Change its first line from:

src/player.rs

        let cost = click_upgrade_cost(self.click_upgrade_level);

to:

src/player.rs

        let cost = self.click_upgrade_cost();

Then the method that hands the picture over. Back in web.rs, inside impl WebGame, under buy_click_upgrade():

src/web.rs

    #[wasm_bindgen(js_name = stateJson)]
    pub fn state_json(&self) -> String {
        let snapshot = Snapshot::of(&self.inner);

        serde_json::to_string(&snapshot).expect("a Snapshot can always be written as JSON")
    }

That expect() is the same promise save_json() makes, for the same reason: a struct of numbers and one string cannot fail to become JSON.

Question: Why does the snapshot contain clickDamage instead of making JavaScript calculate it?

1. JavaScript cannot add two numbers
2. Rust should remain the only place that knows the damage rule
3. JSON requires every number to be calculated twice

Answer: 2. Rust should remain the only place that knows the damage rule

Explanation: The screen receives the answer it needs. If JavaScript repeated the formula, the two versions could disagree after a later rule change.

Build. Quiet.

Saves cross too

Saving is already text, so it crosses as it is:

src/web.rs

    #[wasm_bindgen(js_name = saveJson)]
    pub fn save_json(&self) -> String {
        self.inner.save_json()
    }

Loading is the interesting one, because loading can fail, and now the failure has to cross a border.

Try the obvious thing first:

src/web.rs

    #[wasm_bindgen(js_name = fromJson)]
    pub fn from_json(json: &str) -> Result<WebGame, LoadError> {
        match Game::from_saved_json(json) {
            Ok(inner) => Ok(WebGame { inner }),
            Err(error) => Err(error),
        }
    }

Add use crate::save::LoadError; to the use lines, and build. Rust refuses again, and this time the complaint is about the error half:

error[E0277]: the trait bound `Result<WebGame, LoadError>: ReturnWasmAbi` is not satisfied
   --> src/web.rs:13:1
    |
 13 | #[wasm_bindgen(js_class = Game)]
    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `ReturnWasmAbi` is not implemented for `Result<WebGame, LoadError>`
    |
help: the trait `ReturnWasmAbi` is implemented for `Result<T, E>`
    |
779 | / impl<T, E> ReturnWasmAbi for Result<T, E>
780 | | where
781 | |     T: IntoWasmAbi,
782 | |     E: Into<JsValue>,

Same story as the purchase, with one new piece of information at the bottom.

A Result can cross, as long as both halves can. WebGame is fine. LoadError is not, and the help says what the error half needs to be: something that can become a JsValue, which is the crate's word for any JavaScript value.

A String can. So the adapter translates the error the same way it translated the purchase: into words.

src/web.rs

    #[wasm_bindgen(js_name = fromJson)]
    pub fn from_json(json: &str) -> Result<WebGame, String> {
        match Game::from_saved_json(json) {
            Ok(inner) => Ok(WebGame { inner }),
            Err(LoadError::Unreadable) => Err(String::from("That save could not be read.")),
            Err(LoadError::UnsupportedVersion(version)) => Err(format!(
                "That save is version {version}, and this game cannot read it."
            )),
        }
    }

main() prints a failed load with {error:?}, which shows the variant's name: Could not load the save: Unreadable. That is fine in a terminal only we read. A player deserves a sentence, so the adapter writes one for each way a load can fail.

format!() is println!()'s quieter sibling. Same curly braces, but instead of printing the result, it hands it back as a String.

What does JavaScript see when the Result is an Err? The glue throws it. On the other side, Game.fromJson(text) either returns a game or throws the message, and a try/catch catches it. We will use that next time, when there is a save to load.

Build. Quiet. Here is web.rs so far, for checking against. The Snapshot code at the bottom is unchanged:

src/web.rs

use crate::game::Game;
use crate::player::PurchaseOutcome;
use crate::rules::enemy_health_for_stage;
use crate::save::LoadError;
use serde::Serialize;
use wasm_bindgen::prelude::*;

#[wasm_bindgen(js_name = Game)]
pub struct WebGame {
    inner: Game,
}

#[wasm_bindgen(js_class = Game)]
impl WebGame {
    #[wasm_bindgen(constructor)]
    pub fn new() -> WebGame {
        WebGame { inner: Game::new() }
    }

    pub fn click(&mut self) {
        self.inner.click();
    }

    pub fn tick(&mut self, seconds: u32) {
        self.inner.tick(seconds);
    }

    #[wasm_bindgen(js_name = buyClickUpgrade)]
    pub fn buy_click_upgrade(&mut self) -> String {
        match self.inner.buy_click_upgrade() {
            PurchaseOutcome::Purchased => String::from("purchased"),
            PurchaseOutcome::NotEnoughGold => String::from("notEnoughGold"),
        }
    }

    #[wasm_bindgen(js_name = stateJson)]
    pub fn state_json(&self) -> String {
        let snapshot = Snapshot::of(&self.inner);

        serde_json::to_string(&snapshot).expect("a Snapshot can always be written as JSON")
    }

    #[wasm_bindgen(js_name = saveJson)]
    pub fn save_json(&self) -> String {
        self.inner.save_json()
    }

    #[wasm_bindgen(js_name = fromJson)]
    pub fn from_json(json: &str) -> Result<WebGame, String> {
        match Game::from_saved_json(json) {
            Ok(inner) => Ok(WebGame { inner }),
            Err(LoadError::Unreadable) => Err(String::from("That save could not be read.")),
            Err(LoadError::UnsupportedVersion(version)) => Err(format!(
                "That save is version {version}, and this game cannot read it."
            )),
        }
    }
}

Seven things JavaScript can do. That is the whole border.

Test it where you are

We have not compiled for WebAssembly yet, and we can already test the adapter, because on this machine it is ordinary Rust.

Add a tests module at the bottom of web.rs:

src/web.rs

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_new_game_reports_its_starting_state() {
        let game = WebGame::new();

        assert_eq!(
            game.state_json(),
            r#"{"stage":1,"gold":0,"xp":0,"xpNeeded":20,"level":1,"clickDamage":5,"clickUpgradeLevel":0,"clickUpgradeCost":10,"enemyName":"Training Slime","enemyHealth":20,"enemyMaxHealth":20}"#
        );
    }

    #[test]
    fn a_purchase_answers_in_words() {
        let mut game = WebGame::new();

        assert_eq!(game.buy_click_upgrade(), "notEnoughGold");

        game.tick(100);

        assert_eq!(game.buy_click_upgrade(), "purchased");
    }

    #[test]
    fn a_save_crosses_the_border_and_back() {
        let mut game = WebGame::new();
        game.tick(600);

        let save = game.save_json();
        let restored = WebGame::from_json(&save).expect("the save should load");

        assert_eq!(restored.state_json(), game.state_json());
    }

    #[test]
    fn nonsense_is_refused_at_the_border() {
        assert_eq!(
            WebGame::from_json("banana").err(),
            Some(String::from("That save could not be read."))
        );
    }
}

The first test is the one to read slowly. That is the exact text a browser will receive for a new game: every name in camelCase, every rule already applied. Click damage is 5 because level 1 hits for 5. The upgrade costs 10. The slime has 20 of 20.

The last test uses .err(), which turns a Result into an Option: Some(error) if it failed, None if it did not. We cannot assert_eq! on the whole Result, because WebGame has no PartialEq and does not need one. Comparing just the error half is enough.

Run them:

cargo test

Thirty-two. Thirty in the library, and the two outside tests.

If you see twenty-eight, the mod web; line is missing from lib.rs. Without it, the file is not part of the library at all, and nothing complains until much later, in the browser. Add the line and run the tests again.

Build for the browser

Now the other machine.

wasm-pack build --target web --out-dir web/pkg

--target web asks for glue that a plain web page can import, with no bundler and no Node. --out-dir web/pkg says where to put it.

The first run is slow. wasm-pack fetches the wasm-bindgen command-line program to match the crate version in Cargo.lock, compiles the library for wasm32-unknown-unknown in release mode, runs the glue generator, and shrinks the result. After that it is a few seconds.

When it finishes, the last lines look like this:

[INFO]: Optimizing wasm binaries with `wasm-opt`...
[INFO]: Optional fields missing from Cargo.toml: 'description', 'repository', and 'license'. These are not necessary, but recommended
[INFO]: :-) Done in 24.46s
[INFO]: :-) Your wasm pkg is ready to publish at /home/you/rustbound-idle/web/pkg.

Your time and path will differ, and the note about optional fields is safe to ignore. Look in the folder:

web/pkg/
├── .gitignore
├── package.json
├── rustbound_idle.d.ts
├── rustbound_idle.js
├── rustbound_idle_bg.wasm
└── rustbound_idle_bg.wasm.d.ts

rustbound_idle_bg.wasm is the compiled game, about 110 KB. (We will look at that number again when it is time to ship.) rustbound_idle.js is the glue: the JavaScript that loads the .wasm file and wraps every marked method so that strings go in and out as strings. package.json describes the folder to JavaScript tooling we are not using.

The two .d.ts files are the ones to open. They are written for TypeScript, a version of JavaScript with types, but you do not need to know TypeScript to read this; it is a list of everything JavaScript can call, and it is the clearest summary of what we just built. The Game class is near the top of rustbound_idle.d.ts; everything below it is glue you can ignore:

web/pkg/rustbound_idle.d.ts

export class Game {
    free(): void;
    [Symbol.dispose](): void;
    buyClickUpgrade(): string;
    click(): void;
    static fromJson(json: string): Game;
    constructor();
    saveJson(): string;
    stateJson(): string;
    tick(seconds: number): void;
}

Every js_name we chose is in there. fromJson is static, because it makes a Game rather than being called on one, which is the same reason from_saved_json() was an associated function.

free() and [Symbol.dispose] are the two we did not write. A Game on the Rust side lives in WebAssembly's memory, and JavaScript's garbage collector cannot see in there. free() is how JavaScript gives a game back when it is done with it, and the other is a newer spelling of the same thing. We will not need either today.

The .gitignore inside pkg/ contains a single *. The whole folder is generated, like target/, and it stays out of version control.

If instead you see this:

Error: crate-type must be cdylib to compile to WebAssembly. Add the following to your Cargo.toml file:

[lib]
crate-type = ["cdylib", "rlib"]

then the [lib] section did not make it into Cargo.toml. Add it and run the build again.

And if the build succeeds but the .d.ts file has no Game class in it, mod web; is missing from lib.rs. The page will later complain that the module "does not provide an export named 'Game'", which is the same problem seen from the other side.

A page that runs the engine

Create web/index.html, next to the pkg folder:

web/index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Rustbound Idle</title>
  </head>
  <body>
    <h1>Rustbound Idle</h1>
    <pre id="output">Loading the engine...</pre>

    <script type="module">
      import init, { Game } from "./pkg/rustbound_idle.js";

      await init();

      const game = new Game();
      const before = JSON.parse(game.stateJson());

      game.tick(3600);

      const after = JSON.parse(game.stateJson());

      document.querySelector("#output").textContent =
        `One hour away.\nStage ${before.stage} -> ${after.stage}  ` +
        `Level ${before.level} -> ${after.level}  ` +
        `Gold ${before.gold} -> ${after.gold}`;
    </script>
  </body>
</html>

The script is the whole point, so read it line by line.

import init, { Game } from "./pkg/rustbound_idle.js"; brings in two things from the glue. Game is our class. init is a function that fetches rustbound_idle_bg.wasm and loads it into the browser.

await init(); does that loading. It is the one step that takes time, which is why the page says "Loading the engine..." until it is done. (If you have been told await only works inside an async function: at the top of a <script type="module"> it is allowed. That is one of the things type="module" buys us.)

new Game() runs our constructor. game.stateJson() runs our snapshot. game.tick(3600) runs the same loop that has run in every test since the eighth article.

JSON.parse() turns our text into a JavaScript object, so before.stage and before.gold just work. The names are camelCase, and that is rename_all paying off.

The sandbox below exercises only that browser-side handoff. It does not pretend to compile or load the generated .wasm package. Run it once, then change the three values in after and run it again. The sentence should follow the snapshot without learning a single game rule.

HTML

<h2>Rustbound Idle</h2>
<pre id="output">Waiting for a snapshot...</pre>

JavaScript

const snapshotText = '{"stage":1,"gold":0,"xp":0,"xpNeeded":20,"level":1,"clickDamage":5,"clickUpgradeLevel":0,"clickUpgradeCost":10,"enemyName":"Training Slime","enemyHealth":20,"enemyMaxHealth":20}';

const before = JSON.parse(snapshotText);
const after = {
  ...before,
  stage: 128,
  level: 47,
  gold: 16637,
};

document.querySelector("#output").textContent =
  `One hour away.\nStage ${before.stage} -> ${after.stage}  ` +
  `Level ${before.level} -> ${after.level}  ` +
  `Gold ${before.gold} -> ${after.gold}`;

Live example · render the Rust snapshot on the canonical article.

Then the last lines print the same sentence main() prints. Everything else on the page is scaffolding.

Now serve it. A browser will not load a module or a .wasm file from a plain file on disk; both have to come from a web server, even a trivial one. Python ships with a trivial one:

python3 -m http.server 8080 --directory web

(On Windows the command is usually python rather than python3.)

Open http://localhost:8080/ in a browser.

Rustbound Idle

One hour away.
Stage 1 -> 128  Level 1 -> 47  Gold 0 -> 16637

Stage 128. Level 47.

Those are the numbers in tests/idle_hour.rs, and they have been since the ninth article. The test runs on your machine, in Rust. The page runs in a browser, in WebAssembly, called from JavaScript. Same library. Same answer.

If you open index.html directly instead, by double-clicking it, the page stays on "Loading the engine..." and the browser console says something like:

Access to script at 'file:///.../web/pkg/rustbound_idle.js' from origin 'null'
has been blocked by CORS policy: Cross origin requests are only supported for
protocol schemes: chrome, chrome-untrusted, data, http, https.

That is the browser refusing to load modules from file://. It is not a bug in our code. Use the server.

One habit to pick up now: after you change the Rust and rebuild, browsers like to keep serving the old .wasm file. If a number on the page does not change when you expected it to, do a hard refresh (Ctrl+Shift+R, or Cmd+Shift+R on a Mac) before you go looking for a bug.

One more thing to notice: cargo run still works. Try it. The terminal version prints its three stages and its hour, exactly as before. We did not replace a program. We gave the same library a second door.

The complete program

If you are only reading along, skip to the last two sections.

If you have been following along, here is everything that changed. src/rules.rs, src/enemy.rs, src/game.rs, src/save.rs, src/main.rs, and the two files in tests/ are exactly as they were in the starting point.

The project now looks like this:

rustbound-idle/
├── Cargo.toml
├── Cargo.lock
├── src/
│   ├── lib.rs
│   ├── main.rs
│   ├── rules.rs
│   ├── enemy.rs
│   ├── player.rs
│   ├── game.rs
│   ├── save.rs
│   └── web.rs
├── tests/
│   ├── idle_hour.rs
│   └── save_and_restore.rs
└── web/
    ├── index.html
    └── pkg/            (generated by wasm-pack)

Cargo.toml:

Cargo.toml

[package]
name = "rustbound-idle"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["cdylib", "rlib"]

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
wasm-bindgen = "0.2"

src/lib.rs:

src/lib.rs

mod enemy;
mod game;
mod player;
mod rules;
mod save;
mod web;

pub use enemy::Enemy;
pub use game::Game;
pub use player::{Player, PurchaseOutcome};
pub use save::LoadError;

Only the impl block in src/player.rs changes; the struct, the enum, and the tests are as they were.

impl Player {
    pub(crate) fn new() -> Player {
        Player {
            gold: 0,
            xp: 0,
            level: 1,
            click_upgrade_level: 0,
        }
    }

pub(crate) fn add_gold(&mut self, amount: u32) {
    self.gold = self.gold.saturating_add(amount);
}

pub(crate) fn add_xp(&mut self, amount: u32) {
    self.xp = self.xp.saturating_add(amount);

    while self.xp >= self.xp_needed() {
        self.xp -= self.xp_needed();
        self.level = self.level.saturating_add(1);
    }
}

pub fn xp_needed(&self) -> u32 {
    xp_to_next_level(self.level)
}

pub fn click_damage(&self) -> u32 {
    click_damage(self.base_damage(), self.bonus_damage())
}

pub fn click_upgrade_cost(&self) -> u32 {
    click_upgrade_cost(self.click_upgrade_level)
}

fn base_damage(&self) -> u32 {
    base_damage_for_level(self.level)
}

fn bonus_damage(&self) -> u32 {
    click_upgrade_bonus(self.click_upgrade_level)
}

pub(crate) fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
    let cost = self.click_upgrade_cost();

    if self.gold < cost {
        return PurchaseOutcome::NotEnoughGold;
    }

    self.gold -= cost;
    self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);

    PurchaseOutcome::Purchased
}

}

use crate::game::Game;
use crate::player::PurchaseOutcome;
use crate::rules::enemy_health_for_stage;
use crate::save::LoadError;
use serde::Serialize;
use wasm_bindgen::prelude::*;

#[wasm_bindgen(js_name = Game)]
pub struct WebGame {
    inner: Game,
}
#[wasm_bindgen(js_class = Game)]
impl WebGame {
    #[wasm_bindgen(constructor)]
    pub fn new() -> WebGame {
        WebGame { inner: Game::new() }
    }
pub fn click(&mut self) {
    self.inner.click();
}

pub fn tick(&mut self, seconds: u32) {
    self.inner.tick(seconds);
}

#[wasm_bindgen(js_name = buyClickUpgrade)]
pub fn buy_click_upgrade(&mut self) -> String {
    match self.inner.buy_click_upgrade() {
        PurchaseOutcome::Purchased => String::from("purchased"),
        PurchaseOutcome::NotEnoughGold => String::from("notEnoughGold"),
    }
}

#[wasm_bindgen(js_name = stateJson)]
pub fn state_json(&self) -> String {
    let snapshot = Snapshot::of(&self.inner);

    serde_json::to_string(&snapshot).expect("a Snapshot can always be written as JSON")
}

#[wasm_bindgen(js_name = saveJson)]
pub fn save_json(&self) -> String {
    self.inner.save_json()
}

#[wasm_bindgen(js_name = fromJson)]
pub fn from_json(json: &str) -> Result<WebGame, String> {
    match Game::from_saved_json(json) {
        Ok(inner) => Ok(WebGame { inner }),
        Err(LoadError::Unreadable) => Err(String::from("That save could not be read.")),
        Err(LoadError::UnsupportedVersion(version)) => Err(format!(
            "That save is version {version}, and this game cannot read it."
        )),
    }
}

}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct Snapshot {
    stage: u32,
    gold: u32,
    xp: u32,
    xp_needed: u32,
    level: u32,
    click_damage: u32,
    click_upgrade_level: u32,
    click_upgrade_cost: u32,
    enemy_name: String,
    enemy_health: u32,
    enemy_max_health: u32,
}
impl Snapshot {
    fn of(game: &Game) -> Snapshot {
        Snapshot {
            stage: game.stage,
            gold: game.player.gold,
            xp: game.player.xp,
            xp_needed: game.player.xp_needed(),
            level: game.player.level,
            click_damage: game.player.click_damage(),
            click_upgrade_level: game.player.click_upgrade_level,
            click_upgrade_cost: game.player.click_upgrade_cost(),
            enemy_name: game.enemy.name.clone(),
            enemy_health: game.enemy.health,
            enemy_max_health: enemy_health_for_stage(game.stage),
        }
    }
}
#[cfg(test)]
mod tests {
    use super::*;
#[test]
fn a_new_game_reports_its_starting_state() {
    let game = WebGame::new();

    assert_eq!(
        game.state_json(),
        r#"{"stage":1,"gold":0,"xp":0,"xpNeeded":20,"level":1,"clickDamage":5,"clickUpgradeLevel":0,"clickUpgradeCost":10,"enemyName":"Training Slime","enemyHealth":20,"enemyMaxHealth":20}"#
    );
}

#[test]
fn a_purchase_answers_in_words() {
    let mut game = WebGame::new();

    assert_eq!(game.buy_click_upgrade(), "notEnoughGold");

    game.tick(100);

    assert_eq!(game.buy_click_upgrade(), "purchased");
}

#[test]
fn a_save_crosses_the_border_and_back() {
    let mut game = WebGame::new();
    game.tick(600);

    let save = game.save_json();
    let restored = WebGame::from_json(&save).expect("the save should load");

    assert_eq!(restored.state_json(), game.state_json());
}

#[test]
fn nonsense_is_refused_at_the_border() {
    assert_eq!(
        WebGame::from_json("banana").err(),
        Some(String::from("That save could not be read."))
    );
}

}

  
    
    Rustbound Idle
  
  
    
Rustbound Idle
    
Loading the engine...

<script type="module">
  import init, { Game } from "./pkg/rustbound_idle.js";

  await init();

  const game = new Game();
  const before = JSON.parse(game.stateJson());

  game.tick(3600);

  const after = JSON.parse(game.stateJson());

  document.querySelector("#output").textContent =
    `One hour away.\nStage ${before.stage} -> ${after.stage}  ` +
    `Level ${before.level} -> ${after.level}  ` +
    `Gold ${before.gold} -> ${after.gold}`;
</script>

  

You do not need to add web/pkg to your own .gitignore. The one wasm-pack wrote inside it already keeps the folder out.

Run all three:

cargo test
wasm-pack build --target web --out-dir web/pkg
python3 -m http.server 8080 --directory web

Thirty-two tests pass, the package builds, and the page at http://localhost:8080/ shows the hour away. Clippy should be quiet.

What we learned

Along the way, we encountered:

• compile targets, and wasm32-unknown-unknown
• what WebAssembly can and cannot do on its own
• wasm-bindgen and wasm-pack
• cargo install
• [lib] crate-type, and the difference between rlib and cdylib
• #[wasm_bindgen], js_name, js_class, and constructor
• a prelude, and use ...::*
• an adapter that holds the engine instead of exposing it
• which types can cross a language border, and translating the ones that cannot
• a snapshot that applies every rule before the text leaves Rust
• #[serde(rename_all = "camelCase")]
• .clone() for a String
• format!()
• a Result crossing into JavaScript as a return or a throw
• .err() on a Result
• testing a WebAssembly adapter as plain Rust
• ES modules, import, await init(), and why file:// will not do

You do not need to memorize all of that yet.

Two ideas are worth keeping.

The first is that the border is a translation, not a window. Nothing on the far side can see Game. It sees seven operations, each of which hands numbers or text across, and every rule has already been applied by the time the text leaves. The match in buy_click_upgrade() and the match in from_json() are the only places the two worlds touch, and both of them turn a Rust enum into words.

The second is that the hard part was already done. This article added one file to the library, one line to lib.rs, a four-line method to player.rs, and four lines of configuration. Everything else was two articles ago, when we decided main() should not know any formulas, and last time, when we decided a save should be text. A library that never printed, never asked the time, and never opened a file turned out to be a library that compiles for a machine with none of those things.

That is what the wall was for.

Something to click

Our engine runs in a browser now. Nobody can play it.

There is no button. There is no screen. There is a <pre> tag and a number.

Next time, we put a face on it: one custom HTML element, <idle-game>, that draws the snapshot, turns a click on a button into game.click(), keeps the clock, and saves to the browser's storage so that closing the tab is not game over either.

The browser will own time and storage and pixels.

It still will not get the rules.

Small function. Bigger game.

It cannot survive the program ending.

Close the terminal and everything is gone: the stages, the gold, the levels, the upgrade you bought. The next cargo run starts at stage 1 with a fresh slime, as if nothing ever happened.

An idle game that forgets you the moment you leave is not much of an idle game.

I learned what lost progress feels like on a 386, building DOOM maps. It crashed in the middle of one and took an entire afternoon of carefully placed monsters and secret rooms with it. Nothing has taught me to save my work quite like that afternoon.

Our game deserves better than my DOOM maps got.

Today the game learns to write itself down, and to read itself back.

Not to a file, or a browser, or a server. The library will not know where saves go, and it should not. It will only know how to say, in text:

This is everything about me.

And, handed that same text later:

I remember.

By the end, main() clears three stages, saves, throws the game away, loads the save, and then spends the hour away:

Saved: {"save_version":1,"stage":4,"player":{"gold":11,"xp":4,"level":2,"click_upgrade_level":1},"enemy_health":50}
Loaded. Stage 4, level 2.
One hour away.
Stage 4 -> 131  Level 2 -> 48  Gold 11 -> 17410

Same hour. Same numbers. A different game object, rebuilt from a line of text.

Saving always works. Loading might not: the text could be anything. So Rust hands the loaded game back in a box that holds one of two things, the game or the reason there is no game, and will not let us reach for the game until we have said what happens if it is the other one.

Along the way we add our first dependency, and that box turns out to be how Rust handles everything that can fail. There are five quick knowledge checks, two live examples you can edit and run in the page, and a coding challenge.

Our starting point

This series builds a small idle game: a player clicks to fight slimes, earns gold and XP, and keeps progressing while you are away.

If you are only reading along, skip ahead to "A save is just text." The code is folded away below, one file at a time.

If you are building along, you need the library we built last time: a project called rustbound-idle with six source files and one outside test. (If you kept your project from the last article, you already have all of this. The article_9 branch of the companion repository has it too.)

rustbound-idle/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── main.rs
│   ├── rules.rs
│   ├── enemy.rs
│   ├── player.rs
│   └── game.rs
└── tests/
    └── idle_hour.rs

Cargo.toml is whatever cargo new rustbound-idle gave you. It should say edition = "2024", which needs Rust 1.85 or newer.

mod enemy;
mod game;
mod player;
mod rules;

pub use enemy::Enemy;
pub use game::Game;
pub use player::{Player, PurchaseOutcome};

use rustbound_idle::{Game, PurchaseOutcome};

fn main() {
    let mut game = Game::new();

    while game.stage <= 3 {
        let stage = game.stage;
        let level = game.player.level;

        game.click();

        if game.stage > stage {
            println!(
                "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
                game.player.gold,
                game.player.xp,
                game.player.xp_needed()
            );

            if game.player.level > level {
                println!(
                    "Level up! Now level {}. Click damage: {}",
                    game.player.level,
                    game.player.click_damage()
                );
            }

            println!(
                "  Next up: {} with {} health.",
                game.enemy.name, game.enemy.health
            );
        }

        match game.buy_click_upgrade() {
            PurchaseOutcome::Purchased => println!(
                "Bought click upgrade {}! Click damage: {}  Gold left: {}",
                game.player.click_upgrade_level,
                game.player.click_damage(),
                game.player.gold
            ),
            PurchaseOutcome::NotEnoughGold => {}
        }
    }

    let stage = game.stage;
    let level = game.player.level;
    let gold = game.player.gold;

    game.tick(3600);

    println!("One hour away.");
    println!(
        "Stage {} -> {}  Level {} -> {}  Gold {} -> {}",
        stage, game.stage, level, game.player.level, gold, game.player.gold
    );
}

pub(crate) fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

pub(crate) fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}

pub(crate) fn is_defeated(health: u32) -> bool {
    health == 0
}

pub(crate) fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

pub(crate) fn gold_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(3)
}

pub(crate) fn xp_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(4)
}

pub(crate) fn xp_to_next_level(level: u32) -> u32 {
    level
        .saturating_sub(1)
        .saturating_mul(15)
        .saturating_add(20)
}

pub(crate) fn base_damage_for_level(level: u32) -> u32 {
    level.saturating_add(4)
}

pub(crate) fn idle_damage_for_level(level: u32) -> u32 {
    level
}

pub(crate) fn click_upgrade_bonus(upgrades: u32) -> u32 {
    upgrades.saturating_mul(2)
}

pub(crate) fn click_upgrade_cost(upgrades: u32) -> u32 {
    upgrades.saturating_add(1).saturating_mul(10)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn later_stages_have_tougher_enemies() {
        assert_eq!(enemy_health_for_stage(1), 20);
        assert_eq!(enemy_health_for_stage(2), 30);
    }

    #[test]
    fn later_stages_pay_better() {
        assert_eq!(gold_reward_for_stage(1), 5);
        assert_eq!(gold_reward_for_stage(2), 7);
        assert_eq!(xp_reward_for_stage(1), 6);
        assert_eq!(xp_reward_for_stage(2), 8);
    }

    #[test]
    fn levels_need_more_xp_as_they_go() {
        assert_eq!(xp_to_next_level(1), 20);
        assert_eq!(xp_to_next_level(2), 35);
    }

    #[test]
    fn levels_make_the_player_hit_harder() {
        assert_eq!(base_damage_for_level(1), 5);
        assert_eq!(base_damage_for_level(2), 6);
    }

    #[test]
    fn idle_damage_grows_with_level() {
        assert_eq!(idle_damage_for_level(1), 1);
        assert_eq!(idle_damage_for_level(2), 2);
    }

    #[test]
    fn upgrades_cost_more_each_time() {
        assert_eq!(click_upgrade_cost(0), 10);
        assert_eq!(click_upgrade_cost(1), 20);
    }
}

use crate::rules::{enemy_health_for_stage, gold_reward_for_stage, xp_reward_for_stage};

pub struct Enemy {
    pub name: String,
    pub health: u32,
    pub(crate) gold_reward: u32,
    pub(crate) xp_reward: u32,
}

impl Enemy {
    pub(crate) fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
            xp_reward: xp_reward_for_stage(stage),
        }
    }
}

use crate::rules::{
    base_damage_for_level, click_damage, click_upgrade_bonus, click_upgrade_cost, xp_to_next_level,
};

pub struct Player {
    pub gold: u32,
    pub xp: u32,
    pub level: u32,
    pub click_upgrade_level: u32,
}

#[derive(Debug, PartialEq)]
pub enum PurchaseOutcome {
    Purchased,
    NotEnoughGold,
}

impl Player {
    pub(crate) fn new() -> Player {
        Player {
            gold: 0,
            xp: 0,
            level: 1,
            click_upgrade_level: 0,
        }
    }

    pub(crate) fn add_gold(&mut self, amount: u32) {
        self.gold = self.gold.saturating_add(amount);
    }

    pub(crate) fn add_xp(&mut self, amount: u32) {
        self.xp = self.xp.saturating_add(amount);

        while self.xp >= self.xp_needed() {
            self.xp -= self.xp_needed();
            self.level = self.level.saturating_add(1);
        }
    }

    pub fn xp_needed(&self) -> u32 {
        xp_to_next_level(self.level)
    }

    pub fn click_damage(&self) -> u32 {
        click_damage(self.base_damage(), self.bonus_damage())
    }

    fn base_damage(&self) -> u32 {
        base_damage_for_level(self.level)
    }

    fn bonus_damage(&self) -> u32 {
        click_upgrade_bonus(self.click_upgrade_level)
    }

    pub(crate) fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        let cost = click_upgrade_cost(self.click_upgrade_level);

        if self.gold < cost {
            return PurchaseOutcome::NotEnoughGold;
        }

        self.gold -= cost;
        self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);

        PurchaseOutcome::Purchased
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn leveling_up_keeps_leftover_xp() {
        let mut player = Player::new();

        player.add_xp(25);

        assert_eq!(player.level, 2);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn a_big_reward_can_skip_levels() {
        let mut player = Player::new();

        player.add_xp(60);

        assert_eq!(player.level, 3);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn buying_an_upgrade_needs_gold() {
        let mut player = Player::new();

        assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::NotEnoughGold);
        assert_eq!(player.click_upgrade_level, 0);
        assert_eq!(player.bonus_damage(), 0);
    }

    #[test]
    fn buying_an_upgrade_spends_gold() {
        let mut player = Player::new();
        player.gold = 12;

        assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::Purchased);
        assert_eq!(player.gold, 2);
        assert_eq!(player.click_upgrade_level, 1);
        assert_eq!(player.bonus_damage(), 2);
    }
}

use crate::enemy::Enemy;
use crate::player::{Player, PurchaseOutcome};
use crate::rules::{health_after_hit, idle_damage_for_level, is_defeated};

pub struct Game {
    pub stage: u32,
    pub player: Player,
    pub enemy: Enemy,
}

impl Game {
    pub fn new() -> Game {
        Game {
            stage: 1,
            player: Player::new(),
            enemy: Enemy::for_stage(1),
        }
    }

    pub fn click(&mut self) {
        attack(&self.player, &mut self.enemy);
        self.resolve_hit();
    }

    pub fn tick(&mut self, seconds: u32) {
        for _ in 0..seconds {
            let damage = idle_damage_for_level(self.player.level);

            self.enemy.health = health_after_hit(self.enemy.health, damage);
            self.resolve_hit();
        }
    }

    fn resolve_hit(&mut self) {
        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

    fn defeat_enemy(&mut self) {
        self.player.add_gold(self.enemy.gold_reward);
        self.player.add_xp(self.enemy.xp_reward);

        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }

    pub fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        self.player.buy_click_upgrade()
    }
}

impl Default for Game {
    fn default() -> Game {
        Game::new()
    }
}

fn attack(player: &Player, enemy: &mut Enemy) {
    enemy.health = health_after_hit(enemy.health, player.click_damage());
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player::new();

        let mut enemy = Enemy::for_stage(1);
        enemy.health = 10;

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 5);
    }

    #[test]
    fn a_new_game_starts_at_stage_one() {
        let game = Game::new();

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
        assert_eq!(game.player.gold, 0);
    }

    #[test]
    fn clicking_damages_the_enemy() {
        let mut game = Game::new();

        game.click();

        assert_eq!(game.enemy.health, 15);
    }

    #[test]
    fn defeating_an_enemy_pays_the_player() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }

    #[test]
    fn one_second_is_one_idle_hit() {
        let mut game = Game::new();

        game.tick(1);

        assert_eq!(game.enemy.health, 19);
    }

    #[test]
    fn zero_seconds_changes_nothing() {
        let mut game = Game::new();

        game.tick(0);

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
    }

    #[test]
    fn enough_time_defeats_the_enemy() {
        let mut game = Game::new();

        game.tick(20);

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }

    #[test]
    fn one_long_tick_matches_many_short_ones() {
        let mut long = Game::new();
        let mut short = Game::new();

        long.tick(45);

        for _ in 0..45 {
            short.tick(1);
        }

        assert_eq!(long.stage, short.stage);
        assert_eq!(long.enemy.health, short.enemy.health);
        assert_eq!(long.player.gold, short.player.gold);
        assert_eq!(long.player.xp, short.player.xp);
        assert_eq!(long.player.level, short.player.level);
    }
}

use rustbound_idle::Game;

#[test]
fn an_hour_away_moves_the_game_forward() {
    let mut game = Game::new();

    game.tick(3600);

    assert_eq!(game.stage, 128);
    assert_eq!(game.player.level, 47);
}

Run cargo test, and twenty-two tests pass: twenty-one inside the library and one in tests/idle_hour.rs. Run cargo run, and the player clears three stages, buys an upgrade, and spends an hour away.

Hold on to twenty-two. Today we add six.

A save is just text

What is a save, exactly?

Strip away the menus and the little floppy-disk icon, and a save is a description of the game, written down somewhere that outlives the program.

That icon was a real object once. Our house had hundreds of them, the 5.25-inch kind that actually flopped, full of games and programs. They are probably still boxed up somewhere at my parents' house. The idea outlived them.

For our game, "the game" is one Game value: a stage, a player, and the slime they are fighting. Write those numbers down and you have a save. Read them back into a Game and you have loaded it.

So the question for today is: write them down how?

We could invent a format. One number per line, in a fixed order, and a parser that reads them back:

4
11
4
2
1
50

It would work, until the day we add a field in the middle and every old save quietly reads the wrong number into the wrong slot. Nothing crashes. The player just loads in with fifty gold and an upgrade level of eleven.

There is a better answer, and most programs that save anything already use it.

JSON is a plain-text format for describing values with names. Here is a brand-new game, written as JSON:

{
  "save_version": 1,
  "stage": 1,
  "player": {
    "gold": 0,
    "xp": 0,
    "level": 1,
    "click_upgrade_level": 0
  },
  "enemy_health": 20
}

Every value has a name, and values can nest: player is a group of four values inside the bigger one.

Notice that this is not a copy of every field in Game. There is no enemy name and no reward. It is the minimum we need to rebuild the same game: the stage, the player's progress, and how much health the current slime has left.

That last one matters more than it looks. Growing up, my brothers and I often played Super Nintendo games on an emulator instead of the console, and a big reason was being able to save anywhere. enemy_health is our version of that. We can save in the middle of a fight, and the slime will still be wounded when we come back.

The save_version line looks like it does nothing yet. It is there for a future version of us, and we will come back to it.

Question: Why save the game as named JSON values instead of one number per line?

1. JSON files are always smaller
2. Every value carries its name, so a new or reordered field cannot slide into the wrong slot
3. Rust cannot read a file of plain numbers

Answer: 2. Every value carries its name, so a new or reordered field cannot slide into the wrong slot

Explanation: A fixed order is a promise that nothing will ever change. Names let the loader find gold wherever it is.

We are not going to write the JSON writer and reader by hand. Someone already has, and it is very good.

The first dependency

Until now, every line of this game has been ours. Today we borrow some.

Rust code that other people share is published as crates, and most of them live on crates.io. A crate your project uses is called a dependency. We are adding two:

• serde knows how to take a Rust value apart into named pieces, and put it back together. The name is short for serialize and deserialize, which are the formal words for writing a value down and reading it back.
• serde_json knows how to write those pieces as JSON, and read JSON back into pieces.

Open Cargo.toml. The [dependencies] section has been empty since the first article. Fill it in:

Cargo.toml

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"

"1" means any version 1.x. Cargo picks the newest 1.x it can find, and never jumps to a 2.0 on its own.

The features = ["derive"] part matters, and we will see why in a moment.

Build it:

cargo build

The first time, Cargo downloads the two crates and the handful of smaller ones they depend on, and compiles all of them. You will see a dozen Compiling lines you did not write, and then your own:

   Compiling serde v1.0.229
   Compiling serde_json v1.0.154
   Compiling serde_derive v1.0.229
   ...
   Compiling rustbound-idle v0.1.0

Your version numbers may be newer. That is fine.

That only happens once. Cargo keeps the compiled crates around, and later builds are as fast as before.

Look in your project folder and you will find a new file, Cargo.lock. Cargo wrote it. It records the exact versions that got picked, so that anyone who builds this project later gets the same ones. Leave it alone, and if you use Git, commit it.

Give the save its own shape

serde can turn Rust values into text and back again, but there is a choice to make first.

We could teach serde about Game, Player, and Enemy directly.

That would work.

It would also make our runtime structs the permanent shape of our save files.

Those are not the same job.

A Game is whatever the engine needs while it is running.

A save is the minimum information needed to rebuild that game later.

The difference matters because some values can be recalculated from the rules. An enemy's gold and XP rewards come from its stage. If we saved those numbers, a save made today would carry today's rewards into next month's version of the game, even after we rebalanced them.

So the save gets its own small types.

Create src/save.rs:

src/save.rs

use serde::{Deserialize, Serialize};

const SAVE_VERSION: u32 = 1;

#[derive(Serialize, Deserialize)]
struct PlayerSave {
    gold: u32,
    xp: u32,
    level: u32,
    click_upgrade_level: u32,
}

#[derive(Serialize, Deserialize)]
struct SaveData {
    save_version: u32,
    stage: u32,
    player: PlayerSave,
    enemy_health: u32,
}

The two structs are the JSON from before, written as Rust. Same names, same nesting.

const declares a constant: a value fixed when the program is compiled, which can never change while it runs. Constants are written in capitals by convention, and they need their type spelled out. SAVE_VERSION is the version of the save format this code writes.

The interesting line is the one above each struct.

Asking for a trait

In plain terms, that line tells Rust: these two structs can be written down, and read back.

#[derive(Serialize, Deserialize)] is the same kind of line as the #[derive(Debug, PartialEq)] we put on PurchaseOutcome.

Serialize and Deserialize are traits. A trait is a named ability a type can have. PartialEq is the ability to be compared with ==. Serialize is the ability to be taken apart into named pieces. Deserialize is the ability to be built back up from them.

derive asks the compiler to write that ability for us, by looking at the fields. We could write it by hand. Nobody wants to. The thing that does the writing is called a derive macro; a macro is code that writes code.

That is also what features = ["derive"] was for. Without it, serde gives us the traits but not the code that derives them, and the build stops on every struct:

error: cannot find derive macro `Serialize` in this scope
  --> src\save.rs:5:10
   |
 5 | #[derive(Serialize, Deserialize)]
   |          ^^^^^^^^^
   |
note: `Serialize` is imported here, but it is only a trait, without a derive macro

Only a trait, without a derive macro. The ability exists; the machine that writes it for us was left out.

Last, the library has to know the new file exists. Add mod save; to src/lib.rs:

src/lib.rs

mod enemy;
mod game;
mod player;
mod rules;
mod save;

pub use enemy::Enemy;
pub use game::Game;
pub use player::{Player, PurchaseOutcome};

If you build now, Cargo warns that SAVE_VERSION, PlayerSave, and SaveData are never used. Fair. The next section uses them.

Question: Why does the save store the stage but not the enemy's gold_reward?

1. gold_reward is pub(crate), so serde cannot see it
2. JSON cannot hold more than six numbers
3. The reward can be rebuilt from the stage, so an old save cannot carry old balance rules into a newer game

Answer: 3. The reward can be rebuilt from the stage, so an old save cannot carry old balance rules into a newer game

Explanation: Save what only the player could have done. Rebuild everything else from the current rules.

Writing it down

Saving is the easy direction. Every Game can be described, so save_json() always gets an answer.

Add an impl Game block to src/save.rs, below the structs. It is a second impl block for Game, in a different file from the first, and Rust is fine with that: an impl block can live anywhere in the crate that owns the type.

First, one more import at the top of the file, beside the serde one:

src/save.rs

use crate::game::Game;

Then the block itself:

src/save.rs

impl Game {
    pub fn save_json(&self) -> String {
        let save = SaveData {
            save_version: SAVE_VERSION,
            stage: self.stage,
            player: PlayerSave {
                gold: self.player.gold,
                xp: self.player.xp,
                level: self.player.level,
                click_upgrade_level: self.player.click_upgrade_level,
            },
            enemy_health: self.enemy.health,
        };

        serde_json::to_string(&save).expect("a save made of numbers should always serialize")
    }
}

The method copies the numbers that matter out of the running game into a SaveData, and hands it to serde_json::to_string.

That last line has a word we have not seen.

serde_json::to_string does not hand back a String. It hands back a Result: either Ok, holding the text, or Err, holding what went wrong. It has to, because some Rust values cannot be written as JSON at all.

Ours can. A struct full of numbers always can. So we call .expect(), which says:

Give me what is inside the Ok. If it is somehow an Err, stop the program with this message.

expect() is for the cases where failure would mean a bug in our own code, not bad luck. We will meet a case that is pure bad luck in a moment, and there we will not use it.

Now a test that pins the format down. Add it to the bottom of src/save.rs:

src/save.rs

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_new_game_saves_its_starting_numbers() {
        let json = Game::new().save_json();

        assert_eq!(
            json,
            r#"{"save_version":1,"stage":1,"player":{"gold":0,"xp":0,"level":1,"click_upgrade_level":0},"enemy_health":20}"#
        );
    }
}

That string starts with r#" and ends with "#. It is a raw string. JSON is full of double quotes, and in a normal string every one of them would need a backslash in front of it. In a raw string, a " is just a character, and only "# ends it.

serde_json::to_string writes everything on one line with no spaces, which is why the expected text is one long line.

cargo test

Twenty-three tests pass.

Reading it back

Loading is the hard direction.

Saving starts from a Game, which is always valid. Loading starts from text, and text can be anything. A save from an older version. A half-written file. Somebody's grocery list.

So what should a load function return when the text is not a save?

A Game? Which one? A brand-new game would quietly wipe out the player's progress, and nothing would tell them why. It is the same trap as the shop that answered false in an earlier lesson: an answer that looks like an answer, where a wrong guess about what it means looks just like success.

The honest return type is the one serde_json already used on us:

Result<Game, LoadError>

Either a Game, or the reason there is no Game.

LoadError is ours to define. It is an enum, like PurchaseOutcome, listing the ways loading can fail. For now there is one. Add it near the top of src/save.rs, below SAVE_VERSION:

src/save.rs

#[derive(Debug, PartialEq)]
pub enum LoadError {
    Unreadable,
}

Then the load itself, inside the same impl Game block, below save_json():

src/save.rs

    pub fn from_saved_json(json: &str) -> Result<Game, LoadError> {
        let save: SaveData = match serde_json::from_str(json) {
            Ok(save) => save,
            Err(_) => return Err(LoadError::Unreadable),
        };

        let mut game = Game::new();

        game.stage = save.stage;
        game.player.gold = save.player.gold;
        game.player.xp = save.player.xp;
        game.player.level = save.player.level;
        game.player.click_upgrade_level = save.player.click_upgrade_level;

        game.enemy = Enemy::for_stage(save.stage);
        game.enemy.health = save.enemy_health;

        Ok(game)
    }

And one more import at the top, because we build an enemy:

src/save.rs

use crate::enemy::Enemy;

Let us walk through it.

json: &str means the function borrows some text instead of taking it. &str is a borrowed piece of text, the way &Player is a borrowed player. Whoever calls from_saved_json() keeps their String.

serde_json::from_str(json) reads the text. It returns a Result too, and this time failure is real: the text might be anything. So we match on it, exactly the way we matched on PurchaseOutcome, one arm per possibility:

• Ok(save) => save takes the SaveData out of the Ok and makes it the value of the whole match.
• Err(_) => return Err(LoadError::Unreadable) ignores the details of what went wrong (that is the _) and leaves the function early with our own error.

The : SaveData after let save matters more than it looks. from_str can build anything that implements Deserialize. That annotation is how it knows to build a SaveData, and therefore which names to look for.

The rest rebuilds the game. Start from a new Game, copy the saved progress over it, then ask Enemy::for_stage() for the enemy. That one line is where the save's small shape pays off. The rewards come from the current rules, not from the file. Only the slime's remaining health comes from the save.

Last, Ok(game) wraps the finished game in the success half of the Result.

Here is the same round trip on its own. It runs in the page, using the same two crates.

Run it, and you should see the player saved and loaded. Then break the save on purpose: delete "level":2, from the text line and run again. Then put it back and change 11 to -5.

Live example · break the save on purpose

use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct PlayerSave {
    gold: u32,
    xp: u32,
    level: u32,
    click_upgrade_level: u32,
}

fn main() {
    let player = PlayerSave {
        gold: 11,
        xp: 4,
        level: 2,
        click_upgrade_level: 1,
    };

    let json = serde_json::to_string(&player)
        .expect("a save made of numbers should always serialize");
    println!("Saved: {json}");

    let text = r#"{"gold":11,"xp":4,"level":2,"click_upgrade_level":1}"#;
    let loaded: Result<PlayerSave, serde_json::Error> = serde_json::from_str(text);

    match loaded {
        Ok(player) => println!("Loaded: level {} with {} gold", player.level, player.gold),
        Err(error) => println!("Not a save: {error}"),
    }
}

Run and edit this example on the canonical article.

The first break prints:

Not a save: missing field `level` at line 1 column 42

The second:

Not a save: invalid value: integer `-5`, expected u32 at line 1 column 10

serde_json knew exactly what was wrong both times. from_saved_json() throws those details away and says Unreadable, because the game cannot do anything more useful with them. Either way, the Err arm prints and nothing crashes.

Question: Why does from_saved_json() return Result<Game, LoadError> instead of a Game?

1. A Result loads faster than a plain struct
2. Text that is not a save has no honest Game to return, and the caller has to handle both cases
3. serde_json only works inside functions that return a Result

Answer: 2. Text that is not a save has no honest Game to return, and the caller has to handle both cases

Explanation: Returning Game::new() on failure would look like success and quietly wipe the player's progress.

Rust will not let us forget

Time to use it. In src/main.rs, after the while loop and before the hour away, save the game:

src/main.rs

    let save = game.save_json();
    println!("Saved: {save}");

Then load it back and print where we are. The tempting version is two lines, right under the save lines:

    let mut game = Game::from_saved_json(&save);
    println!("Loaded. Stage {}, level {}.", game.stage, game.player.level);

Build that, and Rust refuses, several times over:

error[E0609]: no field `stage` on type `Result<Game, rustbound_idle::save::LoadError>`
  --> src\main.rs:49:50
   |
49 |     println!("Loaded. Stage {}, level {}.", game.stage, game.player.level);
   |                                                  ^^^^^ unknown field

The other errors say the same thing about player, and about every later line that touches game.

game is not a Game. It is a Result, and a Result has no stage. The Game is inside it, maybe.

That is the whole point. Other languages often hand back the game or a special empty value and trust you to check. Rust hands back a box with one of two things in it, and will not let you reach for the game until you have said what happens if it is the other thing.

So we say it, with a match. Replace the two tempting lines with:

src/main.rs

    let mut game = match Game::from_saved_json(&save) {
        Ok(game) => game,
        Err(error) => {
            println!("Could not load the save: {error:?}");
            return;
        }
    };

    println!("Loaded. Stage {}, level {}.", game.stage, game.player.level);

If the load worked, the Game comes out of the Ok. If not, we print the error and return from main(), which ends the program. {error:?} prints the error with Debug, which is why LoadError derives it.

Anyone outside the library who wants to match on the different kinds of LoadError has to be able to name it. So it goes on the front door, in src/lib.rs:

src/lib.rs

pub use save::LoadError;

main.rs does not name it yet. The browser version of the game, a couple of lessons from now, will.

Throw the game away

Look at the code we just wrote again. There is something odd about it.

We already had a game. Then we wrote let mut game = ... a second time.

That is allowed. A new let with an old name makes a brand-new variable, and the old one can no longer be reached by that name. Rust calls this shadowing.

But the old game is still there, sitting in memory until main() ends. And we want to prove the load works, not just print a game that might secretly be the old one.

So we throw the old one away first, on purpose, right after saving:

src/main.rs

    let save = game.save_json();
    println!("Saved: {save}");

    drop(game);

drop() takes a value and destroys it.

Takes is the important word. In the borrowing article, passing a Player into a function moved it: the function owned it now, and the old variable was empty. drop(game) moves our game into drop, and drop simply ends it.

Try to use the old game anyway. Put this on the line right after drop(game);:

    println!("{}", game.stage);

Rust stops you:

error[E0382]: borrow of moved value: `game`
  --> src\main.rs:49:20
   |
 4 |     let mut game = Game::new();
   |         -------- move occurs because `game` has type `Game`, which does not implement the `Copy` trait
...
48 |     drop(game);
   |          ---- value moved here
49 |     println!("{}", game.stage);
   |                    ^^^^^^^^^^ value borrowed here after move

Delete that line again. Value moved here. After drop(game), the only things left of the game are the text in save and whatever we rebuild from it.

So when the program prints Loaded. Stage 4, level 2. and then spends an hour, every number it shows came through that line of JSON.

Try it on a smaller game. Run it, and you should see Restored game: stage 4. Then remove the // in front of the println! that reads the old game and run it again. Put it back when you have read the error.

Live example · use it after it is gone

struct Game {
    stage: u32,
}

fn main() {
    let game = Game { stage: 4 };
    let saved_stage = game.stage;

    drop(game);

    // println!("Old game: stage {}", game.stage);

    let game = Game { stage: saved_stage };

    println!("Restored game: stage {}", game.stage);
}

Run and edit this example on the canonical article.

Back in your project, run the real game:

cargo run

Stage 1 cleared!  Gold: 5  XP: 6/20
  Next up: Training Slime with 30 health.
Stage 2 cleared!  Gold: 12  XP: 14/20
  Next up: Training Slime with 40 health.
Bought click upgrade 1! Click damage: 7  Gold left: 2
Stage 3 cleared!  Gold: 11  XP: 4/35
Level up! Now level 2. Click damage: 8
  Next up: Training Slime with 50 health.
Saved: {"save_version":1,"stage":4,"player":{"gold":11,"xp":4,"level":2,"click_upgrade_level":1},"enemy_health":50}
Loaded. Stage 4, level 2.
One hour away.
Stage 4 -> 131  Level 2 -> 48  Gold 11 -> 17410

The last line is the same one the game printed last time, with no save involved. The game that spent the hour was not the game that cleared the stages. It only remembered being it.

A save from the future

Now that save_version field.

Some day the save format will change. Maybe a second upgrade, maybe a pet. When it does, we bump SAVE_VERSION to 2.

Then someone opens the new version of the game with a save from version 1. Or, worse, opens an old copy of the game with a save from version 2. Their save might even read correctly as JSON, and still mean something different from what this code thinks it means.

We cannot know today how to convert between formats that do not exist yet. What we can do today is notice the mismatch and refuse, instead of guessing.

That is a second way loading can fail. And unlike Unreadable, this one has a detail worth keeping: which version the save claimed to be.

Coding challenge: Refuse a save from the future

Below is a smaller loader that only reads a version and a stage. It already turns unreadable text into LoadError::Unreadable. Where the // TODO is, add the check that refuses any save_version that is not SAVE_VERSION, with LoadError::UnsupportedVersion holding the version the save claimed.

Keep the names load_stage, LoadError, Unreadable, UnsupportedVersion, and SAVE_VERSION, because the checks use them. Check my code runs hidden tests against your version.

Expected result: the starter prints Ok(4), Ok(4), Err(Unreadable). With your check, the middle line becomes Err(UnsupportedVersion(99)). Until then you will also see two "never used" warnings, for SAVE_VERSION and UnsupportedVersion. They are a hint: your check is what uses them.

Refuse a save from the future

use serde::Deserialize;

const SAVE_VERSION: u32 = 1;

#[derive(Debug, PartialEq)]
enum LoadError {
    Unreadable,
    UnsupportedVersion(u32),
}

#[derive(Deserialize)]
struct SaveData {
    save_version: u32,
    stage: u32,
}

fn load_stage(json: &str) -> Result<u32, LoadError> {
    let save: SaveData = match serde_json::from_str(json) {
        Ok(save) => save,
        Err(_) => return Err(LoadError::Unreadable),
    };

    // TODO: refuse any save_version that is not SAVE_VERSION

    Ok(save.stage)
}

fn main() {
    println!("{:?}", load_stage(r#"{"save_version":1,"stage":4}"#));
    println!("{:?}", load_stage(r#"{"save_version":99,"stage":4}"#));
    println!("{:?}", load_stage("not a save"));
}

/// A save with the current version should still load and give back its stage.
#[test]
fn the_current_version_loads() {
    assert_eq!(load_stage(r#"{"save_version":1,"stage":4}"#), Ok(4));
}

/// A save from version 99 should be refused with `LoadError::UnsupportedVersion`, carrying the 99 so the caller knows which version it was.
#[test]
fn another_version_is_refused() {
    assert_eq!(
        load_stage(r#"{"save_version":99,"stage":4}"#),
        Err(LoadError::UnsupportedVersion(99))
    );
}

/// Text that is not a save at all should still be `LoadError::Unreadable`. Check the version only after the text has been read.
#[test]
fn nonsense_is_still_unreadable() {
    assert_eq!(load_stage("not a save"), Err(LoadError::Unreadable));
}

/// `main()` should run to the end without panicking.
#[test]
fn main_runs() {
    main();
}

Run and edit this example on the canonical article.

Tip: It is an if with an early return, the same shape as the "not enough gold" check in buy_click_upgrade(): compare save.save_version with SAVE_VERSION, and return Err(LoadError::UnsupportedVersion(save.save_version)) when they differ.

Here is the same change in the real game. First the new variant:

src/save.rs

#[derive(Debug, PartialEq)]
pub enum LoadError {
    Unreadable,
    UnsupportedVersion(u32),
}

UnsupportedVersion(u32) is an enum variant that carries a value. PurchaseOutcome::Purchased was just a name. LoadError::UnsupportedVersion(99) is a name and a number: the version that got refused. A match can pull that number back out, the same way Ok(save) pulled out the save.

Then the check, in from_saved_json(), right after the match and before the game is rebuilt:

src/save.rs

        if save.save_version != SAVE_VERSION {
            return Err(LoadError::UnsupportedVersion(save.save_version));
        }

There is nothing to migrate yet. Version 1 is the only version that has ever existed. But every save written from today on says which version wrote it, and that is the part we could never add later. A save without a version number stays without one forever.

Tests that say no

A broken save should get a polite no, not a wiped game. These tests prove it does.

The loader has three ways out: a game, Unreadable, and UnsupportedVersion. Each one deserves a test.

The obvious way to write the first one does not compile:

assert_eq!(
    Game::from_saved_json("definitely not a save"),
    Err(LoadError::Unreadable)
);

error[E0369]: binary operation `==` cannot be applied to type `Result<game::Game, save::LoadError>`
note: an implementation of `PartialEq` might be missing for `game::Game`

error[E0277]: `game::Game` doesn't implement `Debug`

assert_eq! compares the two sides with ==, and prints both if they differ. A Result<Game, LoadError> can only do that if Game can, and Game has never needed to be compared or printed. We could derive PartialEq and Debug on Game, Player, and Enemy just for this. But we do not want to compare whole games here. We want to ask one question: is this an Err(LoadError::Unreadable)?

That is what matches! does. The ! means it is a macro, like println! and assert_eq!. It takes a value and a pattern, the same kind of pattern a match arm uses, and gives back true if the value fits:

assert!(matches!(
    Game::from_saved_json("definitely not a save"),
    Err(LoadError::Unreadable)
));

Here are all the new unit tests. They go inside the tests module at the bottom of src/save.rs, after a_new_game_saves_its_starting_numbers:

src/save.rs

    #[test]
    fn a_loaded_game_rebuilds_the_enemy_from_the_rules() {
        let mut game = Game::new();
        game.tick(600);

        let restored = Game::from_saved_json(&game.save_json()).expect("the save should load");

        assert_eq!(restored.stage, game.stage);
        assert_eq!(restored.enemy.health, game.enemy.health);
        assert_eq!(restored.enemy.gold_reward, game.enemy.gold_reward);
        assert_eq!(restored.enemy.xp_reward, game.enemy.xp_reward);
    }

    #[test]
    fn nonsense_is_not_a_save() {
        assert!(matches!(
            Game::from_saved_json("definitely not a save"),
            Err(LoadError::Unreadable)
        ));
    }

    #[test]
    fn a_save_with_missing_pieces_is_not_a_save() {
        let json = r#"{"save_version":1,"stage":4}"#;

        assert!(matches!(
            Game::from_saved_json(json),
            Err(LoadError::Unreadable)
        ));
    }

    #[test]
    fn a_save_from_another_version_is_refused() {
        let json = r#"{
            "save_version": 99,
            "stage": 1,
            "player": { "gold": 0, "xp": 0, "level": 1, "click_upgrade_level": 0 },
            "enemy_health": 20
        }"#;

        assert!(matches!(
            Game::from_saved_json(json),
            Err(LoadError::UnsupportedVersion(99))
        ));
    }

The first one checks the rewards, which are not in the save at all. It can read gold_reward because it lives inside the library, where pub(crate) fields are visible. Here expect() is the right tool: if a save we just made does not load, that is a bug, and the test should fail loudly.

The last one shows that JSON does not care about spaces or line breaks. The loader reads that save fine. It refuses it anyway, because of the 99.

Question: Why do the failure tests use assert!(matches!(...)) instead of assert_eq!?

1. matches! runs faster than assert_eq!
2. assert_eq! needs both sides to support == and Debug, and Game supports neither
3. assert_eq! cannot compare enum variants that carry a value

Answer: 2. assert_eq! needs both sides to support == and Debug, and Game supports neither

Explanation: matches! only asks whether a value fits a pattern, so Game never has to be compared or printed.

One more test, from the outside, the same way tests/idle_hour.rs tests the library. Create tests/save_and_restore.rs:

tests/save_and_restore.rs

use rustbound_idle::Game;

#[test]
fn a_restored_game_plays_the_same_hour() {
    let mut original = Game::new();
    original.tick(600);

    let mut restored = Game::from_saved_json(&original.save_json()).expect("the save should load");

    original.tick(3600);
    restored.tick(3600);

    assert_eq!(restored.stage, original.stage);
    assert_eq!(restored.enemy.health, original.enemy.health);
    assert_eq!(restored.player.gold, original.player.gold);
    assert_eq!(restored.player.xp, original.player.xp);
    assert_eq!(restored.player.level, original.player.level);
}

It is a cousin of one_long_tick_matches_many_short_ones. Two games that should be the same, run side by side, compared at the end. If the save left anything out, an hour is plenty of time for the difference to show.

Run everything:

cargo test
cargo clippy

Twenty-eight tests pass: twenty-six inside the library, and one in each of the two files in tests/. Clippy should be quiet.

The new and changed files

If anything above went sideways, here is every file that changed. The rest are exactly as they were in "Our starting point."

Cargo.toml (only the [dependencies] section changed):

Cargo.toml

[package]
name = "rustbound-idle"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"

src/lib.rs:

src/lib.rs

mod enemy;
mod game;
mod player;
mod rules;
mod save;

pub use enemy::Enemy;
pub use game::Game;
pub use player::{Player, PurchaseOutcome};
pub use save::LoadError;

use crate::enemy::Enemy;
use crate::game::Game;
use serde::{Deserialize, Serialize};

const SAVE_VERSION: u32 = 1;

#[derive(Debug, PartialEq)]
pub enum LoadError {
    Unreadable,
    UnsupportedVersion(u32),
}

#[derive(Serialize, Deserialize)]
struct PlayerSave {
    gold: u32,
    xp: u32,
    level: u32,
    click_upgrade_level: u32,
}

#[derive(Serialize, Deserialize)]
struct SaveData {
    save_version: u32,
    stage: u32,
    player: PlayerSave,
    enemy_health: u32,
}

impl Game {
    pub fn save_json(&self) -> String {
        let save = SaveData {
            save_version: SAVE_VERSION,
            stage: self.stage,
            player: PlayerSave {
                gold: self.player.gold,
                xp: self.player.xp,
                level: self.player.level,
                click_upgrade_level: self.player.click_upgrade_level,
            },
            enemy_health: self.enemy.health,
        };

        serde_json::to_string(&save).expect("a save made of numbers should always serialize")
    }

    pub fn from_saved_json(json: &str) -> Result<Game, LoadError> {
        let save: SaveData = match serde_json::from_str(json) {
            Ok(save) => save,
            Err(_) => return Err(LoadError::Unreadable),
        };

        if save.save_version != SAVE_VERSION {
            return Err(LoadError::UnsupportedVersion(save.save_version));
        }

        let mut game = Game::new();

        game.stage = save.stage;
        game.player.gold = save.player.gold;
        game.player.xp = save.player.xp;
        game.player.level = save.player.level;
        game.player.click_upgrade_level = save.player.click_upgrade_level;

        game.enemy = Enemy::for_stage(save.stage);
        game.enemy.health = save.enemy_health;

        Ok(game)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_new_game_saves_its_starting_numbers() {
        let json = Game::new().save_json();

        assert_eq!(
            json,
            r#"{"save_version":1,"stage":1,"player":{"gold":0,"xp":0,"level":1,"click_upgrade_level":0},"enemy_health":20}"#
        );
    }

    #[test]
    fn a_loaded_game_rebuilds_the_enemy_from_the_rules() {
        let mut game = Game::new();
        game.tick(600);

        let restored = Game::from_saved_json(&game.save_json()).expect("the save should load");

        assert_eq!(restored.stage, game.stage);
        assert_eq!(restored.enemy.health, game.enemy.health);
        assert_eq!(restored.enemy.gold_reward, game.enemy.gold_reward);
        assert_eq!(restored.enemy.xp_reward, game.enemy.xp_reward);
    }

    #[test]
    fn nonsense_is_not_a_save() {
        assert!(matches!(
            Game::from_saved_json("definitely not a save"),
            Err(LoadError::Unreadable)
        ));
    }

    #[test]
    fn a_save_with_missing_pieces_is_not_a_save() {
        let json = r#"{"save_version":1,"stage":4}"#;

        assert!(matches!(
            Game::from_saved_json(json),
            Err(LoadError::Unreadable)
        ));
    }

    #[test]
    fn a_save_from_another_version_is_refused() {
        let json = r#"{
            "save_version": 99,
            "stage": 1,
            "player": { "gold": 0, "xp": 0, "level": 1, "click_upgrade_level": 0 },
            "enemy_health": 20
        }"#;

        assert!(matches!(
            Game::from_saved_json(json),
            Err(LoadError::UnsupportedVersion(99))
        ));
    }
}

use rustbound_idle::{Game, PurchaseOutcome};

fn main() {
    let mut game = Game::new();

    while game.stage <= 3 {
        let stage = game.stage;
        let level = game.player.level;

        game.click();

        if game.stage > stage {
            println!(
                "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
                game.player.gold,
                game.player.xp,
                game.player.xp_needed()
            );

            if game.player.level > level {
                println!(
                    "Level up! Now level {}. Click damage: {}",
                    game.player.level,
                    game.player.click_damage()
                );
            }

            println!(
                "  Next up: {} with {} health.",
                game.enemy.name, game.enemy.health
            );
        }

        match game.buy_click_upgrade() {
            PurchaseOutcome::Purchased => println!(
                "Bought click upgrade {}! Click damage: {}  Gold left: {}",
                game.player.click_upgrade_level,
                game.player.click_damage(),
                game.player.gold
            ),
            PurchaseOutcome::NotEnoughGold => {}
        }
    }

    let save = game.save_json();
    println!("Saved: {save}");

    drop(game);

    let mut game = match Game::from_saved_json(&save) {
        Ok(game) => game,
        Err(error) => {
            println!("Could not load the save: {error:?}");
            return;
        }
    };

    println!("Loaded. Stage {}, level {}.", game.stage, game.player.level);

    let stage = game.stage;
    let level = game.player.level;
    let gold = game.player.gold;

    game.tick(3600);

    println!("One hour away.");
    println!(
        "Stage {} -> {}  Level {} -> {}  Gold {} -> {}",
        stage, game.stage, level, game.player.level, gold, game.player.gold
    );
}

tests/save_and_restore.rs is exactly as written in the section above.

What we learned

Two ideas are worth keeping.

The first is that failure is part of the answer. from_saved_json() does not return a Game. It returns a Result, and anyone who calls it has to deal with both halves before they get a Game out. There is no way to forget. That is Result doing for errors what PurchaseOutcome did for purchases: making the outcome a value with a name, so that false is never the whole story.

The second is what the save does not contain. No damage numbers, no thresholds, no costs, and no enemy rewards. It stores the player's progress, the stage, and the enemy's remaining health. Everything else is rebuilt from the current rules.

Along the way, we also encountered:

• dependencies in Cargo.toml, and Cargo.lock
• serde and serde_json
• JSON
• traits, and deriving Serialize and Deserialize
• const
• a save shape kept separate from the runtime Game
• Result, Ok, and Err
• match on a Result, and expect() when failure would be a bug
• &str, and raw strings
• drop(), and the word moved
• shadowing: reusing a variable name with a new let
• enum variants that carry a value
• a save version, before there is anything to migrate
• matches!

You do not need to memorize all of that yet.

There is still a loose end. A save is text, and anyone can edit text.

Question: A player opens their save and changes "gold":11 to "gold":11000000. What does from_saved_json() do today?

1. Returns Err(LoadError::Unreadable), because the number is too big
2. Loads it, because it is still valid JSON with the right version and a number that fits in a u32
3. Refuses to compile until we add a maximum

Answer: 2. Loads it, because it is still valid JSON with the right version and a number that fits in a u32

Explanation: The loader checks that the text is a save, not that the save is believable. That is a different job.

Module privacy keeps other Rust code away from private engine details. It cannot make outside data trustworthy. Checking that a save makes sense is a different boundary, and it gets its own article later in the series. Not the next one.

Text crosses any wall

Our game can now describe itself in text, and rebuild itself from text.

Text is one of the easiest things for different languages and environments to share. A terminal can print it. A file can hold it. A browser can keep it in storage and hand it back.

So far, the only thing that has ever driven this engine is main(), in Rust, in a terminal.

Next time, we compile the library to WebAssembly, a format browsers can run right beside JavaScript, and the thing on the other side of the wall is JavaScript.

It will not learn how combat works. It will not learn what a slime is worth. It gets a handful of operations and a save that is already text.

That is all it needs.

Nothing about the game changes. We will not touch a rule.

Nobody planned that file. Each article needed one more thing, and each thing went in the next free spot. But look at what is in there: everything above main() knows nothing about a terminal or a screen. Only main() does.

So we put a wall between them. When we are done, main.rs is fifty-six lines: it creates a game, clicks, and prints. The game itself lives in a library that has never heard of a terminal.

A library like that, made of rules and state that do not know how they are being displayed, is the heart of what people call a game engine.

A small one.

Ours will have a front door and nothing else.

The program still prints the same thing, a few stages cleared and then an hour of waiting:

One hour away.
Stage 4 -> 131  Level 2 -> 48  Gold 11 -> 17410

Same output.

Same twenty-one tests, plus one new one.

Different house.

Our starting point

This series builds a small idle game: a player clicks to fight slimes, earns gold and XP, and keeps progressing while you are away.

If you are only reading along, skip past this code to "The groups are already visible."

If you are building along, create a project with cargo new rustbound-idle if you do not already have one. The name matters later.

At this point, src/main.rs holds three structs, an enum, three impl blocks, twelve small functions, and twenty-one tests:

struct Player {
    gold: u32,
    xp: u32,
    level: u32,
    click_upgrade_level: u32,
}

struct Enemy {
    name: String,
    health: u32,
    gold_reward: u32,
    xp_reward: u32,
}

struct Game {
    stage: u32,
    player: Player,
    enemy: Enemy,
}

#[derive(Debug, PartialEq)]
enum PurchaseOutcome {
    Purchased,
    NotEnoughGold,
}

impl Player {
    fn new() -> Player {
        Player {
            gold: 0,
            xp: 0,
            level: 1,
            click_upgrade_level: 0,
        }
    }

    fn add_gold(&mut self, amount: u32) {
        self.gold = self.gold.saturating_add(amount);
    }

    fn add_xp(&mut self, amount: u32) {
        self.xp = self.xp.saturating_add(amount);

        while self.xp >= xp_to_next_level(self.level) {
            self.xp -= xp_to_next_level(self.level);
            self.level = self.level.saturating_add(1);
        }
    }

    fn base_damage(&self) -> u32 {
        base_damage_for_level(self.level)
    }

    fn bonus_damage(&self) -> u32 {
        click_upgrade_bonus(self.click_upgrade_level)
    }

    fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        let cost = click_upgrade_cost(self.click_upgrade_level);

        if self.gold < cost {
            return PurchaseOutcome::NotEnoughGold;
        }

        self.gold -= cost;
        self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);

        PurchaseOutcome::Purchased
    }
}

impl Enemy {
    fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
            xp_reward: xp_reward_for_stage(stage),
        }
    }
}

impl Game {
    fn new() -> Game {
        Game {
            stage: 1,
            player: Player::new(),
            enemy: Enemy::for_stage(1),
        }
    }

    fn click(&mut self) {
        attack(&self.player, &mut self.enemy);
        self.resolve_hit();
    }

    fn tick(&mut self, seconds: u32) {
        for _ in 0..seconds {
            let damage = idle_damage_for_level(self.player.level);

            self.enemy.health = health_after_hit(self.enemy.health, damage);
            self.resolve_hit();
        }
    }

    fn resolve_hit(&mut self) {
        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

    fn defeat_enemy(&mut self) {
        self.player.add_gold(self.enemy.gold_reward);
        self.player.add_xp(self.enemy.xp_reward);

        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }

    fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        self.player.buy_click_upgrade()
    }
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

fn gold_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(3)
}

fn xp_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(4)
}

fn xp_to_next_level(level: u32) -> u32 {
    level
        .saturating_sub(1)
        .saturating_mul(15)
        .saturating_add(20)
}

fn base_damage_for_level(level: u32) -> u32 {
    level.saturating_add(4)
}

fn idle_damage_for_level(level: u32) -> u32 {
    level
}

fn click_upgrade_bonus(upgrades: u32) -> u32 {
    upgrades.saturating_mul(2)
}

fn click_upgrade_cost(upgrades: u32) -> u32 {
    upgrades.saturating_add(1).saturating_mul(10)
}

fn attack(player: &Player, enemy: &mut Enemy) {
    let damage = click_damage(player.base_damage(), player.bonus_damage());

    enemy.health = health_after_hit(enemy.health, damage);
}

fn main() {
    let mut game = Game::new();

    while game.stage <= 3 {
        let stage = game.stage;
        let level = game.player.level;

        game.click();

        if game.stage > stage {
            println!(
                "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
                game.player.gold,
                game.player.xp,
                xp_to_next_level(game.player.level)
            );

            if game.player.level > level {
                println!(
                    "Level up! Now level {}. Click damage: {}",
                    game.player.level,
                    click_damage(game.player.base_damage(), game.player.bonus_damage())
                );
            }

            println!(
                "  Next up: {} with {} health.",
                game.enemy.name, game.enemy.health
            );
        }

        match game.buy_click_upgrade() {
            PurchaseOutcome::Purchased => println!(
                "Bought click upgrade {}! Click damage: {}  Gold left: {}",
                game.player.click_upgrade_level,
                click_damage(game.player.base_damage(), game.player.bonus_damage()),
                game.player.gold
            ),
            PurchaseOutcome::NotEnoughGold => {}
        }
    }

    let stage = game.stage;
    let level = game.player.level;
    let gold = game.player.gold;

    game.tick(3600);

    println!("One hour away.");
    println!(
        "Stage {} -> {}  Level {} -> {}  Gold {} -> {}",
        stage, game.stage, level, game.player.level, gold, game.player.gold
    );
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player::new();

        let mut enemy = Enemy::for_stage(1);
        enemy.health = 10;

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 5);
    }

    #[test]
    fn later_stages_have_tougher_enemies() {
        assert_eq!(enemy_health_for_stage(1), 20);
        assert_eq!(enemy_health_for_stage(2), 30);
    }

    #[test]
    fn later_stages_pay_better() {
        assert_eq!(gold_reward_for_stage(1), 5);
        assert_eq!(gold_reward_for_stage(2), 7);
        assert_eq!(xp_reward_for_stage(1), 6);
        assert_eq!(xp_reward_for_stage(2), 8);
    }

    #[test]
    fn levels_need_more_xp_as_they_go() {
        assert_eq!(xp_to_next_level(1), 20);
        assert_eq!(xp_to_next_level(2), 35);
    }

    #[test]
    fn leveling_up_keeps_leftover_xp() {
        let mut player = Player::new();

        player.add_xp(25);

        assert_eq!(player.level, 2);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn a_big_reward_can_skip_levels() {
        let mut player = Player::new();

        player.add_xp(60);

        assert_eq!(player.level, 3);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn levels_make_the_player_hit_harder() {
        assert_eq!(base_damage_for_level(1), 5);
        assert_eq!(base_damage_for_level(2), 6);
    }

    #[test]
    fn upgrades_cost_more_each_time() {
        assert_eq!(click_upgrade_cost(0), 10);
        assert_eq!(click_upgrade_cost(1), 20);
    }

    #[test]
    fn buying_an_upgrade_needs_gold() {
        let mut player = Player::new();

        assert_eq!(
            player.buy_click_upgrade(),
            PurchaseOutcome::NotEnoughGold
        );
        assert_eq!(player.click_upgrade_level, 0);
        assert_eq!(player.bonus_damage(), 0);
    }

    #[test]
    fn buying_an_upgrade_spends_gold() {
        let mut player = Player::new();
        player.gold = 12;

        assert_eq!(
            player.buy_click_upgrade(),
            PurchaseOutcome::Purchased
        );
        assert_eq!(player.gold, 2);
        assert_eq!(player.click_upgrade_level, 1);
        assert_eq!(player.bonus_damage(), 2);
    }

    #[test]
    fn a_new_game_starts_at_stage_one() {
        let game = Game::new();

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
        assert_eq!(game.player.gold, 0);
    }

    #[test]
    fn clicking_damages_the_enemy() {
        let mut game = Game::new();

        game.click();

        assert_eq!(game.enemy.health, 15);
    }

    #[test]
    fn defeating_an_enemy_pays_the_player() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }

    #[test]
    fn idle_damage_grows_with_level() {
        assert_eq!(idle_damage_for_level(1), 1);
        assert_eq!(idle_damage_for_level(2), 2);
    }

    #[test]
    fn enough_time_defeats_the_enemy() {
        let mut game = Game::new();

        game.tick(20);

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }

    #[test]
    fn one_second_is_one_idle_hit() {
        let mut game = Game::new();

        game.tick(1);

        assert_eq!(game.enemy.health, 19);
    }

    #[test]
    fn zero_seconds_changes_nothing() {
        let mut game = Game::new();

        game.tick(0);

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
    }

    #[test]
    fn one_long_tick_matches_many_short_ones() {
        let mut long = Game::new();
        let mut short = Game::new();

        long.tick(45);

        for _ in 0..45 {
            short.tick(1);
        }

        assert_eq!(long.stage, short.stage);
        assert_eq!(long.enemy.health, short.enemy.health);
        assert_eq!(long.player.gold, short.player.gold);
        assert_eq!(long.player.xp, short.player.xp);
        assert_eq!(long.player.level, short.player.level);
    }
}

Run it, and the player clears three stages, buys an upgrade, and spends an hour away.

Run cargo test, and all twenty-one tests pass.

You need a recent Rust version. This project uses edition 2024, which requires Rust 1.85 or newer.

Hold on to that test count.

Everything we do today is a reorganization, and the tests are how we prove we did not break anything.

The groups are already visible

Nobody has to invent categories for this code.

It has been sorting itself since the first article:

rules    click_damage, health_after_hit, is_defeated,
         enemy_health_for_stage, gold_reward_for_stage,
         xp_reward_for_stage, xp_to_next_level,
         base_damage_for_level, idle_damage_for_level,
         click_upgrade_bonus, click_upgrade_cost

enemy    Enemy
player   Player, PurchaseOutcome
game     Game, attack
main     everything that prints

Look at the first group.

Those eleven functions take plain values and return plain values.

They never touch a Player, an Enemy, or a Game.

They are the rules of the game, and every other group leans on them.

Rust has a name for a named group of code: a module.

For this project, we are going to give each top-level module its own file, one at a time, and run the tests after every move.

Give the rules their own module

Create a new file next to main.rs:

src/
├── main.rs
└── rules.rs

Cut the eleven rule functions out of main.rs and paste them into rules.rs.

Leave attack() where it is.

It takes a Player and an Enemy, so it is not one of our plain-value rules. It belongs with the game.

The tests for those rules should move too.

Nine of them check nothing but rules:

click_damage_adds_base_and_bonus
health_never_drops_below_zero
zero_health_is_defeated
later_stages_have_tougher_enemies
later_stages_pay_better
levels_need_more_xp_as_they_go
levels_make_the_player_hit_harder
idle_damage_grows_with_level
upgrades_cost_more_each_time

Cut each one out of the tests module in main.rs, including the #[test] line above it, and give rules.rs a tests module of its own at the bottom:

#[cfg(test)]
mod tests {
    use super::*;

    // the nine rule tests go here
}

The use super::*; line means:

Bring in everything from the module above me.

Now main.rs needs to find its rules again.

Add this to the very top of main.rs, above everything else:

mod rules;

use rules::{
    base_damage_for_level, click_damage,
    click_upgrade_bonus, click_upgrade_cost,
    enemy_health_for_stage, gold_reward_for_stage,
    health_after_hit, idle_damage_for_level,
    is_defeated, xp_reward_for_stage,
    xp_to_next_level,
};

mod rules; says:

There is a module called rules, and its code lives in src/rules.rs.

The use line brings its functions into main.rs by name, so the rest of the file can keep calling click_damage() exactly as before.

Build it:

cargo build

Rust refuses:

error[E0603]: function `base_damage_for_level` is private
 --> src/main.rs:4:5
  |
4 |     base_damage_for_level,
  |     ^^^^^^^^^^^^^^^^^^^^^ private function
  |
note: the function `base_damage_for_level` is defined here
 --> src/rules.rs:32:1
  |
32 | fn base_damage_for_level(level: u32) -> u32 {
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You will get one of these for every function.

That is not a bug in what we did.

It is our first encounter with one of Rust's module boundaries:

By default, an item is visible inside its module and the modules beneath it. Sibling modules and outside code cannot use it unless we open that boundary.

main.rs sits outside the rules module.

It cannot reach those functions yet.

The simplest way to open that boundary is pub, short for public.

Put it in front of each of the eleven functions:

pub fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

Run both:

cargo test
cargo run

Twenty-one tests pass, and the output is the same as before.

The count should stay at twenty-one after every move in this article.

We moved eleven functions and nine tests into another file, and nothing changed.

That is what a good move looks like.

The enemy

Enemy is next because it is the smallest.

Create src/enemy.rs, and move the Enemy struct and its impl block into it.

The new file needs to find the rules it uses, so it starts like this:

use crate::rules::{
    enemy_health_for_stage,
    gold_reward_for_stage,
    xp_reward_for_stage,
};

crate means the top of the crate this file belongs to.

A path beginning with crate:: starts there no matter which module we are currently inside.

For now, all of these modules still belong to the executable crate.

In a moment we are going to move them into a library crate, and that distinction will matter.

Back in main.rs, add:

mod enemy;

under mod rules;, and:

use enemy::Enemy;

under the rules import.

Build again.

Rust has an opinion:

error[E0603]: struct `Enemy` is private
 --> src/main.rs:4:12
  |
4 | use enemy::Enemy;
  |            ^^^^^ private struct

Same boundary, same first fix:

pub struct Enemy

Build again, and Rust has a few more opinions.

Making the struct public does not automatically make all of its fields public.

Each field has its own visibility.

So does Enemy::for_stage().

For now, here is the finished file:

use crate::rules::{
    enemy_health_for_stage,
    gold_reward_for_stage,
    xp_reward_for_stage,
};

pub struct Enemy {
    pub name: String,
    pub health: u32,
    pub gold_reward: u32,
    pub xp_reward: u32,
}

impl Enemy {
    pub fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
            xp_reward: xp_reward_for_stage(stage),
        }
    }
}

Everything is pub for now.

That is too generous.

We are going to fix it on purpose once the boundaries are in place.

Run:

cargo test

Twenty-one pass.

You may also see warnings that some imports in main.rs are unused.

That is true.

Enemy was the only caller of enemy_health_for_stage(), gold_reward_for_stage(), and xp_reward_for_stage(), and it just moved.

Delete those names from the use rules::{...} list in main.rs.

The player

Same move, bigger file.

Create src/player.rs.

Move in:

• Player
• PurchaseOutcome
• the impl Player block

PurchaseOutcome goes with Player because it is the player's vocabulary.

It is how a purchase answers.

At the top of the file, import the rules Player uses:

use crate::rules::{
    base_damage_for_level,
    click_upgrade_bonus,
    click_upgrade_cost,
    xp_to_next_level,
};

Then add pub to the struct, its four fields, the enum, and every function in impl Player.

An enum's variants follow the enum's visibility.

Make PurchaseOutcome public, and its Purchased and NotEnoughGold variants are available with it.

Four tests are about the player and nothing else:

leveling_up_keeps_leftover_xp
a_big_reward_can_skip_levels
buying_an_upgrade_needs_gold
buying_an_upgrade_spends_gold

Move those into a tests module at the bottom of player.rs, the same way we did with the rules.

In main.rs, add:

mod player;

and:

use player::{Player, PurchaseOutcome};

Game and attack() still live in main.rs for now, so main.rs still needs Player.

That import drops out again in the next section.

Run:

cargo test

Twenty-one pass.

Clean up the new unused-import warnings the same way: remove base_damage_for_level, click_upgrade_bonus, and click_upgrade_cost from the use rules::{...} list in main.rs.

The game

Last one.

Create src/game.rs and move in:

• Game
• its impl block
• attack()

It needs three things from the other modules:

use crate::enemy::Enemy;
use crate::player::{Player, PurchaseOutcome};
use crate::rules::{
    click_damage,
    health_after_hit,
    idle_damage_for_level,
    is_defeated,
};

Add pub to the struct and its three fields.

Then add it to the four functions the outside world is going to call:

pub fn new() -> Game
pub fn click(&mut self)
pub fn tick(&mut self, seconds: u32)
pub fn buy_click_upgrade(&mut self) -> PurchaseOutcome

Now look at what is not on that list.

resolve_hit() stays private.

defeat_enemy() stays private.

So does attack().

Nothing outside game.rs has a reason to call them.

When a slime dies, the game decides what that means.

A caller should not get to say:

Pretend that enemy just died.

We will close the field loophole shortly.

That is what privacy is for.

It is not about hiding code for the sake of hiding it.

It is about deciding what the rest of the program is allowed to depend on.

Eight tests are about the game, including the one for attack():

attack_reduces_enemy_health
a_new_game_starts_at_stage_one
clicking_damages_the_enemy
defeating_an_enemy_pays_the_player
one_second_is_one_idle_hit
zero_seconds_changes_nothing
enough_time_defeats_the_enemy
one_long_tick_matches_many_short_ones

Move them to the bottom of game.rs.

In main.rs, add:

mod game;

and:

use game::Game;

At this point, the tests module in main.rs is empty.

Delete it.

You can also remove Player from:

use player::{Player, PurchaseOutcome};

because only Game needs it now.

Clear out any remaining unused imports.

The top of main.rs should look like this:

mod enemy;
mod game;
mod player;
mod rules;

use game::Game;
use player::PurchaseOutcome;
use rules::{click_damage, xp_to_next_level};

Under that, only main() is left.

Run both:

cargo test
cargo run

Twenty-one tests.

Same output.

Four files hold the game.

One holds the printing.

But we have not built the wall yet.

main.rs still declares all four modules.

They are part of the executable crate.

Nothing outside that executable could use them as a library.

Build the wall

A Cargo package can contain both a library target and a binary target:

src/lib.rs    library
src/main.rs   executable

Rust compiles them as separate crates.

The binary can depend on the library.

That gives us the wall we have been looking for.

A crate is one compiled unit of Rust code.

Until now, our project has had one crate: the executable.

Now our package will contain two:

library crate
    ↑
binary crate

They live in the same project, but Rust treats them as separate pieces of code.

Create src/lib.rs, and move the four mod lines out of main.rs and into it:

mod enemy;
mod game;
mod player;
mod rules;

The project is named:

rustbound-idle

Rust turns the hyphen into an underscore when we refer to the library in code:

rustbound_idle

At the top of main.rs, replace all the old mod and use lines with:

use rustbound_idle::{Game, PurchaseOutcome};

Build it:

cargo build

Rust complains.

The first problem looks like this:

error[E0432]: unresolved imports
  `rustbound_idle::Game`,
  `rustbound_idle::PurchaseOutcome`
 --> src/main.rs:1:22
  |
  |   no `Game` in the root
  |   no `PurchaseOutcome` in the root

The library has a game module.

That module has a Game.

But mod game; is private.

From outside the library, there is no public path to Game.

As far as the binary can tell, the library's front door is empty.

We choose what appears there.

That is what pub use is for:

mod enemy;
mod game;
mod player;
mod rules;

pub use enemy::Enemy;
pub use game::Game;
pub use player::{Player, PurchaseOutcome};

pub use means:

Take this item from inside the library and make it available through this public path.

Now code using the library can write:

rustbound_idle::Game

Where Game actually lives inside the library is no longer the caller's problem.

Build again.

Now the remaining errors are about rules:

error[E0425]: cannot find function `xp_to_next_level` in this scope
error[E0425]: cannot find function `click_damage` in this scope
error[E0425]: cannot find function `click_damage` in this scope

Those calls used to work because main.rs imported the rules directly.

Now rules is private inside the library.

There are two ways we could fix that.

We could put rules on the front door too:

pub mod rules;

Then main.rs could import those formulas and keep doing this:

click_damage(
    game.player.base_damage(),
    game.player.bonus_damage()
)

That would compile.

But think about what it means.

Every formula in the game becomes part of the library's public API.

And the screen keeps doing game arithmetic.

Today the screen is a terminal.

Later it will be a browser.

If both of them know how to calculate damage, we now have multiple callers depending on an internal game rule.

The rules should live in one place.

The screen should ask for answers.

So we take the second path.

Leave rules private.

Let Player provide the information the outside world needs.

Add two methods inside impl Player, after add_xp():

pub fn xp_needed(&self) -> u32 {
    xp_to_next_level(self.level)
}

pub fn click_damage(&self) -> u32 {
    click_damage(
        self.base_damage(),
        self.bonus_damage()
    )
}

The method and the rule share a name.

That is fine.

Inside the method:

click_damage(...)

with no self. in front of it means the imported rule.

The method is the player asking that rule a question about itself.

First, add click_damage to the use crate::rules::{...} list at the top of player.rs.

It was not there before because Player used to leave that arithmetic to attack().

While we are in there, add_xp() has been calling:

xp_to_next_level(self.level)

twice.

Now that the player has a method for that question, replace its loop with:

while self.xp >= self.xp_needed() {
    self.xp -= self.xp_needed();
    self.level = self.level.saturating_add(1);
}

The loop is still the same loop.

xp_to_next_level stays imported because xp_needed() uses it.

attack() in game.rs can lean on the other new method too:

fn attack(player: &Player, enemy: &mut Enemy) {
    enemy.health =
        health_after_hit(
            enemy.health,
            player.click_damage()
        );
}

It no longer needs the click_damage rule, so remove that name from the use statement at the top of game.rs.

Last, main() gets simpler.

Where it said:

xp_to_next_level(game.player.level)

it now says:

game.player.xp_needed()

And where it said:

click_damage(
    game.player.base_damage(),
    game.player.bonus_damage()
)

it now says:

game.player.click_damage()

That second replacement happens twice in main().

Build, test, and run:

cargo test
cargo run

Same twenty-one tests.

Same output.

Cargo also prints test blocks for main.rs and doc-tests that say:

running 0 tests

That is normal.

And main.rs no longer knows a single game formula.

Make the front door smaller

We said everything was too pub.

Time to fix that.

Right now main() can see far more than it needs.

Try it.

Add this line just after:

let mut game = Game::new();

game.player.add_gold(1_000_000);

It compiles.

A screen can hand the player a million gold, and the game never gets a say.

Let us close that off.

Rust has a visibility setting between fully private and fully public:

pub(crate)

It means:

Visible anywhere inside this crate, but not outside it.

Our library can use the item freely.

main.rs belongs to a different crate now, so it cannot.

Go through the files and tighten everything main() does not need.

The rule for now is:

pub for what outside code needs. pub(crate) or private for everything else.

In rules.rs, change all eleven:

pub fn

to:

pub(crate) fn

In enemy.rs:

• change for_stage() to pub(crate)
• make gold_reward and xp_reward pub(crate)
• leave name and health public because main() displays them

In player.rs, change:

• new
• add_gold
• add_xp
• buy_click_upgrade

to pub(crate).

Take pub off base_damage() and bonus_damage() entirely.

Only Player needs those now.

What remains fully public is what the current screen needs:

Game
  new
  click
  tick
  buy_click_upgrade
  stage
  player
  enemy

Player
  gold
  xp
  level
  click_upgrade_level
  xp_needed
  click_damage

Enemy
  name
  health

PurchaseOutcome

Now try this again:

game.player.add_gold(1_000_000);

It fails.

add_gold() is pub(crate), and main.rs is outside the library crate.

Delete that line.

Run:

cargo test
cargo run

Nothing changes.

That is the point.

If tightening the boundary had broken main(), it would mean main() depended on something we did not actually want to promise publicly.

Now try to cheat another way.

In main(), add:

let secret = game.enemy.gold_reward;

Rust says no:

error[E0616]: field `gold_reward` of struct `Enemy` is private

Delete it.

Now try reaching for an internal damage detail.

Replace:

game.player.click_damage()

with:

game.player.base_damage()

Rust refuses again:

error[E0624]: method `base_damage` is private

Put it back.

Those errors are the wall doing its job.

A test from the outside

Our twenty-one tests all live inside the library, next to the code they check.

That is useful.

Those tests can work closely with the modules they belong to.

But it leaves another question:

Does the library work for code that only gets to use the public front door?

Cargo has a place for that.

Create a folder called tests next to src, and put a file in it:

rustbound-idle/
├── src/
└── tests/
    └── idle_hour.rs

Each Rust file directly inside tests/ is compiled as a separate integration test crate.

It uses the library the same way outside code does: through the public API.

This is the first code in the project that sees the game the way a stranger would.

Put this in tests/idle_hour.rs:

use rustbound_idle::Game;

#[test]
fn an_hour_away_moves_the_game_forward() {
    let mut game = Game::new();

    game.tick(3600);

    assert_eq!(game.stage, 128);
    assert_eq!(game.player.level, 47);
}

The terminal program clicked through three stages before it waited an hour.

This test waits an hour from a brand-new game, so the numbers are different:

stage 128
level 47

Run everything:

cargo test

Cargo prints a block for each piece it tests.

You should see:

• the twenty-one tests inside the library
• the new integration test in tests/idle_hour.rs
• blocks for main.rs and doc-tests that say running 0 tests

That is fine.

Twenty-two tests in all.

One last complaint

There is one more thing, and it has been waiting for us.

Clippy is Rust's linter.

It looks for patterns that compile but could be clearer, more idiomatic, or less error-prone.

If:

cargo clippy

is not available, install the component first:

rustup component add clippy

Then run:

cargo clippy

Clippy has a suggestion:

warning: you should consider adding a `Default` implementation for `Game`

It did not complain before because Game::new() was not part of a public API.

Now Game is public, and so is its zero-argument new().

Clippy notices that callers may reasonably expect the standard Rust Default trait too.

Default describes a type's standard starting value.

We already have one:

Game::new()

So we can say that explicitly:

impl Default for Game {
    fn default() -> Game {
        Game::new()
    }
}

Put it in game.rs, between the impl Game block and attack().

Now:

Game::new()

and:

Game::default()

produce the same starting game.

Run Clippy again.

It should be quiet.

The complete program

If you are only reading along, skip to the last two sections.

If you have been following along in your editor, here is everything in one place.

Your project should now look like this:

rustbound-idle/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── main.rs
│   ├── rules.rs
│   ├── enemy.rs
│   ├── player.rs
│   └── game.rs
└── tests/
    └── idle_hour.rs

src/lib.rs

mod enemy;
mod game;
mod player;
mod rules;

pub use enemy::Enemy;
pub use game::Game;
pub use player::{Player, PurchaseOutcome};

src/main.rs

use rustbound_idle::{Game, PurchaseOutcome};

fn main() {
    let mut game = Game::new();

    while game.stage <= 3 {
        let stage = game.stage;
        let level = game.player.level;

        game.click();

        if game.stage > stage {
            println!(
                "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
                game.player.gold,
                game.player.xp,
                game.player.xp_needed()
            );

            if game.player.level > level {
                println!(
                    "Level up! Now level {}. Click damage: {}",
                    game.player.level,
                    game.player.click_damage()
                );
            }

            println!(
                "  Next up: {} with {} health.",
                game.enemy.name,
                game.enemy.health
            );
        }

        match game.buy_click_upgrade() {
            PurchaseOutcome::Purchased => println!(
                "Bought click upgrade {}! Click damage: {}  Gold left: {}",
                game.player.click_upgrade_level,
                game.player.click_damage(),
                game.player.gold
            ),
            PurchaseOutcome::NotEnoughGold => {}
        }
    }

    let stage = game.stage;
    let level = game.player.level;
    let gold = game.player.gold;

    game.tick(3600);

    println!("One hour away.");
    println!(
        "Stage {} -> {}  Level {} -> {}  Gold {} -> {}",
        stage,
        game.stage,
        level,
        game.player.level,
        gold,
        game.player.gold
    );
}

src/rules.rs

pub(crate) fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

pub(crate) fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}

pub(crate) fn is_defeated(health: u32) -> bool {
    health == 0
}

pub(crate) fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

pub(crate) fn gold_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(3)
}

pub(crate) fn xp_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(4)
}

pub(crate) fn xp_to_next_level(level: u32) -> u32 {
    level
        .saturating_sub(1)
        .saturating_mul(15)
        .saturating_add(20)
}

pub(crate) fn base_damage_for_level(level: u32) -> u32 {
    level.saturating_add(4)
}

pub(crate) fn idle_damage_for_level(level: u32) -> u32 {
    level
}

pub(crate) fn click_upgrade_bonus(upgrades: u32) -> u32 {
    upgrades.saturating_mul(2)
}

pub(crate) fn click_upgrade_cost(upgrades: u32) -> u32 {
    upgrades
        .saturating_add(1)
        .saturating_mul(10)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn later_stages_have_tougher_enemies() {
        assert_eq!(enemy_health_for_stage(1), 20);
        assert_eq!(enemy_health_for_stage(2), 30);
    }

    #[test]
    fn later_stages_pay_better() {
        assert_eq!(gold_reward_for_stage(1), 5);
        assert_eq!(gold_reward_for_stage(2), 7);
        assert_eq!(xp_reward_for_stage(1), 6);
        assert_eq!(xp_reward_for_stage(2), 8);
    }

    #[test]
    fn levels_need_more_xp_as_they_go() {
        assert_eq!(xp_to_next_level(1), 20);
        assert_eq!(xp_to_next_level(2), 35);
    }

    #[test]
    fn levels_make_the_player_hit_harder() {
        assert_eq!(base_damage_for_level(1), 5);
        assert_eq!(base_damage_for_level(2), 6);
    }

    #[test]
    fn idle_damage_grows_with_level() {
        assert_eq!(idle_damage_for_level(1), 1);
        assert_eq!(idle_damage_for_level(2), 2);
    }

    #[test]
    fn upgrades_cost_more_each_time() {
        assert_eq!(click_upgrade_cost(0), 10);
        assert_eq!(click_upgrade_cost(1), 20);
    }
}

src/enemy.rs

use crate::rules::{
    enemy_health_for_stage,
    gold_reward_for_stage,
    xp_reward_for_stage,
};

pub struct Enemy {
    pub name: String,
    pub health: u32,
    pub(crate) gold_reward: u32,
    pub(crate) xp_reward: u32,
}

impl Enemy {
    pub(crate) fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
            xp_reward: xp_reward_for_stage(stage),
        }
    }
}

src/player.rs

use crate::rules::{
    base_damage_for_level,
    click_damage,
    click_upgrade_bonus,
    click_upgrade_cost,
    xp_to_next_level,
};

pub struct Player {
    pub gold: u32,
    pub xp: u32,
    pub level: u32,
    pub click_upgrade_level: u32,
}

#[derive(Debug, PartialEq)]
pub enum PurchaseOutcome {
    Purchased,
    NotEnoughGold,
}

impl Player {
    pub(crate) fn new() -> Player {
        Player {
            gold: 0,
            xp: 0,
            level: 1,
            click_upgrade_level: 0,
        }
    }

    pub(crate) fn add_gold(&mut self, amount: u32) {
        self.gold = self.gold.saturating_add(amount);
    }

    pub(crate) fn add_xp(&mut self, amount: u32) {
        self.xp = self.xp.saturating_add(amount);

        while self.xp >= self.xp_needed() {
            self.xp -= self.xp_needed();
            self.level = self.level.saturating_add(1);
        }
    }

    pub fn xp_needed(&self) -> u32 {
        xp_to_next_level(self.level)
    }

    pub fn click_damage(&self) -> u32 {
        click_damage(
            self.base_damage(),
            self.bonus_damage()
        )
    }

    fn base_damage(&self) -> u32 {
        base_damage_for_level(self.level)
    }

    fn bonus_damage(&self) -> u32 {
        click_upgrade_bonus(self.click_upgrade_level)
    }

    pub(crate) fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        let cost =
            click_upgrade_cost(self.click_upgrade_level);

        if self.gold < cost {
            return PurchaseOutcome::NotEnoughGold;
        }

        self.gold -= cost;
        self.click_upgrade_level =
            self.click_upgrade_level.saturating_add(1);

        PurchaseOutcome::Purchased
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn leveling_up_keeps_leftover_xp() {
        let mut player = Player::new();

        player.add_xp(25);

        assert_eq!(player.level, 2);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn a_big_reward_can_skip_levels() {
        let mut player = Player::new();

        player.add_xp(60);

        assert_eq!(player.level, 3);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn buying_an_upgrade_needs_gold() {
        let mut player = Player::new();

        assert_eq!(
            player.buy_click_upgrade(),
            PurchaseOutcome::NotEnoughGold
        );
        assert_eq!(player.click_upgrade_level, 0);
        assert_eq!(player.bonus_damage(), 0);
    }

    #[test]
    fn buying_an_upgrade_spends_gold() {
        let mut player = Player::new();
        player.gold = 12;

        assert_eq!(
            player.buy_click_upgrade(),
            PurchaseOutcome::Purchased
        );
        assert_eq!(player.gold, 2);
        assert_eq!(player.click_upgrade_level, 1);
        assert_eq!(player.bonus_damage(), 2);
    }
}

src/game.rs

use crate::enemy::Enemy;
use crate::player::{Player, PurchaseOutcome};
use crate::rules::{
    health_after_hit,
    idle_damage_for_level,
    is_defeated,
};

pub struct Game {
    pub stage: u32,
    pub player: Player,
    pub enemy: Enemy,
}

impl Game {
    pub fn new() -> Game {
        Game {
            stage: 1,
            player: Player::new(),
            enemy: Enemy::for_stage(1),
        }
    }

    pub fn click(&mut self) {
        attack(&self.player, &mut self.enemy);
        self.resolve_hit();
    }

    pub fn tick(&mut self, seconds: u32) {
        for _ in 0..seconds {
            let damage =
                idle_damage_for_level(self.player.level);

            self.enemy.health =
                health_after_hit(
                    self.enemy.health,
                    damage
                );

            self.resolve_hit();
        }
    }

    fn resolve_hit(&mut self) {
        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

    fn defeat_enemy(&mut self) {
        self.player.add_gold(self.enemy.gold_reward);
        self.player.add_xp(self.enemy.xp_reward);

        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }

    pub fn buy_click_upgrade(
        &mut self
    ) -> PurchaseOutcome {
        self.player.buy_click_upgrade()
    }
}

impl Default for Game {
    fn default() -> Game {
        Game::new()
    }
}

fn attack(player: &Player, enemy: &mut Enemy) {
    enemy.health =
        health_after_hit(
            enemy.health,
            player.click_damage()
        );
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player::new();

        let mut enemy = Enemy::for_stage(1);
        enemy.health = 10;

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 5);
    }

    #[test]
    fn a_new_game_starts_at_stage_one() {
        let game = Game::new();

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
        assert_eq!(game.player.gold, 0);
    }

    #[test]
    fn clicking_damages_the_enemy() {
        let mut game = Game::new();

        game.click();

        assert_eq!(game.enemy.health, 15);
    }

    #[test]
    fn defeating_an_enemy_pays_the_player() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }

    #[test]
    fn one_second_is_one_idle_hit() {
        let mut game = Game::new();

        game.tick(1);

        assert_eq!(game.enemy.health, 19);
    }

    #[test]
    fn zero_seconds_changes_nothing() {
        let mut game = Game::new();

        game.tick(0);

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
    }

    #[test]
    fn enough_time_defeats_the_enemy() {
        let mut game = Game::new();

        game.tick(20);

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }

    #[test]
    fn one_long_tick_matches_many_short_ones() {
        let mut long = Game::new();
        let mut short = Game::new();

        long.tick(45);

        for _ in 0..45 {
            short.tick(1);
        }

        assert_eq!(long.stage, short.stage);
        assert_eq!(
            long.enemy.health,
            short.enemy.health
        );
        assert_eq!(
            long.player.gold,
            short.player.gold
        );
        assert_eq!(
            long.player.xp,
            short.player.xp
        );
        assert_eq!(
            long.player.level,
            short.player.level
        );
    }
}

tests/idle_hour.rs

use rustbound_idle::Game;

#[test]
fn an_hour_away_moves_the_game_forward() {
    let mut game = Game::new();

    game.tick(3600);

    assert_eq!(game.stage, 128);
    assert_eq!(game.player.level, 47);
}

Run everything:

cargo run
cargo test
cargo clippy

The game should clear three stages, buy one upgrade, and spend an hour away.

All twenty-two tests should pass.

Clippy should be quiet.

What we learned

Along the way, we encountered:

• modules, and mod to declare one
• organizing top-level modules into separate files
• use, and crate:: paths
• Rust's default privacy boundaries
• pub
• pub(crate)
• pub use, for choosing what appears on a library's front door
• a library crate and a binary crate in the same Cargo package
• tests that live beside their code
• integration tests in tests/
• Default, which Clippy asked us to provide

Two ideas are worth keeping.

The first is that privacy is not about hiding.

It is about deciding what everyone else is allowed to depend on.

A private function gives us freedom.

We can rename it, reorganize it, or replace its implementation without outside code depending on that detail, as long as the public behavior stays the same.

resolve_hit() can move.

base_damage() can change.

Code outside their visibility boundary does not get to build itself around those details.

The second idea is where the line went.

We did not decide to build an engine.

We sorted the code, and the sorting kept asking one question:

Does this need to know about a screen?

For everything except main(), the answer was no.

That is the heart of what our little game engine is becoming.

It is not a graphics library.

It does not open a window.

It does not print to a terminal.

It does not know whether a browser even exists.

It owns rules and state.

The game's four main commands are:

new
click
tick
buy_click_upgrade

We still expose some state so main() can display it.

That part of the front door is wider than I want.

Game, Player, and Enemy still have public fields, which means main() could write:

game.enemy.health = 0;

and the compiler would allow it.

That is a loose end.

We are going to lean on it soon.

It cannot remember

Our game can simulate an hour instantly.

It cannot survive the program ending.

Close the terminal and everything is gone:

stage
gold
XP
level
upgrades

An idle game that forgets you the moment you leave is not much of an idle game.

Next time, the game learns to save itself.

Not to a file.

Not to a browser.

Not to a server.

The library will not know where saves go, and it should not.

It will only know how to say, in a form that can be written down:

This is everything about me.

And later, given that same form:

I remember.

Small function. Bigger game.

Kill a slime, get paid, level up, buy damage, kill a tougher slime.

It still stops the moment you stop clicking.

So today we are going to make time part of the game.

Not a timer. Not a clock. Not sleep.

Just a number.

Because the game will never look at a clock, we can test a full hour away in a fraction of a second.

By the end, an hour away from the game is one line:

game.tick(3600);

And here is what the game looks like when you come back:

One hour away.
Stage 4 -> 131  Level 2 -> 48  Gold 11 -> 17410

Our starting point

If you are only reading along, you can skip past this code to "Time is just a number."

If you are building along, you need three structs, an enum, three impl blocks, eleven small functions, and sixteen tests:

struct Player {
    gold: u32,
    xp: u32,
    level: u32,
    click_upgrade_level: u32,
}

struct Enemy {
    name: String,
    health: u32,
    gold_reward: u32,
    xp_reward: u32,
}

struct Game {
    stage: u32,
    player: Player,
    enemy: Enemy,
}

#[derive(Debug, PartialEq)]
enum PurchaseOutcome {
    Purchased,
    NotEnoughGold,
}

impl Player {
    fn new() -> Player {
        Player {
            gold: 0,
            xp: 0,
            level: 1,
            click_upgrade_level: 0,
        }
    }

    fn add_gold(&mut self, amount: u32) {
        self.gold = self.gold.saturating_add(amount);
    }

    fn add_xp(&mut self, amount: u32) {
        self.xp = self.xp.saturating_add(amount);

        while self.xp >= xp_to_next_level(self.level) {
            self.xp -= xp_to_next_level(self.level);
            self.level = self.level.saturating_add(1);
        }
    }

    fn base_damage(&self) -> u32 {
        base_damage_for_level(self.level)
    }

    fn bonus_damage(&self) -> u32 {
        click_upgrade_bonus(self.click_upgrade_level)
    }

    fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        let cost = click_upgrade_cost(self.click_upgrade_level);

        if self.gold < cost {
            return PurchaseOutcome::NotEnoughGold;
        }

        self.gold -= cost;
        self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);

        PurchaseOutcome::Purchased
    }
}

impl Enemy {
    fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
            xp_reward: xp_reward_for_stage(stage),
        }
    }
}

impl Game {
    fn new() -> Game {
        Game {
            stage: 1,
            player: Player::new(),
            enemy: Enemy::for_stage(1),
        }
    }

    fn click(&mut self) {
        attack(&self.player, &mut self.enemy);

        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

    fn defeat_enemy(&mut self) {
        self.player.add_gold(self.enemy.gold_reward);
        self.player.add_xp(self.enemy.xp_reward);

        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }

    fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        self.player.buy_click_upgrade()
    }
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

fn gold_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(3)
}

fn xp_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(4)
}

fn xp_to_next_level(level: u32) -> u32 {
    level
        .saturating_sub(1)
        .saturating_mul(15)
        .saturating_add(20)
}

fn base_damage_for_level(level: u32) -> u32 {
    level.saturating_add(4)
}

fn click_upgrade_bonus(upgrades: u32) -> u32 {
    upgrades.saturating_mul(2)
}

fn click_upgrade_cost(upgrades: u32) -> u32 {
    upgrades.saturating_add(1).saturating_mul(10)
}

fn attack(player: &Player, enemy: &mut Enemy) {
    let damage = click_damage(player.base_damage(), player.bonus_damage());

    enemy.health = health_after_hit(enemy.health, damage);
}

fn main() {
    let mut game = Game::new();

    while game.stage <= 8 {
        let stage = game.stage;
        let level = game.player.level;

        game.click();

        if game.stage > stage {
            println!(
                "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
                game.player.gold,
                game.player.xp,
                xp_to_next_level(game.player.level)
            );

            if game.player.level > level {
                println!(
                    "Level up! Now level {}. Click damage: {}",
                    game.player.level,
                    click_damage(game.player.base_damage(), game.player.bonus_damage())
                );
            }

            println!(
                "  Next up: {} with {} health.",
                game.enemy.name, game.enemy.health
            );
        }

        match game.buy_click_upgrade() {
            PurchaseOutcome::Purchased => println!(
                "Bought click upgrade {}! Click damage: {}  Gold left: {}",
                game.player.click_upgrade_level,
                click_damage(game.player.base_damage(), game.player.bonus_damage()),
                game.player.gold
            ),
            PurchaseOutcome::NotEnoughGold => {}
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player::new();

        let mut enemy = Enemy::for_stage(1);
        enemy.health = 10;

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 5);
    }

    #[test]
    fn later_stages_have_tougher_enemies() {
        assert_eq!(enemy_health_for_stage(1), 20);
        assert_eq!(enemy_health_for_stage(2), 30);
    }

    #[test]
    fn later_stages_pay_better() {
        assert_eq!(gold_reward_for_stage(1), 5);
        assert_eq!(gold_reward_for_stage(2), 7);
        assert_eq!(xp_reward_for_stage(1), 6);
        assert_eq!(xp_reward_for_stage(2), 8);
    }

    #[test]
    fn levels_need_more_xp_as_they_go() {
        assert_eq!(xp_to_next_level(1), 20);
        assert_eq!(xp_to_next_level(2), 35);
    }

    #[test]
    fn leveling_up_keeps_leftover_xp() {
        let mut player = Player::new();

        player.add_xp(25);

        assert_eq!(player.level, 2);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn a_big_reward_can_skip_levels() {
        let mut player = Player::new();

        player.add_xp(60);

        assert_eq!(player.level, 3);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn levels_make_the_player_hit_harder() {
        assert_eq!(base_damage_for_level(1), 5);
        assert_eq!(base_damage_for_level(2), 6);
    }

    #[test]
    fn upgrades_cost_more_each_time() {
        assert_eq!(click_upgrade_cost(0), 10);
        assert_eq!(click_upgrade_cost(1), 20);
    }

    #[test]
    fn buying_an_upgrade_needs_gold() {
        let mut player = Player::new();

        assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::NotEnoughGold);
        assert_eq!(player.click_upgrade_level, 0);
        assert_eq!(player.bonus_damage(), 0);
    }

    #[test]
    fn buying_an_upgrade_spends_gold() {
        let mut player = Player::new();
        player.gold = 12;

        assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::Purchased);
        assert_eq!(player.gold, 2);
        assert_eq!(player.click_upgrade_level, 1);
        assert_eq!(player.bonus_damage(), 2);
    }

    #[test]
    fn a_new_game_starts_at_stage_one() {
        let game = Game::new();

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
        assert_eq!(game.player.gold, 0);
    }

    #[test]
    fn clicking_damages_the_enemy() {
        let mut game = Game::new();

        game.click();

        assert_eq!(game.enemy.health, 15);
    }

    #[test]
    fn defeating_an_enemy_pays_the_player() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }
}

Run it, and the player clears eight stages and buys three upgrades.

Then the program is over, and so is all the progress, because nothing in it ever happens on its own.

Time is just a number

An idle game has to keep going while nobody is looking.

The obvious way to build that is to give the game a clock.

Start a timer. Every second, do some work. When the player leaves, keep the timer running.

That sounds simple, and it is a trap.

A game that watches a clock is a game that has to be tested by waiting, unless you build a fake clock, and then you have rebuilt the idea we are about to use anyway.

Want to know what happens after an hour away? Wait an hour.

So let's turn it around.

The game will not ask what time it is.

Whoever is running the game will tell it how much time went by:

game.tick(10);

Ten seconds passed. What happened?

Game code often uses the word tick for advancing simulation time, so we will borrow the name.

The contract is one sentence:

Tell me how many seconds passed. I will tell you what the game became.

tick will be a method on Game, and the only thing it takes is that number.

The number is the only thing about time that Rust ever sees.

Later in this series, a web page will measure real time and hand the game that number.

For now, our tests can hand it any number they like.

What does a player do while nobody is clicking?

Before the game can work out what happened, it needs to know what the player does with spare seconds.

Our player is going to keep fighting.

One hit per second, and the harder the player has leveled up, the harder it hits.

That is a game rule, and we know what to do with game rules by now.

Give it a small function, next to the others:

fn idle_damage_for_level(level: u32) -> u32 {
    level
}

One damage per second at level 1.

Two at level 2.

It is deliberately small. It is not balanced and it does not need to be yet.

It also ignores the click upgrades on purpose. Those are for clicking.

What matters is that the rule has a name and a test.

Add it at the bottom of the tests module:

#[test]
fn idle_damage_grows_with_level() {
    assert_eq!(idle_damage_for_level(1), 1);
    assert_eq!(idle_damage_for_level(2), 2);
}

Notice what the function does not take.

It does not take a Player. It does not take a Game.

It takes a level and returns a number. It is the same kind of function as base_damage_for_level(), and it asks the same question: what does this level of progress get you?

If you run cargo build now, Rust warns that idle_damage_for_level is never used.

We are about to use it.

One second at a time

Now for tick().

The player hits once per second, so ten seconds is ten hits.

We know exactly how many times to repeat: once per second that passed.

That is not a job for while.

A while loop keeps going until a condition stops being true, like our level-up loop, which cannot know how many levels one reward will cross.

When you know the count in advance, Rust has a loop for that:

for _ in 0..seconds {
    // one second of work
}

0..seconds is a range.

It counts from 0 up to, but not including, seconds.

So 0..3 gives you 0, 1, and 2. That is three trips through the loop, which is exactly what we want for three seconds.

The _ is a placeholder that means:

I do not need this value.

A for loop hands us the current number from the range on every trip.

We do not care which second we are on. We only care that one passed.

If we gave the number a name like second, Rust would warn that we never use it.

The _ says that is on purpose.

Write the first version inside the impl Game block, right under click(). It is indented because it lives inside that block:

    fn tick(&mut self, seconds: u32) {
        for _ in 0..seconds {
            let damage = idle_damage_for_level(self.player.level);

            self.enemy.health = health_after_hit(self.enemy.health, damage);
        }
    }

Each trip through the loop works out the damage for the player's current level and hits the enemy with it.

It uses health_after_hit(), the same small rule that has been protecting enemy health since the first article.

That looks finished.

It is not, and we should have a test to say so.

The slime that died and kept being hit

We have a rule for how fast the player hits.

What we need next is a test for the thing a player cares about: if I wait long enough, does the slime go down?

At level 1, our player hits for 1 per second, and the first slime has 20 health.

Twenty seconds should do it:

#[test]
fn enough_time_defeats_the_enemy() {
    let mut game = Game::new();

    game.tick(20);

    assert_eq!(game.stage, 2);
    assert_eq!(game.enemy.health, 30);
    assert_eq!(game.player.gold, 5);
    assert_eq!(game.player.xp, 6);
}

Those last numbers should look familiar.

They are the same ones the click version of this test checks: stage 2, a 30 health enemy, 5 gold, 6 XP.

It does not matter whether a slime dies from a click or from a wait.

The player should get paid the same either way.

Run it:

cargo test enough_time

and it fails:

assertion `left == right` failed
  left: 1
 right: 2

(Rust prints more than that, including a line number and a note about backtraces. This is the part that matters.)

left is what the game did. right is what the test expected.

The stage is still 1.

Twenty seconds passed. The slime's health reached zero on the twentieth hit.

And then nothing happened.

Our loop never asks whether the enemy is defeated.

That check lives in click():

        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }

tick() took the hit from click() but left the aftermath behind.

Two ways to land a hit

There are two ways to hurt an enemy now: a click, and a second of waiting.

Both of them need the same thing to happen afterward.

If we paste the if into tick(), we have the same three lines in two places.

Then the next time defeating an enemy needs to change, we have to remember both.

We have seen this before.

When the same enemy was being built in three different places, we gave the building a name, and Enemy::for_stage() became the one place that builds an enemy.

Same fix here.

Add a method inside the same impl Game block, under tick():

    fn resolve_hit(&mut self) {
        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

Read it out loud:

A hit just landed. If the enemy went down, handle the defeat.

Now both ways of landing a hit can finish the same way.

Replace the whole click() method with this one. The old if is gone, and a call to resolve_hit() takes its place:

    fn click(&mut self) {
        attack(&self.player, &mut self.enemy);
        self.resolve_hit();
    }

And replace tick() with this. Only the last line inside the loop is new:

    fn tick(&mut self, seconds: u32) {
        for _ in 0..seconds {
            let damage = idle_damage_for_level(self.player.level);

            self.enemy.health = health_after_hit(self.enemy.health, damage);
            self.resolve_hit();
        }
    }

Run the tests again:

cargo test

All eighteen pass, including the clicking tests we did not touch.

That is what a good extraction looks like.

click() does the same thing it did before.

It just does it by calling a method that tick() can call too.

Now follow the path of the twentieth second:

tick()
    ↓
health_after_hit() → 0
    ↓
resolve_hit()
    ↓
defeat_enemy()
    ↓
gold, XP, next stage, next enemy

That bottom half is the same code a click reaches.

The slime can die from a click or from a second of waiting.

Either way, it dies the same way.

Test time without waiting

Look at what we just tested.

Twenty seconds of game time ran, and the test finished instantly.

Nothing slept. Nothing waited.

The game does not know what a second is.

It was handed the number 20 and did twenty steps of work.

That is the payoff for the design.

Time is an input, so a test can supply as much of it as it likes.

Three more tests are worth adding. Put each one at the bottom of the tests module.

One second should be one hit:

#[test]
fn one_second_is_one_idle_hit() {
    let mut game = Game::new();

    game.tick(1);

    assert_eq!(game.enemy.health, 19);
}

Zero seconds should change nothing:

#[test]
fn zero_seconds_changes_nothing() {
    let mut game = Game::new();

    game.tick(0);

    assert_eq!(game.stage, 1);
    assert_eq!(game.enemy.health, 20);
}

We did not write any code to handle zero.

We did not need to.

0..0 is an empty range, so the loop runs zero times and the game stays exactly as it was.

The last test is the one that matters most.

Waiting forty-five seconds in one go should give the same game as waiting one second forty-five times:

#[test]
fn one_long_tick_matches_many_short_ones() {
    let mut long = Game::new();
    let mut short = Game::new();

    long.tick(45);

    for _ in 0..45 {
        short.tick(1);
    }

    assert_eq!(long.stage, short.stage);
    assert_eq!(long.enemy.health, short.enemy.health);
    assert_eq!(long.player.gold, short.player.gold);
    assert_eq!(long.player.xp, short.player.xp);
    assert_eq!(long.player.level, short.player.level);
}

This one passes by construction today, because tick(45) literally is forty-five single steps.

Today it almost looks redundant. Later, when we replace thousands of tiny steps with arithmetic, it becomes the test that proves the optimization did not change the game.

It is a promise to our future selves.

Later, a browser will sometimes call tick(1) every second.

Other times, it will come back after a long absence and call tick(7200) once.

Those two have to be the same game.

If a change ever makes them different, this test will say so.

Run them all:

cargo test

Twenty-one tests should pass.

Leave for an hour

Time to try it for real.

We are going to leave the loop in main() exactly as it is, with one change: stop at stage 3, so the output is short.

    while game.stage <= 3 {

Everything inside the loop stays the same.

Then, after the loop, the player leaves.

Add this after the closing brace of the while loop, still inside main():

    let stage = game.stage;
    let level = game.player.level;
    let gold = game.player.gold;

    game.tick(3600);

    println!("One hour away.");
    println!(
        "Stage {} -> {}  Level {} -> {}  Gold {} -> {}",
        stage, game.stage, level, game.player.level, gold, game.player.gold
    );

Three thousand six hundred is the number of seconds in an hour.

Run it:

cargo run

You should see:

Stage 1 cleared!  Gold: 5  XP: 6/20
  Next up: Training Slime with 30 health.
Stage 2 cleared!  Gold: 12  XP: 14/20
  Next up: Training Slime with 40 health.
Bought click upgrade 1! Click damage: 7  Gold left: 2
Stage 3 cleared!  Gold: 11  XP: 4/35
Level up! Now level 2. Click damage: 8
  Next up: Training Slime with 50 health.
One hour away.
Stage 4 -> 131  Level 2 -> 48  Gold 11 -> 17410

The first half is the player, clicking their way through three stages.

The last two lines are the hour.

One hour, with nobody at the keyboard, took the game from stage 4 to stage 131.

The player also came home with 17,410 gold and nothing spent. Noted.

Look at the level.

It went from 2 to 48.

That was not a bug.

Every trip through the for loop asks for the damage at the player's current level.

When a slime pays out enough XP, the player levels up in the middle of the hour, and every second after that hits a little harder.

Waiting makes the player stronger, which makes waiting faster.

That is the shape of an idle game.

Is it balanced? No.

A stage 131 slime after an hour is a lot.

We will tune that later. We have a rule with a name and a test, so tuning it is changing one function.

What matters today is that the engine can answer a question it could not answer before:

What happened while I was away?

Who owns the clock?

The game never asked what time it was.

It was handed 3600, and it did 3600 seconds of work.

That is going to become one of the most important lines in this series:

Rust owns the rules.
Whatever runs the game owns time.

Today, that caller is a test or main(). Later, it will be a web page.

The caller measures how much real time passed and hands that fact to the game.

Rust decides what that time means for gameplay.

That distinction matters. A browser might report that 28,800 seconds passed while the player was away. The game can still decide that only part of that time should count.

In other words:

caller measures elapsed time
        ↓
Rust receives the number
        ↓
Rust decides how much time counts
        ↓
Rust applies the game rules

That keeps balance decisions inside the game instead of hiding them in whichever environment happens to run it.

There is one honest cost.

tick() does one trip through the loop for every second.

An hour is 3,600 trips. A day is 86,400.

That is still manageable for this tiny program, but the cost grows directly with the number of seconds we simulate.

A number like u32::MAX would be a very long walk.

Later, we can cap credited away-time or replace repeated steps with arithmetic. The caller will still report elapsed time; Rust will still own the policy and the rules.

The complete program

If you are only reading along, skip to the last two sections.

If you have been following along in your editor, here is everything in one place.

At this point, src/main.rs should look like this:

struct Player {
    gold: u32,
    xp: u32,
    level: u32,
    click_upgrade_level: u32,
}

struct Enemy {
    name: String,
    health: u32,
    gold_reward: u32,
    xp_reward: u32,
}

struct Game {
    stage: u32,
    player: Player,
    enemy: Enemy,
}

#[derive(Debug, PartialEq)]
enum PurchaseOutcome {
    Purchased,
    NotEnoughGold,
}

impl Player {
    fn new() -> Player {
        Player {
            gold: 0,
            xp: 0,
            level: 1,
            click_upgrade_level: 0,
        }
    }

    fn add_gold(&mut self, amount: u32) {
        self.gold = self.gold.saturating_add(amount);
    }

    fn add_xp(&mut self, amount: u32) {
        self.xp = self.xp.saturating_add(amount);

        while self.xp >= xp_to_next_level(self.level) {
            self.xp -= xp_to_next_level(self.level);
            self.level = self.level.saturating_add(1);
        }
    }

    fn base_damage(&self) -> u32 {
        base_damage_for_level(self.level)
    }

    fn bonus_damage(&self) -> u32 {
        click_upgrade_bonus(self.click_upgrade_level)
    }

    fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        let cost = click_upgrade_cost(self.click_upgrade_level);

        if self.gold < cost {
            return PurchaseOutcome::NotEnoughGold;
        }

        self.gold -= cost;
        self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);

        PurchaseOutcome::Purchased
    }
}

impl Enemy {
    fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
            xp_reward: xp_reward_for_stage(stage),
        }
    }
}

impl Game {
    fn new() -> Game {
        Game {
            stage: 1,
            player: Player::new(),
            enemy: Enemy::for_stage(1),
        }
    }

    fn click(&mut self) {
        attack(&self.player, &mut self.enemy);
        self.resolve_hit();
    }

    fn tick(&mut self, seconds: u32) {
        for _ in 0..seconds {
            let damage = idle_damage_for_level(self.player.level);

            self.enemy.health = health_after_hit(self.enemy.health, damage);
            self.resolve_hit();
        }
    }

    fn resolve_hit(&mut self) {
        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

    fn defeat_enemy(&mut self) {
        self.player.add_gold(self.enemy.gold_reward);
        self.player.add_xp(self.enemy.xp_reward);

        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }

    fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        self.player.buy_click_upgrade()
    }
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

fn gold_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(3)
}

fn xp_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(4)
}

fn xp_to_next_level(level: u32) -> u32 {
    level
        .saturating_sub(1)
        .saturating_mul(15)
        .saturating_add(20)
}

fn base_damage_for_level(level: u32) -> u32 {
    level.saturating_add(4)
}

fn idle_damage_for_level(level: u32) -> u32 {
    level
}

fn click_upgrade_bonus(upgrades: u32) -> u32 {
    upgrades.saturating_mul(2)
}

fn click_upgrade_cost(upgrades: u32) -> u32 {
    upgrades.saturating_add(1).saturating_mul(10)
}

fn attack(player: &Player, enemy: &mut Enemy) {
    let damage = click_damage(player.base_damage(), player.bonus_damage());

    enemy.health = health_after_hit(enemy.health, damage);
}

fn main() {
    let mut game = Game::new();

    while game.stage <= 3 {
        let stage = game.stage;
        let level = game.player.level;

        game.click();

        if game.stage > stage {
            println!(
                "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
                game.player.gold,
                game.player.xp,
                xp_to_next_level(game.player.level)
            );

            if game.player.level > level {
                println!(
                    "Level up! Now level {}. Click damage: {}",
                    game.player.level,
                    click_damage(game.player.base_damage(), game.player.bonus_damage())
                );
            }

            println!(
                "  Next up: {} with {} health.",
                game.enemy.name, game.enemy.health
            );
        }

        match game.buy_click_upgrade() {
            PurchaseOutcome::Purchased => println!(
                "Bought click upgrade {}! Click damage: {}  Gold left: {}",
                game.player.click_upgrade_level,
                click_damage(game.player.base_damage(), game.player.bonus_damage()),
                game.player.gold
            ),
            PurchaseOutcome::NotEnoughGold => {}
        }
    }

    let stage = game.stage;
    let level = game.player.level;
    let gold = game.player.gold;

    game.tick(3600);

    println!("One hour away.");
    println!(
        "Stage {} -> {}  Level {} -> {}  Gold {} -> {}",
        stage, game.stage, level, game.player.level, gold, game.player.gold
    );
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player::new();

        let mut enemy = Enemy::for_stage(1);
        enemy.health = 10;

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 5);
    }

    #[test]
    fn later_stages_have_tougher_enemies() {
        assert_eq!(enemy_health_for_stage(1), 20);
        assert_eq!(enemy_health_for_stage(2), 30);
    }

    #[test]
    fn later_stages_pay_better() {
        assert_eq!(gold_reward_for_stage(1), 5);
        assert_eq!(gold_reward_for_stage(2), 7);
        assert_eq!(xp_reward_for_stage(1), 6);
        assert_eq!(xp_reward_for_stage(2), 8);
    }

    #[test]
    fn levels_need_more_xp_as_they_go() {
        assert_eq!(xp_to_next_level(1), 20);
        assert_eq!(xp_to_next_level(2), 35);
    }

    #[test]
    fn leveling_up_keeps_leftover_xp() {
        let mut player = Player::new();

        player.add_xp(25);

        assert_eq!(player.level, 2);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn a_big_reward_can_skip_levels() {
        let mut player = Player::new();

        player.add_xp(60);

        assert_eq!(player.level, 3);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn levels_make_the_player_hit_harder() {
        assert_eq!(base_damage_for_level(1), 5);
        assert_eq!(base_damage_for_level(2), 6);
    }

    #[test]
    fn upgrades_cost_more_each_time() {
        assert_eq!(click_upgrade_cost(0), 10);
        assert_eq!(click_upgrade_cost(1), 20);
    }

    #[test]
    fn buying_an_upgrade_needs_gold() {
        let mut player = Player::new();

        assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::NotEnoughGold);
        assert_eq!(player.click_upgrade_level, 0);
        assert_eq!(player.bonus_damage(), 0);
    }

    #[test]
    fn buying_an_upgrade_spends_gold() {
        let mut player = Player::new();
        player.gold = 12;

        assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::Purchased);
        assert_eq!(player.gold, 2);
        assert_eq!(player.click_upgrade_level, 1);
        assert_eq!(player.bonus_damage(), 2);
    }

    #[test]
    fn a_new_game_starts_at_stage_one() {
        let game = Game::new();

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
        assert_eq!(game.player.gold, 0);
    }

    #[test]
    fn clicking_damages_the_enemy() {
        let mut game = Game::new();

        game.click();

        assert_eq!(game.enemy.health, 15);
    }

    #[test]
    fn defeating_an_enemy_pays_the_player() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }

    #[test]
    fn idle_damage_grows_with_level() {
        assert_eq!(idle_damage_for_level(1), 1);
        assert_eq!(idle_damage_for_level(2), 2);
    }

    #[test]
    fn enough_time_defeats_the_enemy() {
        let mut game = Game::new();

        game.tick(20);

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }

    #[test]
    fn one_second_is_one_idle_hit() {
        let mut game = Game::new();

        game.tick(1);

        assert_eq!(game.enemy.health, 19);
    }

    #[test]
    fn zero_seconds_changes_nothing() {
        let mut game = Game::new();

        game.tick(0);

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
    }

    #[test]
    fn one_long_tick_matches_many_short_ones() {
        let mut long = Game::new();
        let mut short = Game::new();

        long.tick(45);

        for _ in 0..45 {
            short.tick(1);
        }

        assert_eq!(long.stage, short.stage);
        assert_eq!(long.enemy.health, short.enemy.health);
        assert_eq!(long.player.gold, short.player.gold);
        assert_eq!(long.player.xp, short.player.xp);
        assert_eq!(long.player.level, short.player.level);
    }
}

Run both:

cargo run
cargo test

The game should clear three stages, buy one upgrade, spend an hour away, and all twenty-one tests should pass.

What we learned

Along the way, we encountered:

• time as a plain number, passed in by the caller
• the tick method
• for loops and ranges like 0..seconds
• _ for a value we do not need
• extracting a shared method so two paths finish the same way
• tests that run an hour without waiting

Two ideas are worth keeping.

The first is how to choose between the two loops we now know.

Ask whether you know the count.

The level-up loop could not know how many levels one reward would cross, so it was a while.

tick() knows exactly how many seconds it was given, so it is a for.

The second is resolve_hit().

The bug was not in the loop. The loop did what we told it.

The bug was that two ways of hurting an enemy had to finish the same way, and only one of them did.

Giving the finish a name fixed it, and now there is one place where "the enemy went down" turns into gold, XP, and a new slime.

You accidentally built a game engine

Open src/main.rs and scroll.

Three structs. An enum. Three impl blocks. Twelve small rules. A click, a purchase, a clock that is not a clock, and twenty-one tests.

All of it is in one file, and the file is getting long.

Nobody planned that.

Each article needed one more thing, and each thing went in the next free spot.

But look at what is in there.

Everything above main() knows nothing about a terminal, a screen, or a clock.

Only main() does.

Today they share a file. Next time, we put a wall between them, and find out that the part on the far side of the wall is already a small game engine.

Small function. Bigger game.

That is not a reward. That is a high score.

So today we are going to sell them something: more damage per click, at a price that goes up every time they buy it.

The shopping is the easy part.

The interesting part is what happens when we try to tell the rest of the program whether the purchase worked.

Because the obvious answer, true or false, turns out to be not quite an answer at all.

Bought click upgrade 1! Click damage: 7  Gold left: 2

Our starting point

If you are only reading along, you can skip past this code to "The free upgrade nobody earned."

If you are building along, you need three structs, three impl blocks, nine small functions, and thirteen tests:

struct Player {
    bonus_damage: u32,
    gold: u32,
    xp: u32,
    level: u32,
}

struct Enemy {
    name: String,
    health: u32,
    gold_reward: u32,
    xp_reward: u32,
}

struct Game {
    stage: u32,
    player: Player,
    enemy: Enemy,
}

impl Player {
    fn new() -> Player {
        Player {
            bonus_damage: 2,
            gold: 0,
            xp: 0,
            level: 1,
        }
    }

    fn add_gold(&mut self, amount: u32) {
        self.gold = self.gold.saturating_add(amount);
    }

    fn add_xp(&mut self, amount: u32) {
        self.xp = self.xp.saturating_add(amount);

        while self.xp >= xp_to_next_level(self.level) {
            self.xp -= xp_to_next_level(self.level);
            self.level = self.level.saturating_add(1);
        }
    }

    fn base_damage(&self) -> u32 {
        base_damage_for_level(self.level)
    }
}

impl Enemy {
    fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
            xp_reward: xp_reward_for_stage(stage),
        }
    }
}

impl Game {
    fn new() -> Game {
        Game {
            stage: 1,
            player: Player::new(),
            enemy: Enemy::for_stage(1),
        }
    }

    fn click(&mut self) {
        attack(&self.player, &mut self.enemy);

        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

    fn defeat_enemy(&mut self) {
        self.player.add_gold(self.enemy.gold_reward);
        self.player.add_xp(self.enemy.xp_reward);

        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

fn gold_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(3)
}

fn xp_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(4)
}

fn xp_to_next_level(level: u32) -> u32 {
    level
        .saturating_sub(1)
        .saturating_mul(15)
        .saturating_add(20)
}

fn base_damage_for_level(level: u32) -> u32 {
    level.saturating_add(4)
}

fn attack(player: &Player, enemy: &mut Enemy) {
    let damage = click_damage(player.base_damage(), player.bonus_damage);

    enemy.health = health_after_hit(enemy.health, damage);
}

fn main() {
    let mut game = Game::new();

    while game.stage <= 8 {
        let stage = game.stage;
        let level = game.player.level;

        game.click();

        if game.stage > stage {
            println!(
                "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
                game.player.gold,
                game.player.xp,
                xp_to_next_level(game.player.level)
            );

            if game.player.level > level {
                println!(
                    "Level up! Now level {}. Click damage: {}",
                    game.player.level,
                    click_damage(game.player.base_damage(), game.player.bonus_damage)
                );
            }

            println!(
                "  Next up: {} with {} health.",
                game.enemy.name, game.enemy.health
            );
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player::new();

        let mut enemy = Enemy::for_stage(1);
        enemy.health = 10;

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 3);
    }

    #[test]
    fn later_stages_have_tougher_enemies() {
        assert_eq!(enemy_health_for_stage(1), 20);
        assert_eq!(enemy_health_for_stage(2), 30);
    }

    #[test]
    fn later_stages_pay_better() {
        assert_eq!(gold_reward_for_stage(1), 5);
        assert_eq!(gold_reward_for_stage(2), 7);
        assert_eq!(xp_reward_for_stage(1), 6);
        assert_eq!(xp_reward_for_stage(2), 8);
    }

    #[test]
    fn levels_need_more_xp_as_they_go() {
        assert_eq!(xp_to_next_level(1), 20);
        assert_eq!(xp_to_next_level(2), 35);
    }

    #[test]
    fn leveling_up_keeps_leftover_xp() {
        let mut player = Player::new();

        player.add_xp(25);

        assert_eq!(player.level, 2);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn a_big_reward_can_skip_levels() {
        let mut player = Player::new();

        player.add_xp(60);

        assert_eq!(player.level, 3);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn levels_make_the_player_hit_harder() {
        assert_eq!(base_damage_for_level(1), 5);
        assert_eq!(base_damage_for_level(2), 6);
    }

    #[test]
    fn a_new_game_starts_at_stage_one() {
        let game = Game::new();

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
        assert_eq!(game.player.gold, 0);
    }

    #[test]
    fn clicking_damages_the_enemy() {
        let mut game = Game::new();

        game.click();

        assert_eq!(game.enemy.health, 13);
    }

    #[test]
    fn defeating_an_enemy_pays_the_player() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }
}

Player stores what the player has earned: gold, XP, and a level. Defeating an enemy pays gold and XP, and enough XP levels the player up.

Click damage comes from two places. base_damage() works it out from the player's level. bonus_damage is just a number stored in the struct.

Run cargo test and all thirteen should pass.

The free upgrade nobody earned

Look at that Player again.

    bonus_damage: u32,

Every new player starts with 2 of it. For free. Since the first time we gave the player a second damage number.

base_damage is already a method, not a field. It is worked out from the player's level, because it is a consequence of that level, not a fact to store.

bonus_damage has the same problem, with a different cause.

Bonus damage should be a consequence of how many upgrades the player has bought.

So the player does not need to store the bonus. The player needs to store the shopping.

Two rules, under base_damage_for_level():

fn click_upgrade_bonus(upgrades: u32) -> u32 {
    upgrades.saturating_mul(2)
}

fn click_upgrade_cost(upgrades: u32) -> u32 {
    upgrades.saturating_add(1).saturating_mul(10)
}

Each upgrade adds 2 damage:

0 upgrades → 0 bonus
1 upgrade  → 2 bonus
2 upgrades → 4 bonus

And each one costs more than the last:

first upgrade  → 10 gold
second upgrade → 20 gold
third upgrade  → 30 gold

Both rules take the number of upgrades already bought. Neither one knows a Player exists.

Now replace the field with a count of purchases:

struct Player {
    gold: u32,
    xp: u32,
    level: u32,
    click_upgrade_level: u32,
}

A new player has bought nothing:

            click_upgrade_level: 0,

And just like base damage, bonus damage becomes a method that asks the rule. Put it under base_damage():

    fn bonus_damage(&self) -> u32 {
        click_upgrade_bonus(self.click_upgrade_level)
    }

attack() gets its second pair of parentheses:

    let damage = click_damage(player.base_damage(), player.bonus_damage());

Notice what Player is made of now.

Player
├── gold
├── xp
├── level
└── click_upgrade_level

Not a single damage number.

Every field is a record of progress: what the player has earned, and what they have done with it.

The damage numbers are worked out from that progress, by rules, on demand.

That is going to matter a great deal in a few articles, when we save the game.

We will only have to save what the player earned. Everything else can be recalculated.

The first fight changes

One honest side effect.

A new player used to hit for 7: 5 base plus 2 free bonus.

Now they hit for 5, because the bonus has to be bought.

The stage 1 slime still has 20 health, so it takes four clicks instead of three.

Two of our tests notice.

clicking_damages_the_enemy expected 13 health after one click. It is 15 now.

attack_reduces_enemy_health expected 3 health left from 10. It is 5.

Update both numbers and run cargo test.

Those tests were not broken. The game changed, and the tests were telling the truth about it.

Buying the upgrade

Here is the first version of the purchase. Add it to impl Player, under bonus_damage():

    fn buy_click_upgrade(&mut self) -> bool {
        let cost = click_upgrade_cost(self.click_upgrade_level);

        if self.gold < cost {
            return false;
        }

        self.gold -= cost;
        self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);

        true
    }

Work out the price.

If the player cannot afford it, stop, and say so.

Otherwise, take the money, add the upgrade, and say so.

Two things to notice.

return false; leaves the method early.

Everything after it only runs if the player could afford the upgrade.

That lets the rest of the method read without an else wrapped around it.

And self.gold -= cost; is a plain minus sign, like the one in add_xp().

The check right above it guarantees self.gold is at least cost, so the subtraction cannot go below zero.

Then Game passes the request along, inside impl Game:

    fn buy_click_upgrade(&mut self) -> bool {
        self.player.buy_click_upgrade()
    }

The game does not know the price of an upgrade.

It does not know what happens when you buy one.

It knows the player handles that.

Nothing calls either method yet, so Rust will warn about both. main() will fix that shortly.

true is not an answer

This works.

Now imagine using it:

if game.buy_click_upgrade() {
    println!("Bought it!");
} else {
    println!("???");
}

What goes in the else?

false means the purchase did not happen.

It does not say why.

Today there is only one reason: not enough gold.

But look at this from the other side.

The code calling buy_click_upgrade() has to remember that false means "not enough gold."

Nothing in the code says so.

Add a second reason to fail someday, say a maximum upgrade level, and false starts meaning two different things.

Every place that checked it is now quietly wrong, and Rust will not say a word.

We want an answer that says what happened in plain words, and that Rust can check for us.

Give the outcome a name

Rust has a type for "one of these specific things":

#[derive(Debug, PartialEq)]
enum PurchaseOutcome {
    Purchased,
    NotEnoughGold,
}

Put it with the structs. It is a type, like they are.

enum is short for enumeration: a type whose values are listed out, one by one.

A PurchaseOutcome is either Purchased or NotEnoughGold.

It cannot be anything else.

It cannot be both.

The two options are called variants, and you name one the same way you reach into a type for a function:

PurchaseOutcome::NotEnoughGold

You can think about bool the same way for this purpose: it also stands for one of exactly two possibilities, true or false.

The difference is that our enum lets us give those possibilities names that belong to our game.

The line above the enum

#[derive(Debug, PartialEq)]

#[derive(...)] asks Rust to generate implementations for the traits we list. Here, that saves us from writing the standard Debug and PartialEq implementations by hand.

PartialEq is what lets == compare two outcomes. Without it, Rust has no idea whether Purchased == Purchased.

Debug is what lets a failing test print the outcome it got, so the failure message can say NotEnoughGold instead of nothing at all.

Our tests will want both.

Use it

Now the purchase can say what happened:

    fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        let cost = click_upgrade_cost(self.click_upgrade_level);

        if self.gold < cost {
            return PurchaseOutcome::NotEnoughGold;
        }

        self.gold -= cost;
        self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);

        PurchaseOutcome::Purchased
    }

Same shape. Same early return.

Only the answers changed, and now they read like the game talking.

Game::buy_click_upgrade() changes its return type to match:

    fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        self.player.buy_click_upgrade()
    }

match: one branch per answer

Rust's match expression gives us a way to handle each possible variant explicitly.

Here is how main() will react to a purchase:

match game.buy_click_upgrade() {
    PurchaseOutcome::Purchased => println!("Bought it!"),
    PurchaseOutcome::NotEnoughGold => {}
}

match looks at the value and runs the branch that fits.

Each line is a pattern, an arrow, and what to do.

The {} on the second branch means: do nothing.

That is allowed. What is not allowed is leaving a variant out.

Delete the NotEnoughGold line and Rust refuses to compile:

error[E0004]: non-exhaustive patterns:
`PurchaseOutcome::NotEnoughGold` not covered

This is the payoff.

With our bool version, the caller had to remember what false meant.

With an enum and match, the possible outcomes are named, and Rust can make us handle every one.

If we add a third variant next month, every match in the program will stop compiling until it says what to do about it.

Rust is keeping a list for us.

main() goes shopping

Add the purchase to the loop, after the stage-cleared block:

        match game.buy_click_upgrade() {
            PurchaseOutcome::Purchased => println!(
                "Bought click upgrade {}! Click damage: {}  Gold left: {}",
                game.player.click_upgrade_level,
                click_damage(game.player.base_damage(), game.player.bonus_damage()),
                game.player.gold
            ),
            PurchaseOutcome::NotEnoughGold => {}
        }

Every turn, main() tries to buy an upgrade, and only says something when it works.

Worth being clear about what that means: in this terminal version, the game buys an upgrade the moment the player can afford one. Nobody is deciding anything.

Later, when this game has a button, the player will choose when to spend. The purchasing rule does not change when that happens. Only who calls it.

Run it:

cargo run

Stage 1 cleared!  Gold: 5  XP: 6/20
  Next up: Training Slime with 30 health.
Stage 2 cleared!  Gold: 12  XP: 14/20
  Next up: Training Slime with 40 health.
Bought click upgrade 1! Click damage: 7  Gold left: 2
Stage 3 cleared!  Gold: 11  XP: 4/35
Level up! Now level 2. Click damage: 8
  Next up: Training Slime with 50 health.
Stage 4 cleared!  Gold: 22  XP: 16/35
  Next up: Training Slime with 60 health.
Bought click upgrade 2! Click damage: 10  Gold left: 2
Stage 5 cleared!  Gold: 15  XP: 30/35
  Next up: Training Slime with 70 health.
Stage 6 cleared!  Gold: 30  XP: 11/50
Level up! Now level 3. Click damage: 11
  Next up: Training Slime with 80 health.
Bought click upgrade 3! Click damage: 13  Gold left: 0
Stage 7 cleared!  Gold: 17  XP: 29/50
  Next up: Training Slime with 90 health.
Stage 8 cleared!  Gold: 36  XP: 49/50
  Next up: Training Slime with 100 health.

Now gold goes somewhere.

It climbs, and then it drops to almost nothing, because something got bought.

Click damage goes 5 → 7 → 8 → 10 → 11 → 13, pushed up from two directions at once: levels the player earns, and upgrades the player buys.

Compare the last line to where we started this article. Ninety-six gold and nothing to do with it, versus thirty-six gold and three upgrades already paid for.

Testing the purchase

The pricing rule gets a test for its numbers:

    #[test]
    fn upgrades_cost_more_each_time() {
        assert_eq!(click_upgrade_cost(0), 10);
        assert_eq!(click_upgrade_cost(1), 20);
    }

Then the two things that can happen.

A broke player cannot buy anything, and a failed purchase changes nothing:

    #[test]
    fn buying_an_upgrade_needs_gold() {
        let mut player = Player::new();

        assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::NotEnoughGold);
        assert_eq!(player.click_upgrade_level, 0);
        assert_eq!(player.bonus_damage(), 0);
    }

    #[test]
    fn buying_an_upgrade_spends_gold() {
        let mut player = Player::new();
        player.gold = 12;

        assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::Purchased);
        assert_eq!(player.gold, 2);
        assert_eq!(player.click_upgrade_level, 1);
        assert_eq!(player.bonus_damage(), 2);
    }

Those assert_eq! lines comparing outcomes are exactly why we asked for PartialEq and Debug.

Without PartialEq, the comparison would not compile. Without Debug, a failure could not tell you which outcome it got instead.

Run them:

cargo test

All sixteen should pass.

The complete program

If you are only reading along, skip to the last two sections.

If you have been following along in your editor, here is everything in one place.

At this point, src/main.rs should look like this:

struct Player {
    gold: u32,
    xp: u32,
    level: u32,
    click_upgrade_level: u32,
}

struct Enemy {
    name: String,
    health: u32,
    gold_reward: u32,
    xp_reward: u32,
}

struct Game {
    stage: u32,
    player: Player,
    enemy: Enemy,
}

#[derive(Debug, PartialEq)]
enum PurchaseOutcome {
    Purchased,
    NotEnoughGold,
}

impl Player {
    fn new() -> Player {
        Player {
            gold: 0,
            xp: 0,
            level: 1,
            click_upgrade_level: 0,
        }
    }

    fn add_gold(&mut self, amount: u32) {
        self.gold = self.gold.saturating_add(amount);
    }

    fn add_xp(&mut self, amount: u32) {
        self.xp = self.xp.saturating_add(amount);

        while self.xp >= xp_to_next_level(self.level) {
            self.xp -= xp_to_next_level(self.level);
            self.level = self.level.saturating_add(1);
        }
    }

    fn base_damage(&self) -> u32 {
        base_damage_for_level(self.level)
    }

    fn bonus_damage(&self) -> u32 {
        click_upgrade_bonus(self.click_upgrade_level)
    }

    fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        let cost = click_upgrade_cost(self.click_upgrade_level);

        if self.gold < cost {
            return PurchaseOutcome::NotEnoughGold;
        }

        self.gold -= cost;
        self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);

        PurchaseOutcome::Purchased
    }
}

impl Enemy {
    fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
            xp_reward: xp_reward_for_stage(stage),
        }
    }
}

impl Game {
    fn new() -> Game {
        Game {
            stage: 1,
            player: Player::new(),
            enemy: Enemy::for_stage(1),
        }
    }

    fn click(&mut self) {
        attack(&self.player, &mut self.enemy);

        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

    fn defeat_enemy(&mut self) {
        self.player.add_gold(self.enemy.gold_reward);
        self.player.add_xp(self.enemy.xp_reward);

        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }

    fn buy_click_upgrade(&mut self) -> PurchaseOutcome {
        self.player.buy_click_upgrade()
    }
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

fn gold_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(3)
}

fn xp_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(4)
}

fn xp_to_next_level(level: u32) -> u32 {
    level
        .saturating_sub(1)
        .saturating_mul(15)
        .saturating_add(20)
}

fn base_damage_for_level(level: u32) -> u32 {
    level.saturating_add(4)
}

fn click_upgrade_bonus(upgrades: u32) -> u32 {
    upgrades.saturating_mul(2)
}

fn click_upgrade_cost(upgrades: u32) -> u32 {
    upgrades.saturating_add(1).saturating_mul(10)
}

fn attack(player: &Player, enemy: &mut Enemy) {
    let damage = click_damage(player.base_damage(), player.bonus_damage());

    enemy.health = health_after_hit(enemy.health, damage);
}

fn main() {
    let mut game = Game::new();

    while game.stage <= 8 {
        let stage = game.stage;
        let level = game.player.level;

        game.click();

        if game.stage > stage {
            println!(
                "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
                game.player.gold,
                game.player.xp,
                xp_to_next_level(game.player.level)
            );

            if game.player.level > level {
                println!(
                    "Level up! Now level {}. Click damage: {}",
                    game.player.level,
                    click_damage(game.player.base_damage(), game.player.bonus_damage())
                );
            }

            println!(
                "  Next up: {} with {} health.",
                game.enemy.name, game.enemy.health
            );
        }

        match game.buy_click_upgrade() {
            PurchaseOutcome::Purchased => println!(
                "Bought click upgrade {}! Click damage: {}  Gold left: {}",
                game.player.click_upgrade_level,
                click_damage(game.player.base_damage(), game.player.bonus_damage()),
                game.player.gold
            ),
            PurchaseOutcome::NotEnoughGold => {}
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player::new();

        let mut enemy = Enemy::for_stage(1);
        enemy.health = 10;

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 5);
    }

    #[test]
    fn later_stages_have_tougher_enemies() {
        assert_eq!(enemy_health_for_stage(1), 20);
        assert_eq!(enemy_health_for_stage(2), 30);
    }

    #[test]
    fn later_stages_pay_better() {
        assert_eq!(gold_reward_for_stage(1), 5);
        assert_eq!(gold_reward_for_stage(2), 7);
        assert_eq!(xp_reward_for_stage(1), 6);
        assert_eq!(xp_reward_for_stage(2), 8);
    }

    #[test]
    fn levels_need_more_xp_as_they_go() {
        assert_eq!(xp_to_next_level(1), 20);
        assert_eq!(xp_to_next_level(2), 35);
    }

    #[test]
    fn leveling_up_keeps_leftover_xp() {
        let mut player = Player::new();

        player.add_xp(25);

        assert_eq!(player.level, 2);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn a_big_reward_can_skip_levels() {
        let mut player = Player::new();

        player.add_xp(60);

        assert_eq!(player.level, 3);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn levels_make_the_player_hit_harder() {
        assert_eq!(base_damage_for_level(1), 5);
        assert_eq!(base_damage_for_level(2), 6);
    }

    #[test]
    fn upgrades_cost_more_each_time() {
        assert_eq!(click_upgrade_cost(0), 10);
        assert_eq!(click_upgrade_cost(1), 20);
    }

    #[test]
    fn buying_an_upgrade_needs_gold() {
        let mut player = Player::new();

        assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::NotEnoughGold);
        assert_eq!(player.click_upgrade_level, 0);
        assert_eq!(player.bonus_damage(), 0);
    }

    #[test]
    fn buying_an_upgrade_spends_gold() {
        let mut player = Player::new();
        player.gold = 12;

        assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::Purchased);
        assert_eq!(player.gold, 2);
        assert_eq!(player.click_upgrade_level, 1);
        assert_eq!(player.bonus_damage(), 2);
    }

    #[test]
    fn a_new_game_starts_at_stage_one() {
        let game = Game::new();

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
        assert_eq!(game.player.gold, 0);
    }

    #[test]
    fn clicking_damages_the_enemy() {
        let mut game = Game::new();

        game.click();

        assert_eq!(game.enemy.health, 15);
    }

    #[test]
    fn defeating_an_enemy_pays_the_player() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }
}

Run both:

cargo run
cargo test

The game should clear eight stages, buying three upgrades along the way, and all sixteen tests should pass.

What we learned

Along the way, we encountered:

• a second rule-derived value, replacing a stored one
• early return
• enum and variants
• #[derive(Debug, PartialEq)]
• match, and the compiler refusing to let us forget a case

Two ideas are worth keeping.

The first finishes the job base_damage() started. Player has no damage numbers in it at all now. It stores progress, and damage is a rule applied to that progress.

The second is PurchaseOutcome.

When a bool would have made the caller remember what false meant, we gave the answers names instead, and Rust started checking that every answer gets handled.

That pattern shows up everywhere in Rust. Two common examples you will eventually meet are Option, for a value that might not be there, and Result, for an operation that might have failed.

This is the first time we needed our own. It will not be the last.

Nothing happens unless you click

Our game finally has a progression loop.

Kill a slime, get paid, level up, buy damage, kill a tougher slime.

There is just one problem with calling it an idle game.

clicks per second while you are playing: a lot
clicks per second while you are not:    zero

Nothing happens unless you click.

Walk away, come back an hour later, and the slime is exactly where you left it.

An idle game is supposed to keep working while you do not.

Next time, we are going to give the game time.

Not a timer. Not a clock. Just a number: how many seconds went by.

The game will take that number and work out everything that should have happened.

Small function. Bigger game.

Click. The slime falls. A tougher one oozes in. Click.

That is a loop.

It is also a treadmill.

Every slime gets stronger. Our player never does.

In this article, winning starts to pay: gold and experience for every kill, and levels that make the player hit harder.

By the end, clearing a stage prints this:

Stage 3 cleared!  Gold: 21  XP: 4/35
Level up! Now level 2. Click damage: 8
  Next up: Training Slime with 50 health.

Our starting point

If you are only reading along, you can skip past this code to "Where does the gold go?"

If you are building along, you need three structs, two impl blocks, five small functions, and eight tests:

struct Player {
    base_damage: u32,
    bonus_damage: u32,
}

struct Enemy {
    name: String,
    health: u32,
}

struct Game {
    stage: u32,
    player: Player,
    enemy: Enemy,
}

impl Enemy {
    fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
        }
    }
}

impl Game {
    fn new() -> Game {
        Game {
            stage: 1,
            player: Player {
                base_damage: 5,
                bonus_damage: 2,
            },
            enemy: Enemy::for_stage(1),
        }
    }

    fn click(&mut self) {
        attack(&self.player, &mut self.enemy);

        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

    fn defeat_enemy(&mut self) {
        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

fn attack(player: &Player, enemy: &mut Enemy) {
    let damage = click_damage(player.base_damage, player.bonus_damage);

    enemy.health = health_after_hit(enemy.health, damage);
}

fn main() {
    let mut game = Game::new();

    while game.stage <= 3 {
        let stage = game.stage;

        game.click();

        if game.stage > stage {
            println!("Stage {stage} cleared!");
        } else {
            println!("{} health: {}", game.enemy.name, game.enemy.health);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player {
            base_damage: 5,
            bonus_damage: 2,
        };

        let mut enemy = Enemy {
            name: String::from("Training Slime"),
            health: 10,
        };

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 3);
    }

    #[test]
    fn later_stages_have_tougher_enemies() {
        assert_eq!(enemy_health_for_stage(1), 20);
        assert_eq!(enemy_health_for_stage(2), 30);
    }

    #[test]
    fn a_new_game_starts_at_stage_one() {
        let game = Game::new();

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
    }

    #[test]
    fn clicking_damages_the_enemy() {
        let mut game = Game::new();

        game.click();

        assert_eq!(game.enemy.health, 13);
    }

    #[test]
    fn defeating_an_enemy_advances_the_stage() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
    }
}

game.click() attacks the enemy. If that attack kills it, defeat_enemy() advances the stage and sends in the next one.

The tests hold those rules in place. Three of them are about to change, so it helps to see them as they are now.

Everything today builds on that.

Where does the gold go?

Defeating an enemy should pay.

Before we can pay the player, the player needs somewhere to put the money.

Right now, our Player has two fields, and neither of them is a wallet.

Add one:

struct Player {
    base_damage: u32,
    bonus_damage: u32,
    gold: u32,
}

Rust immediately complains.

Every place we build a Player now has to say how much gold it starts with.

There are two of those: Game::new() and the attack_reduces_enemy_health test. (cargo run only finds the first one, because it does not compile the tests. cargo test finds both.)

We are about to change Player a few more times today, and we do not want to chase every field through every place a player gets built.

Enemy::for_stage() already solves this exact problem for enemies.

Give Player the same treatment:

impl Player {
    fn new() -> Player {
        Player {
            base_damage: 5,
            bonus_damage: 2,
            gold: 0,
        }
    }
}

Put it right after the structs, next to impl Enemy.

Same convention as Game::new(): new is not a Rust keyword, just the name Rust programmers use for "make me a fresh one of these."

Then use it in Game::new():

            player: Player::new(),

and in the test:

        let player = Player::new();

Now there is exactly one place that knows what a new player looks like.

When Player changes again, and it will, that is the only place we touch.

While you are in the tests, a_new_game_starts_at_stage_one can check that the wallet starts empty:

    assert_eq!(game.player.gold, 0);

Run cargo test.

All eight should still pass.

If you cargo run instead, Rust warns that gold is never read. A warning, not an error. The game is about to read it.

How much is a slime worth?

How much gold should a defeated enemy drop?

That is a game rule.

Game rules get their own small function, like enemy_health_for_stage().

Give this one the same treatment, right next to it:

fn gold_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(3)
}

stage 1 → 5 gold
stage 2 → 7 gold
stage 3 → 9 gold

Later enemies are tougher.

They should also pay better.

Now, where does that reward live?

It belongs to the enemy.

A slime knows how much health it has.

It should also know what it is worth:

struct Enemy {
    name: String,
    health: u32,
    gold_reward: u32,
}

And Enemy::for_stage() fills it in:

impl Enemy {
    fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
        }
    }
}

Because every enemy is built through for_stage(), this is the only place that needed to change.

Now run cargo test again.

cargo run would build, with one more never-read warning, because the game only builds enemies through for_stage().

The tests do not build. attack_reduces_enemy_health builds an Enemy by hand, with a name and 10 health, and Rust wants a gold_reward there too.

That is the compiler finding the last place for us.

Instead of making that test learn about rewards, let it start from a real enemy and adjust the one thing it cares about:

        let mut enemy = Enemy::for_stage(1);
        enemy.health = 10;

The test still checks what it always checked: an attack takes health off the enemy.

Paying out

The player has a wallet. The enemy has a price on its head.

Handing one to the other is the player's job.

Add a method to impl Player, under new():

    fn add_gold(&mut self, amount: u32) {
        self.gold = self.gold.saturating_add(amount);
    }

&mut self is the same &mut self from click().

The method borrows the player, changes it, and gives it back.

Which brings us to defeat_enemy(), the one place in the game that already knows an enemy just died.

It grows:

    fn defeat_enemy(&mut self) {
        self.player.add_gold(self.enemy.gold_reward);

        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }

The order matters.

We pay the player before the enemy is replaced.

On the next line, self.enemy becomes a brand new slime with a brand new reward.

If we paid afterward, the player would get paid for an enemy they have not fought yet.

Read defeat_enemy() out loud now:

Pay the player. Go to the next stage. Bring in the next enemy.

No arithmetic to decode.

Experience and levels

Gold is something to spend.

Experience, or XP, is something to keep.

Every defeated enemy should also give the player experience, and when they have enough, they level up.

That is two rules, so we need two numbers:

how much XP does an enemy give?
how much XP does the next level take?

The first one looks like the gold rule.

Put it right under gold_reward_for_stage():

fn xp_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(4)
}

The second one is new.

Each level should take a little more than the last:

fn xp_to_next_level(level: u32) -> u32 {
    level
        .saturating_sub(1)
        .saturating_mul(15)
        .saturating_add(20)
}

level 1 → 20 XP to reach level 2
level 2 → 35 XP to reach level 3
level 3 → 50 XP to reach level 4

That chain is split across lines so each step is easy to read. A line starting with . just continues the line above it.

Level 1 is the starting line. The saturating_sub(1) makes it count as zero steps taken, so level 1 needs the plain 20 and every level after that adds 15. Without it, the first level would already cost 35.

The exact numbers do not matter yet.

They have names and they will have tests.

The enemy carries its XP reward the same way it carries gold:

struct Enemy {
    name: String,
    health: u32,
    gold_reward: u32,
    xp_reward: u32,
}

Add it to Enemy::for_stage(), under gold_reward:

            xp_reward: xp_reward_for_stage(stage),

And the player needs two more fields: how much XP they have, and what level they are:

struct Player {
    base_damage: u32,
    bonus_damage: u32,
    gold: u32,
    xp: u32,
    level: u32,
}

In Player::new():

            xp: 0,
            level: 1,

That is now the normal place a fresh player is built, so future changes stay concentrated there.

Run cargo test. Still eight, plus a few warnings that the new fields and xp_to_next_level() are never used. The next section uses them.

Leveling up

Now the interesting part.

Adding XP is not like adding gold.

Gold just piles up.

XP piles up until it crosses a line, and then something happens:

    fn add_xp(&mut self, amount: u32) {
        self.xp = self.xp.saturating_add(amount);

        while self.xp >= xp_to_next_level(self.level) {
            self.xp -= xp_to_next_level(self.level);
            self.level = self.level.saturating_add(1);
        }
    }

Add it to impl Player, right under add_gold().

Walk through it with a level 1 player who has 0 XP and just earned 25.

The XP becomes 25.

Level 1 needs 20. We have 25. That is enough, so we go into the loop.

Spend 20 of it. XP is now 5. Level is now 2.

Level 2 needs 35. We have 5. The loop stops.

The player is level 2 with 5 XP toward the next one.

Why a while and not an if?

Because a reward might be big enough to cross two lines at once.

Give that same level 1 player 60 XP.

Spend 20 → level 2, 40 left.

Level 2 needs 35. 40 is enough. Spend 35 → level 3, 5 left.

Level 3 needs 50. The loop stops.

An if would have stopped at level 2 and left 40 XP sitting there, more than enough for another level the player never got.

A while keeps going until the XP really is below the line.

You might notice that xp_to_next_level(self.level) gets called twice in a row. That is fine. It is a tiny calculation, and for the same level it always gives the same answer.

That matters more than it looks right now. Later in this series, a player is going to come back after a few hours away and collect a very large pile of XP all at once.

A plain minus sign

Look at this line:

self.xp -= xp_to_next_level(self.level);

-= is shorthand: self.xp -= 20 means self.xp = self.xp - 20.

That is ordinary subtraction, not saturating_sub().

Everywhere else in this program, subtraction goes through saturating_sub().

Here, it is safe, and the line right above it is the reason.

The while only lets us in when self.xp is at least as big as the amount we are about to subtract.

The result can never drop below zero.

saturating_sub() is for when a number might go somewhere it should not.

When the code right next to it proves that it cannot, plain subtraction says exactly what it means.

Now defeat_enemy() pays both:

        self.player.add_gold(self.enemy.gold_reward);
        self.player.add_xp(self.enemy.xp_reward);

What does a level actually do?

Right now, nothing.

The player levels up, and hits exactly as hard as before.

A level should make the player stronger.

Look at Player again:

struct Player {
    base_damage: u32,
    bonus_damage: u32,
    gold: u32,
    xp: u32,
    level: u32,
}

base_damage is a number we wrote down once, when the player was created, and never touched again.

But base damage should not be a fact about the player anymore.

It should be a consequence of the player's level.

That makes it a rule. Put it under xp_to_next_level():

fn base_damage_for_level(level: u32) -> u32 {
    level.saturating_add(4)
}

level 1 → 5 damage
level 2 → 6 damage
level 3 → 7 damage

Level 1 gives 5, which is exactly the base_damage we have had since the beginning.

Nothing about the first fight changes.

Now the field can go.

Remove base_damage from the struct and from Player::new().

Rust will complain about one more place that still uses it. We will get to that in a second.

In its place, give Player a method that asks the rule, right under add_xp():

    fn base_damage(&self) -> u32 {
        base_damage_for_level(self.level)
    }

There is something new in that signature.

&self, without the mut.

So far, our methods have needed &mut self because they changed something.

A method that only needs to read takes &self instead. This is our first one.

base_damage() looks at the player's level and reports a number.

It does not change anything, so it does not ask for permission to.

One thing still uses the old field: attack().

It reads player.base_damage, and that field no longer exists.

Rust says so (the line is wrapped here to fit):

error[E0615]: attempted to take value of method
`base_damage` on type `&Player`

and even suggests the fix: use parentheses to call the method.

fn attack(player: &Player, enemy: &mut Enemy) {
    let damage = click_damage(player.base_damage(), player.bonus_damage);

    enemy.health = health_after_hit(enemy.health, damage);
}

The parentheses are the only difference.

player.base_damage was a number stored in the player.

player.base_damage() is a number the player works out from its level.

attack() did not have to learn anything about levels.

It asked for base damage. It got base damage.

Run cargo test. All eight still pass, and that is the point: a level 1 player still deals 5 base damage, so nothing a test checks has changed.

main() shows the progress

Our main() has been printing the enemy's health after every click.

That was useful when a fight took three clicks. Now there are rewards to watch, so let us print when something happens instead:

fn main() {
    let mut game = Game::new();

    while game.stage <= 8 {
        let stage = game.stage;
        let level = game.player.level;

        game.click();

        if game.stage > stage {
            println!(
                "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
                game.player.gold,
                game.player.xp,
                xp_to_next_level(game.player.level)
            );

            if game.player.level > level {
                println!(
                    "Level up! Now level {}. Click damage: {}",
                    game.player.level,
                    click_damage(game.player.base_damage(), game.player.bonus_damage)
                );
            }

            println!(
                "  Next up: {} with {} health.",
                game.enemy.name, game.enemy.health
            );
        }
    }
}

Before each click, main() remembers the stage and the level.

After the click, it compares.

Stage went up? The enemy died, so say so, show the wallet, and introduce the next one.

Level went up? Say that too.

Notice that the level check sits inside the stage check. It can, because XP is only ever handed out in defeat_enemy(). No enemy died, no XP, no level up.

One small thing about that first println!. {stage} works because stage is a plain variable. game.player.gold has dots in it, so it goes in the list after the string and a bare {} picks it up.

main() still does not know how leveling works.

It does borrow one rule, xp_to_next_level(), so it can show how far away the next level is. That is display, not a decision.

It clicks, it asks, and it prints what it was told.

Run it:

cargo run

Stage 1 cleared!  Gold: 5  XP: 6/20
  Next up: Training Slime with 30 health.
Stage 2 cleared!  Gold: 12  XP: 14/20
  Next up: Training Slime with 40 health.
Stage 3 cleared!  Gold: 21  XP: 4/35
Level up! Now level 2. Click damage: 8
  Next up: Training Slime with 50 health.
Stage 4 cleared!  Gold: 32  XP: 16/35
  Next up: Training Slime with 60 health.
Stage 5 cleared!  Gold: 45  XP: 30/35
  Next up: Training Slime with 70 health.
Stage 6 cleared!  Gold: 60  XP: 11/50
Level up! Now level 3. Click damage: 9
  Next up: Training Slime with 80 health.
Stage 7 cleared!  Gold: 77  XP: 29/50
  Next up: Training Slime with 90 health.
Stage 8 cleared!  Gold: 96  XP: 49/50
  Next up: Training Slime with 100 health.

Read that top to bottom.

Gold climbs. XP climbs toward a line, crosses it, and resets with the leftover carried over. Click damage starts at 7 and climbs to 8, then 9.

Compare that to where we started this article: 5 base damage plus 2 bonus, on stage 1 and on stage 30 alike.

The slimes still get tougher every stage. The difference is that now, so does the player.

Testing the rules

Each new rule gets a test for its numbers. Add these to the tests module:

    #[test]
    fn later_stages_pay_better() {
        assert_eq!(gold_reward_for_stage(1), 5);
        assert_eq!(gold_reward_for_stage(2), 7);
        assert_eq!(xp_reward_for_stage(1), 6);
        assert_eq!(xp_reward_for_stage(2), 8);
    }

    #[test]
    fn levels_need_more_xp_as_they_go() {
        assert_eq!(xp_to_next_level(1), 20);
        assert_eq!(xp_to_next_level(2), 35);
    }

    #[test]
    fn levels_make_the_player_hit_harder() {
        assert_eq!(base_damage_for_level(1), 5);
        assert_eq!(base_damage_for_level(2), 6);
    }

Then the behaviors.

The two walkthroughs from add_xp() become tests, so the explanation and the code can never drift apart:

    #[test]
    fn leveling_up_keeps_leftover_xp() {
        let mut player = Player::new();

        player.add_xp(25);

        assert_eq!(player.level, 2);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn a_big_reward_can_skip_levels() {
        let mut player = Player::new();

        player.add_xp(60);

        assert_eq!(player.level, 3);
        assert_eq!(player.xp, 5);
    }

And the big one.

The last test in our starting point, defeating_an_enemy_advances_the_stage, checked that a win moved the game forward.

Now a win should also pay.

Rename it and add two checks at the end:

    #[test]
    fn defeating_an_enemy_pays_the_player() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }

This test does not care how damage is calculated, or how XP crosses a threshold.

Those rules have their own tests now.

It asks the bigger question:

When a click kills something, does the player get paid for it?

Run them:

cargo test

All thirteen should pass.

The complete program

If you are only reading along, skip to the last two sections.

If you have been following along in your editor, here is everything in one place.

At this point, src/main.rs should look like this:

struct Player {
    bonus_damage: u32,
    gold: u32,
    xp: u32,
    level: u32,
}

struct Enemy {
    name: String,
    health: u32,
    gold_reward: u32,
    xp_reward: u32,
}

struct Game {
    stage: u32,
    player: Player,
    enemy: Enemy,
}

impl Player {
    fn new() -> Player {
        Player {
            bonus_damage: 2,
            gold: 0,
            xp: 0,
            level: 1,
        }
    }

    fn add_gold(&mut self, amount: u32) {
        self.gold = self.gold.saturating_add(amount);
    }

    fn add_xp(&mut self, amount: u32) {
        self.xp = self.xp.saturating_add(amount);

        while self.xp >= xp_to_next_level(self.level) {
            self.xp -= xp_to_next_level(self.level);
            self.level = self.level.saturating_add(1);
        }
    }

    fn base_damage(&self) -> u32 {
        base_damage_for_level(self.level)
    }
}

impl Enemy {
    fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
            gold_reward: gold_reward_for_stage(stage),
            xp_reward: xp_reward_for_stage(stage),
        }
    }
}

impl Game {
    fn new() -> Game {
        Game {
            stage: 1,
            player: Player::new(),
            enemy: Enemy::for_stage(1),
        }
    }

    fn click(&mut self) {
        attack(&self.player, &mut self.enemy);

        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

    fn defeat_enemy(&mut self) {
        self.player.add_gold(self.enemy.gold_reward);
        self.player.add_xp(self.enemy.xp_reward);

        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

fn gold_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(3)
}

fn xp_reward_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(2).saturating_add(4)
}

fn xp_to_next_level(level: u32) -> u32 {
    level
        .saturating_sub(1)
        .saturating_mul(15)
        .saturating_add(20)
}

fn base_damage_for_level(level: u32) -> u32 {
    level.saturating_add(4)
}

fn attack(player: &Player, enemy: &mut Enemy) {
    let damage = click_damage(player.base_damage(), player.bonus_damage);

    enemy.health = health_after_hit(enemy.health, damage);
}

fn main() {
    let mut game = Game::new();

    while game.stage <= 8 {
        let stage = game.stage;
        let level = game.player.level;

        game.click();

        if game.stage > stage {
            println!(
                "Stage {stage} cleared!  Gold: {}  XP: {}/{}",
                game.player.gold,
                game.player.xp,
                xp_to_next_level(game.player.level)
            );

            if game.player.level > level {
                println!(
                    "Level up! Now level {}. Click damage: {}",
                    game.player.level,
                    click_damage(game.player.base_damage(), game.player.bonus_damage)
                );
            }

            println!(
                "  Next up: {} with {} health.",
                game.enemy.name, game.enemy.health
            );
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player::new();

        let mut enemy = Enemy::for_stage(1);
        enemy.health = 10;

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 3);
    }

    #[test]
    fn later_stages_have_tougher_enemies() {
        assert_eq!(enemy_health_for_stage(1), 20);
        assert_eq!(enemy_health_for_stage(2), 30);
    }

    #[test]
    fn later_stages_pay_better() {
        assert_eq!(gold_reward_for_stage(1), 5);
        assert_eq!(gold_reward_for_stage(2), 7);
        assert_eq!(xp_reward_for_stage(1), 6);
        assert_eq!(xp_reward_for_stage(2), 8);
    }

    #[test]
    fn levels_need_more_xp_as_they_go() {
        assert_eq!(xp_to_next_level(1), 20);
        assert_eq!(xp_to_next_level(2), 35);
    }

    #[test]
    fn leveling_up_keeps_leftover_xp() {
        let mut player = Player::new();

        player.add_xp(25);

        assert_eq!(player.level, 2);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn a_big_reward_can_skip_levels() {
        let mut player = Player::new();

        player.add_xp(60);

        assert_eq!(player.level, 3);
        assert_eq!(player.xp, 5);
    }

    #[test]
    fn levels_make_the_player_hit_harder() {
        assert_eq!(base_damage_for_level(1), 5);
        assert_eq!(base_damage_for_level(2), 6);
    }

    #[test]
    fn a_new_game_starts_at_stage_one() {
        let game = Game::new();

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
        assert_eq!(game.player.gold, 0);
    }

    #[test]
    fn clicking_damages_the_enemy() {
        let mut game = Game::new();

        game.click();

        assert_eq!(game.enemy.health, 13);
    }

    #[test]
    fn defeating_an_enemy_pays_the_player() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
        assert_eq!(game.player.gold, 5);
        assert_eq!(game.player.xp, 6);
    }
}

Run both:

cargo run
cargo test

The game should clear eight stages, and all thirteen tests should pass.

What we learned

Along the way, we encountered:

• Player::new(), so a player is built in one place

• &self methods that read without changing

• a while loop that keeps going until a condition stops being true

• -=, and plain subtraction where the code above it proves the number cannot go below zero

• rules that calculate a value instead of storing it

That is a short list, and the last item is the one worth keeping.

base_damage used to be a number sitting in the player.

Now it is a rule applied to the player's level.

The player got smaller, and the game got bigger.

Hold onto that idea. We are going to do it again next time, to the other half of that damage calculation.

Gold with nothing to buy

Our player finally gets stronger by winning.

There is just one problem.

Look at the last line of that run again:

Stage 8 cleared!  Gold: 96  XP: 49/50

Ninety-six gold.

We call it money, but there is nothing in this game to spend it on.

gold earned: 96
gold spent:  0

Right now it is not a reward.

It is a high score.

Next time, we are going to give the player something to buy, and discover that the obvious way to report whether a purchase worked is not good enough.

Small function. Bigger game.

The slime dies.

Then the program dies with it.

So far, winning has been how our game ends.

In an idle game, winning is how the game keeps going.

One enemy falls, and the next one walks in.

In this article, we are going to give our game a next stage, a tougher enemy waiting there, and one place to keep all of it.

By the end, a whole turn of our game will fit in one line:

game.click();

That one call will attack the enemy, notice when it dies, advance the stage, and send in the next one.

Our starting point

So far, we have a player, a slime, and a way for one to hit the other.

You need two structs and four small functions to follow along:

struct Player {
    base_damage: u32,
    bonus_damage: u32,
}

struct Enemy {
    name: String,
    health: u32,
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(
    health: u32,
    damage: u32,
) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn attack(
    player: &Player,
    enemy: &mut Enemy,
) {
    let damage = click_damage(
        player.base_damage,
        player.bonus_damage,
    );

    enemy.health =
        health_after_hit(enemy.health, damage);
}

attack() borrows the player to read it and the enemy to change it.

Our combat loop looks like this:

fn main() {
    let player = Player {
        base_damage: 5,
        bonus_damage: 2,
    };

    let mut enemy = Enemy {
        name: String::from("Training Slime"),
        health: 20,
    };

    while !is_defeated(enemy.health) {
        attack(&player, &mut enemy);

        println!(
            "{} health: {}",
            enemy.name,
            enemy.health
        );
    }

    println!("{} defeated!", enemy.name);
}

Run it and the Training Slime goes down in three hits.

Then the program is over.

The next enemy needs to be tougher

Before we worry about where the next enemy comes from, we need to decide what it looks like.

If every enemy had 20 health, stage 50 would feel exactly like stage 1.

The next enemy should be tougher.

That is a game rule, and we know what to do with game rules by now.

Give it a small function:

fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

That gives us:

stage 1 → 20 health
stage 2 → 30 health
stage 3 → 40 health

saturating_mul() is the multiplication version of the saturating arithmetic we already use.

The exact balance does not matter yet.

What matters is that the rule has a name and a test:

#[test]
fn later_stages_have_tougher_enemies() {
    assert_eq!(enemy_health_for_stage(1), 20);
    assert_eq!(enemy_health_for_stage(2), 30);
}

If Rust warns that the function is never used yet, that is fine.

We are about to use it.

Try it in main() first

The quickest way to make stages work is to put everything straight into main():

fn main() {
    let player = Player {
        base_damage: 5,
        bonus_damage: 2,
    };

    let mut stage = 1;

    let mut enemy = Enemy {
        name: String::from("Training Slime"),
        health: enemy_health_for_stage(stage),
    };

    while stage <= 3 {
        attack(&player, &mut enemy);

        if is_defeated(enemy.health) {
            println!("Stage {stage} cleared!");

            stage = stage.saturating_add(1);

            enemy = Enemy {
                name: String::from("Training Slime"),
                health: enemy_health_for_stage(stage),
            };
        } else {
            println!(
                "{} health: {}",
                enemy.name,
                enemy.health
            );
        }
    }
}

We stop after stage 3 so the terminal does not scroll forever.

Run it.

It works.

The slime falls, a tougher one takes its place, and the stages keep coming.

It is also a mess.

Look at what main() is doing now:

owns the player
owns the enemy
owns the stage
decides when a stage is cleared
builds the next enemy
prints everything

Only that last job really belongs in main().

Everything else is the game.

Soon, defeating an enemy will also hand out rewards.

If all of those rules stay here, main() becomes the game engine and the terminal UI at the same time.

There is another reason to fix that now.

Later, the browser will replace main().

The game rules need somewhere else to live.

Give the game a shape

We have solved this kind of problem before.

Three loose numbers were not a player, so we built a Player.

A stage, a player, and an enemy sitting loose in main() are not a game.

So we build a Game:

struct Game {
    stage: u32,
    player: Player,
    enemy: Enemy,
}

This struct contains other structs:

Game
├── stage: u32
├── player: Player
└── enemy: Enemy

A struct can hold types we made ourselves.

The Game owns its Player.

It owns its Enemy.

There is now one value we can point at and say:

This is the current state of the game.

Where does a new enemy come from?

We could create a game by spelling out every field manually:

let mut game = Game {
    stage: 1,
    player: Player {
        base_damage: 5,
        bonus_damage: 2,
    },
    enemy: Enemy {
        name: String::from("Training Slime"),
        health: enemy_health_for_stage(1),
    },
};

That works.

But we have already written this enemy more than once:

Enemy {
    name: String::from("Training Slime"),
    health: enemy_health_for_stage(stage),
}

What we really want to say is:

Give me the enemy for this stage.

That sounds like a function.

And because the function is specifically about creating an Enemy, it belongs with Enemy.

Attach functions to a type with impl

Rust lets us attach functions to a type with an impl block:

impl Enemy {
    fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
        }
    }
}

impl Enemy means:

here are functions that belong to Enemy

Now we can write:

Enemy::for_stage(1)

You have already seen this style of call:

String::from("Training Slime")

A function attached to a type that does not need an existing value is called an associated function.

Enemy::for_stage() does not replace our small health rule.

It uses it:

health: enemy_health_for_stage(stage),

One function decides how tough the enemy is.

The other decides how to build one.

A new game

Game gets an impl block too:

impl Game {
    fn new() -> Game {
        Game {
            stage: 1,
            player: Player {
                base_damage: 5,
                bonus_damage: 2,
            },
            enemy: Enemy::for_stage(1),
        }
    }
}

There is nothing magical about new.

Rust has no special constructor keyword.

new is simply a common name for an associated function that creates a fresh value.

Starting the game is now:

let mut game = Game::new();

Game setup has one home.

And it is no longer main().

One click

Now the part we have been building toward.

What happens when the player clicks?

Add this inside impl Game:

fn click(&mut self) {
    attack(&self.player, &mut self.enemy);
}

There is one new name in that signature:

self

self means:

the value this method was called on

When we write:

game.click();

inside click(), self refers to game.

That makes click() a method: a function attached to a type that works on a specific value of that type.

Game::new() does not take self because there is no game yet.

click() does because it works on a game that already exists.

And &mut self should look familiar.

It means click() may temporarily change the game without taking ownership of it.

That is why this needs:

let mut game = Game::new();

Without mut, Rust refuses to let click() borrow the game mutably.

Two borrows, one game

Look inside click():

attack(&self.player, &mut self.enemy);

Last time, we learned:

For the same data at the same time: many readers, or one writer, but not both.

So why can we borrow part of the game to read and another part to change?

Because they are not the same data.

self.player and self.enemy are different fields.

They do not overlap.

Rust can see that reading the player does not interfere with changing the enemy.

Our attack() did not need to change.

The borrowing simply moved inside the game.

What happens when the enemy dies?

Right now, click() only attacks.

When the enemy reaches zero health, the next click would attack a corpse.

That is grim.

After every attack, click() should check whether the enemy was defeated:

fn click(&mut self) {
    attack(&self.player, &mut self.enemy);

    if is_defeated(self.enemy.health) {
        self.defeat_enemy();
    }
}

Now we need defeat_enemy():

fn defeat_enemy(&mut self) {
    self.stage = self.stage.saturating_add(1);
    self.enemy = Enemy::for_stage(self.stage);
}

The stage goes up.

The defeated enemy is replaced with the enemy for the new stage.

We could put both lines directly inside click().

But defeating an enemy is its own event, and that event is going to grow.

Soon it will also hand out rewards.

Keeping it named means click() can stay readable:

Attack the enemy. If it went down, handle the defeat.

And defeat_enemy() says:

Go to the next stage. Bring in the next enemy.

main() gets boring

Here is the new main():

fn main() {
    let mut game = Game::new();

    while game.stage <= 3 {
        let stage = game.stage;

        game.click();

        if game.stage > stage {
            println!("Stage {stage} cleared!");
        } else {
            println!(
                "{} health: {}",
                game.enemy.name,
                game.enemy.health
            );
        }
    }
}

main() still reads the game so it can decide what to print.

But it does not:

• build enemies
• calculate their health
• decide when a stage advances
• handle a defeat

It creates a game, clicks, and prints.

Boring is exactly what we want.

Run:

cargo run

You should see:

Training Slime health: 13
Training Slime health: 6
Stage 1 cleared!
Training Slime health: 23
Training Slime health: 16
Training Slime health: 9
Training Slime health: 2
Stage 2 cleared!
Training Slime health: 33
Training Slime health: 26
Training Slime health: 19
Training Slime health: 12
Training Slime health: 5
Stage 3 cleared!

Three stages.

Each slime tougher than the last.

And the game, not main(), decided all of that.

Test what a player experiences

Our first tests check individual rules.

Game lets us start testing something larger: what happens when those rules work together.

A new game should start at stage 1:

#[test]
fn a_new_game_starts_at_stage_one() {
    let game = Game::new();

    assert_eq!(game.stage, 1);
    assert_eq!(game.enemy.health, 20);
}

A click should hurt the enemy:

#[test]
fn clicking_damages_the_enemy() {
    let mut game = Game::new();

    game.click();

    assert_eq!(game.enemy.health, 13);
}

And defeating an enemy should move the game forward:

#[test]
fn defeating_an_enemy_advances_the_stage() {
    let mut game = Game::new();
    game.enemy.health = 1;

    game.click();

    assert_eq!(game.stage, 2);
    assert_eq!(game.enemy.health, 30);
}

That last test does not care how damage is calculated.

Those smaller rules already have their own tests.

It asks a larger question:

When a click defeats an enemy, does the game move on?

Run:

cargo test

All eight should pass.

The complete program

If you are only reading along, you can skip to the last two sections.

If you are coding along, here is everything in one place:

struct Player {
    base_damage: u32,
    bonus_damage: u32,
}

struct Enemy {
    name: String,
    health: u32,
}

struct Game {
    stage: u32,
    player: Player,
    enemy: Enemy,
}

impl Enemy {
    fn for_stage(stage: u32) -> Enemy {
        Enemy {
            name: String::from("Training Slime"),
            health: enemy_health_for_stage(stage),
        }
    }
}

impl Game {
    fn new() -> Game {
        Game {
            stage: 1,
            player: Player {
                base_damage: 5,
                bonus_damage: 2,
            },
            enemy: Enemy::for_stage(1),
        }
    }

    fn click(&mut self) {
        attack(&self.player, &mut self.enemy);

        if is_defeated(self.enemy.health) {
            self.defeat_enemy();
        }
    }

    fn defeat_enemy(&mut self) {
        self.stage = self.stage.saturating_add(1);
        self.enemy = Enemy::for_stage(self.stage);
    }
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(
    health: u32,
    damage: u32,
) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn enemy_health_for_stage(stage: u32) -> u32 {
    stage.saturating_mul(10).saturating_add(10)
}

fn attack(
    player: &Player,
    enemy: &mut Enemy,
) {
    let damage = click_damage(
        player.base_damage,
        player.bonus_damage,
    );

    enemy.health =
        health_after_hit(enemy.health, damage);
}

fn main() {
    let mut game = Game::new();

    while game.stage <= 3 {
        let stage = game.stage;

        game.click();

        if game.stage > stage {
            println!("Stage {stage} cleared!");
        } else {
            println!(
                "{} health: {}",
                game.enemy.name,
                game.enemy.health
            );
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(
            health_after_hit(3, 10),
            0
        );
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player {
            base_damage: 5,
            bonus_damage: 2,
        };

        let mut enemy = Enemy {
            name: String::from("Training Slime"),
            health: 10,
        };

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 3);
    }

    #[test]
    fn later_stages_have_tougher_enemies() {
        assert_eq!(enemy_health_for_stage(1), 20);
        assert_eq!(enemy_health_for_stage(2), 30);
    }

    #[test]
    fn a_new_game_starts_at_stage_one() {
        let game = Game::new();

        assert_eq!(game.stage, 1);
        assert_eq!(game.enemy.health, 20);
    }

    #[test]
    fn clicking_damages_the_enemy() {
        let mut game = Game::new();

        game.click();

        assert_eq!(game.enemy.health, 13);
    }

    #[test]
    fn defeating_an_enemy_advances_the_stage() {
        let mut game = Game::new();
        game.enemy.health = 1;

        game.click();

        assert_eq!(game.stage, 2);
        assert_eq!(game.enemy.health, 30);
    }
}

Run both:

cargo run
cargo test

The game should clear three stages, and all eight tests should pass.

What we learned

Along the way, we encountered:

• structs that own other structs
• impl blocks
• associated functions like Enemy::for_stage()
• new() as a convention, not a keyword
• methods
• self and &mut self
• borrowing different fields at the same time
• saturating_mul()
• tests that describe larger game behavior

You do not need to memorize all of that yet.

The important change is where the game lives.

We started with a main() that owned everything and decided everything.

We ended with:

let mut game = Game::new();

game.click();

One click is now one full turn:

game.click()
    ↓
attack(&self.player, &mut self.enemy)
    ↓
click_damage()
    ↓
health_after_hit()
    ↓
is_defeated()?
    ↓
defeat_enemy()
    ↓
next stage + Enemy::for_stage()

Look at the bottom of that chain.

click_damage(), health_after_hit(), and is_defeated() are the same small functions we started the series with.

They have not changed.

They are simply a few layers deeper now, inside something that finally looks like a game.

Winning does not pay yet

Our game has a real loop now.

Click. The slime falls. The next one walks in tougher than the last.

But look at what the player gets for all that clicking:

gold:       nothing
experience: nothing
levels:     nothing

We just cleared three stages.

Our player is exactly as strong as when the game started.

Every slime gets tougher.

Our player never does.

Keep going long enough, and every new slime takes more clicks than the last one.

Forever.

That is not progression.

That is a treadmill.

An idle game needs a reason to keep clicking: rewards for winning, levels to reach, and something to spend those rewards on.

And this time, we already know where those rewards will be handed out:

fn defeat_enemy(&mut self)

Next, we will make winning worth something.

Small function. Bigger game.

Then, the moment they fight, we strip them back down for parts:

enemy.health = attack(
    enemy.health,
    player.base_damage,
    player.bonus_damage,
);

We built two real game types.

The moment they interact, we go back to passing loose numbers around.

In this article, we are going to change attack() so it takes the player and the enemy themselves.

Along the way, Rust will refuse to compile our code three times.

Every time, it will be right.

By the end, our combat loop will say what the game actually does:

attack(&player, &mut enemy);

A player attacks an enemy.

Nothing gets torn apart.

Our starting point

You need two structs and four small functions to follow along:

struct Player {
    base_damage: u32,
    bonus_damage: u32,
}

struct Enemy {
    name: String,
    health: u32,
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(
    health: u32,
    damage: u32,
) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn attack(
    health: u32,
    base_damage: u32,
    bonus_damage: u32,
) -> u32 {
    let damage =
        click_damage(base_damage, bonus_damage);

    health_after_hit(health, damage)
}

At the bottom of main.rs, the tests module holds three tests for the small rules and one test that calls attack() directly:

#[test]
fn attack_reduces_enemy_health() {
    assert_eq!(attack(10, 5, 2), 3);
}

We will come back to that test once attack() changes.

Our combat loop looks like this:

fn main() {
    let player = Player {
        base_damage: 5,
        bonus_damage: 2,
    };

    let mut enemy = Enemy {
        name: String::from("Training Slime"),
        health: 20,
    };

    while !is_defeated(enemy.health) {
        enemy.health = attack(
            enemy.health,
            player.base_damage,
            player.bonus_damage,
        );

        println!(
            "{} health: {}",
            enemy.name,
            enemy.health
        );
    }

    println!("{} defeated!", enemy.name);
}

It works.

But attack() does not know what a player is.

It does not know what an enemy is.

It takes three numbers and hands back a fourth, and main() has to put that number back where it belongs.

What we want to write is closer to:

attack(player, enemy);

So let us try that.

Hand the player to attack()

Let us start with the player and leave the enemy alone for a moment.

Change attack() so it takes a whole Player instead of two loose damage values:

fn attack(
    player: Player,
    health: u32,
) -> u32 {
    let damage = click_damage(
        player.base_damage,
        player.bonus_damage,
    );

    health_after_hit(health, damage)
}

The body barely changed.

We read the damage values from the player with the same dot syntax we used in main().

Now update the call inside the loop:

enemy.health =
    attack(player, enemy.health);

That reads much better.

Run it:

cargo run

Rust refuses to build the program.

Trimmed down, the error says:

error[E0382]: use of moved value: `player`

value moved here, in previous
iteration of loop

The full message is longer, and it suggests a few fixes, like cloning the player.

Some of them would work.

None of them is what we want, so let us figure out what actually happened.

The first attack would have been fine.

The second attack is the problem.

Where did the player go?

The player moved

In Rust, every value has an owner.

Right now, main() owns player.

It created it, so it is responsible for it.

When we write:

attack(player, enemy.health)

and attack() asks for a Player, we are not lending the player to attack().

We are giving it away.

Ownership moves into attack().

When attack() finishes, the Player it owns is no longer available back in main().

So on the next trip around the loop, main() tries to hand over a player it no longer owns.

Rust catches that before the program ever runs.

In game terms, our player attacked once and then vanished.

That is a bold balancing decision.

It is not ours.

The attack was supposed to defeat the enemy.

Not the player.

Why did health never move?

We have been passing enemy.health into functions all along, and it never disappeared.

That is because u32 implements Rust's Copy trait.

When we pass a u32 by value, Rust can automatically make a copy, so the original remains available.

Our Player does not implement Copy, so passing it by value moves ownership instead.

You do not need to understand traits yet.

For now, the useful difference is:

u32     → copied
Player  → moved

A u32 gets photocopied.

A Player gets handed over.

We do not want to give the player away.

We want attack() to look at it.

Borrow the player with &

Rust lets a function borrow a value instead of owning it.

Add one character to the parameter type:

fn attack(
    player: &Player,
    health: u32,
) -> u32 {
    let damage = click_damage(
        player.base_damage,
        player.bonus_damage,
    );

    health_after_hit(health, damage)
}

&Player means:

a reference to a Player that someone else owns

A reference lets attack() reach the player without taking ownership of it.

When the call finishes, the player is still sitting in main() where we left it.

Notice that the body did not change.

The dot works the same way through a reference, so:

player.base_damage

still reads the field.

The call needs the same &:

enemy.health =
    attack(&player, enemy.health);

&player says:

let attack() borrow the player for this call

Run it:

cargo run

The Training Slime goes down in three hits again.

The player survives every one of them.

There is a bonus hiding in that &.

A plain & reference gives attack() read-only access to the player's fields.

If attack() tried to assign a new value to:

player.base_damage

Rust would refuse to compile it.

That is exactly the promise we want.

An attack needs to read the player.

It does not need to change the player.

Now the enemy

The player is solved.

The enemy is still split apart:

enemy.health =
    attack(&player, enemy.health);

attack() gets a copy of the enemy's health, calculates a new number, and returns it.

Then main() writes that number back into the enemy.

What we really want is for attack() to change the enemy itself.

We just learned that borrowing keeps a value where it is.

Let us borrow the enemy too:

fn attack(
    player: &Player,
    enemy: &Enemy,
) {
    let damage = click_damage(
        player.base_damage,
        player.bonus_damage,
    );

    enemy.health =
        health_after_hit(enemy.health, damage);
}

Two things changed besides the enemy parameter.

There is no:

-> u32

anymore.

attack() is not handing back a number for someone else to store.

The result lives in the enemy.

Inside the function, we assign the new health directly to:

enemy.health

Update the call in main():

attack(&player, &enemy);

Run it:

cargo run

Rust refuses again:

error[E0594]: cannot assign to
`enemy.health`, which is behind
a `&` reference

You may also see a warning that enemy does not need to be mutable.

Ignore it for a moment.

We are about to need that mut again.

This is the promise from the last section working against us.

&Enemy lets us look at the enemy.

We did not come here to look.

A plain & reference is read-only.

That was perfect for the player.

It is wrong for the enemy because the entire point of an attack is that the enemy's health changes.

Borrow the enemy with &mut

We have already met mut.

It is how we told Rust that our enemy is allowed to change.

References can express the same idea.

Change:

&Enemy

to:

&mut Enemy

Our attack becomes:

fn attack(
    player: &Player,
    enemy: &mut Enemy,
) {
    let damage = click_damage(
        player.base_damage,
        player.bonus_damage,
    );

    enemy.health =
        health_after_hit(enemy.health, damage);
}

&mut Enemy means:

a mutable reference to an Enemy that someone else owns

In game terms:

attack() may temporarily change this enemy, but it does not own the enemy.

The call needs to ask for the same thing:

attack(&player, &mut enemy);

This only works because enemy was already declared with:

let mut enemy

Rust will not let us borrow something mutably if the owner never agreed that it could change.

Run it:

cargo run

You should see:

Training Slime health: 13
Training Slime health: 6
Training Slime health: 0
Training Slime defeated!

The same fight as before.

But now the signature tells the whole story:

&Player     → attack reads the player
&mut Enemy  → attack changes the enemy

Nobody gets consumed.

Nobody gets torn apart.

Both are still in main(), ready for the next attack.

One rule worth knowing now

There is one borrowing rule you will run into early, so here it is in game terms.

Suppose that, instead of the combat loop, main() grabs a reference to the enemy's name before attacking:

let name = &enemy.name;

attack(&player, &mut enemy);

println!("{name} took a hit!");

Rust refuses for the third time:

error[E0502]: cannot borrow `enemy`
as mutable because it is also
borrowed as immutable

A borrow remains active until its last use.

name is used by the println!() after the attack, so that borrow is still active when attack() asks for permission to change the enemy.

Rust will not hand out a mutable borrow while that reading borrow is still being used.

Our combat loop never hits this problem because each borrow is finished before the next conflicting access begins:

attack(&player, &mut enemy);

println!(
    "{} health: {}",
    enemy.name,
    enemy.health
);

In this case, the mutable borrow is finished when attack() returns.

Then println!() is free to read the enemy.

That is the beginner version of the rule:

For the same data at the same time: many readers, or one writer, but not both.

You do not need more than that today.

Update the test

Our attack() test still passes three loose numbers, so it needs the new signature:

#[test]
fn attack_reduces_enemy_health() {
    let player = Player {
        base_damage: 5,
        bonus_damage: 2,
    };

    let mut enemy = Enemy {
        name: String::from("Training Slime"),
        health: 10,
    };

    attack(&player, &mut enemy);

    assert_eq!(enemy.health, 3);
}

The rule it checks has not changed.

An attack with five base damage and two bonus damage takes ten health down to three.

What changed is how the test says it.

It builds a player.

It builds an enemy.

It lets one attack the other.

Then it checks the enemy afterward.

That reads like the game.

The other three tests do not touch attack(), so they stay exactly as they were.

Run them:

cargo test

All four should pass.

We do not need a separate test proving that attack() does not change the player.

With our current Player type, an &Player reference does not allow attack() to assign new values to the player's fields.

The compiler checks that for us every time we build.

The complete program

If you have been following along in your editor, here is everything in one place.

At this point, src/main.rs should look like this:

struct Player {
    base_damage: u32,
    bonus_damage: u32,
}

struct Enemy {
    name: String,
    health: u32,
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(
    health: u32,
    damage: u32,
) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn attack(
    player: &Player,
    enemy: &mut Enemy,
) {
    let damage = click_damage(
        player.base_damage,
        player.bonus_damage,
    );

    enemy.health =
        health_after_hit(enemy.health, damage);
}

fn main() {
    let player = Player {
        base_damage: 5,
        bonus_damage: 2,
    };

    let mut enemy = Enemy {
        name: String::from("Training Slime"),
        health: 20,
    };

    while !is_defeated(enemy.health) {
        attack(&player, &mut enemy);

        println!(
            "{} health: {}",
            enemy.name,
            enemy.health
        );
    }

    println!("{} defeated!", enemy.name);
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(
            health_after_hit(3, 10),
            0
        );
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        let player = Player {
            base_damage: 5,
            bonus_damage: 2,
        };

        let mut enemy = Enemy {
            name: String::from("Training Slime"),
            health: 10,
        };

        attack(&player, &mut enemy);

        assert_eq!(enemy.health, 3);
    }
}

Run both:

cargo run
cargo test

The Training Slime should fall in three hits, and all four tests should pass.

What we learned

Along the way, we encountered:

• ownership

• moves

• Copy values

• &T references

• &mut T references

• functions that change a value instead of returning a new one

• when borrows stop being used

• why Rust prevents conflicting access

You do not need to memorize all of that yet.

The important change is what our attack says.

We started with:

enemy.health = attack(
    enemy.health,
    player.base_damage,
    player.bonus_damage,
);

We ended with:

attack(&player, &mut enemy);

The player is read.

The enemy is changed.

Both stay where they belong.

And the compiler now checks that attack() keeps its side of that deal.

There is a bigger shape missing

Look at what main() is holding now:

player
enemy
the combat loop

That is a fight.

It is not a game.

When the Training Slime dies, the program simply ends.

There is no next enemy.

There is no stage counter.

Nobody earns anything for winning.

And every one of those things would become another loose variable inside main():

player
enemy
stage
gold
experience

We have seen this problem before.

Three numbers were not a player.

A pile of variables in main() is not a game.

The pieces that make up our game need one place to live, and one place that decides what happens when a player clicks.

Next, we will put the game in one place.

Small function. Bigger game.

attack(enemy_health, 5, 2)

Three values. Two belong to the player. One belongs to the enemy.

Nothing in the code says which is which.

In this article, we are going to fix that by grouping those values into two new Rust types: a Player and an Enemy.

By the end, our code will start describing the things that actually exist in our game instead of asking us to remember what those numbers represent.

Our starting point

You only need four small functions to follow along:

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(
    health: u32,
    damage: u32,
) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn attack(
    health: u32,
    base_damage: u32,
    bonus_damage: u32,
) -> u32 {
    let damage =
        click_damage(base_damage, bonus_damage);

    health_after_hit(health, damage)
}

Our combat loop currently looks like this:

fn main() {
    let mut enemy_health = 20;

    while !is_defeated(enemy_health) {
        enemy_health =
            attack(enemy_health, 5, 2);

        println!(
            "Enemy health: {enemy_health}"
        );
    }

    println!("Enemy defeated!");
}

This code works.

The problem is not what it does.

The problem is what it says.

Three numbers with three different meanings

Look at the attack again:

attack(enemy_health, 5, 2)

The first value represents the enemy.

The other two belong to the player.

But nothing in the function call makes those relationships clear.

Someone reading this code has to remember:

enemy_health → the enemy's current health
5            → the player's base damage
2            → the player's bonus damage

That is manageable today.

It will become harder when our player also has:

• a level

• experience

• gold

• upgrade levels

• passive damage

The enemy will need more information too:

• a name

• maximum health

• gold rewards

• experience rewards

Passing every single value as an individual number just isn't going to scale.

We need a way to tell Rust which values belong together.

Give the player some shape

Rust lets us create our own types with struct.

Add this near the top of main.rs:

struct Player {
    base_damage: u32,
    bonus_damage: u32,
}

A struct is a type that groups related values together.

Our new type is called:

Player

It contains two named values:

base_damage
bonus_damage

The named values inside a struct are called fields.

Each field has a type. The colon syntax is the same as a function parameter—it connects the name to the type:

base_damage: u32
bonus_damage: u32

So every Player has a field named base_damage that contains a u32, and a field named bonus_damage that also contains a u32.

The struct definition describes the shape of a player.

It does not create one yet.

Create a player

Now that Rust knows what a Player looks like, we can create one:

let player = Player {
    base_damage: 5,
    bonus_damage: 2,
};

This creates a value with a type of: Player.

The values line up with the fields from our definition:

Player
├── base_damage: 5
└── bonus_damage: 2

We can access a field with a dot:

player.base_damage

That gives us the player's base damage.

We can do the same for bonus damage:

player.bonus_damage

Our attack call can now become:

attack(
    enemy_health,
    player.base_damage,
    player.bonus_damage,
)

That does happen to be longer than:

attack(enemy_health, 5, 2)

But it is also clearer.

We no longer have to remember what 5 and 2 represent.

The code tells us.

Give the enemy some shape

Our enemy is still represented by one loose variable:

let mut enemy_health = 20;

Health is not the only thing an enemy needs.

Even giving it a name creates another related value.

Add another struct:

struct Enemy {
    name: String,
    health: u32,
}

Our new Enemy type contains two fields:

Enemy
├── name
└── health

We already know the type of health:

health: u32

The name introduces a new type:

name: String

Give the enemy a name

String is a Rust type for storing owned text.

That fits our enemy: it should keep its own name for as long as it exists.

We can create a String from text like this:

String::from("Training Slime")

For now, read that as:

Create a String containing "Training Slime."

Our game only needs enough text to name an enemy.

Now we can create one:

let enemy = Enemy {
    name: String::from("Training Slime"),
    health: 20,
};

Rust now understands that the name and health belong to the same enemy.

The enemy still needs to change

There is one problem with our new enemy:

let enemy = Enemy {
    name: String::from("Training Slime"),
    health: 20,
};

Combat changes health.

But enemy is immutable by default.

If we try to assign a new value to:

enemy.health

Rust will refuse to compile the program.

We have already solved this problem once.

The enemy needs to be mutable:

let mut enemy = Enemy {
    name: String::from("Training Slime"),
    health: 20,
};

The mut applies to the enemy value, which allows us to change its fields:

enemy.health = 13;

We are not adding mutability everywhere.

The player does not need to change yet:

let player = Player {

The enemy does:

let mut enemy = Enemy {

Once again, the game tells us which values need to be mutable.

Put the player and enemy into combat

We can now update main():

fn main() {
    let player = Player {
        base_damage: 5,
        bonus_damage: 2,
    };

    let mut enemy = Enemy {
        name: String::from("Training Slime"),
        health: 20,
    };

    while !is_defeated(enemy.health) {
        enemy.health = attack(
            enemy.health,
            player.base_damage,
            player.bonus_damage,
        );

        println!(
            "{} health: {}",
            enemy.name,
            enemy.health
        );
    }

    println!("{} defeated!", enemy.name);
}

There is one small change in our println!() calls.

The {} placeholders are filled from left to right by the values that follow the format string:

println!(
    "{} health: {}",
    enemy.name,
    enemy.health
);

The first {} displays enemy.name.

The second displays enemy.health.

Run the game:

cargo run

You should see:

Training Slime health: 13
Training Slime health: 6
Training Slime health: 0
Training Slime defeated!

The combat still works.

But the code now contains an actual player and enemy.

Notice what the structs made visible

Before, our game looked like this:

let mut enemy_health = 20;

enemy_health =
    attack(enemy_health, 5, 2);

Now it looks like this:

let player = Player {
    base_damage: 5,
    bonus_damage: 2,
};

let mut enemy = Enemy {
    name: String::from("Training Slime"),
    health: 20,
};

enemy.health = attack(
    enemy.health,
    player.base_damage,
    player.bonus_damage,
);

The behavior is the same.

The meaning is not.

Before:

20
5
2

Now:

Player
├── base_damage
└── bonus_damage

Enemy
├── name
└── health

We gave related values names and grouped them into types.

Rust can now help us keep player data with the player and enemy data with the enemy.

The behavior did not change

Notice what we did not touch:

click_damage()

still calculates damage.

health_after_hit()

still reduces health.

is_defeated()

still checks for defeat.

attack()

still combines the smaller rules.

We changed how the application organizes its data.

We did not rewrite the behavior we already trust.

Run the tests:

cargo test

All four should still pass.

No new combat rule was added in this article, so we do not need to invent a new behavior test just to prove that a struct can hold the values we typed into it.

The compiler checks that our struct fields exist and contain the expected types.

Our existing tests continue checking the game rules.

The complete program

At this point, src/main.rs should look like this:

struct Player {
    base_damage: u32,
    bonus_damage: u32,
}

struct Enemy {
    name: String,
    health: u32,
}

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(
    health: u32,
    damage: u32,
) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn attack(
    health: u32,
    base_damage: u32,
    bonus_damage: u32,
) -> u32 {
    let damage =
        click_damage(base_damage, bonus_damage);

    health_after_hit(health, damage)
}

fn main() {
    let player = Player {
        base_damage: 5,
        bonus_damage: 2,
    };

    let mut enemy = Enemy {
        name: String::from("Training Slime"),
        health: 20,
    };

    while !is_defeated(enemy.health) {
        enemy.health = attack(
            enemy.health,
            player.base_damage,
            player.bonus_damage,
        );

        println!(
            "{} health: {}",
            enemy.name,
            enemy.health
        );
    }

    println!("{} defeated!", enemy.name);
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(
            health_after_hit(3, 10),
            0
        );
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        assert_eq!(attack(10, 5, 2), 3);
    }
}

Run both:

cargo run
cargo test

The game should defeat the Training Slime, and all four tests should pass.

What we learned

Along the way, we encountered:

• struct

• custom Rust types

• struct fields

• creating struct values

• field access with .

• String

• mutable struct values

You do not need to memorize all of that yet.

The important change is what happened to our data.

We started with:

enemy_health
5
2

We turned those values into:

Player
Enemy

Our program now has a vocabulary that matches the game we are building.

There is still something awkward

We solved one problem.

But look at our attack again:

enemy.health = attack(
    enemy.health,
    player.base_damage,
    player.bonus_damage,
);

We created a Player.

We created an Enemy.

Then, the moment they need to interact, we pull them apart into individual fields.

attack() does not accept a player.

It does not accept an enemy.

It still accepts three numbers and returns another number that we manually assign back to the enemy.

What we really want to express is:

player attacks enemy

That means our attack needs to:

read the player
change the enemy
leave both available for the next attack

Rust has a way to let a function temporarily use values without taking them away from the code that already owns them.

That is called borrowing.

Next, we will let our player attack an enemy without consuming either one.

Small function. Bigger game.

There is a problem, though.

Those rules do not actually attack anything yet.

In this article, we are going to combine our small Rust functions into a larger attack() function, let enemy health change during combat, and repeat attacks until the enemy is defeated.

By the end, we will have our first actual game mechanic: a combat loop.

Our starting point

You only need three small functions to follow along:

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(
    health: u32,
    damage: u32,
) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

Each one has a single job.

click_damage() calculates how much damage the player deals.

health_after_hit() applies that damage to an enemy's health.

is_defeated() tells us whether the enemy has reached zero health.

Right now, however, something else has to coordinate all three.

That something is main().

main() knows too much

We could attack an enemy like this:

fn main() {
    let enemy_health = 10;

    let damage = click_damage(5, 2);

    let remaining_health =
        health_after_hit(enemy_health, damage);

    println!("Enemy health: {remaining_health}");

    if is_defeated(remaining_health) {
        println!("Enemy defeated!");
    }
}

Technically, this does work.

But look at everything that main() knows about.

It knows how damage is calculated.

It knows how damage affects health.

It knows how to determine whether the enemy has been defeated.

Those first two steps describe one larger idea:

an attack.

So let us give that idea a function.

Build an attack from smaller functions

Add this beneath the functions we already have:

fn attack(
    health: u32,
    base_damage: u32,
    bonus_damage: u32,
) -> u32 {
    let damage =
        click_damage(base_damage, bonus_damage);

    health_after_hit(health, damage)
}

Notice how we are not adding new Rust ideas here.

That is the point.

We are taking functions we already understand and using them to build something more complex.

The first line inside attack():

let damage =
    click_damage(base_damage, bonus_damage);

uses our existing damage rule.

Then:

health_after_hit(health, damage)

uses the result to calculate the enemy's remaining health.

Because it is the final expression and has no semicolon, that remaining health becomes the value returned by attack().

Our functions now fit together like this:

click_damage() ───────┐
                      ├──→ attack()
health_after_hit() ───┘

We did not replace our small functions.

We composed a larger behavior from them.

Instead of teaching attack() every rule from scratch, it delegates those jobs to functions that already know how to calculate damage and reduce health.

We already know what each piece does, so understanding attack() does not require us to understand an entirely new system.

Try the attack

Replace main() with:

fn main() {
    let enemy_health = 10;

    let remaining_health =
        attack(enemy_health, 5, 2);

    println!("Enemy health: {remaining_health}");
}

Run the game:

cargo run

You should see:

Enemy health: 3

Our player dealt seven damage to an enemy with ten health.

That means attack() works.

We can test it too.

Add this to the test module:

#[test]
fn attack_reduces_enemy_health() {
    assert_eq!(attack(10, 5, 2), 3);
}

Then run:

cargo test

We now have a test for behavior that depends on several smaller rules working together.

One attack is not much of a fight

We can attack an enemy once.

An idle game probably needs a little more combat than that.

Suppose our enemy starts with twenty health:

let enemy_health = 20;

The first attack reduces it to thirteen.

The next should reduce it to six.

The next should reduce it to zero.

There is a problem, though.

This:

let enemy_health = 20;

creates a variable that Rust does not allow us to change.

Variables are immutable by default in Rust.

That means this is not allowed:

let enemy_health = 20;

enemy_health = attack(enemy_health, 5, 2);

If you try this, Rust will refuse to compile it and tell us that we cannot assign to an immutable variable.

That error is useful. We have to explicitly tell Rust which values we expect to change.

For most values, that is a useful default.

For health during combat, it is not.

Health is supposed to change.

Let health change with mut

Rust uses the mut keyword when we want a variable to be mutable.

Change:

let enemy_health = 20;

to:

let mut enemy_health = 20;

Now we can assign a new value to it:

enemy_health =
    attack(enemy_health, 5, 2);

The word mut is short for mutable, meaning the value bound to this variable may change.

We are not making everything mutable just because we can.

We are using mutability because enemy health represents something that changes as part of the game.

That distinction will become increasingly useful as our state grows.

Attack again

We can now do this:

fn main() {
    let mut enemy_health = 20;

    enemy_health =
        attack(enemy_health, 5, 2);

    println!("Enemy health: {enemy_health}");

    enemy_health =
        attack(enemy_health, 5, 2);

    println!("Enemy health: {enemy_health}");

    enemy_health =
        attack(enemy_health, 5, 2);

    println!("Enemy health: {enemy_health}");
}

Run it:

cargo run

and we get:

Enemy health: 13
Enemy health: 6
Enemy health: 0

It works.

It is also repetitive.

We know what should happen:

Keep attacking while the enemy is still alive.

Rust has a way to express exactly that.

Repeat with while

A while loop repeats a block of code as long as a condition remains true.

For example:

while enemy_health > 0 {
    // repeat something
}

We could use that.

But we already wrote a function that knows whether the enemy has been defeated:

is_defeated(enemy_health)

We should use the rule we already have.

What we really want to say is:

Keep attacking while the enemy is not defeated.

Rust uses ! to mean not.

So:

!is_defeated(enemy_health)

means:

the enemy has not been defeated

Put that inside a while loop:

while !is_defeated(enemy_health) {
    enemy_health =
        attack(enemy_health, 5, 2);

    println!("Enemy health: {enemy_health}");
}

Now Rust keeps running the block until is_defeated() returns true.

Our first combat loop

Update main():

fn main() {
    let mut enemy_health = 20;

    while !is_defeated(enemy_health) {
        enemy_health =
            attack(enemy_health, 5, 2);

        println!(
            "Enemy health: {enemy_health}"
        );
    }

    println!("Enemy defeated!");
}

Run:

cargo run

You should see:

Enemy health: 13
Enemy health: 6
Enemy health: 0
Enemy defeated!

We have a combat loop.

The player attacks.

Health changes.

The game checks whether combat should continue.

Then it attacks again.

Our little system now looks something like this:

click_damage() ───────┐
                      ├──→ attack()
health_after_hit() ───┘
                      ↓
                  repeat while
          enemy has not been defeated

The individual pieces are still small.

The behavior is getting larger.

Notice what Rust made us say

We encountered three small pieces of Rust syntax in this article:

mut    → health needed to change
while  → combat needed to repeat
!      → we needed to express "not defeated"

But we did not add them because they appeared next on a Rust checklist.

The game gave us reasons to need them.

Enemy health needed to change:

let mut enemy_health = 20;

Combat needed to repeat until the enemy is defeated:

while !is_defeated(enemy_health) {

That is how we are going to keep learning Rust throughout this project.

When the game creates a problem, we will learn the Rust needed to solve it.

Testing the larger rule

Our existing tests still protect the smaller rules:

#[test]
fn click_damage_adds_base_and_bonus() {
    assert_eq!(click_damage(3, 4), 7);
}

#[test]
fn health_never_drops_below_zero() {
    assert_eq!(health_after_hit(3, 10), 0);
}

#[test]
fn zero_health_is_defeated() {
    assert!(is_defeated(0));
    assert!(!is_defeated(1));
}

Now we also have:

#[test]
fn attack_reduces_enemy_health() {
    assert_eq!(attack(10, 5, 2), 3);
}

This test is slightly different.

attack() is not doing one tiny calculation by itself.

It relies on other functions.

That means we are beginning to test not only individual rules, but also the larger behavior created when those rules work together.

The complete program

At this point, src/main.rs should look like this:

fn click_damage(
    base: u32,
    bonus: u32,
) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(
    health: u32,
    damage: u32,
) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn attack(
    health: u32,
    base_damage: u32,
    bonus_damage: u32,
) -> u32 {
    let damage =
        click_damage(base_damage, bonus_damage);

    health_after_hit(health, damage)
}

fn main() {
    let mut enemy_health = 20;

    while !is_defeated(enemy_health) {
        enemy_health =
            attack(enemy_health, 5, 2);

        println!(
            "Enemy health: {enemy_health}"
        );
    }

    println!("Enemy defeated!");
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(
            health_after_hit(3, 10),
            0
        );
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }

    #[test]
    fn attack_reduces_enemy_health() {
        assert_eq!(attack(10, 5, 2), 3);
    }
}

Run both:

cargo run
cargo test

Our game now fights until the enemy is defeated, and all four functions we have written are covered by tests.

What we learned

Along the way, we encountered:

• functions calling other functions
• local variables inside functions
• mut
• reassignment
• while
• !
• tests for composed behavior

You do not need to memorize all of that yet.

The important change is what happened to our game.

We started with three independent rules:

damage
health
defeat

We combined them into:

attack

Then repeated that attack until we had:

combat

Our program became more capable without any individual function becoming particularly complicated.

There is another problem hiding in our code

Look at this:

attack(enemy_health, 5, 2)

We know what those values mean because we just wrote them.

enemy_health belongs to the enemy.

5 is the player's base damage.

2 is the player's bonus damage.

Rust does not know any of that.

As far as Rust is concerned, they are just three u32 values being passed into a function.

And our game is about to need more information:

player level
player gold
enemy name
enemy maximum health
enemy rewards

Passing more and more unrelated-looking numbers around is not going to age well.

The next problem is no longer about making our functions stronger.

It is about giving our data some shape.

Next, we will turn the player and enemy into real Rust types of their own.

Small function. Bigger game.

In this article, I am going to walk you through writing and testing three tiny Rust functions that do something slightly more interesting: calculate attack damage, reduce an enemy's health, and decide whether the enemy has been defeated.

You do not need any previous Rust experience to follow along.

If you are able to edit a file and run a command in your terminal, you can jump right in.

By the end, we will have the first real rules of an idle game, and these functions will not be throwaway tutorial code. We will keep building with them until they are running inside a complete browser game powered by Rust compiled to WebAssembly.

If you are getting excited, then without further ado, it is time to start dealing damage!

Create the project

Our first step is ensuring that Rust is installed on our local machine.

Need Rust installed first?
Rust is installed and managed through rustup, the official Rust toolchain installer. Follow the official Rust installation instructions for your operating system, then open a new terminal when the installation finishes.

You can check that everything is ready with:

rustc --version
cargo --version

If both commands print version numbers, we are all set.

We can create a new project by typing:

cargo new rustbound-idle
cd rustbound-idle

Cargo will create a small Rust application for us:

rustbound-idle/
├── Cargo.toml
└── src/
    └── main.rs

Open src/main.rs.

Notice the traditional Rust greeting:

fn main() {
    println!("Hello, world!");
}

If you want, you can run it once:

cargo run

Then chuck it in the bin.

We are not here to say hello to enemies.

We are here to say goodbye to them.

Our first game rule

Imagine our player has two sources of attack power:

• base damage

• bonus damage from upgrades

Calculating total click damage is just addition.

Add this to main.rs:

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

This is our first Rust function.

Breaking it apart into bits and pieces:

fn click_damage(base: u32, bonus: u32) -> u32

fn means we are defining a function.

The function name is:

click_damage

It takes two values:

base: u32
bonus: u32

u32 is the type of both values. A type tells Rust what kind of data a value represents and what operations make sense for it.

The colon connects the parameter name to its type, so:

base: u32

means that base is a value with a type of u32.

For now, think of u32 as a non-negative whole number. More specifically, it is an unsigned 32-bit integer.

So these are valid u32 values:

0
1
25
1000

But this is not:

-5

After the parameters, we have:

-> u32

This tells Rust that the function returns a value whose type is also u32.

Then:

{
    base.saturating_add(bonus)
}

is the value we return.

Rust lets the last expression in a function become its return value by leaving off the semicolon.

So:

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

means:

Take the player's base damage and bonus damage, add them together, and return the result.

Why not just use base + bonus?

We could. For most ordinary values, both versions give us the same answer. However, u32 has a maximum value.

saturating_add() gives our game explicit behavior at that boundary: damage stops at the largest value u32 can represent instead of leaving overflow behavior to the build configuration.

This is a game-design choice, not a rule that Rust programs should always use saturating arithmetic.

We are choosing it because damage is a quantity where hitting the numeric ceiling makes more sense than allowing overflow.

Call the function

Now we can give main() something to do:

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn main() {
    let damage = click_damage(5, 2);

    println!("You dealt {damage} damage!");
}

Run:

cargo run

You should see:

You dealt 7 damage!

Technically, we did not escape println!() after all.

But at least we are using it to deal some damage as promised.

Give the enemy some health

Damage is not useful if our enemies do not have a health pool.

Our second rule will calculate how much health remains after an attack:

fn health_after_hit(health: u32, damage: u32) -> u32 {
    health.saturating_sub(damage)
}

Notice how this looks a lot like our first function.

It takes:

health
damage

and returns the remaining health.

Again, we are using saturating arithmetic.

Why?

Imagine the enemy has:

3 health

and we deal:

10 damage

For our game, we want the result to be:

0

not:

-7

Health cannot drop below zero.

So:

health.saturating_sub(damage)

expresses this game rule clearly.

Try it:

fn main() {
    let damage = click_damage(5, 2);
    let remaining_health = health_after_hit(10, damage);

    println!("You dealt {damage} damage!");
    println!("Enemy health: {remaining_health}");
}

Run again:

cargo run

You should see:

You dealt 7 damage!
Enemy health: 3

Now we are starting to have something that resembles combat.

Barely. But it counts.

Is the enemy defeated?

Our third rule is even smaller:

fn is_defeated(health: u32) -> bool {
    health == 0
}

This introduces another Rust type:

bool

A boolean has two possible values:

true
false

Our function answers one question:

Has the enemy's health reached zero?

If we call:

is_defeated(0)

we get:

true

If we call:

is_defeated(10)

we get:

false

It is time to use it.

fn main() {
    let enemy_health = 5;

    let damage = click_damage(5, 2);
    let remaining_health =
        health_after_hit(enemy_health, damage);

    println!("You dealt {damage} damage!");
    println!("Enemy health: {remaining_health}");

    if is_defeated(remaining_health) {
        println!("Enemy defeated!");
    }
}

Run it:

cargo run

and now we get:

You dealt 7 damage!
Enemy health: 0
Enemy defeated!

Now we have combat rules!

Tiny ones. But real ones.

Why make these separate functions?

We could have written everything directly inside main():

fn main() {
    let health = 5;
    let base_damage = 5;
    let bonus_damage = 2;

    let damage = base_damage + bonus_damage;
    let remaining_health =
        health.saturating_sub(damage);

    if remaining_health == 0 {
        println!("Enemy defeated!");
    }
}

That works. Especially for a program this small, and it may even look easier.

But this game is not going to stay this small.

Eventually we will need to answer questions like:

• How much damage does the player deal?
• Did the enemy die?
• How much gold should the player receive?
• How much XP did they earn?
• Did they level up?
• How strong should the next enemy be?
• How much passive damage happened while the player was away?

If all of those rules live inside one giant function, the program gets harder to understand very quickly.

Instead, we are starting with small pieces that have clear jobs:

click_damage()
health_after_hit()
is_defeated()

Later, bigger functions will use these functions.

Then even bigger behavior will use those.

That is how we are going to build the entire game.

Not by writing one giant clever function.

By combining small, boring ones until the result is no longer boring.

Testing the rules

These functions have another useful property:

They are easy to test.

We give them input.

We check the output.

At the bottom of main.rs, add:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }
}

Run:

cargo test

You should see three passing tests.

We are not going to turn this into a giant testing lesson yet.

For now, notice how easy it is to verify a small function with a clear input and output.

That will matter more as the game grows.

The complete program

At this point, src/main.rs should look like this:

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

fn health_after_hit(
    health: u32,
    damage: u32,
) -> u32 {
    health.saturating_sub(damage)
}

fn is_defeated(health: u32) -> bool {
    health == 0
}

fn main() {
    let enemy_health = 5;

    let damage = click_damage(5, 2);

    let remaining_health =
        health_after_hit(enemy_health, damage);

    println!("You dealt {damage} damage!");
    println!("Enemy health: {remaining_health}");

    if is_defeated(remaining_health) {
        println!("Enemy defeated!");
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn click_damage_adds_base_and_bonus() {
        assert_eq!(click_damage(3, 4), 7);
    }

    #[test]
    fn health_never_drops_below_zero() {
        assert_eq!(health_after_hit(3, 10), 0);
    }

    #[test]
    fn zero_health_is_defeated() {
        assert!(is_defeated(0));
        assert!(!is_defeated(1));
    }
}

This is not much of a game yet.

And that is okay.

We now have something more useful than a big pile of code, and we have three rules that we understand.

What we learned

Along the way, we have already encountered:

• fn

• function parameters

• return types

• u32

• bool

• let

• expressions

• if

• function calls

• Cargo

• basic Rust tests

You do not need to memorize all of that yet. More importantly, we can now describe combat with three small rules:

calculate damage
       ↓
reduce health
       ↓
check for defeat

That is our first little game system.

And we are keeping it.

Where we will take it next

Right now main() is doing everything — calculating damage, applying it, checking for defeat. Those three steps together represent a single larger idea: an attack.

Next, we will build that concept as its own function, using the three small functions we already wrote. That is where this project starts to show its real shape.

Eventually a click in the browser will travel through a Web Component, into WebAssembly, and down into Rust — all the way to:

fn click_damage(base: u32, bonus: u32) -> u32 {
    base.saturating_add(bonus)
}

Small function. Bigger game.

The last time I posted was on April 28, 2025. I know the exact date because it was the same day I got married.

Looking back, that might explain why this blog settled down soon after.

Not because I stopped programming. I was still building, learning, and working through plenty of code. I just quit writing about it.

As time passed, the blog seemed to drift further down the backlog. When I found myself with some free time, I was more likely to spend it squashing bugs, working on a project, or learning something new than writing about any of it.

So before I start writing about what comes next, I should probably explain what has happened since then.

Because it was a year.

First, a tiny detail I forgot to mention

While participating in a Chingu Voyage, I met my wife.

Yes, that Chingu.

The online platform that put together teams of software engineers and agile leaders to build projects suitable to their abilities, argue politely about Git branches, and every once in a while spend twenty minutes figuring out who forgot to pull before opening a PR.

Before this past year, I had completed several Chingu Voyages, working as a developer and a product owner, and even as a mentor. One of those Voyages just happened to work out particularly well.

I met her.

As far as I am aware, almost nobody over there knows about it. It never really came up, and there never seemed to be a natural moment in a Discord channel to mention it. Plus it all escalated well after that Voyage ended.

This blog has always been about my experience writing code and sharing the lessons I've learned in order to help other developers grow and tap into their potential.

So this may seem like it comes out of left field, but Chingu gave me teammates, portfolio projects, experience working on software teams...

...and a wife.

Maybe not in that order.

You might say that it was a successful Voyage.

Before the Baby, There Was Baby Book

Before summer could even arrive, we found out our lives were about to change again!

We found out we were expecting a son, due November 7. We began to think about all of the little things that come with two people becoming parents.

Naturally, we both looked at each other and said:

We could probably build an app for this.

So we began working on an idea we called Baby Book.

In the first phase, it was only a household task and grocery list tracking app. The long-term plan was to track milestones, achievements, appointments, and eventually the little things one parent might miss while the other was there—so we could stay on the same page.

More or less, we set out to build a shared record of our new favorite person's life as it began to unfold.

We never did polish the application to the original design plan, but for a little while it was actually useful.

When she went into labor, I threw together a quick feature for helping her with breathing and contractions. When our son was born, Baby Book shifted toward the realities of parenthood. We started tracking feeding times and details, diaper changes, and little notes.

It did not take long before we did what most new parents probably do.

We fell into a rhythm and stopped stressing over those details as much.

Our need for this app faded, and Baby Book quietly moved into the category titled:

I should really come back to this someday.

And I still may.

Some of the original idea could still be useful today, especially around milestones and giving us an easy way to share the little things the other parent might miss.

But it is not exactly at the top of the backlog right now.

A Wild Son Has Appeared

Our son was supposed to arrive on November 7.

Apparently, he had his own release schedule. He arrived October 12, about four weeks early.

Anybody who has had an infant can probably relate to what happened to my schedule next. If you haven't, imagine handing your calendar to a tiny version of yourself that only speaks babble, uses his mouth to read, and thinks 3:17 in the morning is the perfect time to discuss politics.

That is roughly the system, right?

The funny part is that another fairly important date had happened only five days earlier.

On October 7, I was accepted into Code the Dream's React course.

Code the Dream Was Already in Motion

I had actually applied to Code the Dream months earlier, around April 2025.

The timing of the whole thing could have been a little better. But it is not like I brought the baby home, learned a thing or two about our new tiny boss, and decided:

You know what this situation needs?

Another commitment.

The decision had already been made.

I had tested out of the Intro to Programming course, which is how I ended up going directly into React.

By this point, I knew that it was going to be a challenge, but it seemed reasonable enough.

Strangely enough, his early arrival may actually have made the start of the course easier. I lost some preparation time, but I gained a few weeks to settle into being a parent before React started. And that made a big difference.

By the time the React cohort started, I was not deciding whether I wanted to begin another programming course while raising a newborn. I had already committed to the course.

Now I just had to figure out what continuing looked like under completely different circumstances.

The answer was very different from the way I had worked before.

Long, uninterrupted coding sessions became harder to find. Development started happening in smaller windows: thirty minutes here, an hour there, whatever time happened to exist between everything else.

If twenty minutes of a thirty-five-minute session were spent trying to remember what I had been doing the last time I opened the project, that was a problem.

So I started leaving myself better notes. I broke problems into smaller pieces. I became more deliberate about commits and less interested in keeping an entire feature in my head.

Without really planning to, becoming a parent forced me to get better at stopping halfway through something while leaving enough breadcrumbs that future me could figure out what past me had been doing.

And then React started.

React, the Second Time Around

I joined Code the Dream's React v3 course as part of the Lark Cohort, which ran from November through February.

Code the Dream was not where I first learned React, or where I first built a full-stack application. I had already built MERN applications, worked with APIs, Express, and MongoDB, and completed several development projects with other people through Chingu.

What CTD gave me was something different.

It gave me several months to go back through technologies I already knew and find the places where my understanding was thinner than I realized.

One of those places was Context.

I had used Context before and understood what it did, but there is a difference between knowing that Context exists and getting comfortable designing state around it, combining it with reducers, deciding what actually belongs there, and thinking about what happens as your component tree gets larger.

Sometimes learning something for the second time is a lot more useful than learning it the first time.

The first time, you are mostly trying to make it work.

The second time, you start asking why it works that way.

That became a recurring theme during the course. It was less:

Here is React.

and more:

You know React. Now let's find the parts you have been getting away with not understanding deeply enough.

My guided project grew throughout the course. Reducers came in, Context became more important, routing got more complicated, external data got involved, state crossed more boundaries, and testing became a larger part of the way I worked.

Eventually something I had built myself six weeks earlier could surprise me, which is always reassuring.

Somewhere during that process, the question I asked after completing something changed.

It used to be:

Does it work?

I would click around a few times, see that everything looked fine, and move on.

Now I am much more likely to ask:

Okay, it works. What breaks it?

What happens if the request fails? What happens if the user refreshes here? What if this state has not hydrated yet? What happens if the component disappears before an asynchronous operation finishes? What happens if somebody clicks the same button five times while the first request is still running?

The happy path is still important.

I just trust it a lot less than I used to.

Then I Went Back Through the Backend

After React, I moved into Code the Dream's Node 26.2 Cohort, which ran from late March through June.

Again, Node and Express were not new territory. I had already built full-stack applications and worked with the MERN stack, but going through a dedicated backend course gave me an opportunity to spend more time on the details instead of treating the backend as whatever needed to exist so the frontend could work.

We spent time with routes, middleware, authentication, validation, error handling, HTTP semantics, database access, and application structure.

One technology I got a lot more practice with was Prisma.

I had used Prisma before CTD, but not enough that I would have called myself particularly comfortable with it. CTD gave me more opportunities to use it deliberately instead of simply following the happy path through an ORM.

That distinction mattered.

There are a lot of technologies I have used. That does not necessarily mean I understand all of the decisions they are making for me.

Knowing how to use a tool is one level.

Knowing what that tool is abstracting away is another.

Then Came Practicum

After finishing the coursework, I joined Code the Dream's Summer 2026 Practicum.

This part felt familiar.

I had already done several team projects through Chingu, so practicum was not my introduction to collaboration, Git, pull requests, requirements, product decisions, or the occasional joy of discovering two developers had spent an afternoon independently solving the same problem.

What made practicum interesting was the amount of structure we had to build around the development itself.

Our team built Sprout, a financial literacy application.

The easiest way I have found to describe it is something like Duolingo pointed at personal finance: short lessons, quizzes, progress tracking, onboarding, and a guided learning path.

The idea was to make a subject people know they should understand feel less like sitting down with a textbook, because almost nobody wakes up Saturday morning thinking:

You know what would really make this weekend? Budgeting terminology.

Sprout was not the project I would have chosen on my own, and I think that made the experience more interesting.

When something is your personal project, you can build whatever you want. On a team, the product does not belong entirely to you. You have to build the thing the group agreed to build.

That is a different skill.

Before We Built Much of Anything, We Built a Backlog

One of the first things I did was start planning.

And then I planned some more.

And then apparently I decided Jira had not suffered enough, because I built a pretty enormous backlog.

There are still plenty of tickets sitting in it that we never touched, and that was intentional. A backlog is not a promise that everything gets built. It is a record of things that could get built.

We split the core work across sprint weeks and broke larger ideas into epics, user stories, and smaller tasks. A Jira ticket would often become a GitHub issue. That issue gave us something concrete to build around and could then map to a branch.

Eventually there was a clear line connecting:

idea → epic → story → issue → branch → pull request → application

That process became one of the more valuable parts of practicum for me because a large application does not get built by somebody opening an editor and thinking:

Today I shall implement the application.

You build a small piece. Then another. Then another.

Sometimes several developers were contributing to the same larger feature, so we would use what amounted to a parent or integration branch. Instead of everybody immediately merging their work into development, we could combine related work there first, get the pieces cooperating, fix whatever exploded, and then merge the larger feature.

It added another layer to the Git workflow, but it also prevented development from becoming quite as adventurous.

We Never Really "Finished" an Epic

Something else became apparent pretty quickly: epics are big.

Really big.

When you only have a limited number of weeks, "complete the epic" is often the wrong goal. So we sliced useful pieces out of them instead.

One week we might improve onboarding. Later, we would come back and add something else. The learning path grew incrementally. Admin tools grew incrementally. Accounts grew incrementally. Testing grew incrementally.

Even now, I do not think I could point at many of our larger epics and say:

Yep. Finished forever.

There are still stories sitting in the backlog, but the application works.

That taught me something useful about MVP development. An epic does not have to be complete for part of it to create value. Sometimes the right feature is simply the smallest useful slice of a much larger idea.

In a strange way, I suppose Baby Book had already taught me a smaller version of that lesson.

It never became the application I originally imagined, but for a brief period the pieces we actually needed were useful.

Sometimes software has already done its job before you finish everything you once imagined for it.

Then Sprout Became Complicated

Sprout used React on the frontend, Node and Express on the backend, and MongoDB underneath. We used Tailwind CSS and eventually created a collection of shared components so the UI could stay relatively consistent while different developers worked on different screens.

That became important very quickly.

Without shared components, five developers can somehow invent seven buttons. Each one is slightly different; none of them are necessarily wrong, and together they make the application look like it was assembled by committee.

Because it was.

Shared components gave us some guardrails, but the more interesting architectural decisions happened around the curriculum.

Several members of the team worked together to build our learning material into structured JSON, and a huge part of the application eventually revolved around that structure: lessons, sections, quizzes, questions, answers, and progress.

The JSON became something close to a content engine for the application.

For a while, that worked really well.

Then we started asking uncomfortable questions. Questions like:

Should the correct answers to a quiz really be sitting somewhere the browser can inspect?

Probably not.

One Architecture Decision Created a Whole New Category of Bugs

Eventually we started integrating more of the curriculum data with MongoDB.

Part of the motivation was protecting quiz answers. If the browser receives everything—including which answer is correct—then somebody who knows their way around developer tools can potentially skip the whole "learning" portion of the learning application.

Which feels slightly against the spirit of the thing.

Moving more responsibility to the backend made sense, but architectural decisions rarely arrive alone. This one brought friends: more requests, more synchronization, more state, more opportunities for the frontend and backend to disagree, performance concerns, and some really annoying bugs.

We solved one problem and introduced an entirely different class of problems.

That does not necessarily mean the decision was wrong. It means the decision had a cost, and that might be one of the most useful things Sprout reinforced for me.

Architecture is usually not:

Which solution is correct?

It is more often:

Which set of problems would you rather have?

I may revisit that part of Sprout in the future because I think there are better ways we could protect assessment data without making parts of the experience as expensive or fragile as they became.

But that is also why I am glad we tried it.

You learn a lot more from an architectural decision that creates unexpected problems than one that only exists in a diagram.

Testing Was Only Half of What I Enjoyed

Testing became a major part of my role on the project. I worked with Jest, Vitest, React Testing Library, and Playwright, and I liked the way testing forced us to think beyond the exact sequence of events we pictured when writing a feature.

What happens if the component unmounts? What happens if the network request fails? What if authentication has not finished hydrating? What if somebody double-clicks? What if the frontend thinks a lesson is complete and the backend disagrees?

We found all of those.

But something else ended up being just as interesting to me:

CI.

I really enjoyed working with GitHub Actions and getting our tests running automatically as part of the development workflow.

There is something deeply satisfying about turning:

Somebody should probably run the tests before we merge this.

into:

The repository literally will not let us forget.

That felt like another step beyond simply knowing how to write tests.

A test suite sitting on somebody's laptop is useful. A test suite that runs automatically against changes is infrastructure.

Once I started working on that side of the project, I found myself liking it quite a bit: tests, coverage, automated checks, GitHub Actions, deployment workflows, and all the little pieces that make it harder for a team to accidentally ship something broken.

None of those things are particularly flashy.

But they make everything else easier to trust.

Some Bugs Deserve Their Own ZIP Code

We still had plenty of bugs.

Some were straightforward, friendly bugs. The sort that basically introduce themselves:

Hello. I am on line 47.

Those are wonderful.

Others required the application to be in exactly the wrong state at exactly the right time.

We had authentication behavior where the frontend could decide where a user should be redirected before it had finished determining whether the user was authenticated. Everything worked unless the timing changed, which is always comforting.

We had asynchronous quiz operations where work could finish after the component that started it no longer existed. We had buttons users could click multiple times while a request was still running. We had lesson progression and quiz completion logic with occasionally incompatible definitions of reality.

Some of those bugs looked completely fine when you clicked through the application manually.

Then an automated test created the right sequence of events and everything fell apart.

Beautiful.

Those are the problems I enjoy the most now: the ones where the solution requires understanding the system rather than simply finding a typo.

Git Got More Interesting Too

Working by yourself gives you a very misleading impression of Git.

You make a branch, write some code, commit it, merge it, and suddenly you feel pretty good about version control.

Working with several developers changes the situation, especially once branches start depending on other branches.

Suddenly Git becomes less:

Save my work.

and more:

Which version of this application represents reality right now?

The parent-branch strategy helped with that. So did smaller pull requests, better issues, and simply talking to each other before two people changed the same area of the application.

That is the funny thing about Git problems.

A surprising number of them are actually communication problems that happen to eventually produce merge conflicts.

Practicum Felt Familiar Because of Chingu

A lot of practicum reminded me of Chingu Voyages, which makes sense because I had already done several Voyages as both a developer and a Product Owner.

Chingu had already taught me that two developers can read the same requirement and walk away with completely different applications in their heads. It had already shown me how important communication becomes once multiple people share a repository, and it had already exposed me to team roles and product planning.

The two programs just approached those experiences differently.

Chingu Does a Great Job Simulating a Product Team

One thing I genuinely like about Chingu is that a Voyage can include several different roles.

Developers may work alongside a Product Owner, Scrum Master, and UI/UX Designer, which creates some separation between responsibilities. A designer is concentrating on how something should look and behave. A Product Owner is shaping priorities and requirements. A Scrum Master helps keep the process moving.

Developers then have to take those ideas and make them real.

And eventually everybody discovers that a button somebody drew in thirty seconds somehow requires half a day to implement correctly.

That structure is useful.

The challenge, particularly in some lower tiers, is that experience levels among developers can vary quite a bit. Everybody might technically satisfy the requirements for the Voyage while having very different levels of comfort with JavaScript, Git, architecture, APIs, or debugging.

Sometimes you discover those differences while trying to ship something.

Which, to be fair, is also pretty realistic.

Code the Dream Gave Us a Different Baseline

Code the Dream's practicum had another advantage: everyone had already completed defined coursework.

That did not make everyone's skills identical—not even close—but it gave us shared reference points. We had all traveled through at least some of the same material before arriving at the project.

The bigger difference was that we did not have every traditional product role separated out. We were mostly developers, so we had to wear more hats ourselves.

Someone had to think about product. Someone had to think about design. Someone had to organize the work and maintain the backlog. Someone had to worry about whether CI was working.

Usually everybody ended up doing more than whatever role they originally imagined themselves doing.

And I think that was good for us.

The People Part

Berenice stepped in beside me as a co-project lead, and that helped me more than I probably said at the time. She even played a role in designing the UI/UX.

She gave me somebody to bounce ideas off of while we built epics, shaped user stories, created tasks, organized Jira, and tried to decide which pieces actually mattered enough to belong in our MVP.

Berenice and I worked together to decide which parts were actually critical for an MVP. Those moved forward; the rest could wait.

There are a lot of small judgment calls hidden inside project planning. Having another person there to challenge an idea—or confirm that I was not completely overthinking it—made that a lot easier.

Kristen and Maryzabeth took on another enormous part of the application.

They worked together on our initial low-fidelity wireframes, which became high-fidelity wireframes and eventually the foundation for the UI and UX. Then they worked together on developing the curriculum that became the content driving much of Sprout.

Kristen had a particularly good instinct for keeping us connected to the original vision. Software developers are exceptionally talented at taking a reasonable idea and turning it into fourteen features, three dashboards, a notification system, and possibly a social network.

Sometimes somebody has to say:

We probably do not need that.

Kristen was good at that. A lot of her vision made it into the final product precisely because she was willing to pull us back toward the application we had actually agreed to build.

Maryzabeth became one of those people every remote team quietly depends on. She contributed across both frontend and backend work, but she also became our unofficial secretary.

She took notes, documented decisions, and if somebody missed a meeting or standup, she was usually the person making sure they knew what happened.

That sounds like a small thing until you work on a distributed team.

Then you discover that keeping everybody operating from the same version of reality is basically a feature of its own.

Everybody ended up bringing something beyond code, and that is the part of team development I find most interesting.

We Also Had Actual Adults in the Room

Code the Dream pairs practicum teams with mentors, and our team had Hector and Mario.

Hector brought real-world software development experience into our conversations, while Mario brought a lot of optimism and was always willing to listen while we worked our way through something.

What helped most was rarely somebody simply handing us an answer. Usually it was somebody with more experience asking a question we had not asked ourselves:

Why did you build it this way?

Sometimes we had a very good answer.

Sometimes the answer turned out to be:

Because that is how it currently is.

Those conversations were useful too.

So What Actually Changed?

This is probably where I would describe the year differently than I would have twelve months ago.

I did not learn that teams exist. I had already worked on teams. I did not learn how to build a full-stack application. I had already built them. I did not discover MERN. I already knew it.

What changed was the level at which I started thinking about all of those things.

I understand React Context better than I did. I am much more comfortable with testing. I have more practical experience with Prisma. I learned more about CI and GitHub Actions than I expected to, and I got more interested in the infrastructure surrounding the code.

I spent more time thinking about how work gets broken down before anyone writes it. I became more deliberate about branch strategies when several pieces of one feature were being developed at the same time. I watched an architectural decision solve one problem while creating three new ones, and I saw how much a shared component library matters when several developers are building the same UI.

More than anything, I got another reminder that software development is full of tradeoffs disguised as decisions.

Maybe that is the biggest thing I got out of this year.

I did not necessarily add another stack to the list of technologies I know.

I got better at seeing the system around them.

The Other Lesson Had Nothing to Do With Code

I also learned that progress does not require the schedule I thought it did.

For a long time, I pictured serious development work happening in large, uninterrupted blocks: a free Saturday, several hours at a desk, headphones on, everything lined up.

That sounds wonderful.

It describes almost none of what the past year looked like.

A lot of this year happened in pieces. Thirty minutes here. An hour after bedtime. A bug before dinner. A pull request during nap time. Reading yesterday's notes because I had absolutely no idea what the version of me from forty-eight hours ago had been thinking.

And somehow it still added up.

I used to think real progress required long stretches of uninterrupted time. It turns out a surprising amount of it comes from getting good at returning.

Open the laptop. Find the note. Read the issue. Make the next change. Commit it. Come back later.

That is not the montage version of learning software development.

It is probably a lot closer to the real one.

The Part That Made Any of This Possible

Outside the project, my wife Jayanti listened to far more discussion about failed tests, authentication bugs, GitHub Actions, pull requests, MongoDB, Render deployments, and merge conflicts than any reasonable marriage contract should require.

She was also there through the much more important part of the year while we figured out how to become parents together.

That included the unfinished Baby Book, the last-minute contraction feature, sleep schedules that were mostly theoretical, and plenty of development sessions squeezed into whatever part of the day happened to survive.

It has been a year.

A really good one, a very busy one, and often a very tired one.

So... What's Next?

Practicum has wrapped.

I may keep tinkering with Sprout. There are still architectural decisions I want to revisit, experiments I want to try, and a Jira backlog large enough to keep several imaginary development teams busy.

But I am also ready to build other things.

I have a Rust game I keep coming back to. I want to contribute to open source properly. Baby Book is still sitting somewhere in the back of my head, too.

And I have a growing list of things from this past year that deserve articles of their own: CI pipelines, testing patterns, authentication races, architecture mistakes, Prisma, React, Rust, and the sort of problems where the first draft of the article usually begins with:

I thought this would be easy.

Those are usually the interesting ones.

I have also applied to Code the Dream's apprenticeship program.

I do not know yet whether I will get in, and strangely, I am okay leaving that part of the story there.

Not knowing.

Because that is actually where I am.

There is a tendency when writing about learning software development to wait until you know how the story ends. Get the job. Finish the project. Earn the certificate. Then go back and write the neat version where everything looks like it was leading somewhere obvious.

Real life rarely gives you that version while you are living it.

Right now, I have finished one thing and I am waiting to find out what comes next. Maybe that is the apprenticeship. Maybe it is a job. Maybe it is open source.

Maybe I disappear into Rust for six months and emerge with something deeply unnecessary.

There are worse outcomes.

What I do know is that I finally want to write again, and I have a lot more to write about than I did when this blog went quiet.

So Journey to Code is back.

Probably a little slower. Definitely with more interruptions.

But I think I am okay with that now.

The last year taught me that progress does not always look like moving quickly. Sometimes it just means you keep coming back.

And, conveniently, I just did.

Because of the available computing power at my fingertips I was often times able to experiment well before I should have with hardware. In our family, my dad would always upgrade his PC almost annually to the next latest and greatest system. One of my very first computers was a 286 processor with 16mhz. This introduced me to the world of the command line. I learned early how to navigate and traverse folders using Disk Operating System (or DOS). I learned the del *.* command at some point. At least one time or two, this got me into trouble. At home, it wasn't as big of a deal. After deleting DOS from my root directory once or twice, my dad decided to install his own standalone operating system for me that never let me reach the command line, instead I could only pick what game to play and it would type the commands for me.

The Tech Hand-Me-Down Dynasty

Our household had its own tech ecosystem, with my dad at the top of the pyramid. He'd get the cutting-edge system, then his previous machine would go to my oldest brother, whose computer would then go to my middle brother, which meant I'd inherit whatever my middle brother was using. Being the youngest in a tech-obsessed family had its perks, even if I was always three generations behind the curve.

When Dad upgraded to his first Pentium running at a mind-blowing 100MHz, it kicked off a beautiful cascade of hand-me-downs: oldest brother got Dad's 486 DX2 with 66MHz, middle brother received the 486DX with 33MHz, and I finally graduated to the 386 with 33MHz. Each time this happened, it felt like Christmas morning, even though I was essentially getting the technological equivalent of my brothers' worn-out sneakers.

Living in a rural West Virginia town where the public schools didn't even connect to the internet until after 2000, our home stood out like a digital oasis in a technological desert. My friends would visit and stare in wonder at our setup. Their jaws would hit the floor when they realized we had dedicated phone lines just for internet—a luxury in the era of dial-up when most families had to choose between making calls or going online.

Dad wasn't just tech-savvy; he ran a dial-up internet service provider. This meant we were always on the cutting edge, while my school was still using computers that might as well have been powered by hamster wheels. I never once experienced the frustration of having someone pick up the phone while I was online—a common trauma for most 90s kids.

DOOM, LAN Parties, and the Cruel Reality of Crashed Map Editors

The mid-90s were the golden age of DOOM, and our basement became command central for epic LAN parties around 1995. Back then, Windows couldn't hold a candle to DOS when it came to gaming performance. We would gather, connect our machines, and blast demons (or each other in deathmatch) for hours on end.

But we weren't just players—we were creators too. The DOOM modding scene was where I cut my teeth on level design, spending countless hours crafting custom maps... only to have my underpowered 386 crash mid-creation, erasing everything I'd done. I can still feel that particular brand of heartbreak that comes from losing hours of creative work to the digital void. Nothing teaches you to save your work like losing an entire afternoon's worth of meticulously placed monsters and secret rooms.

Storage in our house was a sight to behold. We literally had hundreds of 5.25" floppy disks stashed everywhere—loaded with games, programming languages, and applications from computing's early days. These massive, actually-floppy disks are probably still boxed up somewhere in my parents' house, a physical museum of software history.

I still remember the technological disappointment of our first 1x CD-ROM drive. On paper, it could hold way more data than any floppy. In practice? I discovered firsthand that it was often faster to install Windows using 64 separate 1.44" floppy disks than waiting for that sluggish CD to do its thing. The only advantage was being able to start the installation and walk away instead of sitting there feeding in disk after disk like some sort of human vending machine.

The Windows Product Key Savant

Here's a weird party trick I still have: I can recite the Windows 95 and 98 product keys from memory. Seriously. After installing these operating systems dozens of times (usually after breaking something), those alphanumeric sequences are permanently etched into my brain alongside my social security number and childhood phone number.

Was it strictly kosher to use the same key repeatedly? Probably not. But in those days, activation was simpler, and we were just kids excited to get our machines back up and running after whatever catastrophe had befallen them (usually self-inflicted).

Accidental Webmaster and the Great Apache Incident

While most kids were content playing Nintendo, my brothers and I were diving headfirst into the wild west of early web development. We honed our skills on Geocities and AngelFire, painstakingly writing HTML in Notepad and proudly publishing pages that were essentially 99% animated GIFs and "Under Construction" banners.

When Dad discovered our interest, he kicked things up several notches—purchasing us a domain name, setting up a web server, and giving each of us our own subdomain. Suddenly we graduated from Notepad to the "professional-grade" Microsoft FrontPage and were learning about mysterious concepts like FTP and hosting. These were the early days of web development. JavaScript was not nearly as powerful as it has become.

One of my more notorious tech moments came when I accidentally installed Apache on my PC and started hosting a web server without even realizing what I'd done. Dad went into full-on security panic mode, convinced we'd been hacked, only to discover it was just his clueless youngest son experimenting with software he didn't understand. When he demanded to know why I'd done it, I genuinely had no idea what he was talking about—I didn't even know what Apache was! I'd just clicked through some install prompts and suddenly our home network had an unexpected web server. The digital equivalent of accidentally building a shed in the backyard.

Emulation: Console Gaming on PC Terms

While my friends were saving up allowance money for GameBoy cartridges and Super Nintendo games, we were exploring the fascinating world of emulation. Why play Super Mario on a tiny GameBoy screen when you could play it on a computer monitor with the ability to save anywhere and apply cheats without those clunky GameShark devices?

It wasn't that we didn't have consoles—our gaming collection included everything from ancient Ataris and Commodore 64s to Nintendo, Super Nintendo, Genesis, Sega CD, and N64. But the flexibility of emulation gave us superpowers that console gamers could only dream of.

The crown jewel of our portable gaming collection wasn't even a Nintendo product—it was the Sega Nomad, a handheld that played full Genesis cartridges with a backlit screen when that was basically unheard of technology. This thing was truly revolutionary—a fully backlit portable console playing 16-bit games when the GameBoy was still rocking monochrome graphics and requiring external light sources.

Breaking Free: My First Custom Build

Fast forward to my teenage years. I was finally ready to break free from the hand-me-down cycle and build my very first PC from scratch. Spoiler alert: it didn't go smoothly.

My first motherboard purchase ended with the vendor vanishing faster than my motivation to do homework. Still salty about that one, but it taught me an early lesson about researching vendors before handing over cash.

Eventually, I assembled what felt like a supercomputer at the time: a Pentium 4 Dual Core running at 1.2GHz paired with some NVIDIA graphics card whose model number has long since faded from memory. But it ran World of Warcraft on maximum settings, and that's all that mattered to teenage me.

The Brother "Borrowing" Incident

When I moved out west, my computer stayed behind. At some point, my brother decided my PC looked lonely and "borrowed" it without asking (as brothers do). Then Christmas rolled around, and guess what appeared under the tree with my name on it? MY OWN PC. With a blown power supply.

I never did replace that power supply. The PC sat gathering dust, a monument to sibling shenanigans and the importance of surge protectors.

The Corporate Castoff Renaissance

Years later, that same brother (yes, redemption arc incoming) was working at a bank that was throwing out perfectly good Dell Optiplex computers. Their only crime? Slow hard drives. These machines were destined for a landfill until he rescued one and brought one to me.

The transformation was mind-blowing: swapping the old HDD for an SSD made boot time instantaneous. We're talking from "go make a sandwich while Windows loads" to "blink and you'll miss it." These corporate castoffs were treasure in disguise!

I happily used one of these rescued machines for years, only upgrading the video card with something cheap off eBay and naturally the power supply to support it. The best part? Unlike many modern proprietary systems, these old Dells accepted standard parts without too much fuss.

Modern Times: From Prebuilt to Power User

Fast forward to last year. I did something that would make younger me gasp in horror—I bought a prebuilt PC from Walmart. I know, I know! But with component prices being what they were, it was actually a good deal.

Of course, I couldn't leave well enough alone. Soon I was upgrading to a Ryzen 5900X and stuffing it with 4x32GB RAM chips because... reasons? Definitely overkill since I don't even game much anymore. But there's something deeply satisfying about having more RAM than you'll ever need.

When my fiancée moved in, I wanted us to have matching battle stations so we could work/game together. My brilliant plan: use the old Dell Optiplex case as the foundation for a second build.

Cue the comedy of errors:

1. Bought a high-end Radeon 7600XT, only to discover neither of my power supplies could support it.

2. Tried to install the motherboard in the Optiplex case, only to find out it does not support it.

3. Attempted to bench test with my spare PSU, which didn't have the required 8-pin connector.

4. Dismantled my prebuilt setup to test the new motherboard.

5. Got the dreaded amber DRAM light.

6. Finally realized I needed to actually connect a GPU to see anything (rookie mistake).

7. Swapped in the 5900X and... red CPU light. Heart attack moment.

8. Discovered several bent pins on my precious processor.

Ever tried to straighten CPU pins? It's like performing microsurgery with household items. I used a playing card to view each row and a sewing needle for gentle bending. After a significant amount of stress and perhaps some foul language, I managed to somehow, SOMEHOW, fix it without breaking off a single pin. Special thanks to Jayanti for holding the flashlight because I could not see a thing without her.

The Unfinished Symphony

The second PC isn't completed yet, but it's coming. It'll be a fully custom AM4 build featuring some of the best components it will support. Probably not the wisest financial decision, but since when has PC building been about making sensible choices?

Looking back at my journey from that hand-me-down 286 to performing pin surgery on high-end AMD processors, I can't help but marvel at how far both technology and my relationship with it have come. From accidentally formatting drives with del *.* to carefully repairing processors that cost more than my first three computers combined, each disaster and triumph has deepened my understanding of these machines.

My dad's tech obsession became my own, passing down through the generations like some kind of digital inheritance. That rural West Virginia kid with a 286 eventually became someone who could resurrect dead machines and build new ones from scratch. (On a good day)

Would I recommend this hobby to others? Absolutely! Just maybe don't start by accidentally hosting web servers, formatting your boot drive, or lending your PC to siblings.

Thank you for joining me on this nostalgic tech journey! Did you experience the hand-me-down computer cycle, DOOM LAN parties, or GeoCities web design? Share your first computer or gaming memories in the comments—I would love to hear how your path through personal computing compares to mine.

In this final article of our Web Components series, we'll explore beyond the present—examining emerging trends, community innovations, and the exciting possibilities that lie on the horizon. The future of Web Components isn't just about technical specifications; it's about how they'll reshape our collective approach to building for the web.

Retrospective

Style Encapsulation: The Shadow DOM’s Protective Barrier

The true power of Web Components lies in their ability to maintain style isolation through Shadow DOM. Unlike traditional HTML elements that are vulnerable to style collisions in complex applications, components with encapsulated styles create a protective boundary that shields their internal structure from external CSS. This isolation enables developers to write simpler, more intuitive CSS without worrying about specificity wars or unintended side effects. A button component, for instance, can maintain its carefully crafted appearance regardless of whether it's placed inside a legacy application with aggressive global styles or a modern design system with strict visual guidelines. This encapsulation doesn't just prevent styles from leaking in—it also prevents internal styles from contaminating the rest of the page, creating a clean contract between the component and its containing application. As applications grow in complexity and teams scale, this level of predictability becomes increasingly valuable, allowing components to be developed, tested, and deployed with confidence.

Fluid Theming with CSS Custom Properties

CSS Custom Properties, also known as CSS Variables, have revolutionized how we approach theming across component boundaries. Unlike earlier approaches that struggled with Shadow DOM's encapsulation, custom properties flow naturally through component boundaries, creating an elegant bridge between isolation and customization. By defining a consistent set of design tokens at the root level—like --primary-color, --font-family, or --border-radius—developers can establish a coherent design language that penetrates even the most deeply nested components. This creates a powerful contract between component authors and consumers: components can expose "styling hooks" through properties while maintaining their internal structure, while applications can inject theme values without needing to understand component internals. The real magic emerges when these properties are combined with dynamic JavaScript manipulation, enabling real-time theme switching, dark mode toggles, or even user-customized themes without complex style recalculations. For large-scale applications and design systems built with Web Components, this approach has become the foundation of scalable theming strategies, balancing component autonomy with system-wide visual consistency.

Cross-Component Styling: How CSS ::part() and the Future of Component Styling

The CSS ::part() pseudo-element represents a significant breakthrough in Web Component styling flexibility. Unlike earlier approaches that compromised encapsulation, ::part() allows component authors to selectively expose specific elements within their shadow DOM for external styling. As MDN documentation explains, it works by targeting "any element within a shadow tree that has a matching part attribute". Component authors maintain control over which elements can be styled while still providing customization points for developers using their components. This creates a clean "styling API" that preserves encapsulation while enabling theming across component boundaries. The syntax is straightforward – simply add a part attribute to internal elements you want to expose, then use the ::part() selector from outside to target them. For component systems and design libraries, this feature is transformative, enabling consistent theming across nested components without sacrificing the isolation that makes Web Components so robust.

This feature shows the Web Component ecosystem maturing to address real-world styling needs, finding the balance between encapsulation and customization that earlier approaches like deep selectors or custom properties couldn't fully achieve.

Custom Events: The Language of Component Conversation

Component communication represents one of Web Components' most elegant solutions, striking a balance between isolation and interconnection. At its core lies the Custom Events API, which enables components to dispatch and listen for events that cross shadow boundaries without sacrificing encapsulation. This pattern follows the platform's own event model, making components feel like natural HTML citizens while maintaining loose coupling. For more complex scenarios, patterns have emerged that mirror popular framework approaches—from simple event buses that facilitate application-wide messaging to sophisticated store implementations that provide observable state changes. The true strength of these approaches is their framework agnosticism; a component built with Lit can seamlessly communicate with one built in vanilla JavaScript, breaking down the walled gardens that have fragmented frontend development. As applications scale, this communication layer becomes the invisible glue that transforms isolated components into cohesive, interactive systems.

The Rising Tide: Emerging Trends

As technology evolves, new paradigms reshape how we build digital experiences. Among these shifts, the push toward modular, interoperable solutions has gained undeniable momentum—nowhere more visibly than in frontend development.

Web Component Libraries on the Rise

Web component libraries have surged in popularity as essential tools for building fast, scalable, and maintainable user interfaces, driven by their framework-agnostic nature, native browser compatibility, and growing standardization. Among the most prominent libraries is Lit (developed by Google), celebrated for its simplicity, lightweight footprint, and high performance. Lit leverages modern Web Components standards like custom elements and shadow DOM, combined with its reactive templating system, to enable developers to create reusable components efficiently. Its declarative syntax and seamless integration with JavaScript, HTML, and CSS make it a top choice for teams prioritizing speed and flexibility.

Shoelace stands out as a UI library offering a rich suite of pre-built, customizable components that work across frameworks. With a focus on design consistency and accessibility, Shoelace emphasizes declarative styling and zero dependencies, allowing developers to adopt components "out of the box" while retaining full control over themes and behavior via CSS custom properties. Its use of native Web Components ensures broad compatibility and future-proofing.

FAST (by Microsoft) is a modern library prioritizing performance, developer ergonomics, and adaptive interfaces. Built on Web Components, FAST provides tools like the FAST Element base class and a design system for creating lightweight, high-performance UIs. Its template engine optimizes rendering speed, while its modular architecture supports incremental adoption in existing projects.

Stencil, a compiler rather than a traditional library, bridges the gap between JSX/React-like syntax and Web Components. It allows developers to write components with TypeScript and JSX, then compiles them into standards-based custom elements. Stencil’s focus on lazy-loading, code splitting, and tree-shaking ensures optimal runtime performance, making it ideal for large-scale applications.

These libraries empower developers to build reusable, cross-platform components with minimal boilerplate, while offering features like scoped CSS (via shadow DOM), server-side rendering support, and seamless integration with modern build tools. Their emphasis on browser standards reduces vendor lock-in and ensures longevity. However, challenges include varying learning curves, the need for polyfills in legacy browsers (e.g., IE11), and potential SEO considerations due to client-side rendering. Additionally, shadow DOM encapsulation can complicate global styling strategies.

As browser support for Web Components matures, libraries like Lit, Shoelace, FAST, and Stencil are increasingly vital for teams seeking performant, maintainable solutions. They not only streamline development workflows but also align with the industry’s shift toward modular, interoperable architectures, solidifying their role in the future of web development.

Is State Management Going Native?: Beyond Properties and Attributes

State management within Web Components has evolved from simple property getters and setters to sophisticated reactive systems that rival established framework solutions. Unlike traditional elements that update through direct DOM manipulation, modern Web Components employ observability patterns that elegantly synchronize internal state with rendered output. The proposed Custom State Pseudo-Class specification takes this further, exposing component states like "loading" or "expanded" directly to CSS, enabling powerful styling based on component behavior without breaking encapsulation. Libraries like Lit State and Web Signals have emerged to facilitate cross-component communication, allowing state to flow between related components without tight coupling. The true innovation comes in how these approaches maintain the platform-native spirit of Web Components—avoiding framework lock-in while still providing the reactivity developers expect. As applications grow increasingly complex, component authors are adopting patterns like stores, reducers, and context-like providers that feel familiar to framework developers but remain firmly rooted in standards-based web platform capabilities. This balance of sophistication and standards-compliance represents the maturing ecosystem around Web Components, addressing what was once considered their primary weakness compared to framework-based solutions.

What is a Web Component Library?

Advanced state management approaches have brought sophisticated patterns like Context to the world of Web Components, elevating them beyond isolated elements to cohesive systems. Inspired by React's Context API but built on platform standards, these implementations create hierarchical state containers that elegantly solve the theme propagation challenge. A ThemeProvider component, for instance, can establish a subscription model where child components automatically receive and react to theme changes without direct parent-child coupling. This pattern creates a powerful alternative to CSS Custom Properties for complex scenarios, enabling not just style values but entire theme configurations to flow through component trees. Libraries like Lit State have formalized these approaches, offering lightweight stores with observability that feels familiar to Redux or Zedustand developers while maintaining Web Components' framework-independence. The true elegance emerges in how these systems leverage existing DOM relationships rather than imposing artificial hierarchies—context flows naturally through component composition, just as it does in native HTML. For enterprise applications with complex theming requirements, this approach transforms Web Components from isolated islands to orchestrated ecosystems without compromising their fundamental platform alignment.

Declarative Shadow DOM: Server-Side Renaissance

One of the most significant limitations of Web Components has long been server-side rendering capabilities. The Declarative Shadow DOM (DSD) is changing this landscape, enabling Web Components to be rendered on the server before reaching the browser.

Frameworks like Astro and Enhance.dev are embracing this approach, delivering Web Components with the performance benefits of server-side rendering:

<my-card>  
  <template shadowroot="open">  
    <style>:host { display: block; }</style>  
    <slot name="title"></slot>  
  </template>  
  <h1 slot="title">Hello from the server!</h1>  
</my-card>

This pattern is already improving initial load times in production applications. As we move into 2025, expect DSD adoption to accelerate, particularly with edge runtime integrations like Cloudflare Workers making server-rendered components even more accessible.

Check out this interactive demo on CodePen to see this pattern in action:

State Management Evolves

State management in complex Web Components can quickly become unwieldy. The community has responded with elegant solutions that feel increasingly native to the platform.

Projects like Web Signals offer a React-inspired state model without the framework dependencies, while Lit State provides reactive state management specifically tailored to component systems. Most exciting is the proposed Custom State Pseudo-Class that will allow styling components based on their internal state:

my-element:--state(loading) {  
  opacity: 0.5;  
}

These approaches promise to be transformative for complex component systems, addressing one of the key challenges in Web Component adoption.

Here is another CodePen that demonstrates how we might be able to use the CSS ::—state() pseudo class in the future.

Micro-Frontends: The Enterprise Adoption

Large enterprises are increasingly embracing Web Components as the foundation of their micro-frontend strategies. Companies that once viewed them as too experimental are now seeing their potential for cross-framework compatibility.

Organizations like Adobe (with Spectrum Web Components) and Microsoft (with Fast Design) are building entire design systems using Web Components that work seamlessly across React, Angular, and Vue applications. Tools like SingleSPA and Webpack Module Federation now offer first-class Web Component support for these multi-framework architectures.

The pattern is clear: as organizations struggle with framework fragmentation, Web Components offer a unifying language that works across team boundaries and technology stacks.

Community Momentum: Tools & Libraries

Lit 4.0: The Evolution Continues

The Lit library continues to lead innovation in the Web Component ecosystem. The upcoming Lit 4.0 brings compiled template literals (delivering 20% faster renders) and enhanced reactive controllers for shared logic patterns.

Their new @lit-labs/analyzer CLI automatically generates TypeScript types and documentation from component code. These quality-of-life improvements address the pain points that have historically made Web Components feel cumbersome compared to framework alternatives.

Scoped Custom Element Registries: Solving Collisions

A persistent challenge in large applications has been the global nature of custom element registration. The proposed Scoped Registries specification offers an elegant solution:

const registry = new CustomElementRegistry();  
registry.define('my-element', MyElement);  
document.createElement('my-element', { registry });

Libraries like @webcomponents/scoped-registry-polyfill are already experimenting with this pattern, allowing different parts of an application to use components with the same names without conflicts. This represents a critical evolution for enterprise adoption, especially in large-scale applications.

Below is a CodePen that demonstrates the usefulness of having a scoped custom registry for a component.

Testing Gets Easier

Testing has long been the Achilles' heel of Web Component development—but the landscape is finally changing. Web Test Runner brings native Web Component support to testing workflows, while Storybook 8.0 now auto-generates documentation and interactive demos for custom elements.

These tools are closing the development experience gap that has kept many developers tethered to framework-specific workflows.

On the Horizon: Speculative Features

Imperative Slotting API

The proposed Imperative Slot API represents perhaps the most significant enhancement to the core Web Components model since Shadow DOM itself. This API will allow dynamic control over slot content via JavaScript:

const slot = element.attachSlot('header');  
slot.appendChild(document.createElement('h1'));

For performance-critical applications that need to bypass DOM operations, this approach could unlock significant optimizations and simplify complex component composition patterns.

Cross-Component Styles

One of the challenges with Shadow DOM has been the balance between style isolation and style sharing. The CSS Scope Proposal introduces an elegant middle path with the @scope directive:

@scope (.card) {  
  h1 { color: red; } /* Only applies inside .card */  
}

This would provide the best of both worlds: style isolation where needed and controlled style inheritance where beneficial.

WebAssembly Integration

The most speculative—but potentially most transformative—frontier is WebAssembly integration. Projects like wasm-bindgen are already exploring paths for Rust-based custom elements that could deliver near-native performance.

Web Components that process complex data visualizations or run machine learning models with the efficiency of compiled code, while maintaining a declarative interface, would open incredible new possibilities.

Check out a simulation of how we can bring WebAssembly into a web component below:

Challenges We Must Overcome

Framework Interoperability

While React 19 and Angular 18 have improved Web Component compatibility, framework-specific patterns (particularly React's hooks system) still create friction with vanilla custom elements. The community is addressing this through the Custom Element Manifest standard, which aims to provide consistent metadata for better tooling and framework integration.

Accessibility Gaps

Despite progress, many Web Components still lack built-in accessibility features. The Accessibility Object Model (AOM) proposal offers a promising solution, allowing components to programmatically declare their semantic roles:

class MyButton extends HTMLElement {  
  constructor() {  
    super();  
    this.accessibleRole = 'button'; // Proposed API  
  }  
}

This evolution is particularly important for components used in applications with strict accessibility requirements, such as government and education sectors.

Education & Advocacy

Technical challenges aside, the most persistent barrier to Web Components adoption remains education. Misconceptions about complexity and boilerplate requirements continue to deter developers from exploring the standard.

Initiatives like webcomponents.org and OpenWC are making strides in curating best practices, while platforms like StackBlitz now offer zero-configuration Web Component development environments. These efforts to lower the barrier to entry will be crucial for the next wave of adoption.

The Ecosystem in 2026 and Beyond

Looking further ahead, several transformative shifts appear on the horizon:

• Browser vendors are experimenting with native lazy-loading for custom elements and GPU-accelerated shadow roots, promising significant performance improvements.

• Design tools like Webflow and Figma are moving toward generating Web Components directly from designs, potentially revolutionizing the designer-developer workflow.

• Decentralized applications are increasingly leveraging Web Components for their portability and framework independence, making them ideal building blocks for blockchain-based interfaces.

Conclusion

The future of Web Components is bright and increasingly central to the web platform's evolution. As browsers continue to implement native solutions for common patterns, the line between "framework features" and "platform features" will increasingly blur, with Web Components sitting at the intersection.

To stay at the forefront of this evolution:

• Follow the W3C Web Components Community Group for standards updates

• Experiment with cutting-edge tools like Lit Labs and Stencil

• Share your work and learn from others

Thank you for joining this exploration of Web Components throughout this article series. Whether you're building a small blog or the next Netflix, these technologies can enhance your development experience and create more resilient, interoperable user interfaces.

Why Framework Integration Matters

Web Components were designed to be universal, but the reality of modern web development means they must coexist with frameworks that have their own component models and lifecycles. Successful integration requires understanding both worlds and the boundaries between them.

"The true power of Web Components isn't isolation from frameworks, but seamless cooperation with them."

What makes integration challenging?

• Different Data Flow Models: React's unidirectional data flow differs fundamentally from the property-based approach of Web Components.

• Event Handling Discrepancies: Each framework has its own event system that must be reconciled with the DOM event model.

• Lifecycle Management: Coordinating component lifecycle events between frameworks and Web Components requires careful orchestration.

Let's explore how to overcome these challenges with practical, reusable patterns.

Seamless Integration with Modern Frameworks

React Integration Strategies

React's declarative approach to UI challenges direct integration with the imperative DOM APIs of Web Components. Here are advanced patterns to bridge this gap:

1. The Ref Pattern: Direct DOM Access

function MyReactComponent() {
  const wcRef = useRef(null);

  useEffect(() => {
    if (wcRef.current) {
      // Direct property assignment for complex data
      wcRef.current.complexData = { key: "value" };

      // Event handling with proper cleanup
      const handleEvent = (e) => console.log(e.detail);
      wcRef.current.addEventListener('custom-event', handleEvent);

      return () => {
        wcRef.current.removeEventListener('custom-event', handleEvent);
      };
    }
  }, []);

  return <my-web-component ref={wcRef} string-prop="This works" />;
}

Key Insights:

• React passes string attributes directly, but complex data requires refs

• Event handling needs manual listeners with proper cleanup

• Ref access enables imperative methods on Web Components

2. The Wrapper Pattern: Creating React-Friendly Components

React developers expect components with React-like patterns. Create wrapper components that abstract Web Component peculiarities:

// Wrapper that handles property mapping and events
function EnhancedWebComponent({ data, onCustomEvent, children }) {
  const ref = useRef(null);

  useEffect(() => {
    const element = ref.current;
    if (element) {
      // Set complex data
      element.data = data;

      // Handle events
      const eventHandler = (e) => onCustomEvent(e.detail);
      element.addEventListener('custom-event', eventHandler);

      return () => element.removeEventListener('custom-event', eventHandler);
    }
  }, [data, onCustomEvent]);

  return (
    <my-web-component ref={ref}>
      {children}
    </my-web-component>
  );
}

// Usage feels like a normal React component
function App() {
  return (
    <EnhancedWebComponent 
      data={{complex: "data"}} 
      onCustomEvent={handleEvent}
    >
      <p>Child content</p>
    </EnhancedWebComponent>
  );
}

Interactive Demo: Try the React integration patterns yourself

Angular Integration Strategies

Angular has built-in support for Web Components through its @angular/elements package, but deeper integration still requires specific techniques:

1. Element Binding with Custom Directives

@Directive({
  selector: 'my-web-component'
})
export class WebComponentDirective implements OnInit, OnChanges, OnDestroy {
  @Input() complexData: any;
  @Output() customEvent = new EventEmitter<any>();

  constructor(private el: ElementRef) {}

  ngOnInit() {
    this.el.nativeElement.addEventListener('custom-event', 
      this.handleCustomEvent.bind(this));
  }

  ngOnChanges(changes: SimpleChanges) {
    if (changes.complexData) {
      this.el.nativeElement.complexData = this.complexData;
    }
  }

  ngOnDestroy() {
    this.el.nativeElement.removeEventListener('custom-event', 
      this.handleCustomEvent.bind(this));
  }

  private handleCustomEvent(event: CustomEvent) {
    this.customEvent.emit(event.detail);
  }
}

Key Insights:

• Angular directives provide clean property and event binding

• OnChanges lifecycle hook updates properties efficiently

• ElementRef gives direct access to the native element

Interactive Demo: Explore Angular integrations

Vue Integration Strategies

Vue offers excellent built-in support for Web Components with its attribute and event binding syntax:

<template>
  <my-web-component 
    :complex-prop="myData" 
    @custom-event="handleEvent"
  />
</template>

<script>
export default {
  data() {
    return {
      myData: { key: 'value' }
    }
  },
  methods: {
    handleEvent(event) {
      console.log(event.detail);
    }
  },
  mounted() {
    // For cases where direct property access is needed
    this.$refs.myComponent.directMethod();
  }
}
</script>

Key Insights:

• Vue's :prop syntax works with kebab-case attributes

• Native event handling with @event-name

• Vue's reactivity system naturally updates Web Component properties

Interactive Demo: Explore Vue integrations

Svelte Integration Strategies

Svelte treats Web Components as first-class citizens and makes integration particularly straightforward:

<script>
  import { onMount } from 'svelte';

  let el;
  let myData = { key: 'value' };

  // Reactive assignments automatically update the Web Component
  $: if (el) {
    el.complexData = myData;
  }

  function handleEvent(event) {
    console.log(event.detail);
  }

  onMount(() => {
    // If needed, do direct manipulation here
    el.addEventListener('special-event', specialHandler);

    return () => {
      el.removeEventListener('special-event', specialHandler);
    }
  });
</script>

<my-web-component 
  bind:this={el} 
  on:custom-event={handleEvent}
/>

Key Insights:

• bind:this provides direct access to the element

• Svelte's reactivity automatically updates properties

• Svelte's event handling works natively with Web Component events

Interactive Demo: Explore Svelte integration Techniques

Framework Comparison Demo: Compare integration approaches across frameworks

Performance Optimization Techniques

Lazy-Loading Strategies

Loading Web Components only when needed can significantly improve initial page load performance:

Dynamic Import Pattern

// Only load when needed
const loadComponent = async () => {
  const { MyComponent } = await import('./my-component.js');
  customElements.define('my-component', MyComponent);
}

// Call on demand or when component is about to be needed
button.addEventListener('click', loadComponent);

Intersection Observer Pattern

// Setup observer to load component when scrolled into view
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      import('./components/lazy-component.js')
        .then(() => {
          // Component is now registered
          observer.unobserve(entry.target);
        });
    }
  });
}, { rootMargin: '100px' });

// Observe placeholder elements
document.querySelectorAll('.component-placeholder')
  .forEach(el => observer.observe(el));

Interactive Demo: See lazy-loading in action

Shadow DOM Performance

The Shadow DOM provides encapsulation but comes with performance considerations:

1. Containment for Performance

    :host {
      contain: content; /* Limit style recalculation scope */
      container-type: inline-size; /* For container queries */
    }
   

2. Minimizing Selectors

    /* Avoid overly complex selectors that cross shadow boundaries */
    :host ::slotted(*) > * { /* Expensive */ }
   
    /* Better to use direct, simple selectors */
    .my-item { /* More efficient */ }
   

3. Slot Change Optimization

    // Listen only when needed
    constructor() {
      super();
      this.shadowRoot.querySelector('slot')
        .addEventListener('slotchange', this._handleSlotChange);
    }
   
    // Debounce frequent updates
    _handleSlotChange = debounce(() => {
      this._processSlottedChildren();
    }, 100);
   

Render Optimization

Efficient rendering patterns can dramatically improve performance:

1. Batched DOM Updates

    // Poor: Multiple separate DOM operations
    this.shadowRoot.querySelector('.title').textContent = title;
    this.shadowRoot.querySelector('.desc').textContent = description;
   
    // Better: Batch DOM operations with DocumentFragment
    update(data) {
      const fragment = document.createDocumentFragment();
      // Build complete update in memory
      const title = document.createElement('div');
      title.className = 'title';
      title.textContent = data.title;
      fragment.appendChild(title);
      // etc...
   
      // Single DOM operation
      const container = this.shadowRoot.querySelector('.container');
      container.innerHTML = '';
      container.appendChild(fragment);
    }
   

2. RequestAnimationFrame for Visual Updates

    updateVisuals() {
      // Schedule visual updates in animation frame
      requestAnimationFrame(() => {
        this.elements.forEach(el => {
          el.style.transform = `translate(${this.x}px, ${this.y}px)`;
        });
      });
    }
   

Interactive Demo: Compare optimized vs. unoptimized components

Advanced Patterns and Best Practices

State Management Across Boundaries

Managing state between Web Components and frameworks requires thoughtful patterns:

1. The Context Pattern

Create a shared context accessible to all components:

// context.js - Framework agnostic state management
export class ComponentContext {
  constructor() {
    this._data = {};
    this._listeners = new Map();
  }

  get(key) {
    return this._data[key];
  }

  set(key, value) {
    this._data[key] = value;
    if (this._listeners.has(key)) {
      this._listeners.get(key).forEach(callback => callback(value));
    }
  }

  subscribe(key, callback) {
    if (!this._listeners.has(key)) {
      this._listeners.set(key, new Set());
    }
    this._listeners.get(key).add(callback);

    return () => {
      this._listeners.get(key).delete(callback);
    };
  }
}

// Create shared instance
export const context = new ComponentContext();

Usage in components:

import { context } from './context.js';

class MyComponent extends HTMLElement {
  connectedCallback() {
    // Subscribe to state changes
    this._unsubscribe = context.subscribe('userData', 
      (data) => this._updateFromState(data));

    // Initial state
    this._updateFromState(context.get('userData'));
  }

  disconnectedCallback() {
    // Clean up subscription
    this._unsubscribe();
  }

  _updateState(data) {
    // Update shared state
    context.set('userData', data);
  }
}

2. The Message Bus Pattern

For loosely coupled components, a pub/sub event bus provides flexible communication:

// event-bus.js
export class EventBus {
  constructor() {
    this.listeners = {};
  }

  on(event, callback) {
    if (!this.listeners[event]) {
      this.listeners[event] = [];
    }
    this.listeners[event].push(callback);

    return () => this.off(event, callback);
  }

  off(event, callback) {
    if (this.listeners[event]) {
      this.listeners[event] = this.listeners[event]
        .filter(cb => cb !== callback);
    }
  }

  emit(event, data) {
    if (this.listeners[event]) {
      this.listeners[event].forEach(callback => {
        callback(data);
      });
    }
  }
}

// Shared instance
export const eventBus = new EventBus();

Server-Side Rendering with Web Components

Server-side rendering improves initial load performance. With Declarative Shadow DOM, you can now SSR Web Components:

<!-- Server-rendered output -->
<my-component>
  <template shadowroot="open">
    <style>
      /* Shadow DOM styles */
      .card { 
        padding: 16px;
        border: 1px solid #ddd;
      }
    </style>
    <div class="card">
      <slot></slot>
    </div>
  </template>
  <p>This content is slotted from light DOM</p>
</my-component>

<!-- Polyfill for browsers without Declarative Shadow DOM -->
<script>
  if (!HTMLTemplateElement.prototype.hasOwnProperty('shadowRoot')) {
    document.querySelectorAll('template[shadowroot]').forEach(template => {
      const mode = template.getAttribute('shadowroot');
      const shadowRoot = template.parentNode.attachShadow({ mode });
      shadowRoot.appendChild(template.content);
      template.remove();
    });
  }
</script>

Testing Strategies

Testing Web Components requires specialized approaches:

1. Component Unit Testing

// Using web-test-runner and @open-wc/testing
import { html, fixture, expect } from '@open-wc/testing';
import '../src/my-component.js';

describe('MyComponent', () => {
  it('renders with default values', async () => {
    const el = await fixture(html`<my-component></my-component>`);

    expect(el.shadowRoot.querySelector('.title').textContent)
      .to.equal('Default Title');
  });

  it('updates when properties change', async () => {
    const el = await fixture(html`<my-component></my-component>`);

    el.title = 'New Title';
    await el.updateComplete; // For LitElement components

    expect(el.shadowRoot.querySelector('.title').textContent)
      .to.equal('New Title');
  });

  it('fires custom events', async () => {
    const el = await fixture(html`<my-component></my-component>`);

    // Setup event listener
    let eventFired = false;
    el.addEventListener('custom-event', () => eventFired = true);

    // Trigger event
    el.shadowRoot.querySelector('button').click();

    expect(eventFired).to.be.true;
  });
});

2. Integration Testing with Frameworks

// React Testing Library example
import { render, fireEvent, screen } from '@testing-library/react';
import MyReactComponent from '../src/MyReactComponent';

// Register Web Component if not done globally
import '../src/web-components/my-element.js';

test('React component interacts with Web Component', async () => {
  render(<MyReactComponent initialData="test" />);

  // Interact with the wrapped Web Component
  fireEvent.click(screen.getByRole('button'));

  // Check the result
  expect(screen.getByText('Success')).toBeInTheDocument();
});

The Future of Web Components

Web Components continue to evolve with exciting new capabilities on the horizon:

• CSS Shadow Parts: More sophisticated styling across shadow boundaries

• Form-associated Custom Elements: Better integration with native forms

• Constructable Stylesheets: Improved performance for shared styles

• Scoped Custom Element Registries: Avoiding name conflicts

• Declarative Custom Elements: Simplified component definition

Conclusion

Web Components shine brightest when they seamlessly integrate with existing frameworks and tools. By leveraging the advanced patterns covered in this guide, you can build truly reusable components that work anywhere while maintaining optimal performance and developer experience.

The future of front-end development isn't about choosing between Web Components and frameworks—it's about building bridges between them to create more maintainable, performant applications.

Let's start with a basic example of a Web Component. This interactive demo shows the fundamental structure and lifecycle methods that make Web Components work. You can see how the component reacts when it's added to the DOM, removed, or when its attributes change:

Try clicking the buttons to see the lifecycle methods in action. This simple example demonstrates the core concepts of Web Components: custom elements, shadow DOM encapsulation, and lifecycle callbacks.

Who's Using Web Components Today?

Several major tech companies have embraced Web Components for their production applications:

Google

Google was an early champion of Web Components and continues to use them extensively:

• YouTube: The YouTube web application uses Web Components for its video player interface, comments section, and recommendation panels.

• Google Maps: Many of the interactive elements in Google Maps are built as custom elements.

• Google Earth: The web version leverages Web Components for its UI controls.

Microsoft

Microsoft has significantly invested in Web Components:

• Microsoft's Fluent UI: Their design system is implemented as Web Components to ensure consistent UIs across products.

• Microsoft 365: Various applications within the suite use custom elements for shared functionality.

• VS Code: Many interface elements are implemented as Web Components.

Adobe

Adobe has embraced Web Components for their design systems:

• Adobe Spectrum: Their design system is available as Web Components through the Spectrum Web Components library.

• Adobe Experience Cloud: Uses components from their Spectrum library across products.

Other Notable Examples

• Salesforce: Their Lightning Web Components framework is built on the Web Components standards.

• ING Bank: Redesigned their web applications using Web Components for consistent UX across platforms.

• IBM: Carbon design system offers Web Components implementations.

• GitHub: Uses Web Components for various UI elements across their platform.

• Netflix: Has incorporated custom elements in parts of their streaming interface.

Popular Web Component Libraries & Hosting Strategies

Libraries and Frameworks

Several libraries have emerged to simplify Web Component development:

1. Lit: Google's lightweight library (successor to Polymer) has become the most popular choice for creating Web Components with minimal boilerplate.

2. Stencil: Created by the Ionic team, Stencil generates highly optimized Web Components and can output framework-specific wrappers.

3. FAST: Microsoft's adaptive UI library produces Web Components that automatically adapt to user preferences.

4. Shoelace: A collection of professionally designed, every day UI components built on a framework-agnostic technology.

5. Enhance: A framework that uses progressive enhancement to create multi-page applications with Web Components.

Hosting & Distribution Strategies

Companies distribute their Web Components in several ways:

1. NPM Packages: The most common approach, allowing developers to install components via package managers.

   • Example: npm install @adobe/spectrum-web-components

2. CDN Delivery: Pre-built components hosted on CDNs allow for quick inclusion without build steps.

   • Example: <script type="module" src="https://unpkg.com/@shoelace-style/shoelace@2.0.0/dist/shoelace.js"></script>

3. Custom Element Registries: Specialized registries like webcomponents.org catalog available components.

4. Bundled with Applications: Many applications bundle custom elements as part of their build process.

5. Micro-frontend Architecture: Components distributed across multiple teams but united in a single application.

Common Patterns in Production Web Components

Composition Pattern

One of the most powerful patterns is component composition:

<!-- Container component -->
<user-profile>
  <!-- Composable child components -->
  <user-avatar slot="avatar"></user-avatar>
  <user-info slot="info"></user-info>
  <user-stats slot="stats"></user-stats>
</user-profile>

This pattern enables teams to build complex UIs from simpler building blocks, a strategy employed by many design systems.

To see the composition pattern in action, here's an interactive demo that demonstrates how slots distribute content in Web Components:

This card component uses three distinct slots (header, body, and footer) to create a flexible, reusable UI element. Try toggling different parts of the content to see how:

1. The component maintains its structure even when slots are empty

2. Content from the "light DOM" (your HTML) flows into the designated slots

3. The component's styling remains consistent regardless of the content provided

4. The theme can change while preserving the composition structure

5. The code preview updates to show exactly what HTML you would write to achieve the current state

This pattern is especially powerful for design systems, as it allows components to maintain consistent styling and behavior while giving content authors flexibility to provide custom content for different sections.

Property/Attribute Pattern

Attributes for simple values, properties for complex data:

class DataTable extends HTMLElement {
  // Simple configuration via attributes
  static get observedAttributes() { 
    return ['loading', 'pagination']; 
  }

  // Complex data via properties
  set data(value) {
    this._data = value;
    this._renderTable();
  }
}

Google's Material Web Components and Adobe's Spectrum Web Components both follow this pattern.

To better understand how attributes and properties work together in Web Components, let's explore this interactive demo that clearly demonstrates their differences:

This demo shows how attributes are best for simple values that can be represented in HTML markup (strings, booleans), while properties excel at handling complex data like arrays and objects. Try using the controls to manipulate both attributes and properties, and observe how:

1. Attribute changes trigger the attributeChangedCallback() and appear in the HTML markup

2. Property changes don't affect the HTML markup but can handle complex data structures

3. The component responds to both types of changes in different ways

This pattern is widely used in production Web Components. For example, Google's Material Web Components use attributes for styling options (like variant or dense), while reserving properties for data binding with complex values.

Event-Based Communication Pattern

Components communicate through custom events:

// Inside the component
this.dispatchEvent(new CustomEvent('item-selected', {
  bubbles: true,
  composed: true, // Crosses shadow DOM boundary
  detail: { id: selectedId }
}));

// Parent listening for events
document.querySelector('my-component')
  .addEventListener('item-selected', (e) => console.log(e.detail.id));

GitHub's web components utilize this pattern for their interactive elements.

Let's see events in action with this interactive demo. Here, two completely separate web components communicate through custom events without direct references to each other - a fundamental pattern for creating loosely coupled, reusable components:

In this example:

• The color picker component dispatches a color-changed event when a color is selected

• The event includes detailed data in the detail property (color code and name)

• The display component listens for this event and updates accordingly

• Notice how bubbles: true and composed: true allow the event to cross shadow DOM boundaries

API Consistency Pattern

Successful Web Component libraries establish consistent APIs:

// Consistent naming and behavior across components
<sl-button variant="primary" size="large" disabled></sl-button>
<sl-dropdown variant="primary" size="large" disabled></sl-dropdown>
<sl-checkbox variant="primary" size="large" disabled></sl-checkbox>

Microsoft's FAST components and Shoelace both exemplify this pattern with predictable property names.

Real-World Implementation Examples

Design System Components

Design systems often implement form controls with enhanced functionality:

class EnhancedSelect extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.innerHTML = `
      <style>
        :host {
          display: inline-block;
          position: relative;
          width: 200px;
        }
        .select-container {
          border: 1px solid var(--border-color, #ccc);
          border-radius: 4px;
          padding: 8px;
        }
        /* Additional styles... */
      </style>
      <div class="select-container">
        <slot name="selected-option"></slot>
        <div class="dropdown">
          <slot></slot>
        </div>
      </div>
    `;

    // Implementation details...
  }
}

customElements.define('enhanced-select', EnhancedSelect);

Now let's explore a fully functional implementation of the EnhancedSelect component that demonstrates how design system principles are applied in practice:

This enhanced select component showcases several key design system features:

1. Theming - The component responds to design tokens for colors, spacing, and typography

2. Consistent Visual Language - The styling follows design system patterns with proper spacing and visual hierarchy

3. Accessibility - The component implements ARIA attributes, keyboard navigation, and focus management

4. Configurability - Properties like density, size, and shape variants provide flexibility within the design system

5. Component API - The interface follows consistent patterns with attributes and properties

Try changing the theme, density, and other properties to see how the component adapts while maintaining design system consistency. This pattern of using CSS custom properties as design tokens is used by libraries like Adobe's Spectrum Web Components and Microsoft's FAST.

Content Widgets

News sites and content platforms often use web components for interactive widgets:

class ContentRecommendation extends HTMLElement {
  static get observedAttributes() {
    return ['category', 'count'];
  }

  attributeChangedCallback(name, oldValue, newValue) {
    if (oldValue !== newValue) {
      this._fetchRecommendations();
    }
  }

  connectedCallback() {
    this._fetchRecommendations();
  }

  async _fetchRecommendations() {
    const category = this.getAttribute('category') || 'general';
    const count = parseInt(this.getAttribute('count') || '3', 10);

    try {
      const response = await fetch(`/api/recommendations?category=${category}&count=${count}`);
      const data = await response.json();
      this._renderRecommendations(data);
    } catch (error) {
      console.error('Failed to fetch recommendations:', error);
    }
  }

  _renderRecommendations(items) {
    // Render logic...
  }
}

customElements.define('content-recommendation', ContentRecommendation);

This pattern is used by sites like The Guardian and Washington Post for their recommendation modules.

Here's a working example of a content recommendation component that demonstrates the key concepts of content widgets in web components:

This demonstration shows how content-focused components:

1. Fetch and display dynamic content - Simulating API calls to retrieve articles based on user selections

2. Handle loading states - Using skeleton loaders to improve perceived performance

3. Manage error conditions - Gracefully handling failures with clear user feedback

4. Communicate via events - Dispatching custom events when articles are loaded or selected

5. Respond to configuration changes - Updating content based on category and count selections

This pattern is commonly used by news sites, blogs, and content platforms to create modular, reusable recommendation widgets that can be placed throughout their applications.

This pattern is similar to what you'd find on content-heavy sites like The Guardian or The Washington Post, where web components encapsulate complex content widgets while maintaining clean integration with the surrounding application.

Performance Patterns

Lazy-Loading Components

Many production Web Components implement lazy-loading to improve performance:

// Only load the component when needed
document.querySelector('#show-comments').addEventListener('click', async () => {
  // Dynamically import the component
  await import('./components/comment-section.js');

  // Now create and use it
  const commentSection = document.createElement('comment-section');
  document.querySelector('#comments-container').appendChild(commentSection);
});

YouTube uses this pattern extensively to load UI components only when needed.

To demonstrate the power of lazy loading web components, here's an interactive example that simulates loading resource-intensive UI components only when needed:

This demo shows how lazy loading can dramatically improve initial page load performance by:

1. Reducing initial page weight - Only the core 10KB of code loads initially

2. Loading components on demand - Each component is loaded only when requested

3. Providing visual feedback - The performance meter shows the impact of each loaded component

4. Using dynamic imports - Components are loaded asynchronously without blocking the main thread

Try clicking the buttons to load different components and watch how the page weight increases only when new components are added. This pattern is used extensively by YouTube for their video player interface, where heavy components are loaded only when the user interacts with them.

Constructable Stylesheets

For components used multiple times on a page, shared stylesheets improve performance:

// Create once, use many times
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  :host {
    display: block;
    padding: 16px;
  }
  .content {
    color: var(--text-color, #333);
  }
`);

class ReusableCard extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    // Use the shared stylesheet
    shadow.adoptedStyleSheets = [sheet];
    shadow.innerHTML = `<div class="content"><slot></slot></div>`;
  }
}

Google's Material Web Components use this pattern for performance optimization.

To better understand the performance benefits of Constructable Stylesheets, this interactive demo demonstrates the difference between traditional inline styles (duplicated for each component) and shared stylesheets (reused across all components):

Try adding multiple components with both methods to see how Constructable Stylesheets significantly reduce memory usage and improve performance as the number of components increases. This technique is especially valuable in applications like YouTube, where dozens or hundreds of component instances might appear on a single page.

Accessibility in Production Web Components

Successful Web Components in production prioritize accessibility:

class AccessibleTabPanel extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.innerHTML = `
      <div class="tabs" role="tablist">
        <slot name="tab"></slot>
      </div>
      <div class="panels">
        <slot name="panel"></slot>
      </div>
    `;

    // Add keyboard navigation, ARIA attributes, etc.
  }

  connectedCallback() {
    // Set up accessibility requirements
    const tabs = this.querySelectorAll('[slot="tab"]');
    const panels = this.querySelectorAll('[slot="panel"]');

    tabs.forEach((tab, index) => {
      // Set ARIA attributes
      tab.setAttribute('role', 'tab');
      tab.setAttribute('aria-selected', index === 0 ? 'true' : 'false');
      tab.setAttribute('tabindex', index === 0 ? '0' : '-1');
      tab.setAttribute('aria-controls', `panel-${index}`);

      // Set panel attributes
      panels[index].setAttribute('role', 'tabpanel');
      panels[index].setAttribute('id', `panel-${index}`);
      panels[index].setAttribute('aria-labelledby', tab.id);
      panels[index].hidden = index !== 0;

      // Add event listeners for keyboard navigation
      // ...
    });
  }
}

Adobe's Spectrum Web Components and Microsoft's FAST components both implement comprehensive accessibility features like this.

Accessibility is a crucial aspect of web components. Let's explore an accessible tab panel component that demonstrates proper keyboard navigation and ARIA attributes:

This accessible tab panel implementation showcases several key accessibility features:

1. Proper ARIA roles and attributes - Using role="tablist", role="tab", and role="tabpanel" with appropriate relationships

2. Keyboard navigation - Arrow keys to move between tabs, Home/End to jump to first/last tab

3. Focus management - Visible focus indicators and proper focus order

4. Screen reader support - Appropriate announcements when tabs change

Try navigating the tabs using only your keyboard. Press Tab to focus on the tab list, then use arrow keys to move between tabs. Notice how the focus is visually indicated and how the selected tab's content is displayed.

This implementation follows the WAI-ARIA Authoring Practices for tab panels, ensuring that users of assistive technologies can effectively interact with the component.

Integration with Frameworks

Many organizations need to integrate Web Components with existing framework codebases:

React Integration

// React wrapper around a Web Component
import React, { useRef, useEffect } from 'react';
import 'my-web-components/dist/data-chart.js';

function DataChartWrapper(props) {
  const chartRef = useRef(null);

  useEffect(() => {
    // Pass complex data as properties
    if (chartRef.current) {
      chartRef.current.data = props.data;
    }
  }, [props.data]);

  // Pass simple values as attributes
  return (
    <data-chart
      ref={chartRef}
      theme={props.theme}
      height={props.height}
      onChartUpdate={props.onUpdate}
    />
  );
}

Salesforce uses this pattern to integrate their Lightning Web Components with React applications.

To see how React and Web Components work together in practice, here's an interactive demo showing the integration patterns in action:

This demo showcases the key integration patterns described earlier:

1. Using refs to access Web Component properties - React uses a ref to directly set properties on the Web Component

2. Event-based communication - The Web Component dispatches custom events that React listens for

3. Bidirectional data flow - Changes in either React or the Web Component are synchronized

Try changing the color or clicking the buttons on either side to see how React and the Web Component communicate. Notice how property changes flow from React to the Web Component, while events flow from the Web Component back to React.

Micro-Frontend Architectures with Web Components

Organizations like ING Bank have implemented micro-frontend architectures using Web Components:

<!-- Shell application -->
<html>
<head>
  <title>Banking Dashboard</title>
  <!-- Import shared components -->
  <script type="module" src="/shared/components/ing-header.js"></script>
  <script type="module" src="/shared/components/ing-footer.js"></script>
</head>
<body>
  <!-- Shared header component owned by core team -->
  <ing-header user-id="12345"></ing-header>

  <!-- Micro-frontend container -->
  <main>
    <!-- Accounts micro-frontend owned by accounts team -->
    <accounts-overview></accounts-overview>

    <!-- Investments micro-frontend owned by investments team -->
    <investments-summary></investments-summary>

    <!-- Loans micro-frontend owned by loans team -->
    <loans-overview></loans-overview>
  </main>

  <!-- Shared footer component -->
  <ing-footer></ing-footer>

  <!-- Load micro-frontends -->
  <script type="module" src="/accounts/components/accounts-overview.js"></script>
  <script type="module" src="/investments/components/investments-summary.js"></script>
  <script type="module" src="/loans/components/loans-overview.js"></script>
</body>
</html>

This approach allows different teams to develop and deploy independently while maintaining a cohesive user experience.

Let's visualize how a micro-frontend architecture might work in practice with this interactive demo:

This simplified banking portal demonstrates the core principles of micro-frontend architecture:

1. Team Ownership Separation - Each colored section is owned by a different team

2. Independent Development - Each team can build and deploy their component independently

3. Cross-Team Communication - Components interact through a centralized event bus

4. Consistent User Experience - Despite being developed separately, components provide a unified experience

Try interacting with different components and watch the event log to see how they communicate. When you click on an account in the Accounts section, notice how the Support widget responds with contextual information - demonstrating cross-component communication.

This pattern is similar to ING Bank's approach, where different teams own distinct parts of the application while maintaining a cohesive user experience through standardized design systems and communication protocols.

Future Trends

Based on real-world adoptions, several trends are emerging:

1. Server-Side Rendering with Declarative Shadow DOM - Companies like Salesforce and Google are exploring SSR for Web Components.

2. Web Components in Design Systems - More organizations are standardizing their design systems as Web Components.

3. Framework Integration Tools - Better tools for seamless integration with React, Angular, and Vue are being developed.

4. Performance Optimizations - Techniques like Constructable Stylesheets and lazy-loading are becoming standard practice.

5. Web Component Marketplaces - More robust ecosystems for sharing and discovering components are emerging.

Conclusion

Web Components have moved beyond theory into practical, production-ready solutions embraced by major tech companies. The patterns established by these implementations provide valuable blueprints for organizations looking to create scalable, maintainable component libraries that work across frameworks and technologies.

By examining real-world examples from Google, Microsoft, Adobe, and others, we can see that Web Components excel in scenarios requiring reusability, framework-agnosticism, and long-term stability. Whether you're building a design system, implementing micro-frontends, or simply creating UI widgets, these production-tested patterns can guide your implementation.

As browser support and tooling continue to improve, we can expect Web Components to become an even more essential part of the web development ecosystem.

Resources

• Web Components on MDN

• Google's Lit library

• Microsoft's FAST components

• Adobe's Spectrum Web Components

• Shoelace components

• WebComponents.org

Meet Sarah, a web user who navigates the internet using a screen reader. When she encounters custom elements on websites, her experience isn't determined by visual design—it's determined by whether developers prioritized accessibility. When developers overlook the needs of millions of users with disabilities, they transform bridges into barriers, creating frustration instead of inclusive solutions.

Web components unlock a world of possibilities, empowering developers to craft highly customizable, reusable elements that elevate both modularity and maintainability. Yet their true power lies not just in technical elegance, but in their ability to serve all users. This guide will take you through essential strategies for creating truly inclusive web components—exploring semantic HTML, ARIA roles, keyboard navigation, and robust testing methodologies. You'll find interactive examples throughout that invite you to experiment, transforming abstract concepts into tangible skills you can immediately apply.

With these fundamentals in mind, let's see accessibility in action.

The Accessibility Difference

The following examples demonstrate how seemingly small details create dramatically different user experiences:

Before diving into details, let's visualize the difference accessibility makes:

Try using only your keyboard (Tab and Enter) to interact with both buttons above. Notice how the accessible version provides:

• Clear focus indication
• Proper state announcement
• Keyboard operability

These seemingly small details make a tremendous difference for users relying on assistive technologies.

Understanding Accessibility in Web Components

Now that we've seen the tangible impact of accessibility features, let's explore the core principles that make web components truly inclusive for all users.

Accessibility (often abbreviated as A11y) involves designing products usable by people with disabilities. For Web Components, this means ensuring custom elements are perceivable, operable, understandable, and robust for all users.

Key Considerations:

• Semantic HTML: Use appropriate HTML elements to convey meaning, as browsers and assistive technologies rely on these semantics.
• ARIA Roles and Properties: When native HTML elements are insufficient, ARIA roles and properties provide additional accessibility information.
• Keyboard Accessibility: Ensure all interactive elements are navigable and operable via keyboard.
• Focus Management: Properly manage focus to assist users navigating with keyboards or assistive devices.

While these accessibility considerations apply to all web development, Web Components introduce unique challenges through their use of Shadow DOM—an essential feature that requires thoughtful implementation.

The Shadow DOM Challenge

Web Components use Shadow DOM to encapsulate styles and functionality, creating unique accessibility challenges:

1. Style Isolation: Focus styles might not be visible if they rely on global CSS
2. DOM Isolation: ARIA relationships across shadow boundaries might not work as expected
3. Event Handling: Custom events must properly handle keyboard interactions

Despite these challenges, you can create fully accessible Web Components with the right approach. Let's explore practical implementation strategies that address these concerns while maintaining the benefits of encapsulation.

Implementing Accessibility in Web Components

These challenges can be overcome with proper implementation, as demonstrated in the examples below.

1. Semantic HTML and ARIA Roles

Start with native HTML elements that inherently provide accessibility. When creating custom elements, assign appropriate ARIA roles and properties to convey their purpose and state.

Interactive Example: Accessible Toggle Button

class AccessibleToggle extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.pressed = false;
    this.render();
  }

  connectedCallback() {
    this.shadowRoot.querySelector('button').addEventListener('click', () => this.toggle());
    this.shadowRoot.querySelector('button').addEventListener('keydown', (e) => {
      if (e.key === 'Enter' || e.key === ' ') {
        e.preventDefault();
        this.toggle();
      }
    });
  }

  toggle() {
    this.pressed = !this.pressed;
    this.render();
    this.dispatchEvent(new CustomEvent('toggle', { 
      bubbles: true,
      detail: { pressed: this.pressed }
    }));
  }

  render() {
    const button = this.shadowRoot.querySelector('button') || document.createElement('button');
    button.setAttribute('role', 'button');
    button.setAttribute('aria-pressed', this.pressed);
    button.setAttribute('aria-label', this.getAttribute('label') || 'Toggle');
    button.innerHTML = this.pressed ? 'ON' : 'OFF';
    button.className = this.pressed ? 'pressed' : '';

    if (!this.shadowRoot.querySelector('button')) {
      this.shadowRoot.innerHTML = `
        <style>
          button {
            padding: 8px 16px;
            border: 2px solid #333;
            border-radius: 4px;
            font-size: 16px;
            cursor: pointer;
            transition: all 0.3s;
          }
          button:focus-visible {
            outline: 3px solid blue;
            outline-offset: 2px;
          }
          button.pressed {
            background-color: #4CAF50;
            color: white;
          }
          button:not(.pressed) {
            background-color: #f1f1f1;
          }
        </style>
      `;
      this.shadowRoot.appendChild(button);
    }
  }
}

customElements.define('accessible-toggle', AccessibleToggle);

Key accessibility features:

• Uses aria-pressed to convey state to assistive technologies
• Provides visible state indication through color and text changes
• Ensures keyboard operability with Enter and Space keys
• Implements strong focus indication with high contrast outline
• Dispatches events that can be caught by parent components

Try navigating to the button with Tab and activating it with Enter or Space. A screen reader would announce: "Toggle button, not pressed" and after activation: "Toggle button, pressed."

2. Keyboard Accessibility and Focus Management

With the foundation of proper semantics established, let's focus on how users navigate through interactive components without a mouse.

Proper focus management is crucial, especially with dynamic content or modal dialogs. Users navigating with keyboards need clear focus indication and logical tab order.

Interactive Example: Accessible Modal Dialog

class AccessibleModal extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this._previouslyFocusedElement = null;
    this.render();
  }

  connectedCallback() {
    const trigger = this.shadowRoot.querySelector('#modal-trigger');
    const closeBtn = this.shadowRoot.querySelector('#modal-close');
    const dialog = this.shadowRoot.querySelector('[role="dialog"]');

    trigger.addEventListener('click', () => this.open());
    closeBtn.addEventListener('click', () => this.close());

    // Close on Escape key
    this.addEventListener('keydown', e => {
      if (e.key === 'Escape' && !dialog.hasAttribute('aria-hidden')) {
        this.close();
      }
    });

    // Close when clicking outside the modal
    this.shadowRoot.querySelector('.modal-overlay').addEventListener('click', e => {
      if (e.target.classList.contains('modal-overlay')) {
        this.close();
      }
    });
  }

  open() {
    this._previouslyFocusedElement = document.activeElement;
    const dialog = this.shadowRoot.querySelector('[role="dialog"]');
    dialog.removeAttribute('aria-hidden');
    this.shadowRoot.querySelector('.modal-overlay').style.display = 'flex';
    this.shadowRoot.querySelector('#modal-close').focus();

    // Trap focus inside modal
    this._handleFocusTrap();
  }

  close() {
    this.shadowRoot.querySelector('[role="dialog"]').setAttribute('aria-hidden', 'true');
    this.shadowRoot.querySelector('.modal-overlay').style.display = 'none';

    // Restore focus
    if (this._previouslyFocusedElement) {
      this._previouslyFocusedElement.focus();
    }
  }

  _handleFocusTrap() {
    const focusableElements = this.shadowRoot.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
    const firstFocusable = focusableElements[0];
    const lastFocusable = focusableElements[focusableElements.length - 1];

    this.shadowRoot.addEventListener('keydown', e => {
      if (e.key === 'Tab') {
        if (e.shiftKey && document.activeElement === firstFocusable) {
          e.preventDefault();
          lastFocusable.focus();
        } else if (!e.shiftKey && document.activeElement === lastFocusable) {
          e.preventDefault();
          firstFocusable.focus();
        }
      }
    });
  }

  render() {
    this.shadowRoot.innerHTML = `
      <style>
        .modal-overlay {
          position: fixed;
          top: 0;
          left: 0;
          right: 0;
          bottom: 0;
          background-color: rgba(0, 0, 0, 0.5);
          display: none;
          justify-content: center;
          align-items: center;
          z-index: 1000;
        }

        .modal-content {
          background-color: white;
          padding: 20px;
          border-radius: 4px;
          max-width: 500px;
          width: 90%;
          box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);
        }

        button {
          padding: 8px 16px;
          cursor: pointer;
          border-radius: 4px;
        }

        button:focus-visible {
          outline: 3px solid blue;
          outline-offset: 2px;
        }

        #modal-close {
          float: right;
          background: none;
          border: 1px solid #ccc;
          font-size: 16px;
        }

        #modal-trigger {
          background-color: #4CAF50;
          color: white;
          border: none;
          font-size: 16px;
        }
      </style>

      <button id="modal-trigger">Open Modal</button>

      <div class="modal-overlay">
        <div role="dialog" aria-labelledby="modal-title" aria-modal="true" aria-hidden="true" class="modal-content">
          <button id="modal-close" aria-label="Close dialog">×</button>
          <h2 id="modal-title">Accessible Modal Dialog</h2>
          <p>This is an example of an accessible modal dialog component.</p>
          <p>It traps focus inside the modal, can be closed with the ESC key, and restores focus when closed.</p>
          <button>Test Button 1</button>
          <button>Test Button 2</button>
        </div>
      </div>
    `;
  }
}

customElements.define('accessible-modal', AccessibleModal);

Key accessibility features:

• Focus trap within the modal (users can't tab out accidentally)
• Keyboard closing with Escape key
• Focus restoration when modal closes
• Proper ARIA roles (dialog, aria-labelledby, aria-modal)
• Clear visual focus indicators

Try opening the modal and navigating with Tab. Notice how focus is trapped inside the modal and restored to the trigger button when closed.

3. Complex Components and Keyboard Navigation

While proper keyboard navigation creates a solid foundation, complex components like tabs, accordions, and carousels require specialized interaction patterns to maintain usability.

Interactive Example: Accessible Tabs

class AccessibleTabs extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.render();
  }

  connectedCallback() {
    const tabs = Array.from(this.shadowRoot.querySelectorAll('[role="tab"]'));
    const panels = Array.from(this.shadowRoot.querySelectorAll('[role="tabpanel"]'));

    // Select first tab by default
    this.selectTab(tabs[0]);

    tabs.forEach(tab => {
      tab.addEventListener('click', () => this.selectTab(tab));

      tab.addEventListener('keydown', e => {
        // Arrow key navigation
        if (e.key === 'ArrowRight' || e.key === 'ArrowLeft') {
          e.preventDefault();

          const currentIndex = tabs.indexOf(tab);
          let nextIndex;

          if (e.key === 'ArrowRight') {
            nextIndex = (currentIndex + 1) % tabs.length;
          } else {
            nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
          }

          tabs[nextIndex].focus();
          this.selectTab(tabs[nextIndex]);
        }

        // Home and End keys for first/last tabs
        if (e.key === 'Home') {
          e.preventDefault();
          tabs[0].focus();
          this.selectTab(tabs[0]);
        }

        if (e.key === 'End') {
          e.preventDefault();
          tabs[tabs.length - 1].focus();
          this.selectTab(tabs[tabs.length - 1]);
        }
      });
    });
  }

  selectTab(selectedTab) {
    const tabs = Array.from(this.shadowRoot.querySelectorAll('[role="tab"]'));
    const panels = Array.from(this.shadowRoot.querySelectorAll('[role="tabpanel"]'));

    tabs.forEach(tab => {
      const selected = tab === selectedTab;
      tab.setAttribute('aria-selected', selected);
      tab.setAttribute('tabindex', selected ? '0' : '-1');
    });

    panels.forEach(panel => {
      const isSelected = panel.id === selectedTab.getAttribute('aria-controls');
      panel.hidden = !isSelected;
    });
  }

  render() {
    this.shadowRoot.innerHTML = `
      <style>
        .tabs {
          display: flex;
          border-bottom: 1px solid #ccc;
        }

        [role="tab"] {
          padding: 10px 15px;
          margin-right: 5px;
          background-color: #f1f1f1;
          border: 1px solid #ccc;
          border-bottom: none;
          border-radius: 4px 4px 0 0;
          cursor: pointer;
          position: relative;
          top: 1px;
        }

        [role="tab"][aria-selected="true"] {
          background-color: white;
          border-bottom: 1px solid white;
        }

        [role="tab"]:focus-visible {
          outline: 3px solid blue;
          outline-offset: 2px;
        }

        [role="tabpanel"] {
          padding: 20px;
          border: 1px solid #ccc;
          border-top: none;
        }
      </style>

      <div class="tabs-container">
        <div role="tablist" class="tabs" aria-label="Programming information">
          <button role="tab" id="tab-1" aria-selected="true" aria-controls="panel-1" tabindex="0">HTML</button>
          <button role="tab" id="tab-2" aria-selected="false" aria-controls="panel-2" tabindex="-1">CSS</button>
          <button role="tab" id="tab-3" aria-selected="false" aria-controls="panel-3" tabindex="-1">JavaScript</button>
        </div>

        <div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
          <h3>HTML</h3>
          <p>HTML (HyperText Markup Language) is the standard markup language for documents designed to be displayed in a web browser.</p>
        </div>

        <div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
          <h3>CSS</h3>
          <p>CSS (Cascading Style Sheets) is a style sheet language used for describing the presentation of a document written in HTML.</p>
        </div>

        <div role="tabpanel" id="panel-3" aria-labelledby="tab-3" hidden>
          <h3>JavaScript</h3>
          <p>JavaScript is a programming language that enables interactive web pages and is an essential part of web applications.</p>
        </div>
      </div>
    `;
  }
}

customElements.define('accessible-tabs', AccessibleTabs);

Key accessibility features:

• Proper ARIA roles for tablist, tab, and tabpanel
• Keyboard navigation with arrow keys, Home, and End
• Single tab stop in the tab order with arrow key navigation between tabs
• Proper state management with aria-selected and tabindex
• Clear relationship between tabs and panels using aria-controls and aria-labelledby

Try using the arrow keys to navigate between tabs. Notice how this follows the expected keyboard interaction pattern for tabs.

4. Announcements for Dynamic Content

Beyond static structure and interaction, many modern interfaces feature dynamic content that changes without page reloads. This presents another accessibility challenge: how do we keep non-visual users informed of these changes?

class LiveRegion extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.render();
  }

  connectedCallback() {
    const button = this.shadowRoot.querySelector('button');
    const liveRegion = this.shadowRoot.querySelector('[aria-live]');
    let count = 0;

    button.addEventListener('click', () => {
      count++;
      liveRegion.textContent = `Button clicked ${count} time${count === 1 ? '' : 's'}`;
    });
  }

  render() {
    this.shadowRoot.innerHTML = `
      <style>
        button {
          padding: 8px 16px;
          background-color: #4CAF50;
          color: white;
          border: none;
          border-radius: 4px;
          cursor: pointer;
        }

        button:focus-visible {
          outline: 3px solid blue;
          outline-offset: 2px;
        }

        .live-region {
          margin-top: 10px;
          padding: 10px;
          background-color: #f8f8f8;
          border-radius: 4px;
        }
      </style>

      <div>
        <button>Increment Counter</button>
        <div class="live-region" aria-live="polite">Counter starts at 0</div>
      </div>
    `;
  }
}

customElements.define('live-region', LiveRegion);

Key accessibility feature:

• Uses aria-live="polite" to announce changes to screen readers without interrupting current announcements

Testing for Accessibility

Implementing these accessibility features is only half the journey. To ensure your components work reliably for all users, you need a systematic approach to testing. Let's explore the tools and techniques that will help you verify your implementation meets accessibility standards.

1. Automated Testing

Utilize tools like axe-core or Lighthouse:

// Example of using axe-core for accessibility testing
import axe from 'axe-core';

// Test a specific web component
axe.run(document.querySelector('accessible-tabs'), (err, results) => {
  if (err) {
    console.error('Accessibility testing failed:', err);
  } else {
    console.log('Accessibility test results:', results);
  }
});

What is Lighthouse?

Lighthouse is an open-source automated tool developed by Google that audits web pages for performance, accessibility, progressive web apps, SEO, and more.

Getting Started with Lighthouse

Method 1: Using Chrome DevTools

1. Open Chrome browser
2. Navigate to the webpage you want to test
3. Press F12 or right-click and select "Inspect" to open DevTools
4. Click on the "Lighthouse" tab
5. Select "Accessibility" checkbox (deselect others if you only want accessibility)
6. Click "Generate report"

Method 2: Chrome Extension

1. Install the Lighthouse extension from Chrome Web Store
2. Navigate to the page you want to test
3. Click the Lighthouse icon in your browser toolbar
4. Select "Accessibility" checkbox
5. Click "Generate report"

Method 3: Command Line

# Install Lighthouse globally
npm install -g lighthouse

# Run Lighthouse accessibility audit
lighthouse https://example.com --only-categories=accessibility --output=html --output-path=./report.html

2. Manual Testing

Automated tests can't catch everything. Manual testing should include:

Keyboard Testing:

• Can all interactive elements be accessed via Tab key?
• Do all controls work with keyboard alternatives (Enter, Space, arrow keys)?
• Is there a visible focus indicator at all times?

Screen Reader Testing:

• Try your components with VoiceOver (macOS), NVDA or JAWS (Windows), or TalkBack (Android)
• Is all relevant information announced?
• Are state changes communicated properly?

High Contrast Mode:

• Test with high contrast mode enabled in your OS
• Do all interactive elements remain visible and distinct?

Screen Reader Simulator

This interactive CodePen demonstrates how screen readers interpret web content, without requiring any software installation. Simply enter your HTML or use the built-in generator to compare non-semantic versus semantic markup. See firsthand how thoughtful HTML structure dramatically changes the experience for users who rely on assistive technology. Test your own code to identify potential accessibility improvements. Note: This simulator provides educational insights only and should not replace testing with actual screen reader technology when evaluating web accessibility.

Guide to Testing with NVDA Screen Reader

To test with NVDA (NonVisual Desktop Access), download and install it from nvaccess.org. After installation, you'll hear a startup sound and voice feedback will begin. Use the NVDA key (usually Insert) combined with other keys to navigate. Press NVDA+Space to toggle focus and browse modes when testing web applications.

Pay attention to how NVDA announces your interface elements. Ensure all interactive elements are properly labeled and keyboard-accessible. Test different scenarios: form completion, menu navigation, and custom component interaction. Listen for proper announcements of headings (NVDA+H to navigate), landmarks (NVDA+D), and alerts. Verify that dynamic content changes are announced and error messages are accessible.

Common Accessibility Pitfalls in Web Components

Even with thorough testing, certain accessibility issues frequently emerge in Web Component development. By understanding these common pitfalls, you can address them proactively in your implementation.

1. Shadow DOM Isolation Issues

Problem: ARIA relationships that cross shadow boundaries don't work as expected.

Solution: Keep related elements within the same shadow root or use alternative techniques like aria-live regions for updates.

2. Forgetting About Non-Mouse Users

Problem: Components only work with mouse events (click, hover).

Solution: Include keyboard event handlers and touch events for mobile accessibility.

// Bad example - only mouse support
button.addEventListener('click', handleAction);

// Good example - comprehensive interaction support
button.addEventListener('click', handleAction);
button.addEventListener('keydown', e => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    handleAction();
  }
});