604 lines
20 KiB
Rust
604 lines
20 KiB
Rust
//! Loading and calling mods with wasmtime's component model.
|
|
use crate::manifest::{Manifest, Package, Side};
|
|
use std::{
|
|
path::{Path, PathBuf},
|
|
sync::Arc,
|
|
time::{Duration, Instant, SystemTime},
|
|
};
|
|
use wasmtime::{
|
|
Config, Engine, Store, StoreLimits, StoreLimitsBuilder, Trap,
|
|
component::{Component, HasSelf, Linker},
|
|
};
|
|
|
|
mod bindings {
|
|
wasmtime::component::bindgen!({
|
|
path: "../horizon-mod-sdk/wit",
|
|
world: "horizon-mod",
|
|
});
|
|
}
|
|
pub use bindings::horizon::mods::{
|
|
game::{Clock, Player},
|
|
hud::{Corner, Line},
|
|
};
|
|
use bindings::{
|
|
HorizonMod,
|
|
exports::horizon::mods::events::Registration,
|
|
horizon::mods::{chat, command, game, hud, log as mod_log, storage},
|
|
};
|
|
|
|
/// A mod's linear memory cap.
|
|
const MEMORY: usize = 64 << 20;
|
|
/// Fuel (about one unit per WebAssembly instruction) per call: a bound on
|
|
/// runaway loops, far above the hooks' time budgets.
|
|
const FUEL_INIT: u64 = 2_000_000_000;
|
|
const FUEL_TICK: u64 = 50_000_000;
|
|
const FUEL_FRAME: u64 = 10_000_000;
|
|
const FUEL_EVENT: u64 = 100_000_000;
|
|
/// Chat lines a mod may show per call, HUD lines and their length.
|
|
const CHAT_PER_CALL: usize = 8;
|
|
const HUD_LINES: usize = 16;
|
|
const LINE_CHARS: usize = 256;
|
|
/// Total bytes a mod's `storage` may hold on disk, across all its keys.
|
|
const STORAGE_QUOTA: u64 = 4 << 20;
|
|
/// Distinct keys a mod's `storage` may hold: `STORAGE_QUOTA` alone doesn't
|
|
/// bound a flood of zero- or near-zero-byte files (each still a file name,
|
|
/// a directory entry and an inode).
|
|
const STORAGE_MAX_KEYS: usize = 64;
|
|
/// Bytes `storage::set` may write across one hook call: fuel bounds a
|
|
/// mod's CPU time per call, not the time a synchronous disk write takes, so
|
|
/// a cheap-in-fuel loop replacing one key with large payloads needs its own
|
|
/// cap, separate from the on-disk quota it would otherwise stay under.
|
|
const STORAGE_WRITE_BUDGET: u64 = 1 << 20;
|
|
/// A mod's data, beside its `horizon-mods` folder (`find`'s `path.parent()`
|
|
/// never has a manifest there, so `find` never mistakes it for a mod).
|
|
const STORAGE_DIR: &str = ".horizon-mod-data";
|
|
|
|
/// What mods may read of the game, copied once per tick by the game.
|
|
#[derive(Clone, Debug, Default)]
|
|
pub struct Snapshot {
|
|
pub player: Option<Player>,
|
|
pub clock: Option<Clock>,
|
|
}
|
|
|
|
/// What mods asked the game to show since the last [`Mods::drain`].
|
|
#[derive(Clone, Debug, PartialEq)]
|
|
pub enum Output {
|
|
/// `chat.show`: a line after the mod's name.
|
|
Chat { name: String, text: String },
|
|
/// A mod command's feedback, red when `error`.
|
|
Feedback { text: String, error: bool },
|
|
/// `command.run`: a vanilla command line, without its slash, to run as
|
|
/// the player.
|
|
Command { line: String },
|
|
/// The mod was turned off: it trapped, overran or failed to start.
|
|
Stopped { name: String, reason: String },
|
|
}
|
|
|
|
/// A mod's text panel, drawn every frame until it changes.
|
|
#[derive(Clone, Debug)]
|
|
pub struct Panel {
|
|
pub corner: Corner,
|
|
pub lines: Vec<Line>,
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq)]
|
|
pub enum Status {
|
|
/// Installed and turned off by the player.
|
|
Off,
|
|
Running,
|
|
/// Could not load or start, or stopped while running.
|
|
Failed(String),
|
|
}
|
|
|
|
/// One installed mod, for the Mods page.
|
|
pub struct Entry {
|
|
pub path: PathBuf,
|
|
/// None when the manifest could not be read (`status` says why).
|
|
pub manifest: Option<Manifest>,
|
|
pub status: Status,
|
|
/// The mod's average time per call of its busiest hook.
|
|
pub cost: Duration,
|
|
run: Option<Running>,
|
|
modified: Option<SystemTime>,
|
|
}
|
|
|
|
struct Running {
|
|
store: Store<State>,
|
|
exports: HorizonMod,
|
|
hooks: Registration,
|
|
}
|
|
|
|
struct State {
|
|
name: String,
|
|
id: String,
|
|
snapshot: Arc<Snapshot>,
|
|
out: Vec<Output>,
|
|
panel: Option<Panel>,
|
|
/// Capability `storage`'s folder; made on first `set`.
|
|
data_dir: PathBuf,
|
|
/// Bytes `storage::set` may still write before this hook call ends
|
|
/// (reset per call in [`Mods::call`]): fuel bounds a mod's CPU time but
|
|
/// not disk I/O time, so a loop of small-fuel, large-payload `set`s
|
|
/// needs its own budget.
|
|
storage_budget: u64,
|
|
limits: StoreLimits,
|
|
}
|
|
|
|
/// The installed mods and the engine running them. `Mods::default()` is
|
|
/// the state with none: no engine, and every hook a no-op.
|
|
#[derive(Default)]
|
|
pub struct Mods {
|
|
engine: Option<(Engine, Linker<State>)>,
|
|
entries: Vec<Entry>,
|
|
snapshot: Arc<Snapshot>,
|
|
out: Vec<Output>,
|
|
}
|
|
|
|
impl Mods {
|
|
/// Reads every mod at `paths` and starts those `enabled` says are on.
|
|
/// A command that `reserved` (vanilla's commands) or an earlier mod
|
|
/// already uses is refused.
|
|
pub fn load(
|
|
paths: &[PathBuf],
|
|
enabled: impl Fn(&str) -> bool,
|
|
reserved: impl Fn(&str) -> bool,
|
|
) -> Mods {
|
|
let mut mods = Mods::default();
|
|
for path in paths {
|
|
let modified = modified(path);
|
|
let mut entry = Entry {
|
|
path: path.clone(),
|
|
manifest: None,
|
|
status: Status::Off,
|
|
cost: Duration::ZERO,
|
|
run: None,
|
|
modified,
|
|
};
|
|
match Package::read(path) {
|
|
Err(e) => entry.status = Status::Failed(e),
|
|
Ok(package) => {
|
|
let on = enabled(&package.manifest.id);
|
|
entry.manifest = Some(package.manifest.clone());
|
|
if on {
|
|
// Content is read before the world loads; a mod whose
|
|
// content is refused stays off, with the reason.
|
|
let content = crate::Content::read(path, &package.manifest);
|
|
entry.status =
|
|
match content.and_then(|_| mods.start(path, &package, &reserved)) {
|
|
Ok(run) => {
|
|
entry.run = run;
|
|
Status::Running
|
|
}
|
|
Err(e) => Status::Failed(e),
|
|
};
|
|
}
|
|
}
|
|
}
|
|
if let (Status::Failed(reason), Some(m)) = (&entry.status, &entry.manifest) {
|
|
log::warn!("Horizon: mod {} did not start: {reason}", m.id);
|
|
}
|
|
mods.entries.push(entry);
|
|
}
|
|
mods
|
|
}
|
|
|
|
fn engine(&mut self) -> Result<&(Engine, Linker<State>), String> {
|
|
if self.engine.is_none() {
|
|
let mut config = Config::new();
|
|
config.wasm_component_model(true).consume_fuel(true);
|
|
let engine = Engine::new(&config).map_err(|e| e.to_string())?;
|
|
let mut linker = Linker::new(&engine);
|
|
HorizonMod::add_to_linker::<State, HasSelf<State>>(&mut linker, |s| s)
|
|
.map_err(|e| e.to_string())?;
|
|
self.engine = Some((engine, linker));
|
|
}
|
|
Ok(self.engine.as_ref().expect("made above"))
|
|
}
|
|
|
|
/// Starts a mod's code; `Ok(None)` for a content-only mod, which has
|
|
/// nothing to run (the game reads its content before the world loads).
|
|
/// `path` is the mod's own `.hmod` or folder, for capability `storage`'s
|
|
/// per-mod directory.
|
|
fn start(
|
|
&mut self,
|
|
path: &Path,
|
|
package: &Package,
|
|
reserved: &dyn Fn(&str) -> bool,
|
|
) -> Result<Option<Running>, String> {
|
|
let m = &package.manifest;
|
|
let Some(wasm) = &package.wasm else {
|
|
return Ok(None);
|
|
};
|
|
if m.side == Side::Server {
|
|
return Err("server mods do not run yet".into());
|
|
}
|
|
// Two running mods with the same id would share one `data_dir`
|
|
// (capability `storage`): the first loaded keeps the id.
|
|
if self
|
|
.entries
|
|
.iter()
|
|
.any(|e| e.run.is_some() && e.manifest.as_ref().is_some_and(|other| other.id == m.id))
|
|
{
|
|
return Err(format!("another running mod already uses id {}", m.id));
|
|
}
|
|
let taken: Vec<String> = self
|
|
.entries
|
|
.iter()
|
|
.filter_map(|e| e.run.as_ref())
|
|
.flat_map(|r| r.hooks.commands.iter().cloned())
|
|
.collect();
|
|
let snapshot = self.snapshot.clone();
|
|
let (engine, linker) = self.engine()?;
|
|
let component =
|
|
Component::new(engine, wasm).map_err(|e| format!("not a component: {e}"))?;
|
|
let ty = component.component_type();
|
|
let imports: Vec<String> = ty
|
|
.imports(engine)
|
|
.map(|(name, _)| name.to_string())
|
|
.collect();
|
|
m.check_imports(imports.iter().map(String::as_str))?;
|
|
let data_dir = path
|
|
.parent()
|
|
.unwrap_or(Path::new("."))
|
|
.join(STORAGE_DIR)
|
|
.join(&m.id);
|
|
let state = State {
|
|
name: m.name.clone(),
|
|
id: m.id.clone(),
|
|
snapshot,
|
|
out: Vec::new(),
|
|
panel: None,
|
|
data_dir,
|
|
storage_budget: STORAGE_WRITE_BUDGET,
|
|
limits: StoreLimitsBuilder::new()
|
|
.memory_size(MEMORY)
|
|
.instances(16)
|
|
.build(),
|
|
};
|
|
let mut store = Store::new(engine, state);
|
|
store.limiter(|s| &mut s.limits);
|
|
store.set_fuel(FUEL_INIT).map_err(|e| e.to_string())?;
|
|
let exports =
|
|
HorizonMod::instantiate(&mut store, &component, linker).map_err(|e| reason(&e))?;
|
|
let mut hooks = exports
|
|
.horizon_mods_events()
|
|
.call_init(&mut store)
|
|
.map_err(|e| reason(&e))??;
|
|
hooks.commands.retain(|c| {
|
|
let free = !reserved(c) && !taken.contains(c);
|
|
if !free {
|
|
log::warn!("Horizon: mod {} cannot take /{c}: already a command", m.id);
|
|
}
|
|
free
|
|
});
|
|
self.out.append(&mut store.data_mut().out);
|
|
Ok(Some(Running {
|
|
store,
|
|
exports,
|
|
hooks,
|
|
}))
|
|
}
|
|
|
|
/// True when at least one mod runs: the game skips its mod work otherwise.
|
|
pub fn is_running(&self) -> bool {
|
|
self.entries.iter().any(|e| e.run.is_some())
|
|
}
|
|
pub fn entries(&self) -> &[Entry] {
|
|
&self.entries
|
|
}
|
|
/// What mods read until the next snapshot.
|
|
pub fn set_snapshot(&mut self, snapshot: Snapshot) {
|
|
self.snapshot = Arc::new(snapshot);
|
|
}
|
|
|
|
/// Calls `f` on every running mod whose hooks `wants`, with `fuel`.
|
|
fn each(
|
|
&mut self,
|
|
fuel: u64,
|
|
wants: impl Fn(&Registration) -> bool,
|
|
mut f: impl FnMut(&HorizonMod, &mut Store<State>) -> wasmtime::Result<()>,
|
|
) {
|
|
for i in 0..self.entries.len() {
|
|
if self.entries[i]
|
|
.run
|
|
.as_ref()
|
|
.is_some_and(|r| wants(&r.hooks))
|
|
{
|
|
self.call(i, fuel, &mut f);
|
|
}
|
|
}
|
|
}
|
|
|
|
/// One call into mod `i`; a trap or an overrun turns the mod off.
|
|
fn call<R>(
|
|
&mut self,
|
|
i: usize,
|
|
fuel: u64,
|
|
f: impl FnOnce(&HorizonMod, &mut Store<State>) -> wasmtime::Result<R>,
|
|
) -> Option<R> {
|
|
let entry = &mut self.entries[i];
|
|
let run = entry.run.as_mut()?;
|
|
run.store.data_mut().snapshot = self.snapshot.clone();
|
|
run.store.data_mut().storage_budget = STORAGE_WRITE_BUDGET;
|
|
let started = Instant::now();
|
|
let result = run
|
|
.store
|
|
.set_fuel(fuel)
|
|
.and_then(|()| f(&run.exports, &mut run.store));
|
|
// An average over about the last 64 calls.
|
|
entry.cost = (entry.cost * 63 + started.elapsed()) / 64;
|
|
self.out.append(&mut run.store.data_mut().out);
|
|
match result {
|
|
Ok(r) => Some(r),
|
|
Err(e) => {
|
|
let reason = reason(&e);
|
|
log::warn!("Horizon: mod {} stopped: {reason}", run.store.data().id);
|
|
let name = run.store.data().name.clone();
|
|
self.out.push(Output::Stopped {
|
|
name,
|
|
reason: reason.clone(),
|
|
});
|
|
entry.status = Status::Failed(reason);
|
|
entry.run = None;
|
|
None
|
|
}
|
|
}
|
|
}
|
|
|
|
/// A game tick.
|
|
pub fn tick(&mut self, tick: u64) {
|
|
self.each(
|
|
FUEL_TICK,
|
|
|h| h.tick,
|
|
|m, s| m.horizon_mods_events().call_tick(s, tick),
|
|
);
|
|
}
|
|
/// A rendered frame, `seconds` after the last.
|
|
pub fn frame(&mut self, seconds: f32) {
|
|
self.each(
|
|
FUEL_FRAME,
|
|
|h| h.frame,
|
|
|m, s| m.horizon_mods_events().call_frame(s, seconds),
|
|
);
|
|
}
|
|
/// A chat line the player received, as plain text.
|
|
pub fn chat(&mut self, text: &str) {
|
|
self.each(
|
|
FUEL_EVENT,
|
|
|h| h.chat,
|
|
|m, s| m.horizon_mods_events().call_chat(s, text),
|
|
);
|
|
}
|
|
/// Whether a running mod owns `/name`.
|
|
pub fn has_command(&self, name: &str) -> bool {
|
|
self.command_owner(name).is_some()
|
|
}
|
|
fn command_owner(&self, name: &str) -> Option<usize> {
|
|
self.entries.iter().position(|e| {
|
|
e.run
|
|
.as_ref()
|
|
.is_some_and(|r| r.hooks.commands.iter().any(|c| c == name))
|
|
})
|
|
}
|
|
/// Runs `line` (without its slash) if a mod owns its command; false
|
|
/// when none does.
|
|
pub fn command(&mut self, line: &str) -> bool {
|
|
let (name, args) = line.split_once(' ').unwrap_or((line, ""));
|
|
let Some(i) = self.command_owner(name) else {
|
|
return false;
|
|
};
|
|
let result = self.call(i, FUEL_EVENT, |m, s| {
|
|
m.horizon_mods_events().call_command(s, name, args)
|
|
});
|
|
match result {
|
|
Some(Ok(Some(text))) => self.out.push(Output::Feedback { text, error: false }),
|
|
Some(Err(text)) => self.out.push(Output::Feedback { text, error: true }),
|
|
Some(Ok(None)) | None => {}
|
|
}
|
|
true
|
|
}
|
|
/// The commands running mods own, for suggestions.
|
|
pub fn commands(&self) -> impl Iterator<Item = &str> {
|
|
self.entries
|
|
.iter()
|
|
.filter_map(|e| e.run.as_ref())
|
|
.flat_map(|r| r.hooks.commands.iter().map(String::as_str))
|
|
}
|
|
|
|
/// The running mods' HUD panels.
|
|
pub fn panels(&self) -> impl Iterator<Item = &Panel> {
|
|
self.entries
|
|
.iter()
|
|
.filter_map(|e| e.run.as_ref()?.store.data().panel.as_ref())
|
|
}
|
|
/// What mods asked to show since the last call.
|
|
pub fn drain(&mut self) -> Vec<Output> {
|
|
std::mem::take(&mut self.out)
|
|
}
|
|
|
|
/// Restarts the mods whose file changed since they loaded (mod
|
|
/// development: rebuild, and the game picks it up). True when any did.
|
|
pub fn reload_changed(&mut self, reserved: impl Fn(&str) -> bool) -> bool {
|
|
let mut any = false;
|
|
for i in 0..self.entries.len() {
|
|
let entry = &self.entries[i];
|
|
let now = modified(&entry.path);
|
|
let was_on = entry.status != Status::Off;
|
|
if now == entry.modified || !was_on {
|
|
continue;
|
|
}
|
|
any = true;
|
|
self.entries[i].modified = now;
|
|
self.entries[i].run = None;
|
|
let path = self.entries[i].path.clone();
|
|
let started = Package::read(&path).and_then(|p| {
|
|
self.entries[i].manifest = Some(p.manifest.clone());
|
|
self.start(&path, &p, &reserved)
|
|
});
|
|
let entry = &mut self.entries[i];
|
|
let id = entry.manifest.as_ref().map_or("?", |m| m.id.as_str());
|
|
match started {
|
|
Ok(run) => {
|
|
log::info!("Horizon: mod {id} reloaded");
|
|
entry.run = run;
|
|
entry.status = Status::Running;
|
|
}
|
|
Err(e) => {
|
|
log::warn!("Horizon: mod {id} did not reload: {e}");
|
|
entry.status = Status::Failed(e);
|
|
}
|
|
}
|
|
}
|
|
any
|
|
}
|
|
}
|
|
|
|
fn modified(path: &Path) -> Option<SystemTime> {
|
|
let meta = std::fs::metadata(path).ok()?;
|
|
if meta.is_dir() {
|
|
// A folder mod changes when its component does.
|
|
return std::fs::metadata(path.join(crate::manifest::WASM))
|
|
.ok()?
|
|
.modified()
|
|
.ok();
|
|
}
|
|
meta.modified().ok()
|
|
}
|
|
|
|
/// A trap or error, as the player reads it.
|
|
fn reason(e: &wasmtime::Error) -> String {
|
|
match e.downcast_ref::<Trap>() {
|
|
Some(Trap::OutOfFuel) => "it took too long (an endless loop?)".into(),
|
|
Some(Trap::UnreachableCodeReached) => "it crashed (a panic)".into(),
|
|
Some(trap) => format!("it crashed: {trap}"),
|
|
None => format!("{e:#}"),
|
|
}
|
|
}
|
|
|
|
fn clip(text: String) -> String {
|
|
match text.char_indices().nth(LINE_CHARS) {
|
|
Some((at, _)) => text[..at].to_string(),
|
|
None => text,
|
|
}
|
|
}
|
|
|
|
impl mod_log::Host for State {
|
|
fn write(&mut self, level: mod_log::Level, message: String) {
|
|
let level = match level {
|
|
mod_log::Level::Debug => log::Level::Debug,
|
|
mod_log::Level::Info => log::Level::Info,
|
|
mod_log::Level::Warn => log::Level::Warn,
|
|
mod_log::Level::Error => log::Level::Error,
|
|
};
|
|
log::log!(level, "[mod {}] {}", self.id, clip(message));
|
|
}
|
|
}
|
|
impl game::Host for State {
|
|
fn get_player(&mut self) -> Option<Player> {
|
|
self.snapshot.player.clone()
|
|
}
|
|
fn get_clock(&mut self) -> Option<Clock> {
|
|
self.snapshot.clock
|
|
}
|
|
}
|
|
impl chat::Host for State {
|
|
fn show(&mut self, text: String) {
|
|
let shown = self
|
|
.out
|
|
.iter()
|
|
.filter(|o| matches!(o, Output::Chat { .. }))
|
|
.count();
|
|
if shown < CHAT_PER_CALL {
|
|
let name = self.name.clone();
|
|
self.out.push(Output::Chat {
|
|
name,
|
|
text: clip(text),
|
|
});
|
|
}
|
|
}
|
|
}
|
|
impl command::Host for State {
|
|
fn run(&mut self, line: String) {
|
|
let queued = self
|
|
.out
|
|
.iter()
|
|
.filter(|o| matches!(o, Output::Command { .. }))
|
|
.count();
|
|
if queued < CHAT_PER_CALL {
|
|
self.out.push(Output::Command { line: clip(line) });
|
|
}
|
|
}
|
|
}
|
|
impl hud::Host for State {
|
|
fn set_panel(&mut self, corner: Corner, lines: Vec<Line>) {
|
|
let lines = lines
|
|
.into_iter()
|
|
.take(HUD_LINES)
|
|
.map(|l| Line {
|
|
text: clip(l.text),
|
|
color: l.color & 0xFF_FFFF,
|
|
})
|
|
.collect();
|
|
self.panel = Some(Panel { corner, lines });
|
|
}
|
|
fn clear(&mut self) {
|
|
self.panel = None;
|
|
}
|
|
}
|
|
impl storage::Host for State {
|
|
fn get(&mut self, key: String) -> Option<Vec<u8>> {
|
|
storage_key_ok(&key)
|
|
.then(|| std::fs::read(self.data_dir.join(&key)).ok())
|
|
.flatten()
|
|
}
|
|
fn set(&mut self, key: String, value: Vec<u8>) -> Result<(), String> {
|
|
if !storage_key_ok(&key) {
|
|
return Err(format!("{key:?} is not [a-z0-9_.-]{{1,64}}"));
|
|
}
|
|
let len = value.len() as u64;
|
|
if len > self.storage_budget {
|
|
return Err("too much storage traffic in one call".into());
|
|
}
|
|
// Everything already on disk but the file this call replaces.
|
|
let existing: Vec<std::fs::DirEntry> = std::fs::read_dir(&self.data_dir)
|
|
.into_iter()
|
|
.flatten()
|
|
.flatten()
|
|
.filter(|e| e.file_name().to_string_lossy() != key)
|
|
.collect();
|
|
if existing.len() >= STORAGE_MAX_KEYS {
|
|
return Err(format!("would hold over {STORAGE_MAX_KEYS} keys"));
|
|
}
|
|
let used: u64 = existing
|
|
.iter()
|
|
.filter_map(|e| e.metadata().ok())
|
|
.map(|m| m.len())
|
|
.sum();
|
|
if used + len > STORAGE_QUOTA {
|
|
return Err(format!(
|
|
"would use over {} MiB of storage",
|
|
STORAGE_QUOTA >> 20
|
|
));
|
|
}
|
|
std::fs::create_dir_all(&self.data_dir).map_err(|e| e.to_string())?;
|
|
std::fs::write(self.data_dir.join(&key), value).map_err(|e| e.to_string())?;
|
|
self.storage_budget -= len;
|
|
Ok(())
|
|
}
|
|
fn delete(&mut self, key: String) {
|
|
if storage_key_ok(&key) {
|
|
let _ = std::fs::remove_file(self.data_dir.join(&key));
|
|
}
|
|
}
|
|
}
|
|
|
|
/// A storage key: one path segment of `[a-z0-9_.-]{1,64}`, not `.` or `..`.
|
|
/// No `/`, so a key can never leave the mod's own directory.
|
|
fn storage_key_ok(key: &str) -> bool {
|
|
let chars_ok = (1..=64).contains(&key.len())
|
|
&& key
|
|
.bytes()
|
|
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"_.-".contains(&b));
|
|
chars_ok && key != "." && key != ".."
|
|
}
|