WebAssembly

Rust mods

Build a Zeus mod in Rust with the zeus crate, compile it to WebAssembly and package it.

विज्ञापन

This page builds a small mod in Rust. It draws your name on the HUD and says welcome back when you join a world.

What you need

  • Rust, installed with rustup
  • The WebAssembly target: rustup target add wasm32-unknown-unknown
  • The zeus crate from the Zeus SDK

Set up the project

Make a library crate and tell Cargo to build a cdylib, which is the kind of library WebAssembly needs.

Cargo.toml:

[package]
name = "hello_hud"
version = "1.0.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
zeus = { path = "path/to/zeus/sdk/rust" }

[profile.release]
opt-level = "s"
lto = true
panic = "abort"
strip = true
codegen-units = 1

The release profile keeps the .wasm file small. panic = "abort" matters most: it stops a panic from pulling in a lot of extra code.

Write the mod

src/lib.rs:

use zeus::{chat, events, hud, player, Args, Ctx};

zeus::main!(start);

fn start() -> zeus::Result<()> {
    hud::add("hello", |ctx: Ctx, _partial: f64| -> zeus::Result<()> {
        ctx.text(&format!("Hello, {}", player::name()?), 4.0, 4.0, "#55FF55")?;
        Ok(())
    })?;
    events::on("world_join", |_: Args| chat::print("Welcome back!"))?;
    Ok(())
}

zeus::main!(start) tells Zeus which function to run when the mod loads. Think of start as your main.lua: register everything there. If start returns an error, the mod fails to load and the Mods menu shows the error.

Build it

cargo build --release --target wasm32-unknown-unknown
cp target/wasm32-unknown-unknown/release/hello_hud.wasm mod.wasm
zip hello_hud.zip metadata.json mod.wasm

metadata.json is the one from WebAssembly mods, with "main": "mod.wasm". Drop the zip onto the game to install it.

How the SDK works

Every call returns a Result. Anything that talks to the game can fail, so the API functions return zeus::Result, and ? works everywhere. The few exceptions, like settings::bool and storage::get_f64, return a plain value with a default.

Callbacks can return almost anything. A callback can return (), a bool, a number, a String, a Value, a Vec<Value> or a Result of any of those. If it returns an Err, the error goes to your mod's Log, the same as an error in a Lua function.

Arguments are counted from 0. A callback that takes Args reads them with args.str(0), args.num(1), args.int(2), args.bool(3) or args.get(0). Each one gives a default (like "" or 0) when the argument is missing.

A panic stops the mod. The Mods menu shows the panic message so you can see what went wrong.

Printing is different. On this target, println! goes nowhere. Use zeus::log, zeus::warn and zeus::error to write to your mod's Log.

A callback cannot call itself. If an event handler emits the event it listens to, the second call fails with an error instead of looping forever.

The typed API

These modules have typed functions for the most common parts of the API:

ModuleWhat is in it
chatprint, send, command
eventson, once, emit
hudadd, hide, show
playerexists, name, pos, block_pos, velocity, yaw, pitch, health, facing, biome and more
gameversion, fps, width, height, in_world, is_paused, screen
worldtime, day, time_of_day, weather, block, light
commandsregister(name, description, callback)
settingstoggle, slider, choice, color, text, key, button, get, set, on_change
storageget, set, save
timerafter, every, time, ticks
keysbind, is_down
soundplay
utilhsv, rgb, format_time
uinotify, screen, open
modsexport, get

Ctx has the drawing methods (text, rect, fill, line, circle, item and the rest), and Screen builds menus. Note that commands::register takes the description before the callback, the other way around from Lua.

Everything else

For any part of the API without a typed function, call it by its name:

let point = zeus::call("camera.project", (x, y, z))?;
let gl = zeus::object("gl")?;
let held = zeus::call1("player.heldItem", ())?;
let table = zeus::map! { "name" => "Steve", "level" => 5 };
  • zeus::call takes the function's path as a string literal and the arguments as a tuple. One argument still needs a tuple: (x,).
  • zeus::object gives you a handle (Obj) to a game table, with get, set, call and invoke.
  • zeus::map! builds a table to pass to the game.

Handles you get back only last until your current callback returns. To keep one longer (for example, the handle from events::on or timer::every, so you can remove or cancel it later), call .keep() on it.

A bigger example

The Zeus team's Session Stats mod is written this way. It shows play time, distance, speed and jumps in a HUD panel, has four settings and a keybind, adds a /stats-rust command and keeps lifetime totals in storage. It shares its state between callbacks with Rc<RefCell<...>>, which is the usual way to do it in a Rust mod.