448 lines
16 KiB
Rust
448 lines
16 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::{
|
|
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<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::{
|
|
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<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`, 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<Item = Argument>,
|
|
) -> 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<i32>, max: Option<i32>) -> 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<i32> {
|
|
match self.get(name)? {
|
|
ArgumentValue::Integer(n) => Some(*n),
|
|
_ => None,
|
|
}
|
|
}
|
|
pub fn number(&self, name: &str) -> Option<f64> {
|
|
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<bool> {
|
|
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<BlockPos> {
|
|
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<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,
|
|
values: Vec<(String, ArgumentValue)>,
|
|
) -> Result<Option<String>, 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 _ = <Export as $crate::server::__Guest>::init;
|
|
};
|
|
};
|
|
}
|