WebAssembly

Go mods

Build a Zeus mod in Go 1.24 or newer, compile it to WebAssembly and package it.

Advertisement

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

What you need

  • Go 1.24 or newer
  • The Zeus Go SDK, github.com/ruleyourowngame/zeus/sdk/go

Set up the project

Make a module that requires the SDK, and point a replace at your copy of it.

go.mod:

module hellohud

go 1.24

require github.com/ruleyourowngame/zeus/sdk/go v0.0.0

replace github.com/ruleyourowngame/zeus/sdk/go => ../path/to/zeus/sdk/go

Write the mod

main.go:

package main

import zeus "github.com/ruleyourowngame/zeus/sdk/go"

func init() {
	zeus.Main(start)
}

func main() {}

func start() {
	zeus.Hud.Add("hello", func(ctx zeus.Ctx, partialTick float64) {
		ctx.Text("Hello, "+zeus.Player.Name(), 4, 4, "#55FF55")
	})
	zeus.Events.On("world_join", func(zeus.Args) { zeus.Chat.Print("Welcome back!") })
}

Go mods start a little differently from normal Go programs. main never runs. Instead, you register your start function from init with zeus.Main, and Zeus calls it when the mod loads.

Build it

GOOS=wasip1 GOARCH=wasm go build -buildmode=c-shared -ldflags="-s -w" -o 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.

Go mods are bigger than Rust ones, around 2.5 MB for a small mod, because the Go runtime comes along. That is fine: the limit is 8 MB. It does mean you should share Go mods as a zip, not as a share code.

How the SDK works

The typed API panics when a call fails. zeus.Chat, zeus.Player, zeus.Settings and the rest keep your code short by panicking instead of returning errors. Inside a callback, the SDK catches the panic and reports it like an error in a Lua function, so your mod keeps running.

A panic in your start function is different. Nothing catches it, so the mod fails to load and the Mods menu shows the panic.

The low level calls return errors. zeus.Call, Obj.Get, Obj.Set, Obj.Call and Obj.Invoke return an error instead of panicking. Use them for anything the typed API does not cover, like zeus.Call("camera.project", x, y, z).

Printing goes to your mod's Log. fmt.Println writes normal lines. Anything written to os.Stderr, or with the println builtin, shows up as an error.

Never block. time.Sleep, or waiting on a channel that nothing fills during the same call, cannot work, because the game waits for your call to finish. Use zeus.Timer.After and zeus.Timer.Every to do things later.

Some Go types cannot be sent to the game. Numbers, strings, booleans, []any, []string, []int, []float64, map[string]any, map[string]string and the SDK's own types all work. Other types, like structs or []bool, give an error. Turn them into a map[string]any first.

The typed API

ObjectWhat is in it
zeus.ChatPrint, Send, Command
zeus.EventsOn, Once, Emit
zeus.HudAdd, Hide, Show
zeus.PlayerExists, Name, Pos, BlockPos, Velocity, Yaw, Pitch, Health, Facing, Biome and more
zeus.GameVersion, FPS, Width, Height, InWorld, IsPaused
zeus.WorldTime, Day, TimeOfDay, Weather, Block, Light
zeus.CommandsRegister(name, description, callback)
zeus.SettingsToggle, Slider, Choice, Color, Text, Key, Button, Get, Set, OnChange
zeus.StorageGet, Int, Num, Set, Save
zeus.TimerAfter, Every, Time, Ticks
zeus.KeysBind, IsDown
zeus.SoundPlay
zeus.UtilHSV, RGB, FormatTime
zeus.UINotify, Screen, Open
zeus.ModsExport, Get

zeus.Ctx has the drawing methods (Text, Rect, Fill, Line, Circle, Item and the rest), and zeus.Screen builds menus. Like in Rust, Commands.Register takes the description before the callback.

Handles you get back from the game, like the ones from Events.On and the timers, only last until your current callback returns. Call .Keep() on one if you want to remove or cancel it later.