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

ExportSignatureWhat it does
memorymemoryyour module's own memory. Imported memories are refused
zeus_init() -> ()called once after loading. Register everything here
zeus_alloc(size i32) -> i32returns 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) -> i32runs 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.

ImportSignatureWhat it does
get(obj, key, key_len) -> result_lenreads 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_lensets obj[key] = value. kv is two encoded values. Dotted paths work with obj 0
call(fn, args, args_len) -> result_lencalls a function. args is an encoded list
invoke(obj, name, name_len, args, args_len) -> result_lencalls a method, like obj:name(args...) in Lua
len(obj) -> result_lenthe length, like Lua's #
snapshot(obj) -> result_lena 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) -> handlekeeps 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.

TagValueFollowed by
0nilnothing
1, 2false, truenothing
3integeran i64
4floatan f64
5stringa u32 length, then the bytes
6handlea u32: a table, function or userdata from the game
7arraya u32 count, then the values (a table with keys 1 to n)
8mapa u32 count, then key and value pairs
9callbacka 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.

FunctionWhat it does
fd_writewrites stdout (fd 1) to the Log as info and stderr (fd 2) as errors, one line at a time
fd_readstdin (fd 0) is always empty
fd_fdstat_get, fd_filestat_getreport fds 0 to 2 as character devices
fd_seek, fd_close, fd_prestat_get, fd_prestat_dir_namereturn an error. There are no files or directories
args_sizes_get, args_getone argument: your mod's id
environ_sizes_get, environ_getan empty environment
clock_time_get, clock_res_getthe wall clock in milliseconds, and a clock since the game started
random_getrandom bytes, up to 1 MB per call. They are not safe for cryptography
poll_oneoffreturns right away, as if everything happened
sched_yielddoes nothing
proc_exitstops 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:

ErrorWhat 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 provideyou are using an import that is not in the tables above
WebAssembly threads (atomics) are not supportedbuild without threads
WebAssembly GC is not supportedyour language needs the GC proposal, which Zeus does not have yet
the WebAssembly module is ... KB; the limit is 8 MBmake the file smaller, for example with size optimizations