//! A mod run with no game: `cargo horizon-mod test` (docs/mods.md, "Testing a mod"). //! //! [`TestGame`] loads one `.hmod` from a scratch copy (its `storage` lives and //! dies with the run) into the same sandbox the game uses, and plays the game's //! part: the snapshot, ticks, frames, chat lines and commands, and for a //! server mod the players joining, leaving, chatting and breaking or placing //! blocks. [`Script`] is a //! test written in TOML, `tests/.toml` in the mod's folder: steps, each //! saying what happens and what the mod must have shown by then. use crate::{ BlockPos, Clock, Corner, GameMode, Mods, Output, Panel, Player, ServerPlayer, Snapshot, Status, }; use serde::Deserialize; use std::{ path::{Path, PathBuf}, sync::atomic::{AtomicUsize, Ordering}, }; /// One mod in the sandbox, driven by a test. pub struct TestGame { mods: Mods, dir: PathBuf, hmod: PathBuf, /// What the mod reads with `game-read`; ticks move the clock as the game does. pub player: Option, pub clock: Option, /// The players on the server, for a server mod, in join order. pub players: Vec, /// Every name that joined, for their id. names: Vec, tick: u64, /// Capability `world`'s Overworld: the blocks a script set or the mod /// changed; every other block, and the other dimensions, are air. Every /// biome is the dimension's plainest: plains, nether wastes, the end. pub world: std::collections::BTreeMap<(i32, i32, i32), String>, } /// The world a script's mod reads: [`TestGame::world`], copied for a step. struct ScriptWorld(std::collections::BTreeMap<(i32, i32, i32), String>); impl crate::WorldView for ScriptWorld { fn block(&self, dimension: &str, x: i32, y: i32, z: i32) -> Option { let here = (dimension == "minecraft:overworld") .then(|| self.0.get(&(x, y, z)).cloned()) .flatten(); Some(here.unwrap_or_else(|| "minecraft:air".into())) } fn biome(&self, dimension: &str, _x: i32, _y: i32, _z: i32) -> Option { let biome = match dimension { "minecraft:overworld" => "minecraft:plains", "minecraft:the_nether" => "minecraft:nether_wastes", "minecraft:the_end" => "minecraft:the_end", _ => return None, }; Some(biome.into()) } fn has_dimension(&self, dimension: &str) -> bool { matches!( dimension, "minecraft:overworld" | "minecraft:the_nether" | "minecraft:the_end" ) } fn check_state(&self, state: &str) -> Result<(), String> { // No registry here: the shape only (the game checks the names). let name = state.split('[').next().unwrap_or_default(); let plain = |t: &str| { !t.is_empty() && t.bytes() .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"_.-/".contains(&b)) }; let ok = match name.split_once(':') { Some((ns, path)) => plain(ns) && plain(path), None => plain(name), }; let closed = !state.contains('[') || state.ends_with(']'); (ok && closed) .then_some(()) .ok_or_else(|| format!("{state} is not a block state")) } } /// Where a script starts: standing at 0.5 64 0.5 in the Overworld, facing /// south, full health and food, at the first tick of a new world's first morning. pub fn default_player() -> Player { Player { x: 0.5, y: 64.0, z: 0.5, yaw: 0.0, pitch: 0.0, health: 20.0, food: 20, dimension: "minecraft:overworld".into(), } } impl TestGame { /// Starts the mod at `hmod`, as the game would with it turned on. Errs /// when it doesn't start, with the game's reason. pub fn load(hmod: &Path) -> Result { static RUN: AtomicUsize = AtomicUsize::new(0); let dir = std::env::temp_dir().join(format!( "horizon-mod-test-{}-{}", std::process::id(), RUN.fetch_add(1, Ordering::Relaxed) )); let _ = std::fs::remove_dir_all(&dir); std::fs::create_dir_all(&dir).map_err(|e| format!("{}: {e}", dir.display()))?; let copy = dir.join(hmod.file_name().unwrap_or("mod.hmod".as_ref())); let mut game = TestGame { mods: Mods::default(), hmod: copy.clone(), dir, player: Some(default_player()), clock: Some(Clock { game_time: 0, day_time: 0, }), players: Vec::new(), names: Vec::new(), tick: 0, world: Default::default(), }; copy_mod(hmod, ©)?; game.start()?; Ok(game) } fn start(&mut self) -> Result<(), String> { self.mods = Mods::load(std::slice::from_ref(&self.hmod), |_| true, |_| false); match &self.mods.entries()[0].status { Status::Failed(reason) => Err(format!("the mod didn't start: {reason}")), _ if !self.mods.is_running() => Err("the mod has no code to run".into()), _ => Ok(()), } } /// Stops the mod and starts it again, as a rebuild does in the game: its /// memory starts over, its `storage` stays. pub fn reload(&mut self) -> Result<(), String> { self.mods = Mods::default(); self.start() } fn snapshot(&mut self) { self.mods.set_snapshot(Snapshot { player: self.player.clone(), clock: self.clock, players: self.players.clone(), // The GUI of a 1280 x 720 window at scale 3, as the trial run's. gui_size: (427.0, 240.0), ..Snapshot::default() }); } /// Whether the mod is a server mod. pub fn server(&self) -> bool { self.mods.runs_server() } /// `n` game ticks; each moves the clock one tick on, as the game does. pub fn tick(&mut self, n: u64) { for _ in 0..n { self.tick += 1; if let Some(clock) = &mut self.clock { clock.game_time += 1; clock.day_time += 1; } self.snapshot(); self.mods.tick(self.tick); self.mods.server_tick(self.tick); } } /// `n` frames, 1/60 s apart. pub fn frames(&mut self, n: u64) { self.snapshot(); for _ in 0..n { self.mods.frame(1.0 / 60.0); } } /// A chat line the player receives. pub fn chat(&mut self, line: &str) { self.snapshot(); self.mods.chat(line); } /// `/line` typed by the player (without the slash); false when the mod /// owns no such command. pub fn command(&mut self, line: &str) -> bool { self.snapshot(); self.mods.command(line) } /// A player named `name` joins the server, standing where a script starts /// in survival. Their id is `00000000-0000-4000-8000-000000000001` for /// the first name that joined, `...0002` for the second, and so on. pub fn join(&mut self, name: &str) -> ServerPlayer { let n = match self.names.iter().position(|n| n == name) { Some(i) => i + 1, None => { self.names.push(name.to_owned()); self.names.len() } }; let p = default_player(); let player = ServerPlayer { id: format!("00000000-0000-4000-8000-{n:012x}"), name: name.to_owned(), x: p.x, y: p.y, z: p.z, dimension: p.dimension, game_mode: GameMode::Survival, health: p.health, }; self.players.push(player.clone()); self.snapshot(); self.mods.player_joined(&player); player } /// The player named `name` leaves; false when no such player is on. pub fn leave(&mut self, name: &str) -> bool { let Some(i) = self.players.iter().position(|p| p.name == name) else { return false; }; let player = self.players.remove(i); self.snapshot(); self.mods.player_left(&player); true } /// A chat message `player` sends, for a server mod. pub fn player_chat(&mut self, player: &ServerPlayer, line: &str) { self.snapshot(); self.mods.player_chat(player, line); } /// `/line` typed by `player`, for a server mod; false when the mod owns /// no such command. pub fn player_command(&mut self, player: &ServerPlayer, line: &str) -> bool { self.snapshot(); self.mods.server_command(player, line) } /// `player` breaks (or places) `state` at `pos`. pub fn block(&mut self, player: &ServerPlayer, pos: BlockPos, state: &str, placed: bool) { self.snapshot(); if placed { self.mods.block_placed(player, pos, state); } else { self.mods.block_broken(player, pos, state); } } /// The scratch copy the mod runs from; its `storage` is beside it. pub fn hmod(&self) -> &Path { &self.hmod } /// The commands the mod registered. pub fn commands(&self) -> Vec { let server = self.mods.server_commands(); self.mods .commands() .chain(server) .map(str::to_owned) .collect() } pub fn panel(&self) -> Option<&Panel> { self.mods.panels().next() } pub fn status(&self) -> &Status { &self.mods.entries()[0].status } /// What the mod showed since the last call. pub fn drain(&mut self) -> Vec { self.mods.drain() } } impl Drop for TestGame { fn drop(&mut self) { let _ = std::fs::remove_dir_all(&self.dir); } } /// A `.hmod` file, or a mod folder (`horizon-mod.toml` + `mod.wasm`). fn copy_mod(from: &Path, to: &Path) -> Result<(), String> { let err = |e: std::io::Error| format!("{}: {e}", from.display()); if !from.is_dir() { return std::fs::copy(from, to).map(drop).map_err(err); } std::fs::create_dir_all(to).map_err(err)?; for entry in std::fs::read_dir(from).map_err(err)? { let entry = entry.map_err(err)?; if entry.file_type().map_err(err)?.is_file() { std::fs::copy(entry.path(), to.join(entry.file_name())).map_err(err)?; } } Ok(()) } /// A test in TOML: where a client mod's player starts, then steps run in order. #[derive(Debug, Default, Deserialize)] #[serde(deny_unknown_fields, rename_all = "kebab-case")] pub struct Script { #[serde(default)] pub player: PlayerSet, #[serde(default)] pub clock: ClockSet, #[serde(default, rename = "step")] pub steps: Vec, } /// Fields of the player to change; the others keep their values. A server /// mod's players have no `yaw`, `pitch` or `food`, and a client mod's player /// no `game-mode`. #[derive(Debug, Default, Deserialize)] #[serde(deny_unknown_fields, rename_all = "kebab-case")] pub struct PlayerSet { x: Option, y: Option, z: Option, yaw: Option, pitch: Option, health: Option, food: Option, dimension: Option, game_mode: Option, } /// `players.game-mode` as a script spells it. #[derive(Clone, Copy, Debug, Deserialize)] #[serde(rename_all = "lowercase")] enum Mode { Survival, Creative, Adventure, Spectator, } impl From for GameMode { fn from(m: Mode) -> GameMode { match m { Mode::Survival => GameMode::Survival, Mode::Creative => GameMode::Creative, Mode::Adventure => GameMode::Adventure, Mode::Spectator => GameMode::Spectator, } } } /// A block a player breaks or places. #[derive(Debug, Deserialize)] #[serde(deny_unknown_fields)] pub struct BlockSet { x: i32, y: i32, z: i32, state: String, } #[derive(Debug, Default, Deserialize)] #[serde(deny_unknown_fields, rename_all = "kebab-case")] pub struct ClockSet { game_time: Option, day_time: Option, } /// One step. Its parts happen in this order: `reload`, `title-screen`, /// `blocks`, `join`, `player`, `clock`, `ticks`, `frames`, `chat`, `command`, /// `break`, `place`, `leave`; then the blocks the mod set are made, and /// `expect` is checked against what the mod showed and changed during the /// step. For a server mod, `player`, `chat`, `command`, `break` /// and `place` are the doing of the player named by `as`, or of the first /// player on. #[derive(Debug, Default, Deserialize)] #[serde(deny_unknown_fields, rename_all = "kebab-case")] pub struct Step { #[serde(default)] reload: bool, /// Leave the world: the mod reads no player and no clock until a step sets them. #[serde(default)] title_screen: bool, player: Option, clock: Option, #[serde(default)] ticks: u64, #[serde(default)] frames: u64, chat: Option, command: Option, /// Server mods: a player joins, leaves, breaks or places a block. join: Option, leave: Option, #[serde(rename = "as")] actor: Option, #[serde(rename = "break")] broken: Option, place: Option, /// Blocks of the Overworld before the rest of the step (capability /// `world`); every other block is air. #[serde(default)] blocks: Vec, #[serde(default)] expect: Expect, } /// What a step checks; a part left out is not checked. #[derive(Debug, Default, Deserialize)] #[serde(deny_unknown_fields, rename_all = "kebab-case")] pub struct Expect { /// The commands the mod owns. commands: Option>, /// Every chat line shown during the step, in order. chat: Option>, /// The command's feedback, and its red error. feedback: Option, error: Option, /// Server mods: every `players.tell` as `"Name: text"`, and every /// `players.broadcast`, in order. told: Option>, broadcast: Option>, /// The panel's lines (`[]`: no panel) and its corner. panel: Option>, corner: Option, /// Blocks of the Overworld after the step, the mod's changes made /// (capability `world`). blocks: Option>, /// The mod is turned off during this step, for a reason holding this text. /// Without it, a mod that stops fails the test. stopped: Option, } impl Script { pub fn parse(text: &str) -> Result { toml::from_str(text).map_err(|e| e.to_string()) } /// Runs every step on `game`; the error names the first step that failed. pub fn run(&self, game: &mut TestGame) -> Result<(), String> { if let Some(p) = &mut game.player { self.player.apply(p); } if let Some(c) = &mut game.clock { self.clock.apply(c); } for (i, step) in self.steps.iter().enumerate() { step.run(game) .map_err(|e| format!("step {} ({}): {e}", i + 1, step.describe()))?; } Ok(()) } } impl PlayerSet { fn apply(&self, p: &mut Player) { let set = |to: &mut f64, v: Option| *to = v.unwrap_or(*to); set(&mut p.x, self.x); set(&mut p.y, self.y); set(&mut p.z, self.z); p.yaw = self.yaw.unwrap_or(p.yaw); p.pitch = self.pitch.unwrap_or(p.pitch); p.health = self.health.unwrap_or(p.health); p.food = self.food.unwrap_or(p.food); if let Some(d) = &self.dimension { p.dimension.clone_from(d); } } fn apply_server(&self, p: &mut ServerPlayer) { let set = |to: &mut f64, v: Option| *to = v.unwrap_or(*to); set(&mut p.x, self.x); set(&mut p.y, self.y); set(&mut p.z, self.z); p.health = self.health.unwrap_or(p.health); p.game_mode = self.game_mode.map_or(p.game_mode, GameMode::from); if let Some(d) = &self.dimension { p.dimension.clone_from(d); } } } impl ClockSet { fn apply(&self, c: &mut Clock) { c.game_time = self.game_time.unwrap_or(c.game_time); c.day_time = self.day_time.unwrap_or(c.day_time); } } impl Step { fn describe(&self) -> String { let mut parts = Vec::new(); if self.reload { parts.push("reload".to_string()); } let count = |n: u64, what: &str| format!("{n} {what}{}", if n == 1 { "" } else { "s" }); if self.ticks > 0 { parts.push(count(self.ticks, "tick")); } if self.frames > 0 { parts.push(count(self.frames, "frame")); } if let Some(line) = &self.chat { parts.push(format!("chat {line:?}")); } if let Some(line) = &self.command { parts.push(format!("/{line}")); } if let Some(name) = &self.join { parts.insert(0, format!("{name} joins")); } for (what, b) in [("breaks", &self.broken), ("places", &self.place)] { if let Some(b) = b { parts.push(format!("{what} {} at {} {} {}", b.state, b.x, b.y, b.z)); } } if let Some(name) = &self.leave { parts.push(format!("{name} leaves")); } if parts.is_empty() { parts.push("checks".into()); } parts.join(", ") } fn run(&self, game: &mut TestGame) -> Result<(), String> { if self.reload { game.reload()?; } if self.title_screen { game.player = None; game.clock = None; } for b in &self.blocks { game.world.insert((b.x, b.y, b.z), b.state.clone()); } game.mods .lend_world(Box::new(ScriptWorld(game.world.clone()))); if let Some(name) = &self.join { game.join(name); } let server = game.server(); let actor = |game: &TestGame| match &self.actor { Some(name) => game .players .iter() .position(|p| p.name == *name) .ok_or_else(|| format!("{name} is not on the server")), None => (!game.players.is_empty()) .then_some(0) .ok_or_else(|| "no player is on the server: add join = \"Name\"".to_string()), }; let acts = self.player.is_some() || self.chat.is_some() || self.command.is_some() || self.broken.is_some() || self.place.is_some(); let actor = if server && acts { Some(actor(game)?) } else { None }; if let Some(set) = &self.player { match actor { Some(i) => set.apply_server(&mut game.players[i]), None => set.apply(game.player.get_or_insert_with(default_player)), } } if let Some(set) = &self.clock { set.apply(game.clock.get_or_insert(Clock { game_time: 0, day_time: 0, })); } game.tick(self.ticks); game.frames(self.frames); let who = actor.map(|i| game.players[i].clone()); if let Some(line) = &self.chat { match &who { Some(p) => game.player_chat(p, line), None => game.chat(line), } } let owned = self.command.as_ref().map(|line| match &who { Some(p) => game.player_command(p, line), None => game.command(line), }); for (b, placed) in [(&self.broken, false), (&self.place, true)] { if let (Some(b), Some(p)) = (b, &who) { let pos = BlockPos { x: b.x, y: b.y, z: b.z, }; game.block(p, pos, &b.state, placed); } } if let Some(name) = &self.leave && !game.leave(name) { return Err(format!("{name} is not on the server")); } game.mods.take_world(); let out = game.drain(); for o in &out { if let Output::SetBlocks { dimension, blocks, .. } = o && dimension == "minecraft:overworld" { for b in blocks { game.world.insert((b.x, b.y, b.z), b.state.clone()); } } } let stopped = out.iter().find_map(|o| match o { Output::Stopped { reason, .. } => Some(reason.as_str()), _ => None, }); let e = &self.expect; match (stopped, &e.stopped) { (Some(reason), Some(want)) if !reason.contains(want.as_str()) => { return Err(format!("the mod stopped ({reason}), expected {want:?}")); } (Some(_), Some(_)) => return Ok(()), (Some(reason), None) => return Err(format!("the mod stopped: {reason}")), (None, Some(want)) => { return Err(format!( "the mod kept running, expected it to stop ({want:?})" )); } (None, None) => {} } if owned == Some(false) { let line = self.command.as_deref().unwrap_or_default(); let name = line.split(' ').next().unwrap_or_default(); return Err(format!("the mod owns no command /{name}")); } if let Some(want) = &e.commands { same("commands", want, &game.commands())?; } if let Some(want) = &e.chat { let got: Vec = out .iter() .filter_map(|o| match o { Output::Chat { text, .. } => Some(text.clone()), _ => None, }) .collect(); same("chat", want, &got)?; } let feedback = |error: bool| { out.iter().rev().find_map(|o| match o { Output::Feedback { text, error: e } | Output::Reply { text, error: e, .. } if *e == error => { Some(text.clone()) } _ => None, }) }; if let Some(want) = &e.told { let name = |id: &str| { let p = game.players.iter().find(|p| p.id == id); p.map_or(id.to_owned(), |p| p.name.clone()) }; let got: Vec = out .iter() .filter_map(|o| match o { Output::Tell { player, text, .. } => Some(format!("{}: {text}", name(player))), _ => None, }) .collect(); same("told", want, &got)?; } if let Some(want) = &e.broadcast { let got: Vec = out .iter() .filter_map(|o| match o { Output::Broadcast { text, .. } => Some(text.clone()), _ => None, }) .collect(); same("broadcast", want, &got)?; } if let Some(want) = &e.feedback { same("feedback", &Some(want.clone()), &feedback(false))?; } if let Some(want) = &e.error { same("error", &Some(want.clone()), &feedback(true))?; } if let Some(want) = &e.panel { let got: Vec = game .panel() .map(|p| p.lines.iter().map(|l| l.text.clone()).collect()) .unwrap_or_default(); same("panel", want, &got)?; } if let Some(want) = &e.blocks { for b in want { let got = game.world.get(&(b.x, b.y, b.z)); let got = got.map_or("minecraft:air", String::as_str); if got != b.state { return Err(format!( "block at {} {} {}: expected {}, got {got}", b.x, b.y, b.z, b.state )); } } } if let Some(want) = &e.corner { let got = game.panel().map(|p| corner_name(p.corner).to_string()); same("corner", &Some(want.clone()), &got)?; } Ok(()) } } fn corner_name(c: Corner) -> &'static str { match c { Corner::TopLeft => "top-left", Corner::TopRight => "top-right", Corner::BottomLeft => "bottom-left", Corner::BottomRight => "bottom-right", } } fn same(what: &str, want: &T, got: &T) -> Result<(), String> { if want == got { return Ok(()); } Err(format!( "{what}\n expected: {want:?}\n got: {got:?}" )) }