diff --git a/Cargo.lock b/Cargo.lock index 760e25457..5bbc54701 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -320,6 +320,14 @@ dependencies = [ "wayland-client", ] +[[package]] +name = "cargo-horizon-mod" +version = "0.1.0" +dependencies = [ + "horizon-mods", + "serde_json", +] + [[package]] name = "cc" version = "1.6.0" @@ -1290,6 +1298,7 @@ dependencies = [ "toml", "wasmtime", "wit-component 0.239.0", + "wit-parser 0.239.0", "zip", ] diff --git a/Cargo.toml b/Cargo.toml index c2c15c1a8..03b7e1d66 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [workspace] exclude = ["launcher", "crates/horizon-telemetry-server"] -members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/horizon-mod-sdk/examples/coords-hud", "xtask"] +members = ["crates/horizon-core", "crates/horizon-world", "crates/voxel-kernels", "crates/horizon-client", "crates/horizon-assets", "crates/horizon-protocol", "crates/horizon-theme", "crates/horizon-prepare", "crates/horizon-telemetry", "crates/horizon-bench", "crates/horizon-friends", "crates/horizon-relay", "crates/horizon-mod-sdk", "crates/horizon-mods", "crates/horizon-mods/tests/guest", "crates/cargo-horizon-mod", "crates/horizon-mod-sdk/examples/coords-hud", "xtask"] resolver = "2" [workspace.package] diff --git a/crates/cargo-horizon-mod/Cargo.toml b/crates/cargo-horizon-mod/Cargo.toml new file mode 100644 index 000000000..6d0a231ec --- /dev/null +++ b/crates/cargo-horizon-mod/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "cargo-horizon-mod" +version = "0.1.0" +edition.workspace = true +license.workspace = true +rust-version = "1.86" +description = "cargo horizon-mod new/build/run: make Horizon mods in Rust (docs/mods.md)" + +[dependencies] +horizon-mods = { path = "../horizon-mods", default-features = false, features = ["pack"] } +serde_json = "1.0.151" + +[lints] +workspace = true diff --git a/crates/cargo-horizon-mod/src/main.rs b/crates/cargo-horizon-mod/src/main.rs new file mode 100644 index 000000000..6b088d278 --- /dev/null +++ b/crates/cargo-horizon-mod/src/main.rs @@ -0,0 +1,201 @@ +//! `cargo horizon-mod`: make Horizon mods in Rust (`docs/mods.md`). +//! +//! - `new [--name "Name"] [--sdk-path ]`: a mod crate from the template. +//! - `build [--debug]`: the `.hmod` in `target/horizon-mod/`. +//! - `run [--game ] [-- ]`: build, then play with +//! the mod; run `build` again and the game reloads it. +use horizon_mods::{ + Manifest, Package, + manifest::{MANIFEST, component_imports, componentize}, +}; +use std::{ + path::{Path, PathBuf}, + process::{Command, ExitCode, Stdio}, +}; + +const TARGET: &str = "wasm32-unknown-unknown"; +const SDK_GIT: &str = "{ git = \"https://github.com/ludovic111/horizon\" }"; + +fn main() -> ExitCode { + // Cargo runs `cargo-horizon-mod horizon-mod `. + let mut args: Vec = std::env::args().skip(1).collect(); + if args.first().is_some_and(|a| a == "horizon-mod") { + args.remove(0); + } + let result = match args.first().map(String::as_str) { + Some("new") => new(&args[1..]), + Some("build") => build(!args.iter().any(|a| a == "--debug")).map(|p| { + println!("Built {}", p.display()); + }), + Some("run") => run(&args[1..]), + _ => Err("usage: cargo horizon-mod new | build [--debug] | run [--game ] [-- ]".into()), + }; + match result { + Ok(()) => ExitCode::SUCCESS, + Err(e) => { + eprintln!("error: {e}"); + ExitCode::FAILURE + } + } +} + +/// The value after `flag` in `args`. +fn flag<'a>(args: &'a [String], flag: &str) -> Option<&'a str> { + let i = args.iter().position(|a| a == flag)?; + args.get(i + 1).map(String::as_str) +} + +fn new(args: &[String]) -> Result<(), String> { + let path = args + .first() + .filter(|a| !a.starts_with("--")) + .ok_or("cargo horizon-mod new ")?; + let dir = Path::new(path); + if dir.exists() { + return Err(format!("{} already exists", dir.display())); + } + let base = dir + .file_name() + .and_then(|n| n.to_str()) + .ok_or("the path needs a folder name")?; + let id: String = base + .chars() + .map(|c| { + if c.is_ascii_alphanumeric() { + c.to_ascii_lowercase() + } else { + '_' + } + }) + .collect(); + let name = flag(args, "--name").map_or_else(|| base.replace(['-', '_'], " "), str::to_string); + let sdk = match flag(args, "--sdk-path") { + Some(p) => { + let p = std::fs::canonicalize(p).map_err(|e| format!("--sdk-path {p}: {e}"))?; + format!("{{ path = {:?} }}", p.display().to_string()) + } + None => SDK_GIT.to_string(), + }; + let fill = |t: &str| { + t.replace("{crate}", &id.replace('_', "-")) + .replace("{id}", &id) + .replace("{name}", &name) + .replace("{sdk}", &sdk) + }; + let files = [ + ("Cargo.toml", include_str!("../template/Cargo.toml.in")), + (MANIFEST, include_str!("../template/horizon-mod.toml")), + ("src/lib.rs", include_str!("../template/src/lib.rs")), + (".gitignore", include_str!("../template/gitignore")), + ]; + for (file, text) in files { + let to = dir.join(file); + std::fs::create_dir_all(to.parent().expect("a file in the mod")) + .map_err(|e| e.to_string())?; + std::fs::write(&to, fill(text)).map_err(|e| format!("{}: {e}", to.display()))?; + } + Manifest::parse(&std::fs::read_to_string(dir.join(MANIFEST)).map_err(|e| e.to_string())?)?; + println!( + "Created {} (mod id {id}). Next: cd {path} && cargo horizon-mod run", + dir.display() + ); + Ok(()) +} + +/// Builds the crate in the current folder and packs `target/horizon-mod/.hmod`. +fn build(release: bool) -> Result { + let manifest_text = std::fs::read_to_string(MANIFEST) + .map_err(|e| format!("{MANIFEST}: {e} (run this in a mod's folder)"))?; + let manifest = Manifest::parse(&manifest_text)?; + let cargo = std::env::var("CARGO").unwrap_or_else(|_| "cargo".into()); + let mut cmd = Command::new(cargo); + cmd.args([ + "build", + "--lib", + "--target", + TARGET, + "--message-format=json-render-diagnostics", + ]); + if release { + cmd.arg("--release"); + } + let out = cmd + .stderr(Stdio::inherit()) + .output() + .map_err(|e| e.to_string())?; + if !out.status.success() { + return Err(format!( + "cargo build failed (is the target installed? rustup target add {TARGET})" + )); + } + let core = String::from_utf8_lossy(&out.stdout) + .lines() + .filter_map(|l| serde_json::from_str::(l).ok()) + .filter(|m| m["reason"] == "compiler-artifact") + .flat_map(|m| m["filenames"].as_array().cloned().unwrap_or_default()) + .filter_map(|f| f.as_str().map(PathBuf::from)) + .rfind(|f| f.extension().is_some_and(|e| e == "wasm")) + .ok_or("the build made no .wasm: is the crate a cdylib?")?; + let wasm = componentize(&std::fs::read(&core).map_err(|e| e.to_string())?)?; + // The game refuses a component importing capabilities the manifest lacks. + manifest.check_imports(component_imports(&wasm)?.iter().map(String::as_str))?; + let target_dir = core.ancestors().nth(3).ok_or("unexpected target folder")?; + let dir = target_dir.join("horizon-mod"); + std::fs::create_dir_all(&dir).map_err(|e| e.to_string())?; + let path = dir.join(format!("{}.hmod", manifest.id)); + // Write then rename, so a running game never reads half a file. + let partial = path.with_extension("hmod.partial"); + std::fs::write(&partial, Package::write(&manifest_text, &wasm)?).map_err(|e| e.to_string())?; + std::fs::rename(&partial, &path).map_err(|e| e.to_string())?; + Ok(path) +} + +fn run(args: &[String]) -> Result<(), String> { + let path = build(true)?; + let game = flag(args, "--game") + .map(str::to_string) + .or_else(|| std::env::var("HORIZON_CLIENT").ok()) + .unwrap_or_else(|| "horizon-client".into()); + let extra = args.iter().skip_while(|a| *a != "--").skip(1); + println!( + "Starting {game} with {} (rebuild with `cargo horizon-mod build` to reload it)", + path.display() + ); + let status = Command::new(&game) + .arg("--dev-mod") + .arg(&path) + .args(extra) + .status() + .map_err(|e| { + format!("{game}: {e} (pass --game or set HORIZON_CLIENT)") + })?; + status + .success() + .then_some(()) + .ok_or_else(|| format!("the game exited with {status}")) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn the_template_is_a_valid_mod() { + let dir = std::env::temp_dir().join(format!("horizon-mod-new-{}", std::process::id())); + let path = dir.join("My-Mod"); + new(&[path.display().to_string(), "--name".into(), "My Mod".into()]).unwrap(); + let manifest = + Manifest::parse(&std::fs::read_to_string(path.join(MANIFEST)).unwrap()).unwrap(); + assert_eq!( + (manifest.id.as_str(), manifest.name.as_str()), + ("my_mod", "My Mod") + ); + let cargo = std::fs::read_to_string(path.join("Cargo.toml")).unwrap(); + assert!(cargo.contains("name = \"my-mod\"") && cargo.contains(SDK_GIT)); + assert!( + new(&[path.display().to_string()]).is_err(), + "never overwrites" + ); + std::fs::remove_dir_all(&dir).unwrap(); + } +} diff --git a/crates/cargo-horizon-mod/template/Cargo.toml.in b/crates/cargo-horizon-mod/template/Cargo.toml.in new file mode 100644 index 000000000..74d494340 --- /dev/null +++ b/crates/cargo-horizon-mod/template/Cargo.toml.in @@ -0,0 +1,14 @@ +[package] +name = "{crate}" +version = "0.1.0" +edition = "2024" + +[lib] +crate-type = ["cdylib"] + +[dependencies] +horizon-mod-sdk = {sdk} + +[profile.release] +opt-level = "s" +lto = true diff --git a/crates/cargo-horizon-mod/template/gitignore b/crates/cargo-horizon-mod/template/gitignore new file mode 100644 index 000000000..ea8c4bf7f --- /dev/null +++ b/crates/cargo-horizon-mod/template/gitignore @@ -0,0 +1 @@ +/target diff --git a/crates/cargo-horizon-mod/template/horizon-mod.toml b/crates/cargo-horizon-mod/template/horizon-mod.toml new file mode 100644 index 000000000..e2639d84f --- /dev/null +++ b/crates/cargo-horizon-mod/template/horizon-mod.toml @@ -0,0 +1,12 @@ +id = "{id}" +name = "{name}" +version = "0.1.0" +description = "" +authors = [] +# The Horizon mod API the SDK targets. +api = "0.1" +# client: runs in the player's game. +side = "client" +# What the mod may do, shown to players before they turn it on: +# game-read (position, health, time), chat (show messages), hud (draw text). +capabilities = ["chat"] diff --git a/crates/cargo-horizon-mod/template/src/lib.rs b/crates/cargo-horizon-mod/template/src/lib.rs new file mode 100644 index 000000000..6cf67e770 --- /dev/null +++ b/crates/cargo-horizon-mod/template/src/lib.rs @@ -0,0 +1,19 @@ +use horizon_mod_sdk::{Mod, Registration, chat}; + +struct MyMod { + greeted: u32, +} + +impl Mod for MyMod { + fn init() -> Result<(Self, Registration), String> { + Ok((MyMod { greeted: 0 }, Registration::new().command("hello"))) + } + + fn command(&mut self, _name: &str, args: &str) -> Result, String> { + self.greeted += 1; + chat::show(&format!("Hello {args}! ({} so far)", self.greeted)); + Ok(None) + } +} + +horizon_mod_sdk::export_mod!(MyMod); diff --git a/crates/horizon-mods/Cargo.toml b/crates/horizon-mods/Cargo.toml index 93b46eb14..ee325261d 100644 --- a/crates/horizon-mods/Cargo.toml +++ b/crates/horizon-mods/Cargo.toml @@ -15,12 +15,13 @@ log = "0.4" wasmtime = { version = "36.0.18", default-features = false, features = ["runtime", "cranelift", "component-model", "std"], optional = true } # Turns a mod's core module into a component (cargo horizon-mod build, the tests). wit-component = { version = "0.239", optional = true } +wit-parser = { version = "0.239", optional = true } [features] default = ["runtime"] # Loads and runs mods; without it only manifests and packaging (cargo horizon-mod). runtime = ["dep:wasmtime"] -pack = ["dep:wit-component"] +pack = ["dep:wit-component", "dep:wit-parser"] [dev-dependencies] horizon-mods = { path = ".", features = ["pack"] } diff --git a/crates/horizon-mods/src/manifest.rs b/crates/horizon-mods/src/manifest.rs index 4a0f5f31e..984ef7e6b 100644 --- a/crates/horizon-mods/src/manifest.rs +++ b/crates/horizon-mods/src/manifest.rs @@ -199,6 +199,27 @@ pub fn componentize(core: &[u8]) -> Result, String> { .map_err(|e| format!("{e:#}")) } +/// The names a component imports: `horizon:mods/game@0.1.0`, ... +#[cfg(feature = "pack")] +pub fn component_imports(component: &[u8]) -> Result, String> { + use wit_parser::{WorldItem, WorldKey}; + let wit_component::DecodedWasm::Component(resolve, world) = + wit_component::decode(component).map_err(|e| format!("{e:#}"))? + else { + return Err("a WIT package, not a component".into()); + }; + let names = resolve.worlds[world] + .imports + .iter() + .map(|(key, item)| match (key, item) { + (WorldKey::Interface(id), _) | (_, WorldItem::Interface { id, .. }) => resolve + .id_of(*id) + .unwrap_or_else(|| resolve.name_world_key(key)), + _ => resolve.name_world_key(key), + }); + Ok(names.collect()) +} + #[cfg(test)] mod tests { use super::*;