Files
horizon-airdef/crates/horizon-mod-sdk/src/lib.rs
T
Ludovic Marie b90ab85f44 Merge remote-tracking branch 'origin/main' into feat/server-mods-0.3
# Conflicts:
#	Cargo.toml
#	crates/cargo-horizon-mod/src/check.rs
#	crates/horizon-client/src/game/mods.rs
#	crates/horizon-mod-sdk/src/lib.rs
#	crates/horizon-mod-sdk/wit/horizon.wit
#	crates/horizon-mods/src/manifest.rs
#	crates/horizon-mods/src/runtime.rs
#	crates/horizon-mods/src/testing.rs
#	crates/horizon-mods/tests/sandbox.rs
#	docs/api/mods-reference.md
#	docs/api/mods.md
#	docs/mods.md
2026-10-26 09:51:00 +01:00

326 lines
12 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`, `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::{chat, command, game, hud, input, log, 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<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) {}
/// 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<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))
}
}
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 _ = (
<Export as $crate::__Guest>::init,
<Export as $crate::__UiEventsGuest>::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::{BlockPos, Guest as __Guest, Registration};
pub use horizon::mods::players::{self, GameMode, Player};
/// 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`. `Ok(Some(text))` is their
/// feedback, `Err(text)` their error in red.
fn command(
&mut self,
_player: &Player,
_name: &str,
_args: &str,
) -> Result<Option<String>, 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`.
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_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()
}
}
}
/// 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::{BlockPos, Player, Registration, ServerMod};
::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::server::__Guest for Export {
fn init() -> Result<Registration, String> {
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,
) -> Result<Option<String>, String> {
let mut out = Err("The mod is not running".to_string());
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 _ = <Export as $crate::server::__Guest>::init;
};
};
}