For ten articles, the only thing that has ever run our game is main(), in Rust, in a terminal.
Today, a browser runs it.
\nNot 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.
\nBy the end, a web page shows this:
\nOne hour away.\nStage 1 -> 128 Level 1 -> 47 Gold 0 -> 16637\nStage 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.
\nThis series builds a small idle game: a player clicks to fight slimes, earns gold and XP, and keeps progressing while you are away.
\nIf you are only reading along, skip past this code to \"A second machine.\"
\nIf 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/\n├── Cargo.toml\n├── Cargo.lock\n├── src/\n│ ├── lib.rs\n│ ├── main.rs\n│ ├── rules.rs\n│ ├── enemy.rs\n│ ├── player.rs\n│ ├── game.rs\n│ └── save.rs\n└── tests/\n ├── idle_hour.rs\n └── save_and_restore.rs\nCargo.toml:
[package]\nname = \"rustbound-idle\"\nversion = \"0.1.0\"\nedition = \"2024\"\n\n[dependencies]\nserde = { version = \"1\", features = [\"derive\"] }\nserde_json = \"1\"\nsrc/lib.rs · 10 linesmod enemy;\nmod game;\nmod player;\nmod rules;\nmod save;\n\npub use enemy::Enemy;\npub use game::Game;\npub use player::{Player, PurchaseOutcome};\npub use save::LoadError;\nsrc/main.rs · 71 linesuse rustbound_idle::{Game, PurchaseOutcome};\n\nfn main() {\n let mut game = Game::new();\n\n while game.stage <= 3 {\n let stage = game.stage;\n let level = game.player.level;\n\n game.click();\n\n if game.stage > stage {\n println!(\n \"Stage {stage} cleared! Gold: {} XP: {}/{}\",\n game.player.gold,\n game.player.xp,\n game.player.xp_needed()\n );\n\n if game.player.level > level {\n println!(\n \"Level up! Now level {}. Click damage: {}\",\n game.player.level,\n game.player.click_damage()\n );\n }\n\n println!(\n \" Next up: {} with {} health.\",\n game.enemy.name, game.enemy.health\n );\n }\n\n match game.buy_click_upgrade() {\n PurchaseOutcome::Purchased => println!(\n \"Bought click upgrade {}! Click damage: {} Gold left: {}\",\n game.player.click_upgrade_level,\n game.player.click_damage(),\n game.player.gold\n ),\n PurchaseOutcome::NotEnoughGold => {}\n }\n }\n\n let save = game.save_json();\n println!(\"Saved: {save}\");\n\n drop(game);\n\n let mut game = match Game::from_saved_json(&save) {\n Ok(game) => game,\n Err(error) => {\n println!(\"Could not load the save: {error:?}\");\n return;\n }\n };\n\n println!(\"Loaded. Stage {}, level {}.\", game.stage, game.player.level);\n\n let stage = game.stage;\n let level = game.player.level;\n let gold = game.player.gold;\n\n game.tick(3600);\n\n println!(\"One hour away.\");\n println!(\n \"Stage {} -> {} Level {} -> {} Gold {} -> {}\",\n stage, game.stage, level, game.player.level, gold, game.player.gold\n );\n}\nsrc/rules.rs · 105 linespub(crate) fn click_damage(base: u32, bonus: u32) -> u32 {\n base.saturating_add(bonus)\n}\n\npub(crate) fn health_after_hit(health: u32, damage: u32) -> u32 {\n health.saturating_sub(damage)\n}\n\npub(crate) fn is_defeated(health: u32) -> bool {\n health == 0\n}\n\npub(crate) fn enemy_health_for_stage(stage: u32) -> u32 {\n stage.saturating_mul(10).saturating_add(10)\n}\n\npub(crate) fn gold_reward_for_stage(stage: u32) -> u32 {\n stage.saturating_mul(2).saturating_add(3)\n}\n\npub(crate) fn xp_reward_for_stage(stage: u32) -> u32 {\n stage.saturating_mul(2).saturating_add(4)\n}\n\npub(crate) fn xp_to_next_level(level: u32) -> u32 {\n level\n .saturating_sub(1)\n .saturating_mul(15)\n .saturating_add(20)\n}\n\npub(crate) fn base_damage_for_level(level: u32) -> u32 {\n level.saturating_add(4)\n}\n\npub(crate) fn idle_damage_for_level(level: u32) -> u32 {\n level\n}\n\npub(crate) fn click_upgrade_bonus(upgrades: u32) -> u32 {\n upgrades.saturating_mul(2)\n}\n\npub(crate) fn click_upgrade_cost(upgrades: u32) -> u32 {\n upgrades.saturating_add(1).saturating_mul(10)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn click_damage_adds_base_and_bonus() {\n assert_eq!(click_damage(3, 4), 7);\n }\n\n #[test]\n fn health_never_drops_below_zero() {\n assert_eq!(health_after_hit(3, 10), 0);\n }\n\n #[test]\n fn zero_health_is_defeated() {\n assert!(is_defeated(0));\n assert!(!is_defeated(1));\n }\n\n #[test]\n fn later_stages_have_tougher_enemies() {\n assert_eq!(enemy_health_for_stage(1), 20);\n assert_eq!(enemy_health_for_stage(2), 30);\n }\n\n #[test]\n fn later_stages_pay_better() {\n assert_eq!(gold_reward_for_stage(1), 5);\n assert_eq!(gold_reward_for_stage(2), 7);\n assert_eq!(xp_reward_for_stage(1), 6);\n assert_eq!(xp_reward_for_stage(2), 8);\n }\n\n #[test]\n fn levels_need_more_xp_as_they_go() {\n assert_eq!(xp_to_next_level(1), 20);\n assert_eq!(xp_to_next_level(2), 35);\n }\n\n #[test]\n fn levels_make_the_player_hit_harder() {\n assert_eq!(base_damage_for_level(1), 5);\n assert_eq!(base_damage_for_level(2), 6);\n }\n\n #[test]\n fn idle_damage_grows_with_level() {\n assert_eq!(idle_damage_for_level(1), 1);\n assert_eq!(idle_damage_for_level(2), 2);\n }\n\n #[test]\n fn upgrades_cost_more_each_time() {\n assert_eq!(click_upgrade_cost(0), 10);\n assert_eq!(click_upgrade_cost(1), 20);\n }\n}\nsrc/enemy.rs · 19 linesuse crate::rules::{enemy_health_for_stage, gold_reward_for_stage, xp_reward_for_stage};\n\npub struct Enemy {\n pub name: String,\n pub health: u32,\n pub(crate) gold_reward: u32,\n pub(crate) xp_reward: u32,\n}\n\nimpl Enemy {\n pub(crate) fn for_stage(stage: u32) -> Enemy {\n Enemy {\n name: String::from(\"Training Slime\"),\n health: enemy_health_for_stage(stage),\n gold_reward: gold_reward_for_stage(stage),\n xp_reward: xp_reward_for_stage(stage),\n }\n }\n}\nsrc/player.rs · 114 linesuse crate::rules::{\n base_damage_for_level, click_damage, click_upgrade_bonus, click_upgrade_cost, xp_to_next_level,\n};\n\npub struct Player {\n pub gold: u32,\n pub xp: u32,\n pub level: u32,\n pub click_upgrade_level: u32,\n}\n\n#[derive(Debug, PartialEq)]\npub enum PurchaseOutcome {\n Purchased,\n NotEnoughGold,\n}\n\nimpl Player {\n pub(crate) fn new() -> Player {\n Player {\n gold: 0,\n xp: 0,\n level: 1,\n click_upgrade_level: 0,\n }\n }\n\n pub(crate) fn add_gold(&mut self, amount: u32) {\n self.gold = self.gold.saturating_add(amount);\n }\n\n pub(crate) fn add_xp(&mut self, amount: u32) {\n self.xp = self.xp.saturating_add(amount);\n\n while self.xp >= self.xp_needed() {\n self.xp -= self.xp_needed();\n self.level = self.level.saturating_add(1);\n }\n }\n\n pub fn xp_needed(&self) -> u32 {\n xp_to_next_level(self.level)\n }\n\n pub fn click_damage(&self) -> u32 {\n click_damage(self.base_damage(), self.bonus_damage())\n }\n\n fn base_damage(&self) -> u32 {\n base_damage_for_level(self.level)\n }\n\n fn bonus_damage(&self) -> u32 {\n click_upgrade_bonus(self.click_upgrade_level)\n }\n\n pub(crate) fn buy_click_upgrade(&mut self) -> PurchaseOutcome {\n let cost = click_upgrade_cost(self.click_upgrade_level);\n\n if self.gold < cost {\n return PurchaseOutcome::NotEnoughGold;\n }\n\n self.gold -= cost;\n self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);\n\n PurchaseOutcome::Purchased\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn leveling_up_keeps_leftover_xp() {\n let mut player = Player::new();\n\n player.add_xp(25);\n\n assert_eq!(player.level, 2);\n assert_eq!(player.xp, 5);\n }\n\n #[test]\n fn a_big_reward_can_skip_levels() {\n let mut player = Player::new();\n\n player.add_xp(60);\n\n assert_eq!(player.level, 3);\n assert_eq!(player.xp, 5);\n }\n\n #[test]\n fn buying_an_upgrade_needs_gold() {\n let mut player = Player::new();\n\n assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::NotEnoughGold);\n assert_eq!(player.click_upgrade_level, 0);\n assert_eq!(player.bonus_damage(), 0);\n }\n\n #[test]\n fn buying_an_upgrade_spends_gold() {\n let mut player = Player::new();\n player.gold = 12;\n\n assert_eq!(player.buy_click_upgrade(), PurchaseOutcome::Purchased);\n assert_eq!(player.gold, 2);\n assert_eq!(player.click_upgrade_level, 1);\n assert_eq!(player.bonus_damage(), 2);\n }\n}\nsrc/game.rs · 158 linesuse crate::enemy::Enemy;\nuse crate::player::{Player, PurchaseOutcome};\nuse crate::rules::{health_after_hit, idle_damage_for_level, is_defeated};\n\npub struct Game {\n pub stage: u32,\n pub player: Player,\n pub enemy: Enemy,\n}\n\nimpl Game {\n pub fn new() -> Game {\n Game {\n stage: 1,\n player: Player::new(),\n enemy: Enemy::for_stage(1),\n }\n }\n\n pub fn click(&mut self) {\n attack(&self.player, &mut self.enemy);\n self.resolve_hit();\n }\n\n pub fn tick(&mut self, seconds: u32) {\n for _ in 0..seconds {\n let damage = idle_damage_for_level(self.player.level);\n\n self.enemy.health = health_after_hit(self.enemy.health, damage);\n self.resolve_hit();\n }\n }\n\n fn resolve_hit(&mut self) {\n if is_defeated(self.enemy.health) {\n self.defeat_enemy();\n }\n }\n\n fn defeat_enemy(&mut self) {\n self.player.add_gold(self.enemy.gold_reward);\n self.player.add_xp(self.enemy.xp_reward);\n\n self.stage = self.stage.saturating_add(1);\n self.enemy = Enemy::for_stage(self.stage);\n }\n\n pub fn buy_click_upgrade(&mut self) -> PurchaseOutcome {\n self.player.buy_click_upgrade()\n }\n}\n\nimpl Default for Game {\n fn default() -> Game {\n Game::new()\n }\n}\n\nfn attack(player: &Player, enemy: &mut Enemy) {\n enemy.health = health_after_hit(enemy.health, player.click_damage());\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn attack_reduces_enemy_health() {\n let player = Player::new();\n\n let mut enemy = Enemy::for_stage(1);\n enemy.health = 10;\n\n attack(&player, &mut enemy);\n\n assert_eq!(enemy.health, 5);\n }\n\n #[test]\n fn a_new_game_starts_at_stage_one() {\n let game = Game::new();\n\n assert_eq!(game.stage, 1);\n assert_eq!(game.enemy.health, 20);\n assert_eq!(game.player.gold, 0);\n }\n\n #[test]\n fn clicking_damages_the_enemy() {\n let mut game = Game::new();\n\n game.click();\n\n assert_eq!(game.enemy.health, 15);\n }\n\n #[test]\n fn defeating_an_enemy_pays_the_player() {\n let mut game = Game::new();\n game.enemy.health = 1;\n\n game.click();\n\n assert_eq!(game.stage, 2);\n assert_eq!(game.enemy.health, 30);\n assert_eq!(game.player.gold, 5);\n assert_eq!(game.player.xp, 6);\n }\n\n #[test]\n fn one_second_is_one_idle_hit() {\n let mut game = Game::new();\n\n game.tick(1);\n\n assert_eq!(game.enemy.health, 19);\n }\n\n #[test]\n fn zero_seconds_changes_nothing() {\n let mut game = Game::new();\n\n game.tick(0);\n\n assert_eq!(game.stage, 1);\n assert_eq!(game.enemy.health, 20);\n }\n\n #[test]\n fn enough_time_defeats_the_enemy() {\n let mut game = Game::new();\n\n game.tick(20);\n\n assert_eq!(game.stage, 2);\n assert_eq!(game.enemy.health, 30);\n assert_eq!(game.player.gold, 5);\n assert_eq!(game.player.xp, 6);\n }\n\n #[test]\n fn one_long_tick_matches_many_short_ones() {\n let mut long = Game::new();\n let mut short = Game::new();\n\n long.tick(45);\n\n for _ in 0..45 {\n short.tick(1);\n }\n\n assert_eq!(long.stage, short.stage);\n assert_eq!(long.enemy.health, short.enemy.health);\n assert_eq!(long.player.gold, short.player.gold);\n assert_eq!(long.player.xp, short.player.xp);\n assert_eq!(long.player.level, short.player.level);\n }\n}\nsrc/save.rs · 130 linesuse crate::enemy::Enemy;\nuse crate::game::Game;\nuse serde::{Deserialize, Serialize};\n\nconst SAVE_VERSION: u32 = 1;\n\n#[derive(Debug, PartialEq)]\npub enum LoadError {\n Unreadable,\n UnsupportedVersion(u32),\n}\n\n#[derive(Serialize, Deserialize)]\nstruct PlayerSave {\n gold: u32,\n xp: u32,\n level: u32,\n click_upgrade_level: u32,\n}\n\n#[derive(Serialize, Deserialize)]\nstruct SaveData {\n save_version: u32,\n stage: u32,\n player: PlayerSave,\n enemy_health: u32,\n}\n\nimpl Game {\n pub fn save_json(&self) -> String {\n let save = SaveData {\n save_version: SAVE_VERSION,\n stage: self.stage,\n player: PlayerSave {\n gold: self.player.gold,\n xp: self.player.xp,\n level: self.player.level,\n click_upgrade_level: self.player.click_upgrade_level,\n },\n enemy_health: self.enemy.health,\n };\n\n serde_json::to_string(&save).expect(\"a save made of numbers should always serialize\")\n }\n\n pub fn from_saved_json(json: &str) -> Result<Game, LoadError> {\n let save: SaveData = match serde_json::from_str(json) {\n Ok(save) => save,\n Err(_) => return Err(LoadError::Unreadable),\n };\n\n if save.save_version != SAVE_VERSION {\n return Err(LoadError::UnsupportedVersion(save.save_version));\n }\n\n let mut game = Game::new();\n\n game.stage = save.stage;\n game.player.gold = save.player.gold;\n game.player.xp = save.player.xp;\n game.player.level = save.player.level;\n game.player.click_upgrade_level = save.player.click_upgrade_level;\n\n game.enemy = Enemy::for_stage(save.stage);\n game.enemy.health = save.enemy_health;\n\n Ok(game)\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn a_new_game_saves_its_starting_numbers() {\n let json = Game::new().save_json();\n\n assert_eq!(\n json,\n r#\"{\"save_version\":1,\"stage\":1,\"player\":{\"gold\":0,\"xp\":0,\"level\":1,\"click_upgrade_level\":0},\"enemy_health\":20}\"#\n );\n }\n\n #[test]\n fn a_loaded_game_rebuilds_the_enemy_from_the_rules() {\n let mut game = Game::new();\n game.tick(600);\n\n let restored = Game::from_saved_json(&game.save_json()).expect(\"the save should load\");\n\n assert_eq!(restored.stage, game.stage);\n assert_eq!(restored.enemy.health, game.enemy.health);\n assert_eq!(restored.enemy.gold_reward, game.enemy.gold_reward);\n assert_eq!(restored.enemy.xp_reward, game.enemy.xp_reward);\n }\n\n #[test]\n fn nonsense_is_not_a_save() {\n assert!(matches!(\n Game::from_saved_json(\"definitely not a save\"),\n Err(LoadError::Unreadable)\n ));\n }\n\n #[test]\n fn a_save_with_missing_pieces_is_not_a_save() {\n let json = r#\"{\"save_version\":1,\"stage\":4}\"#;\n\n assert!(matches!(\n Game::from_saved_json(json),\n Err(LoadError::Unreadable)\n ));\n }\n\n #[test]\n fn a_save_from_another_version_is_refused() {\n let json = r#\"{\n \"save_version\": 99,\n \"stage\": 1,\n \"player\": { \"gold\": 0, \"xp\": 0, \"level\": 1, \"click_upgrade_level\": 0 },\n \"enemy_health\": 20\n }\"#;\n\n assert!(matches!(\n Game::from_saved_json(json),\n Err(LoadError::UnsupportedVersion(99))\n ));\n }\n}\ntests/idle_hour.rs · 11 linesuse rustbound_idle::Game;\n\n#[test]\nfn an_hour_away_moves_the_game_forward() {\n let mut game = Game::new();\n\n game.tick(3600);\n\n assert_eq!(game.stage, 128);\n assert_eq!(game.player.level, 47);\n}\ntests/save_and_restore.rs · 18 linesuse rustbound_idle::Game;\n\n#[test]\nfn a_restored_game_plays_the_same_hour() {\n let mut original = Game::new();\n original.tick(600);\n\n let mut restored = Game::from_saved_json(&original.save_json()).expect(\"the save should load\");\n\n original.tick(3600);\n restored.tick(3600);\n\n assert_eq!(restored.stage, original.stage);\n assert_eq!(restored.enemy.health, original.enemy.health);\n assert_eq!(restored.player.gold, original.player.gold);\n assert_eq!(restored.player.xp, original.player.xp);\n assert_eq!(restored.player.level, original.player.level);\n}\nRun cargo test, and twenty-eight tests pass. Run cargo run, and the player clears three stages, saves, loads, and spends an hour away.
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.
\nWebAssembly is one of those targets.
\nIt 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.
\nThe target has a long name:
\nwasm32-unknown-unknown\nThe 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.
\nThere 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.
\nIt 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:
\nrustup target add wasm32-unknown-unknown\nThat 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.
Why does main.rs stay behind when we compile the library for the browser?
lib.rsmain.rs prints to a terminal, and this browser target has no terminalmain() functionAnswer: B. main.rs prints to a terminal, and this browser target has no terminal
The engine only calculates with numbers and text. The terminal-specific printing stays in main.rs on the machine that has a terminal.
WebAssembly has one more limitation that matters to us.
\nAt 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 file and writes the JavaScript glue for everything marked.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\ncargo 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:
[package]\nname = \"rustbound-idle\"\nversion = \"0.1.0\"\nedition = \"2024\"\n\n[lib]\ncrate-type = [\"cdylib\", \"rlib\"]\n\n[dependencies]\nserde = { version = \"1\", features = [\"derive\"] }\nserde_json = \"1\"\nwasm-bindgen = \"0.2\"\nThe dependency is the familiar part.
\nThe [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:
\ncargo build\nCargo 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.
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:
use crate::game::Game;\nuse wasm_bindgen::prelude::*;\n\n#[wasm_bindgen(js_name = Game)]\npub struct WebGame {\n inner: Game,\n}\n\n#[wasm_bindgen(js_class = Game)]\nimpl WebGame {\n #[wasm_bindgen(constructor)]\n pub fn new() -> WebGame {\n WebGame { inner: Game::new() }\n }\n\n pub fn click(&mut self) {\n self.inner.click();\n }\n\n pub fn tick(&mut self, seconds: u32) {\n self.inner.tick(seconds);\n }\n}\nAnd 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.
Why does WebGame hold a private Game instead of exporting every engine field?
Answer: B. The adapter keeps JavaScript's interface small and leaves the rules in Rust
\nJavaScript gets a few operations chosen by the adapter. It cannot reach into the engine and start calculating a second version of a rule.
\nBuild it:
\ncargo build\nIt 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.
buy_click_upgrade() is next. The engine's version returns a PurchaseOutcome. Try handing that straight across. Add this inside the impl WebGame block:
#[wasm_bindgen(js_name = buyClickUpgrade)]\n pub fn buy_click_upgrade(&mut self) -> PurchaseOutcome {\n self.inner.buy_click_upgrade()\n }\nAnd 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:
\nerror[E0277]: the trait bound `PurchaseOutcome: IntoWasmAbi` is not satisfied\n --> src/web.rs:10:1\n |\n10 | #[wasm_bindgen(js_class = Game)]\n | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ unsatisfied trait bound\n |\nhelp: the trait `IntoWasmAbi` is not implemented for `PurchaseOutcome`\n(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?
\nfalse 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:
#[wasm_bindgen(js_name = buyClickUpgrade)]\n pub fn buy_click_upgrade(&mut self) -> String {\n match self.inner.buy_click_upgrade() {\n PurchaseOutcome::Purchased => String::from(\"purchased\"),\n PurchaseOutcome::NotEnoughGold => String::from(\"notEnoughGold\"),\n }\n }\nReplace the version you just wrote with this one.
\nThe 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.
What crosses into JavaScript when an upgrade cannot be bought?
\nPurchaseOutcome enum definitionfalse\"notEnoughGold\"Answer: C. The string \"notEnoughGold\"
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.
\nIf JavaScript ever computes click damage, there are two programs that know how, and one day they will disagree.
\nThat is the rule this whole section protects.
\nThe 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.
\nSo the adapter answers all of it at once, as one piece of JSON, and Rust does every bit of arithmetic before the text leaves.
\nAdd this at the bottom of web.rs, after the impl WebGame block:
#[derive(Serialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct Snapshot {\n stage: u32,\n gold: u32,\n xp: u32,\n xp_needed: u32,\n level: u32,\n click_damage: u32,\n click_upgrade_level: u32,\n click_upgrade_cost: u32,\n enemy_name: String,\n enemy_health: u32,\n enemy_max_health: u32,\n}\n\nimpl Snapshot {\n fn of(game: &Game) -> Snapshot {\n Snapshot {\n stage: game.stage,\n gold: game.player.gold,\n xp: game.player.xp,\n xp_needed: game.player.xp_needed(),\n level: game.player.level,\n click_damage: game.player.click_damage(),\n click_upgrade_level: game.player.click_upgrade_level,\n click_upgrade_cost: game.player.click_upgrade_cost(),\n enemy_name: game.enemy.name.clone(),\n enemy_health: game.enemy.health,\n enemy_max_health: enemy_health_for_stage(game.stage),\n }\n }\n}\nAnd at the top of the file, two more use lines, under the one for PurchaseOutcome:
use crate::rules::enemy_health_for_stage;\nuse serde::Serialize;\nA 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:
\n#[serde(rename_all = \"camelCase\")]\nThis 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.
\nTwo small things remain before it builds.
\nclick_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():
pub fn click_upgrade_cost(&self) -> u32 {\n click_upgrade_cost(self.click_upgrade_level)\n }\nAnd since the player can answer that now, buy_click_upgrade() should ask instead of reaching for the rule. Change its first line from:
let cost = click_upgrade_cost(self.click_upgrade_level);\nto:
\n let cost = self.click_upgrade_cost();\nThen the method that hands the picture over. Back in web.rs, inside impl WebGame, under buy_click_upgrade():
#[wasm_bindgen(js_name = stateJson)]\n pub fn state_json(&self) -> String {\n let snapshot = Snapshot::of(&self.inner);\n\n serde_json::to_string(&snapshot).expect(\"a Snapshot can always be written as JSON\")\n }\nThat expect() is the same promise save_json() makes, for the same reason: a struct of numbers and one string cannot fail to become JSON.
Why does the snapshot contain clickDamage instead of making JavaScript calculate it?
Answer: B. Rust should remain the only place that knows the damage rule
\nThe screen receives the answer it needs. If JavaScript repeated the formula, the two versions could disagree after a later rule change.
\nBuild. Quiet.
\nSaving is already text, so it crosses as it is:
\n #[wasm_bindgen(js_name = saveJson)]\n pub fn save_json(&self) -> String {\n self.inner.save_json()\n }\nLoading is the interesting one, because loading can fail, and now the failure has to cross a border.
\nTry the obvious thing first:
\n #[wasm_bindgen(js_name = fromJson)]\n pub fn from_json(json: &str) -> Result<WebGame, LoadError> {\n match Game::from_saved_json(json) {\n Ok(inner) => Ok(WebGame { inner }),\n Err(error) => Err(error),\n }\n }\nAdd 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\n --> src/web.rs:13:1\n |\n 13 | #[wasm_bindgen(js_class = Game)]\n | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `ReturnWasmAbi` is not implemented for `Result<WebGame, LoadError>`\n |\nhelp: the trait `ReturnWasmAbi` is implemented for `Result<T, E>`\n |\n779 | / impl<T, E> ReturnWasmAbi for Result<T, E>\n780 | | where\n781 | | T: IntoWasmAbi,\n782 | | E: Into<JsValue>,\nSame story as the purchase, with one new piece of information at the bottom.
\nA 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.
#[wasm_bindgen(js_name = fromJson)]\n pub fn from_json(json: &str) -> Result<WebGame, String> {\n match Game::from_saved_json(json) {\n Ok(inner) => Ok(WebGame { inner }),\n Err(LoadError::Unreadable) => Err(String::from(\"That save could not be read.\")),\n Err(LoadError::UnsupportedVersion(version)) => Err(format!(\n \"That save is version {version}, and this game cannot read it.\"\n )),\n }\n }\nmain() 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:
use crate::game::Game;\nuse crate::player::PurchaseOutcome;\nuse crate::rules::enemy_health_for_stage;\nuse crate::save::LoadError;\nuse serde::Serialize;\nuse wasm_bindgen::prelude::*;\n\n#[wasm_bindgen(js_name = Game)]\npub struct WebGame {\n inner: Game,\n}\n\n#[wasm_bindgen(js_class = Game)]\nimpl WebGame {\n #[wasm_bindgen(constructor)]\n pub fn new() -> WebGame {\n WebGame { inner: Game::new() }\n }\n\n pub fn click(&mut self) {\n self.inner.click();\n }\n\n pub fn tick(&mut self, seconds: u32) {\n self.inner.tick(seconds);\n }\n\n #[wasm_bindgen(js_name = buyClickUpgrade)]\n pub fn buy_click_upgrade(&mut self) -> String {\n match self.inner.buy_click_upgrade() {\n PurchaseOutcome::Purchased => String::from(\"purchased\"),\n PurchaseOutcome::NotEnoughGold => String::from(\"notEnoughGold\"),\n }\n }\n\n #[wasm_bindgen(js_name = stateJson)]\n pub fn state_json(&self) -> String {\n let snapshot = Snapshot::of(&self.inner);\n\n serde_json::to_string(&snapshot).expect(\"a Snapshot can always be written as JSON\")\n }\n\n #[wasm_bindgen(js_name = saveJson)]\n pub fn save_json(&self) -> String {\n self.inner.save_json()\n }\n\n #[wasm_bindgen(js_name = fromJson)]\n pub fn from_json(json: &str) -> Result<WebGame, String> {\n match Game::from_saved_json(json) {\n Ok(inner) => Ok(WebGame { inner }),\n Err(LoadError::Unreadable) => Err(String::from(\"That save could not be read.\")),\n Err(LoadError::UnsupportedVersion(version)) => Err(format!(\n \"That save is version {version}, and this game cannot read it.\"\n )),\n }\n }\n}\nSeven things JavaScript can do. That is the whole border.
\nWe have not compiled for WebAssembly yet, and we can already test the adapter, because on this machine it is ordinary Rust.
\nAdd a tests module at the bottom of web.rs:
#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn a_new_game_reports_its_starting_state() {\n let game = WebGame::new();\n\n assert_eq!(\n game.state_json(),\n r#\"{\"stage\":1,\"gold\":0,\"xp\":0,\"xpNeeded\":20,\"level\":1,\"clickDamage\":5,\"clickUpgradeLevel\":0,\"clickUpgradeCost\":10,\"enemyName\":\"Training Slime\",\"enemyHealth\":20,\"enemyMaxHealth\":20}\"#\n );\n }\n\n #[test]\n fn a_purchase_answers_in_words() {\n let mut game = WebGame::new();\n\n assert_eq!(game.buy_click_upgrade(), \"notEnoughGold\");\n\n game.tick(100);\n\n assert_eq!(game.buy_click_upgrade(), \"purchased\");\n }\n\n #[test]\n fn a_save_crosses_the_border_and_back() {\n let mut game = WebGame::new();\n game.tick(600);\n\n let save = game.save_json();\n let restored = WebGame::from_json(&save).expect(\"the save should load\");\n\n assert_eq!(restored.state_json(), game.state_json());\n }\n\n #[test]\n fn nonsense_is_refused_at_the_border() {\n assert_eq!(\n WebGame::from_json(\"banana\").err(),\n Some(String::from(\"That save could not be read.\"))\n );\n }\n}\nThe 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.
\nThe 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:
\ncargo test\nThirty-two. Thirty in the library, and the two outside tests.
\nIf 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.
Now the other machine.
\nwasm-pack build --target web --out-dir web/pkg\n--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:
\n[INFO]: Optimizing wasm binaries with `wasm-opt`...\n[INFO]: Optional fields missing from Cargo.toml: 'description', 'repository', and 'license'. These are not necessary, but recommended\n[INFO]: :-) Done in 24.46s\n[INFO]: :-) Your wasm pkg is ready to publish at /home/you/rustbound-idle/web/pkg.\nYour time and path will differ, and the note about optional fields is safe to ignore. Look in the folder:
\nweb/pkg/\n├── .gitignore\n├── package.json\n├── rustbound_idle.d.ts\n├── rustbound_idle.js\n├── rustbound_idle_bg.wasm\n└── rustbound_idle_bg.wasm.d.ts\nrustbound_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:
export class Game {\n free(): void;\n [Symbol.dispose](): void;\n buyClickUpgrade(): string;\n click(): void;\n static fromJson(json: string): Game;\n constructor();\n saveJson(): string;\n stateJson(): string;\n tick(seconds: number): void;\n}\nEvery 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:
\nError: crate-type must be cdylib to compile to WebAssembly. Add the following to your Cargo.toml file:\n\n[lib]\ncrate-type = [\"cdylib\", \"rlib\"]\nthen 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.
Create web/index.html, next to the pkg folder:
<!doctype html>\n<html lang=\"en\">\n <head>\n <meta charset=\"UTF-8\" />\n <title>Rustbound Idle</title>\n </head>\n <body>\n <h1>Rustbound Idle</h1>\n <pre id=\"output\">Loading the engine...</pre>\n\n <script type=\"module\">\n import init, { Game } from \"./pkg/rustbound_idle.js\";\n\n await init();\n\n const game = new Game();\n const before = JSON.parse(game.stateJson());\n\n game.tick(3600);\n\n const after = JSON.parse(game.stateJson());\n\n document.querySelector(\"#output\").textContent =\n `One hour away.\\nStage ${before.stage} -> ${after.stage} ` +\n `Level ${before.level} -> ${after.level} ` +\n `Gold ${before.gold} -> ${after.gold}`;\n </script>\n </body>\n</html>\nThe script is the whole point, so read it line by line.
\nimport 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>\n<pre id="output">Waiting for a snapshot...</pre>\nJavaScript
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}';\n\nconst before = JSON.parse(snapshotText);\nconst after = {\n ...before,\n stage: 128,\n level: 47,\n gold: 16637,\n};\n\ndocument.querySelector("#output").textContent =\n `One hour away.\\nStage ${before.stage} -> ${after.stage} ` +\n `Level ${before.level} -> ${after.level} ` +\n `Gold ${before.gold} -> ${after.gold}`;\nOpen the live preview on the original 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\n(On Windows the command is usually python rather than python3.)
Open http://localhost:8080/ in a browser.
Rustbound Idle\n\nOne hour away.\nStage 1 -> 128 Level 1 -> 47 Gold 0 -> 16637\nStage 128. Level 47.
\nThose 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'\nhas been blocked by CORS policy: Cross origin requests are only supported for\nprotocol schemes: chrome, chrome-untrusted, data, http, https.\nThat 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.
If you are only reading along, skip to the last two sections.
\nIf 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:
\nrustbound-idle/\n├── Cargo.toml\n├── Cargo.lock\n├── src/\n│ ├── lib.rs\n│ ├── main.rs\n│ ├── rules.rs\n│ ├── enemy.rs\n│ ├── player.rs\n│ ├── game.rs\n│ ├── save.rs\n│ └── web.rs\n├── tests/\n│ ├── idle_hour.rs\n│ └── save_and_restore.rs\n└── web/\n ├── index.html\n └── pkg/ (generated by wasm-pack)\nCargo.toml:
[package]\nname = \"rustbound-idle\"\nversion = \"0.1.0\"\nedition = \"2024\"\n\n[lib]\ncrate-type = [\"cdylib\", \"rlib\"]\n\n[dependencies]\nserde = { version = \"1\", features = [\"derive\"] }\nserde_json = \"1\"\nwasm-bindgen = \"0.2\"\nsrc/lib.rs:
mod enemy;\nmod game;\nmod player;\nmod rules;\nmod save;\nmod web;\n\npub use enemy::Enemy;\npub use game::Game;\npub use player::{Player, PurchaseOutcome};\npub use save::LoadError;\nOnly the impl block in src/player.rs changes; the struct, the enum, and the tests are as they were.
src/player.rs · changed 56-line implimpl Player {\n pub(crate) fn new() -> Player {\n Player {\n gold: 0,\n xp: 0,\n level: 1,\n click_upgrade_level: 0,\n }\n }\n\n pub(crate) fn add_gold(&mut self, amount: u32) {\n self.gold = self.gold.saturating_add(amount);\n }\n\n pub(crate) fn add_xp(&mut self, amount: u32) {\n self.xp = self.xp.saturating_add(amount);\n\n while self.xp >= self.xp_needed() {\n self.xp -= self.xp_needed();\n self.level = self.level.saturating_add(1);\n }\n }\n\n pub fn xp_needed(&self) -> u32 {\n xp_to_next_level(self.level)\n }\n\n pub fn click_damage(&self) -> u32 {\n click_damage(self.base_damage(), self.bonus_damage())\n }\n\n pub fn click_upgrade_cost(&self) -> u32 {\n click_upgrade_cost(self.click_upgrade_level)\n }\n\n fn base_damage(&self) -> u32 {\n base_damage_for_level(self.level)\n }\n\n fn bonus_damage(&self) -> u32 {\n click_upgrade_bonus(self.click_upgrade_level)\n }\n\n pub(crate) fn buy_click_upgrade(&mut self) -> PurchaseOutcome {\n let cost = self.click_upgrade_cost();\n\n if self.gold < cost {\n return PurchaseOutcome::NotEnoughGold;\n }\n\n self.gold -= cost;\n self.click_upgrade_level = self.click_upgrade_level.saturating_add(1);\n\n PurchaseOutcome::Purchased\n }\n}\nsrc/web.rs · 137 linesuse crate::game::Game;\nuse crate::player::PurchaseOutcome;\nuse crate::rules::enemy_health_for_stage;\nuse crate::save::LoadError;\nuse serde::Serialize;\nuse wasm_bindgen::prelude::*;\n\n#[wasm_bindgen(js_name = Game)]\npub struct WebGame {\n inner: Game,\n}\n\n#[wasm_bindgen(js_class = Game)]\nimpl WebGame {\n #[wasm_bindgen(constructor)]\n pub fn new() -> WebGame {\n WebGame { inner: Game::new() }\n }\n\n pub fn click(&mut self) {\n self.inner.click();\n }\n\n pub fn tick(&mut self, seconds: u32) {\n self.inner.tick(seconds);\n }\n\n #[wasm_bindgen(js_name = buyClickUpgrade)]\n pub fn buy_click_upgrade(&mut self) -> String {\n match self.inner.buy_click_upgrade() {\n PurchaseOutcome::Purchased => String::from(\"purchased\"),\n PurchaseOutcome::NotEnoughGold => String::from(\"notEnoughGold\"),\n }\n }\n\n #[wasm_bindgen(js_name = stateJson)]\n pub fn state_json(&self) -> String {\n let snapshot = Snapshot::of(&self.inner);\n\n serde_json::to_string(&snapshot).expect(\"a Snapshot can always be written as JSON\")\n }\n\n #[wasm_bindgen(js_name = saveJson)]\n pub fn save_json(&self) -> String {\n self.inner.save_json()\n }\n\n #[wasm_bindgen(js_name = fromJson)]\n pub fn from_json(json: &str) -> Result<WebGame, String> {\n match Game::from_saved_json(json) {\n Ok(inner) => Ok(WebGame { inner }),\n Err(LoadError::Unreadable) => Err(String::from(\"That save could not be read.\")),\n Err(LoadError::UnsupportedVersion(version)) => Err(format!(\n \"That save is version {version}, and this game cannot read it.\"\n )),\n }\n }\n}\n\n#[derive(Serialize)]\n#[serde(rename_all = \"camelCase\")]\nstruct Snapshot {\n stage: u32,\n gold: u32,\n xp: u32,\n xp_needed: u32,\n level: u32,\n click_damage: u32,\n click_upgrade_level: u32,\n click_upgrade_cost: u32,\n enemy_name: String,\n enemy_health: u32,\n enemy_max_health: u32,\n}\n\nimpl Snapshot {\n fn of(game: &Game) -> Snapshot {\n Snapshot {\n stage: game.stage,\n gold: game.player.gold,\n xp: game.player.xp,\n xp_needed: game.player.xp_needed(),\n level: game.player.level,\n click_damage: game.player.click_damage(),\n click_upgrade_level: game.player.click_upgrade_level,\n click_upgrade_cost: game.player.click_upgrade_cost(),\n enemy_name: game.enemy.name.clone(),\n enemy_health: game.enemy.health,\n enemy_max_health: enemy_health_for_stage(game.stage),\n }\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn a_new_game_reports_its_starting_state() {\n let game = WebGame::new();\n\n assert_eq!(\n game.state_json(),\n r#\"{\"stage\":1,\"gold\":0,\"xp\":0,\"xpNeeded\":20,\"level\":1,\"clickDamage\":5,\"clickUpgradeLevel\":0,\"clickUpgradeCost\":10,\"enemyName\":\"Training Slime\",\"enemyHealth\":20,\"enemyMaxHealth\":20}\"#\n );\n }\n\n #[test]\n fn a_purchase_answers_in_words() {\n let mut game = WebGame::new();\n\n assert_eq!(game.buy_click_upgrade(), \"notEnoughGold\");\n\n game.tick(100);\n\n assert_eq!(game.buy_click_upgrade(), \"purchased\");\n }\n\n #[test]\n fn a_save_crosses_the_border_and_back() {\n let mut game = WebGame::new();\n game.tick(600);\n\n let save = game.save_json();\n let restored = WebGame::from_json(&save).expect(\"the save should load\");\n\n assert_eq!(restored.state_json(), game.state_json());\n }\n\n #[test]\n fn nonsense_is_refused_at_the_border() {\n assert_eq!(\n WebGame::from_json(\"banana\").err(),\n Some(String::from(\"That save could not be read.\"))\n );\n }\n}\nweb/index.html · 29 lines<!doctype html>\n<html lang=\"en\">\n <head>\n <meta charset=\"UTF-8\" />\n <title>Rustbound Idle</title>\n </head>\n <body>\n <h1>Rustbound Idle</h1>\n <pre id=\"output\">Loading the engine...</pre>\n\n <script type=\"module\">\n import init, { Game } from \"./pkg/rustbound_idle.js\";\n\n await init();\n\n const game = new Game();\n const before = JSON.parse(game.stateJson());\n\n game.tick(3600);\n\n const after = JSON.parse(game.stateJson());\n\n document.querySelector(\"#output\").textContent =\n `One hour away.\\nStage ${before.stage} -> ${after.stage} ` +\n `Level ${before.level} -> ${after.level} ` +\n `Gold ${before.gold} -> ${after.gold}`;\n </script>\n </body>\n</html>\nYou 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:
\ncargo test\nwasm-pack build --target web --out-dir web/pkg\npython3 -m http.server 8080 --directory web\nThirty-two tests pass, the package builds, and the page at http://localhost:8080/ shows the hour away. Clippy should be quiet.
Along the way, we encountered:
\nwasm32-unknown-unknownwasm-bindgen and wasm-packcargo install[lib] crate-type, and the difference between rlib and cdylib#[wasm_bindgen], js_name, js_class, and constructoruse ...::*#[serde(rename_all = \"camelCase\")].clone() for a Stringformat!()Result crossing into JavaScript as a return or a throw.err() on a Resultimport, await init(), and why file:// will not doYou do not need to memorize all of that yet.
\nTwo ideas are worth keeping.
\nThe 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.
\nOur engine runs in a browser now. Nobody can play it.
\nThere 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.
\nIt still will not get the rules.
\nSmall function. Bigger game.
\nJoin the discussion on the original article.
\n", "content_text": "JavaScript Does Not Get the Rules.\nCanonical: https://mnixblog.netlify.app/rust-game-webassembly-wasm-bindgen/\nCompile Your Rust Game to WebAssembly\nFor ten articles, the only thing that has ever run our game is main(), in Rust, in a terminal.\nToday, a browser runs it.\nNot 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.\nBy the end, a web page shows this:\nOne hour away.\nStage 1 -> 128 Level 1 -> 47 Gold 0 -> 16637\nStage 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.\nAlong the way we meet WebAssembly, two tools that do the glue work, and one new rule about what is allowed to cross a border.\nOur starting point\nThis series builds a small idle game: a player clicks to fight slimes, earns gold and XP, and keeps progressing while you are away.\nIf you are only reading along, skip past this code to \"A second machine.\"\nIf 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.)\nrustbound-idle/\n├── Cargo.toml\n├── Cargo.lock\n├── src/\n│ ├── lib.rs\n│ ├── main.rs\n│ ├── rules.rs\n│ ├── enemy.rs\n│ ├── player.rs\n│ ├── game.rs\n│ └── save.rs\n└── tests/\n├── idle_hour.rs\n└── save_and_restore.rs\nCargo.toml:\nCargo.toml\n[package]\nname = \"rustbound-idle\"\nversion = \"0.1.0\"\nedition = \"2024\"\n[dependencies]\nserde = { version = \"1\", features = [\"derive\"] }\nserde_json = \"1\"\nsrc/lib.rs · 10 linessrc/main.rs · 71 linessrc/rules.rs · 105 linessrc/enemy.rs · 19 linessrc/player.rs · 114 linessrc/game.rs · 158 linessrc/save.rs · 130 linestests/idle_hour.rs · 11 linestests/save_and_restore.rs · 18 linesLoading the engine...\n\n\n\nThe script is the whole point, so read it line by line.\nimport 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.\nawait 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 \n