Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Your first WebAssembly mod

A WebAssembly mod is the same Rust you write for a native mod, built to mod.wasm instead. The game runs it in a sandbox, with limits on time and memory, so a player needs no compiler and no trust prompt for native code. In this page you build the greeter from Your first native mod as a WebAssembly mod.

You need cargo horizon-mod (installed as in the content mod tutorial) and rustup: the first build installs the pinned Rust toolchain with rust-src.

1. Start from the native project

Make the project from the wasm template. It is the native project without the [native] table: a mod carries native code or WebAssembly, never both, and the build writes its own [wasm] table. The SDK build the mod is made for is pinned in Cargo.toml instead, under [package.metadata.horizon] sdk (the pin).

cargo horizon-mod new greeter --template wasm
cd greeter

Keep the code in src/lib.rs as it is:

use mod_api::{self, Hooks, PlayerLoggedInEvent, ServerHost, Text};

#[derive(Default)]
struct Mod;

#[mod_api::horizon_mod]
impl Hooks for Mod {
    /// A player joined the server: greet them.
    fn player_logged_in(&self, host: &mut dyn ServerHost, event: &mut PlayerLoggedInEvent<'_>) {
        let line = format!("greeter says hello, {}!", event.name);
        if let Some(player) = host.player(event.player) {
            let _ = player.tell(host, Text::literal(line));
        }
    }
}

2. Build

cargo horizon-mod build --wasm

The tool compiles the crate with the pinned toolchain, writes mod.wasm beside horizon-mod.toml, records it in a [wasm] table, and packs target/horizon-mod/greeter.hmod:

[wasm]
sha512 = "…"                    # mod.wasm's hash, checked when the game loads it
toolchain = "<version> <commit>" # every mod linked together is built by the same one

Never write [wasm] by hand; rebuild instead.

3. Play

Copy greeter.hmod into the game folder's horizon-mods/ (in the launcher: Open folder in the instance's ⋮ menu), and turn it on with a line mod.greeter:true in horizon-mods.txt beside options.txt. The game loads it at start-up; join a world and the greeting appears. If the game refuses the mod (a wrong layout, a missing dependency, a limit), the Mods screen shows why in red.

What differs from native

Hooks, Parts, attachments, [dependencies] and the manifest mean the same on both targets. A WebAssembly mod cannot use the native route ([native.*] tables), and an API item marked Not on wasm in the API reference is unavailable to it. Values cross between the game and mod.wasm in one shared encoding; your own types cross when they derive Wire.

WebAssembly mods covers dependencies, memory, limits and the module cache.