Merge pull request #1816 from ludovic111/feat/mod-test-runner

🤖 Agent: cargo horizon-mod test runs a mod's test scripts with no game. Main is merged in, and the runner fills the new snapshot fields (input, render, frame stats) with the trial run's screen size. Verified: clippy, the cargo-horizon-mod, coords-hud and horizon-mods tests (57), launcher, and cargo horizon-mod test on coords-hud (2 scripts).
This commit is contained in:
Ludovic Marie
2026-10-26 08:07:39 +01:00
committed by GitHub
10 changed files with 704 additions and 9 deletions
+68 -1
View File
@@ -6,12 +6,15 @@
//! `assets/` and `data/`; a folder without `Cargo.toml` is content only.
//! - `run [--game <horizon-client>] [-- <game args>]`: build, then play with
//! the mod; run `build` again and the game reloads it.
//! - `test [--debug] [--hmod <file>] [<name>]`: build, then run the mod's
//! `tests/*.toml` scripts in the sandbox, with no game.
//! - `check <file> [--json]`: what the registry checks of a submission
//! (`.hmod`, `.hpack`, resource pack `.zip`), with a trial run for a mod.
//! - `registry build|review|check|list`: the registry repository's CI.
use horizon_mods::{
Capability, Content, Manifest, Package,
manifest::{MANIFEST, component_imports, componentize},
testing::{Script, TestGame},
};
mod check;
mod registry;
@@ -36,9 +39,10 @@ fn main() -> ExitCode {
println!("Built {}", p.display());
}),
Some("run") => run(&args[1..]),
Some("test") => test(&args[1..]),
Some("check") => check(&args[1..]),
Some("registry") => registry::main(&args[1..]),
_ => Err("usage: cargo horizon-mod new <path> [--template code|content] | build [--debug] | run [--game <horizon-client>] [-- <game args>] | check <file> [--kind <kind>] [--key <public key> --signature <file.minisig>] [--json] | registry build|review|check|list".into()),
_ => Err("usage: cargo horizon-mod new <path> [--template code|content] | build [--debug] | run [--game <horizon-client>] [-- <game args>] | test [--debug] [--hmod <file>] [<name>] | check <file> [--kind <kind>] [--key <public key> --signature <file.minisig>] [--json] | registry build|review|check|list".into()),
};
match result {
Ok(()) => ExitCode::SUCCESS,
@@ -97,6 +101,10 @@ fn new(args: &[String]) -> Result<(), String> {
(MANIFEST, include_str!("../template/horizon-mod.toml")),
("src/lib.rs", include_str!("../template/src/lib.rs")),
(".gitignore", include_str!("../template/gitignore")),
(
"tests/hello.toml",
include_str!("../template/tests/hello.toml"),
),
];
// A block copying a vanilla one, with its model, name, loot, recipe and tag.
let content = [
@@ -270,6 +278,63 @@ fn check(args: &[String]) -> Result<(), String> {
Ok(())
}
/// `test`: every `tests/*.toml` script (those whose name holds `<name>`)
/// against the built mod, or the `.hmod` given with `--hmod`.
fn test(args: &[String]) -> Result<(), String> {
let hmod = match flag(args, "--hmod") {
Some(p) => PathBuf::from(p),
None => build(!args.iter().any(|a| a == "--debug"))?,
};
let filter = args
.iter()
.enumerate()
.find(|(i, a)| !a.starts_with("--") && (*i == 0 || args[i - 1] != "--hmod"))
.map(|(_, a)| a.as_str());
let mut scripts: Vec<PathBuf> = std::fs::read_dir("tests")
.map_err(|e| {
format!(
"tests/: {e} (a mod's tests are tests/<name>.toml: docs/mods.md, \"Testing a mod\")"
)
})?
.filter_map(|e| Some(e.ok()?.path()))
.filter(|p| p.extension().is_some_and(|e| e == "toml"))
.filter(|p| filter.is_none_or(|f| p.to_string_lossy().contains(f)))
.collect();
scripts.sort();
if scripts.is_empty() {
return Err("no tests/*.toml to run".into());
}
println!(
"running {} scripts against {}",
scripts.len(),
hmod.display()
);
let mut failed = 0;
for path in &scripts {
let result = std::fs::read_to_string(path)
.map_err(|e| e.to_string())
.and_then(|text| Script::parse(&text))
.and_then(|script| {
let mut game = TestGame::load(&hmod)?;
script.run(&mut game)?;
Ok(script.steps.len())
});
match result {
Ok(steps) => println!("test {} ... ok ({steps} steps)", path.display()),
Err(e) => {
failed += 1;
println!("test {} ... FAILED\n {e}", path.display());
}
}
}
let passed = scripts.len() - failed;
if failed > 0 {
return Err(format!("{failed} failed, {passed} passed"));
}
println!("test result: ok. {passed} passed");
Ok(())
}
fn run(args: &[String]) -> Result<(), String> {
let path = build(true)?;
let game = flag(args, "--game")
@@ -312,6 +377,8 @@ mod tests {
);
let cargo = std::fs::read_to_string(path.join("Cargo.toml")).unwrap();
assert!(cargo.contains("name = \"my-mod\"") && cargo.contains(SDK_GIT));
let script = std::fs::read_to_string(path.join("tests/hello.toml")).unwrap();
assert_eq!(Script::parse(&script).unwrap().steps.len(), 3);
assert!(
new(&[path.display().to_string()]).is_err(),
"never overwrites"
@@ -0,0 +1,14 @@
# `cargo horizon-mod test` runs every tests/*.toml against the built mod, with no game:
# steps happen in order, and `expect` checks what the mod showed during the step.
# Every key: docs/mods.md, "Testing a mod".
[[step]]
expect.commands = ["hello"]
[[step]]
command = "hello world"
expect.chat = ["Hello world! (1 so far)"]
[[step]]
command = "hello again"
expect.chat = ["Hello again! (2 so far)"]
@@ -0,0 +1,36 @@
# The panel follows the player and the clock; /coords hides and shows it.
[player]
x = 12.5
z = -3.25
yaw = 180.0
[clock]
day-time = 29999
[[step]]
ticks = 1
expect.panel = ["XYZ 12.5 / 64.0 / -3.2", "Facing North (-Z)", "Day 2, 12:00"]
expect.corner = "top-left"
[[step]]
player = { x = -100.0, yaw = 90.0 }
ticks = 1
expect.panel = ["XYZ -100.0 / 64.0 / -3.2", "Facing West (-X)", "Day 2, 12:00"]
[[step]]
command = "coords"
expect.feedback = "Coordinates panel hidden"
# A step's ticks come before its command: the panel goes at the next tick.
[[step]]
ticks = 1
expect.panel = []
[[step]]
command = "coords"
expect.feedback = "Coordinates panel shown"
[[step]]
ticks = 1
expect.panel = ["XYZ -100.0 / 64.0 / -3.2", "Facing West (-X)", "Day 2, 12:00"]
@@ -0,0 +1,17 @@
# /where puts the position in chat; on the title screen it answers with an error.
[player]
x = 12.5
y = 70.2
z = -3.25
dimension = "minecraft:the_nether"
[[step]]
command = "where"
expect.chat = ["12, 70, -4 in minecraft:the_nether"]
[[step]]
title-screen = true
command = "where"
expect.chat = []
expect.error = "Not in a world"
+2
View File
@@ -12,6 +12,8 @@ pub mod manifest;
pub mod modpack;
#[cfg(feature = "runtime")]
mod runtime;
#[cfg(feature = "runtime")]
pub mod testing;
pub use content::Content;
pub use manifest::{Capability, Manifest, Package, Side, find};
+416
View File
@@ -0,0 +1,416 @@
//! 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. [`Script`] is a
//! test written in TOML, `tests/<name>.toml` in the mod's folder: steps, each
//! saying what happens and what the mod must have shown by then.
use crate::{Clock, Corner, Mods, Output, Panel, Player, 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<Player>,
pub clock: Option<Clock>,
tick: u64,
}
/// 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<TestGame, String> {
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,
}),
tick: 0,
};
copy_mod(hmod, &copy)?;
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,
// The GUI of a 1280 x 720 window at scale 3, as the trial run's.
gui_size: (427.0, 240.0),
..Snapshot::default()
});
}
/// `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);
}
}
/// `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)
}
/// 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<String> {
self.mods.commands().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<Output> {
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 the 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<Step>,
}
/// Fields of the player to change; the others keep their values.
#[derive(Debug, Default, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PlayerSet {
x: Option<f64>,
y: Option<f64>,
z: Option<f64>,
yaw: Option<f32>,
pitch: Option<f32>,
health: Option<f32>,
food: Option<u32>,
dimension: Option<String>,
}
#[derive(Debug, Default, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "kebab-case")]
pub struct ClockSet {
game_time: Option<u64>,
day_time: Option<u64>,
}
/// One step. Its parts happen in this order: `reload`, `title-screen`,
/// `player`, `clock`, `ticks`, `frames`, `chat`, `command`; then `expect` is
/// checked against what the mod showed during the step.
#[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<PlayerSet>,
clock: Option<ClockSet>,
#[serde(default)]
ticks: u64,
#[serde(default)]
frames: u64,
chat: Option<String>,
command: Option<String>,
#[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<Vec<String>>,
/// Every chat line shown during the step, in order.
chat: Option<Vec<String>>,
/// The command's feedback, and its red error.
feedback: Option<String>,
error: Option<String>,
/// The panel's lines (`[]`: no panel) and its corner.
panel: Option<Vec<String>>,
corner: Option<String>,
/// 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<String>,
}
impl Script {
pub fn parse(text: &str) -> Result<Script, String> {
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<f64>| *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);
}
}
}
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 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;
}
if let Some(set) = &self.player {
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);
if let Some(line) = &self.chat {
game.chat(line);
}
let owned = self.command.as_ref().map(|line| game.command(line));
let out = game.drain();
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<String> = 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 } if *e == error => Some(text.clone()),
_ => None,
})
};
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<String> = 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.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<T: PartialEq + std::fmt::Debug>(what: &str, want: &T, got: &T) -> Result<(), String> {
if want == got {
return Ok(());
}
Err(format!(
"{what}\n expected: {want:?}\n got: {got:?}"
))
}
+78
View File
@@ -4,6 +4,7 @@
use horizon_mods::{
Clock, Corner, HeldItem, Mods, Output, Package, Player, Shape, Snapshot, Status,
manifest::componentize,
testing::{Script, TestGame},
};
use std::{
path::{Path, PathBuf},
@@ -703,3 +704,80 @@ capabilities = ["registries"]
// Content has no hooks: the game's per-tick mod work stays skipped.
assert!(!mods.is_running());
}
/// `cargo horizon-mod test` on the example: its own `tests/*.toml` pass.
#[test]
fn the_examples_test_scripts_pass() {
let tests =
Path::new(env!("CARGO_MANIFEST_DIR")).join("../horizon-mod-sdk/examples/coords-hud/tests");
let mut ran = 0;
for entry in std::fs::read_dir(tests).unwrap() {
let path = entry.unwrap().path();
let script = Script::parse(&std::fs::read_to_string(&path).unwrap()).unwrap();
let mut game = TestGame::load(&mods_dir().join("coords_hud.hmod")).unwrap();
script
.run(&mut game)
.unwrap_or_else(|e| panic!("{}: {e}", path.display()));
ran += 1;
}
assert_eq!(ran, 2);
}
#[test]
fn a_test_script_says_which_step_failed_and_why() {
let script = Script::parse(
r#"
[[step]]
ticks = 3
command = "hello there"
expect.chat = ["hello there after 2 ticks"]
"#,
)
.unwrap();
let mut game = TestGame::load(&mods_dir().join("horizon_mods_test_guest.hmod")).unwrap();
assert_eq!(
script.run(&mut game).unwrap_err(),
"step 1 (3 ticks, /hello there): chat\n expected: [\"hello there after 2 ticks\"]\n \
got: [\"hello there after 3 ticks\"]"
);
assert!(
Script::parse("[[step]]\ntick = 1").is_err(),
"a typo is an error"
);
}
#[test]
fn a_test_script_reloads_and_expects_a_stop() {
let script = Script::parse(
r#"
[[step]]
command = "save kept"
expect.feedback = "saved"
[[step]]
reload = true
command = "load"
expect.chat = ["kept"]
[[step]]
command = "panic"
expect.stopped = "panic"
[[step]]
reload = true
command = "nope"
"#,
)
.unwrap();
let mut game = TestGame::load(&mods_dir().join("horizon_mods_test_guest.hmod")).unwrap();
let dir = game.hmod().parent().unwrap().to_path_buf();
assert_eq!(
script.run(&mut game).unwrap_err(),
"step 4 (reload, /nope): the mod owns no command /nope"
);
drop(game);
assert!(
!dir.exists(),
"the scratch copy and its storage are removed"
);
}
+8 -4
View File
@@ -19,7 +19,7 @@ the player before the mod is turned on, and checked against the component's real
| Capabilities | 5: `game-read`, `chat`, `hud`, `storage`, `registries` |
| Manifest `api` lines served | 2: `0.1` (code), `0.2` (content) |
| SDK | the `Mod` trait (5 methods), `Registration` (4 builders), `export_mod!`, log helpers |
| `cargo horizon-mod` | `new` (templates `code` and `content`), `build`, `run`, `check` |
| `cargo horizon-mod` | `new` (templates `code` and `content`), `build`, `run`, `test`, `check` |
| Example mods | `coords-hud` (code), `ruby-content` (content) |
## Guide
@@ -33,7 +33,10 @@ The step-by-step guide, from installing the tools to publishing on the registry,
([The manifest](../mods.md#the-manifest)).
3. `cargo horizon-mod run` builds the `.hmod` and starts the game with it as a dev mod; after an edit,
`cargo horizon-mod build` and the running game reloads it.
4. Content mods: [Content mods (API 0.2)](../mods.md#content-mods-api-02).
4. `cargo horizon-mod test` runs the mod's `tests/*.toml` scripts in the sandbox, with no game: ticks, commands,
chat lines and the player's position in, chat, feedback and the HUD panel checked
([Testing a mod](../mods.md#testing-a-mod)).
5. Content mods: [Content mods (API 0.2)](../mods.md#content-mods-api-02).
## Reference
@@ -94,11 +97,12 @@ What real mods need next, in the order modpacks and servers need it:
- **Config**: typed settings the game shows and stores for the mod, on the server too.
- **Keys and the crosshair target**: keybinds in Controls; what the player is looking at.
- **Script mods and other languages**: see [Ways in](#ways-in).
- **SDK**: a headless test runner (load a mod, feed it ticks and events, assert on its output, no window), templates
per kind of mod, typed wrappers in the SDK for every interface. Dev mods already reload when rebuilt.
- **SDK**: templates per kind of mod, typed wrappers in the SDK for every interface. Dev mods already reload when
rebuilt, and `cargo horizon-mod test` runs a mod headless.
## Changelog
- SDK: `cargo horizon-mod test` and `horizon_mods::testing`, test scripts in TOML; the template has one.
- Experimental: `ui` button widget; `render.set-corner`, `text-width`, `frame-stats`; `input.mapping`,
`clicks-per-second` (what the official FPS, keystrokes and zoom mods need).
- Experimental `input` (`experimental = ["input"]`): `claim-items`, `register-key`, `held`, `poll` (use-start,
+64 -3
View File
@@ -17,7 +17,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
| Example mods | `crates/horizon-mod-sdk/examples/coords-hud`, `examples/predator-missile` | coordinates, facing and time HUD, `/where`, `/coords`; `/missile`, a guided missile from vanilla commands |
| Horizon's official mods | `mods/official/` | the extras moving to the registry: FPS Counter (`fps-overlay`), Keystrokes, Zoom |
| Runtime | `crates/horizon-mods` | wasmtime 48 LTS, component model |
| Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new [--template code\|content] / build / run / check`, and the registry's CI (`registry build / review / list`) |
| Authoring tool | `crates/cargo-horizon-mod` | `cargo horizon-mod new [--template code\|content] / build / run / test / check`, and the registry's CI (`registry build / review / list`) |
| In the game | `crates/horizon-client/src/game/mods.rs`, Options > Mods | client mods |
| Launcher mod browser (Modrinth, CurseForge with a key) | [mod-browser.md](mod-browser.md) | resource packs, modpacks |
| Registry index (`index.json`, `.hpack`), signatures | `horizon_mods::index`, [api/mod-index.md](api/mod-index.md) | schema 1; launcher and website next |
@@ -220,11 +220,12 @@ Benchmarks (`--benchmark`) never load mods.
```sh
rustup target add wasm32-unknown-unknown
cargo install --git https://github.com/ludovic111/horizon cargo-horizon-mod
cargo horizon-mod new my-mod # Cargo.toml, horizon-mod.toml, src/lib.rs
cargo horizon-mod new my-mod # Cargo.toml, horizon-mod.toml, src/lib.rs, tests/hello.toml
# (--template content: a content mod, no code)
cd my-mod
cargo horizon-mod run # build, then start the game with it
cargo horizon-mod build # again after an edit: the running game reloads it
cargo horizon-mod test # build, then run tests/*.toml with no game
```
`run` starts `horizon-client` (on `PATH`, or `--game PATH`, or
@@ -245,13 +246,73 @@ and each of its commands: it must start and never trap or overrun. It checks a
`.hpack` and a resource pack `.zip` too, and a signature with `--key <public
key> --signature <file>.minisig`.
### Testing a mod
`cargo horizon-mod test` builds the mod, then runs each `tests/<name>.toml` in
the sandbox the game uses, with no game and no window: the test plays the
game's part (the player and the clock the mod reads, ticks, frames, chat lines,
commands) and checks what the mod showed. A script fails at its first wrong
step, with what it expected and what it got; the command fails if any script
does. `--debug` builds without optimizing, `--hmod <file>` tests a `.hmod`
already built, and a name runs only the scripts whose path holds it. Each
script gets a scratch copy of the mod, so its `storage` starts empty and is
removed afterwards.
```toml
# tests/panel.toml (examples/coords-hud)
[player] # where the script starts; unset fields keep the defaults
x = 12.5 # (0.5 64 0.5, yaw 0, 20 health and food, the Overworld)
z = -3.25
yaw = 180.0
[clock] # day-time 0 is 6:00 on day 1; each tick adds one
day-time = 29999
[[step]]
ticks = 1
expect.panel = ["XYZ 12.5 / 64.0 / -3.2", "Facing North (-Z)", "Day 2, 12:00"]
expect.corner = "top-left"
[[step]]
command = "coords"
expect.feedback = "Coordinates panel hidden"
```
A step's parts happen in this order:
| Key | Does |
| --- | --- |
| `reload = true` | stops the mod and starts it again, as a rebuild does in the game: its memory starts over, its `storage` stays |
| `title-screen = true` | no player and no clock until a step sets them |
| `player = { x = 3.0, ... }`, `clock = { day-time = 0 }` | changes those fields (`x y z yaw pitch health food dimension`, `game-time day-time`) |
| `ticks = n`, `frames = n` | that many ticks (the game's tick counter and the clock move on), then frames 1/60 s apart |
| `chat = "<Steve> hi"` | a chat line the player receives |
| `command = "where north"` | the player types `/where north`; a command the mod doesn't own fails the step |
Then `expect` checks what the mod did during the step; a key left out is not
checked:
| `expect.` | Checks |
| --- | --- |
| `commands = ["where"]` | the commands the mod owns |
| `chat = ["..."]` | every chat line it showed, in order (`[]`: none) |
| `feedback = "..."`, `error = "..."` | the command's answer, shown plain or in red |
| `panel = ["..."]`, `corner = "top-left"` | its HUD panel's lines (`[]`: no panel) and corner |
| `stopped = "panic"` | the mod was turned off, for a reason holding this text; without it, a mod that traps, panics or overruns fails the test |
Unknown keys are errors, so a typo never passes silently. The same runner is
`horizon_mods::testing` for Rust code that drives a mod (`TestGame`,
`Script`): Horizon's own tests run the examples' scripts with it. Scripts test
any mod, whatever it was written in.
### Template layout
```
my-mod/
├── Cargo.toml # cdylib, horizon-mod-sdk, release: opt-level "s", LTO
├── horizon-mod.toml # the manifest
└── src/lib.rs # impl Mod, export_mod!
├── src/lib.rs # impl Mod, export_mod!
└── tests/hello.toml # cargo horizon-mod test
```
A mod is a type implementing `horizon_mod_sdk::Mod`; its state lives in the
+1 -1
View File
@@ -32,7 +32,7 @@ cd my-mod
cargo horizon-mod build
```
The [Mod API](/docs/api/mods) lists what a mod can do today and what comes next, and its [reference](/docs/api/mods-reference) every function. Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](/docs/modpacks)).
`cargo horizon-mod test` runs the mod's test scripts (`tests/*.toml`: ticks, commands and the player's position in, chat and HUD lines checked) with no game open. The [Mod API](/docs/api/mods) lists what a mod can do today and what comes next, and its [reference](/docs/api/mods-reference) every function. Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](/docs/modpacks)).
## Finding resource packs and modpacks