670e055f4a
horizon-mod-sdk wraps wit-bindgen: a Mod trait with default hooks and export_mod!. coords-hud shows coordinates, facing and the time of day, with /where and /coords. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
142 lines
4.6 KiB
Rust
142 lines
4.6 KiB
Rust
//! 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<Option<String>, 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`).
|
|
|
|
wit_bindgen::generate!({
|
|
path: "wit",
|
|
world: "horizon-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 horizon::mods::{chat, game, hud, log};
|
|
|
|
/// 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<Option<String>, String> {
|
|
Err("This command does nothing".into())
|
|
}
|
|
/// A chat line the player received, when [`Registration::chat`] is set.
|
|
fn chat(&mut self, _text: &str) {}
|
|
}
|
|
|
|
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<Option<$t>> = 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<Option<String>, 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))
|
|
}
|
|
}
|
|
$crate::__export_horizon_mod!(Export);
|
|
};
|
|
};
|
|
}
|