//! Write Horizon mods in Rust (`docs/mods.md`). //! //! A mod is a type implementing [`Mod`], exported with [`export_mod!`] from //! a `cdylib` crate built for `wasm32-unknown-unknown`; //! `cargo horizon-mod build` turns it into the component the game loads. //! //! ```ignore //! use horizon_mod_sdk::{Mod, Registration, chat}; //! //! struct Hello; //! impl Mod for Hello { //! fn init() -> Result<(Self, Registration), String> { //! Ok((Hello, Registration::new().command("hello"))) //! } //! fn command(&mut self, _name: &str, _args: &str) -> Result, String> { //! chat::show("Hello from a mod!"); //! Ok(None) //! } //! } //! horizon_mod_sdk::export_mod!(Hello); //! ``` //! //! Every interface but `log` is a capability: list the ones the mod uses in //! `horizon-mod.toml` (`game-read`, `chat`, `hud`, `storage`, `command`, `ui`; //! a server mod `storage` and `players`). Server mods: [`server`]. //! //! Widgets (capability `ui`): a mod shows a screen it owns with //! [`ui::open_screen`] and a page in Options > Mods with //! [`ui::set_settings`]; what the player does with them comes back as //! [`Mod::ui_select`], [`Mod::ui_closed`] and [`Mod::ui_settings_opened`]. wit_bindgen::generate!({ path: "wit", world: "horizon-ui-mod", pub_export_macro: true, export_macro_name: "__export_horizon_mod", default_bindings_module: "horizon_mod_sdk", }); pub use exports::horizon::mods::events::{Guest as __Guest, Registration}; pub use exports::horizon::mods::ui_events::Guest as __UiEventsGuest; pub use horizon::mods::{ browser, chat, command, game, hud, input, log, recipes, render, storage, ui, }; /// The game's calls into a mod. Only the hooks [`Registration`] asks for /// are called; the others may stay as their defaults. pub trait Mod: Sized + 'static { /// Once, after loading: the mod's state and the hooks it wants. An error /// keeps the mod off and is shown to the player. fn init() -> Result<(Self, Registration), String>; /// Every game tick, when [`Registration::tick`] is set. fn tick(&mut self, _tick: u64) {} /// Every rendered frame, when [`Registration::frame`] is set. fn frame(&mut self, _seconds: f32) {} /// `/name args` for a command the mod registered. `Ok(Some(text))` is /// shown as feedback, `Err(text)` in red. fn command(&mut self, _name: &str, _args: &str) -> Result, String> { Err("This command does nothing".into()) } /// A chat line the player received, when [`Registration::chat`] is set. fn chat(&mut self, _text: &str) {} /// A row of one of the mod's `list` widgets was picked (capability /// `ui`): the widget's `id` and the row. fn ui_select(&mut self, _id: u32, _row: u32) {} /// The player left the mod's screen (Esc or Done; capability `ui`). fn ui_closed(&mut self) {} /// The player opened the mod's settings page (capability `ui`): call /// [`ui::set_settings`] for fresh widgets. fn ui_settings_opened(&mut self) {} } impl Registration { /// No commands and no hooks. pub fn new() -> Self { Self { commands: Vec::new(), tick: false, frame: false, chat: false, } } /// Adds `/name`. pub fn command(mut self, name: &str) -> Self { self.commands.push(name.into()); self } pub fn on_tick(mut self) -> Self { self.tick = true; self } pub fn on_frame(mut self) -> Self { self.frame = true; self } pub fn on_chat(mut self) -> Self { self.chat = true; self } } impl Default for Registration { fn default() -> Self { Self::new() } } /// `log::write` at info level. pub fn info(message: &str) { log::write(log::Level::Info, message); } /// `log::write` at warn level. pub fn warn(message: &str) { log::write(log::Level::Warn, message); } /// Exports a [`Mod`] as the component's `events` interface. The state lives /// in a thread local: a mod instance is single-threaded. #[macro_export] macro_rules! export_mod { ($t:ty) => { const _: () = { use ::std::cell::RefCell; ::std::thread_local! { static STATE: RefCell> = const { RefCell::new(None) }; } fn with(f: impl FnOnce(&mut $t)) { STATE.with(|s| { if let Some(m) = s.borrow_mut().as_mut() { f(m) } }) } struct Export; impl $crate::__Guest for Export { fn init() -> Result<$crate::Registration, String> { let (m, registration) = <$t as $crate::Mod>::init()?; STATE.with(|s| *s.borrow_mut() = Some(m)); Ok(registration) } fn tick(tick: u64) { with(|m| $crate::Mod::tick(m, tick)) } fn frame(seconds: f32) { with(|m| $crate::Mod::frame(m, seconds)) } fn command(name: String, args: String) -> Result, String> { let mut out = Err("The mod is not running".to_string()); with(|m| out = $crate::Mod::command(m, &name, &args)); out } fn chat(text: String) { with(|m| $crate::Mod::chat(m, &text)) } } impl $crate::__UiEventsGuest for Export { fn select(id: u32, row: u32) { with(|m| $crate::Mod::ui_select(m, id, row)) } fn closed() { with(|m| $crate::Mod::ui_closed(m)) } fn settings_opened() { with(|m| $crate::Mod::ui_settings_opened(m)) } } // Only WebAssembly has the component's exports: a host build (cargo test or // clippy on the workspace) checks the mod without them, which macOS // couldn't link (its exported-symbols list cuts names at the `#`). #[cfg(target_arch = "wasm32")] $crate::__export_horizon_mod!(Export); #[cfg(not(target_arch = "wasm32"))] let _ = ( ::init, ::select, ); }; }; } /// Server mods (manifest `side = "server"`, `api = "0.3"`, experimental): a /// type implementing [`ServerMod`](server::ServerMod), exported with /// [`export_server_mod!`]. It runs where the world is simulated, and reads /// and messages the players with capability `players`. pub mod server { wit_bindgen::generate!({ path: "wit", world: "horizon-server-mod", pub_export_macro: true, export_macro_name: "__export_horizon_server_mod", default_bindings_module: "horizon_mod_sdk::server", with: { "horizon:mods/log@0.1.0": crate::log, "horizon:mods/storage@0.1.0": crate::storage, }, }); pub use exports::horizon::mods::server_events::{ Argument, ArgumentKind, ArgumentValue, BlockPos, Guest as __Guest, Registration, ServerCommand, }; pub use horizon::mods::players::{self, GameMode, Player}; pub use horizon::mods::world::{self, BlockChange}; /// The server's calls into a mod. Only the hooks [`Registration`] asks /// for are called; the others may stay as their defaults. pub trait ServerMod: Sized + 'static { /// Once, after loading: the mod's state and the hooks it wants. An /// error keeps the mod off and is logged. fn init() -> Result<(Self, Registration), String>; /// Every server tick, when [`Registration::tick`] is set. fn tick(&mut self, _tick: u64) {} /// When [`Registration::joins`] is set. fn player_joined(&mut self, _player: &Player) {} fn player_left(&mut self, _player: &Player) {} /// A chat message a player sent, when [`Registration::chat`] is set. fn chat(&mut self, _player: &Player, _text: &str) {} /// `/name args` typed by `player`, parsed as the command's /// arguments say ([`Registration::command_with`]). `Ok(Some(text))` /// is their feedback, `Err(text)` their error in red. fn command( &mut self, _player: &Player, _name: &str, _args: &Args, ) -> Result, String> { Err("This command does nothing".into()) } /// When [`Registration::blocks`] is set: `state` is what was there. fn block_broken(&mut self, _player: &Player, _pos: BlockPos, _state: &str) {} fn block_placed(&mut self, _player: &Player, _pos: BlockPos, _state: &str) {} } impl Registration { /// No commands and no hooks. pub fn new() -> Self { Self { commands: Vec::new(), tick: false, joins: false, chat: false, blocks: false, } } /// Adds `/name`, taking free text ([`Args::text`]): one optional /// `text` argument named `args`. pub fn command(self, name: &str) -> Self { self.command_with(name, [Argument::text("args").optional()]) } /// Adds `/name` with typed arguments (none: nothing after the name): /// players' chat boxes complete and check them, and the server /// parses them into [`Args`]. pub fn command_with( mut self, name: &str, arguments: impl IntoIterator, ) -> Self { self.commands.push(ServerCommand { name: name.into(), arguments: arguments.into_iter().collect(), }); self } pub fn on_tick(mut self) -> Self { self.tick = true; self } pub fn on_joins(mut self) -> Self { self.joins = true; self } pub fn on_chat(mut self) -> Self { self.chat = true; self } pub fn on_blocks(mut self) -> Self { self.blocks = true; self } } impl Default for Registration { fn default() -> Self { Self::new() } } impl Argument { fn of(name: &str, kind: ArgumentKind) -> Self { Self { name: name.into(), kind, optional: false, } } /// One word: letters, digits and `_ - . +`. pub fn word(name: &str) -> Self { Self::of(name, ArgumentKind::Word) } /// The rest of the line: only last. pub fn text(name: &str) -> Self { Self::of(name, ArgumentKind::Text) } /// A whole number, at least `min` and at most `max` when given. pub fn integer(name: &str, min: Option, max: Option) -> Self { Self::of(name, ArgumentKind::Integer((min, max))) } pub fn number(name: &str) -> Self { Self::of(name, ArgumentKind::Number) } pub fn boolean(name: &str) -> Self { Self::of(name, ArgumentKind::Boolean) } /// One online player: a name, `@s` or `@p`. pub fn player(name: &str) -> Self { Self::of(name, ArgumentKind::Player) } /// `x y z`, each one also `~` or `~n`. pub fn block_pos(name: &str) -> Self { Self::of(name, ArgumentKind::BlockPos) } /// May be left out; optional arguments come after the required ones. pub fn optional(mut self) -> Self { self.optional = true; self } } /// A command's arguments: the line as typed, and the values the server /// parsed from it, by argument name. #[derive(Clone, Debug, Default)] pub struct Args { text: String, values: Vec<(String, ArgumentValue)>, } impl Args { pub fn new(text: String, values: Vec<(String, ArgumentValue)>) -> Self { Self { text, values } } /// The line after the command's name, as typed. pub fn text(&self) -> &str { &self.text } /// The value of argument `name`; `None` when it was left out. pub fn get(&self, name: &str) -> Option<&ArgumentValue> { self.values.iter().find(|(n, _)| n == name).map(|(_, v)| v) } pub fn integer(&self, name: &str) -> Option { match self.get(name)? { ArgumentValue::Integer(n) => Some(*n), _ => None, } } pub fn number(&self, name: &str) -> Option { match self.get(name)? { ArgumentValue::Number(n) => Some(*n), _ => None, } } /// A `word` or `text` argument. pub fn string(&self, name: &str) -> Option<&str> { match self.get(name)? { ArgumentValue::Word(s) | ArgumentValue::Text(s) => Some(s), _ => None, } } pub fn boolean(&self, name: &str) -> Option { match self.get(name)? { ArgumentValue::Boolean(b) => Some(*b), _ => None, } } pub fn player(&self, name: &str) -> Option<&Player> { match self.get(name)? { ArgumentValue::Player(p) => Some(p), _ => None, } } pub fn block_pos(&self, name: &str) -> Option { match self.get(name)? { ArgumentValue::BlockPos(p) => Some(*p), _ => None, } } } } /// Exports a [`ServerMod`](server::ServerMod) as the component's /// `server-events` interface, as [`export_mod!`] does for a client mod. #[macro_export] macro_rules! export_server_mod { ($t:ty) => { const _: () = { use ::std::cell::RefCell; use $crate::server::{Args, ArgumentValue, BlockPos, Player, Registration, ServerMod}; ::std::thread_local! { static STATE: RefCell> = const { RefCell::new(None) }; } fn with(f: impl FnOnce(&mut $t)) { STATE.with(|s| { if let Some(m) = s.borrow_mut().as_mut() { f(m) } }) } struct Export; impl $crate::server::__Guest for Export { fn init() -> Result { let (m, registration) = <$t as ServerMod>::init()?; STATE.with(|s| *s.borrow_mut() = Some(m)); Ok(registration) } fn tick(tick: u64) { with(|m| m.tick(tick)) } fn player_joined(player: Player) { with(|m| m.player_joined(&player)) } fn player_left(player: Player) { with(|m| m.player_left(&player)) } fn chat(player: Player, text: String) { with(|m| m.chat(&player, &text)) } fn command( player: Player, name: String, args: String, values: Vec<(String, ArgumentValue)>, ) -> Result, String> { let mut out = Err("The mod is not running".to_string()); let args = Args::new(args, values); with(|m| out = m.command(&player, &name, &args)); out } fn block_broken(player: Player, pos: BlockPos, state: String) { with(|m| m.block_broken(&player, pos, &state)) } fn block_placed(player: Player, pos: BlockPos, state: String) { with(|m| m.block_placed(&player, pos, &state)) } } #[cfg(target_arch = "wasm32")] $crate::server::__export_horizon_server_mod!(Export); #[cfg(not(target_arch = "wasm32"))] let _ = ::init; }; }; }