WebAssembly
The ABI
The low level interface between the game and a WebAssembly mod, for anyone writing a mod or bindings in a new language.
The Rust and Go SDKs are built on a small interface (an ABI) between the game and your .wasm file. You only need this page if you are writing a mod in another language, or writing your own bindings. Everything here is what the SDKs do for you.
Two rules hold everywhere. All pointers are offsets into your mod's own memory, and all numbers are little endian.
What your module exports
| Export | Signature | What it does |
|---|---|---|
memory | memory | your module's own memory. Imported memories are refused |
zeus_init | () -> () | called once after loading. Register everything here |
zeus_alloc | (size i32) -> i32 | returns size bytes the game can write to. The game writes callback arguments there, and your mod frees them |
zeus_invoke | (callback i32, args i32, args_len i32) -> i32 | runs one of your callbacks. Return 0 for success. Anything else is an error, whose message you passed to ret. Only needed if your mod passes callbacks |
_initialize | () -> () | optional, called before zeus_init (for WASI reactors such as Go) |
When your mod loads, Zeus runs its WebAssembly start function if it has one, then _initialize, then zeus_init. Export names starting with __zeus_ are reserved.
What the game gives you
These are imported from the module zeus.
| Import | Signature | What it does |
|---|---|---|
get | (obj, key, key_len) -> result_len | reads obj[key]. key is one encoded value. obj 0 is your mod's global table, where a string key can be a dotted path like "player.pos" |
set | (obj, kv, kv_len) -> result_len | sets obj[key] = value. kv is two encoded values. Dotted paths work with obj 0 |
call | (fn, args, args_len) -> result_len | calls a function. args is an encoded list |
invoke | (obj, name, name_len, args, args_len) -> result_len | calls a method, like obj:name(args...) in Lua |
len | (obj) -> result_len | the length, like Lua's # |
snapshot | (obj) -> result_len | a deep copy of a table as arrays and maps |
result | (dst) -> () | copies the result of the last call above (result_len bytes) to dst |
keep | (handle) -> handle | keeps a handle alive after the current callback returns. Returns 0 for a handle that is not valid |
release | (handle) -> () | frees a handle |
ret | (values, len) -> () | sets the return values (an encoded list) of the running zeus_invoke |
log | (level, text, len) -> () | writes to the mod's Log: 0 info, 1 warning, 2 error, 3 a panic message, which is shown when the mod stops |
Results
Every call that returns result_len leaves a result waiting. Call result to copy it into your memory. A result is one status byte, 0 for success or 1 for an error, then an encoded list. On success the list holds the return values. On an error it holds one string, the error message.
Values
Every value starts with a tag byte.
| Tag | Value | Followed by |
|---|---|---|
| 0 | nil | nothing |
| 1, 2 | false, true | nothing |
| 3 | integer | an i64 |
| 4 | float | an f64 |
| 5 | string | a u32 length, then the bytes |
| 6 | handle | a u32: a table, function or userdata from the game |
| 7 | array | a u32 count, then the values (a table with keys 1 to n) |
| 8 | map | a u32 count, then key and value pairs |
| 9 | callback | a u32 id that your mod picks |
A list is a u32 count followed by that many values. Strings are raw bytes, usually but not always UTF-8.
snapshot turns a table into arrays and maps. A table becomes an array only when its keys are exactly 1 to n, and an empty table comes back as an empty array. Values nested more than 64 deep stay handles.
Handles
Tables, functions and userdata from the game always arrive as handles. A handle stays valid until the zeus_init or zeus_invoke that received it returns. If you need it for longer, pass it to keep, and it lives until you release it or your mod unloads. A mod can hold up to 1,000,000 handles at once.
Callbacks
To give the game a function (an event handler, a button's onClick), send a value with tag 9 and any id you like. When the game calls it, Zeus calls your zeus_invoke with that id and the encoded arguments.
The game can call back into your mod while one of your own calls is still running, for example during events.emit or ui.open, so your bindings have to be re-entrant. Calls can nest up to 64 deep.
WASI
Zeus provides the parts of WASI that language runtimes need to start up and print. Both wasi_snapshot_preview1 and wasi_unstable work.
| Function | What it does |
|---|---|
fd_write | writes stdout (fd 1) to the Log as info and stderr (fd 2) as errors, one line at a time |
fd_read | stdin (fd 0) is always empty |
fd_fdstat_get, fd_filestat_get | report fds 0 to 2 as character devices |
fd_seek, fd_close, fd_prestat_get, fd_prestat_dir_name | return an error. There are no files or directories |
args_sizes_get, args_get | one argument: your mod's id |
environ_sizes_get, environ_get | an empty environment |
clock_time_get, clock_res_get | the wall clock in milliseconds, and a clock since the game started |
random_get | random bytes, up to 1 MB per call. They are not safe for cryptography |
poll_oneoff | returns right away, as if everything happened |
sched_yield | does nothing |
proc_exit | stops the mod |
Any other WASI function returns ENOSYS (or does nothing, if it returns nothing).
Load errors
Zeus checks your module before it runs it. These are the most common errors, and what they mean:
| Error | What to fix |
|---|---|
| the module must define and export its memory as "memory" | export your memory instead of importing it |
| the module must export a function "zeus_init" | add zeus_init, with no arguments and no results |
| the module imports ..., which Zeus does not provide | you are using an import that is not in the tables above |
| WebAssembly threads (atomics) are not supported | build without threads |
| WebAssembly GC is not supported | your language needs the GC proposal, which Zeus does not have yet |
| the WebAssembly module is ... KB; the limit is 8 MB | make the file smaller, for example with size optimizations |



