WebAssembly

WebAssembly mods

Write mods in Rust, Go, C, Zig or any other language that compiles to WebAssembly, with the same API as Lua.

Advertisement

Lua is the easy way in, but it is not the only option. A mod can be written in any language that compiles to WebAssembly (a fast, portable format that browsers run natively). Rust, Go, C, C++, Zig, AssemblyScript and TinyGo all work.

A WebAssembly mod uses the same API as a Lua mod. It listens to the same events, draws with the same ctx, has the same settings and storage, and is installed, shared and paused the same way. Lua mods and WebAssembly mods can even call each other through mod.export.

When to pick WebAssembly

Pick WebAssembly when you already know Rust or Go and would rather use it, when you have heavy math to do every frame, or when you want to reuse code you already have. In the browser, WebAssembly mods run on the browser's own WebAssembly engine, so they are fast.

Stick with Lua for most mods. You can write Lua in the game's editor and see your change right away, while a WebAssembly mod has to be compiled on your computer first.

What a WebAssembly mod looks like

It is a normal mod zip, except main in metadata.json points at a .wasm file.

my-mod.zip
├── metadata.json
├── icon.png
└── mod.wasm
{
  "id": "hello_hud",
  "name": "Hello HUD",
  "version": "1.0.0",
  "main": "mod.wasm",
  "minecraft": ["26.2", "26.3"]
}

A .wasm file on its own cannot be installed. It always needs the metadata.json next to it, in a zip.

Everything on Packaging still applies: ids, dependencies, permissions and Export .zip all work the same, and mod.read can read any other file in the zip. Two things are different:

  • Edit code in the Mods menu can only change metadata.json and the text files in your zip, not the compiled code.
  • Share codes get long fast. A small Rust mod fits, but a Go mod is usually millions of characters, far more than the 200,000 the paste box takes. Share the zip instead.

The SDKs

Zeus has bindings for two languages that do the low level work for you:

  • Rust, with typed functions that return Result, so ? works everywhere
  • Go, with typed objects like zeus.Chat and zeus.Player

The Rust and Go SDKs are not public yet. Until they are, you can still write a WebAssembly mod in any language by talking to the game directly, the way the SDKs do. The ABI page describes exactly how.

Limits

WebAssembly mods have to play nice with the game, so they get a budget. Zeus counts the work your code does (close to one unit per instruction) and stops a mod that runs out.

LimitValue
size of the .wasm file8 MB
memory256 MB
work per call (an event, a timer, a command)200 million instructions
work while loading2 billion instructions

The size limit is checked when the mod loads, not when you install it, so a mod that is too big installs and then shows an error.

A mod that runs out of budget, panics, hits unreachable or a bad memory access, calls exit or runs out of memory is stopped and marked with an error in the Mods menu. The error says which one it was, like "took too long (ran out of fuel)" or "ran out of memory (mods can use up to 256 MB)". The game keeps running.

What works and what does not

Supported: WebAssembly 1.0 with multi-value, bulk memory, reference types, sign extension, non-trapping float to int conversions and tail calls.

Not supported: threads, exception handling, 64-bit memories, multiple memories and the garbage collection proposal. That means Kotlin and other languages that need WebAssembly GC do not work yet. SIMD works in the browser but not in the desktop client.

WASI (the standard system interface) is limited to what a mod needs: printing to your mod's Log, clocks and random numbers. There are no files or sockets. Use the Zeus API instead: storage to save data, mod.read to read files in your zip and http.get for the network.

async and wait are Lua features, so they do not exist here. Use timer.after to do something later.