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.
The Rust SDK is not public yet. This page shows how it works so you can plan ahead, and the ABI page has everything you need to talk to the game without it.
What you need
- Rust, installed with rustup
- The WebAssembly target:
rustup target add wasm32-unknown-unknown - The
zeuscrate 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:
| Module | What is in it |
|---|---|
chat | print, send, command |
events | on, once, emit |
hud | add, hide, show |
player | exists, name, pos, block_pos, velocity, yaw, pitch, health, facing, biome and more |
game | version, fps, width, height, in_world, is_paused, screen |
world | time, day, time_of_day, weather, block, light |
commands | register(name, description, callback) |
settings | toggle, slider, choice, color, text, key, button, get, set, on_change |
storage | get, set, save |
timer | after, every, time, ticks |
keys | bind, is_down |
sound | play |
util | hsv, rgb, format_time |
ui | notify, screen, open |
mods | export, 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::calltakes the function's path as a string literal and the arguments as a tuple. One argument still needs a tuple:(x,).zeus::objectgives you a handle (Obj) to a game table, withget,set,callandinvoke.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.



