Build a mod

Packaging

Turn a single Lua file into a full mod package with metadata, an icon, more files, dependencies and permissions.

광고

A mod can be one .lua file or a .zip package. One file is perfect for small mods. When your mod grows (more files, images, an icon, other mods it needs), switch to a package.

Either way, Zeus stores every mod as a package. When you import a single .lua file, it builds the package for you: your code becomes main.lua, and a metadata.json is made from the comments at the top.

One file

A single .lua file describes itself with comment lines at the very top.

-- name: Cool HUD
-- id: coolhud
-- version: 1.2.0
-- author: you
-- description: Shows FPS, coordinates and more.
-- permissions: network

hud.add(function(ctx) end)
LineWhat it sets
namethe name players see
idthe mod's id. Made from the name if you leave it out
versionyour version, 1.0.0 if you leave it out
authorwho made it. Separate several names with commas
descriptiona line or two about the mod
permissionsextra powers it needs, separated by commas or spaces

Zeus only reads these lines when the mod is imported. Changing them later in the game's editor does nothing, because the mod already has a metadata.json. To rename a mod after that, click the File: button in the editor to switch to metadata.json and change it there.

Always give a single file mod a name. Without one it is called Untitled Mod, and the next unnamed mod you import replaces it.

A package

A package is a .zip, a lot like a browser extension.

my-mod.zip
├── metadata.json
├── icon.png          (optional, shown in the Mods menu)
├── main.lua          (the code that runs first)
├── lib/helpers.lua   (load it with require("lib.helpers"))
└── assets/logo.png   (load it with textures.load("assets/logo.png"))

You can also zip the whole folder. Zeus looks for the metadata.json closest to the top of the zip and treats its folder as the mod. Files outside that folder are left out.

metadata.json

{
  "id": "coolhud",
  "name": "Cool HUD",
  "version": "1.2.0",
  "description": "Shows FPS, coordinates and more.",
  "authors": ["you"],
  "icon": "icon.png",
  "main": "main.lua",
  "api": 1,
  "minecraft": ["26.2", "26.3"],
  "dependencies": { "other_mod_id": "*" },
  "permissions": ["network"]
}
FieldDefaultWhat it is
idmade from namethe mod's unique id
namethe idthe name players see
version"1.0.0"your version. Zeus shows it but never compares versions
descriptiona line or two about the mod
authorsa list of names
icon"icon.png"a PNG in the zip, at the exact path you give
main"main.lua"the file that runs first. A .wasm file makes it a WebAssembly mod
api1the Zeus API version your mod was written for
minecraftanythe game versions your mod supports
dependenciesnoneother mods yours needs
permissionsnoneextra powers your mod needs
homepage, licensekept with the mod for anyone reading it

You need an id or a name. Zeus fills in the other one.

Ids

An id is up to 64 characters of lowercase letters, numbers, _, - and ., like coolhud or cool-hud. It cannot start with a . or end with a _. Pick it once and keep it: the id is how Zeus knows a new version is an update, and it is what other mods use to find yours.

Game versions

Each entry in minecraft is an exact version like "26.3", a prefix like "26.*", or "*" for any version. If the player's version is not on the list, the install prompt warns them, but the mod still loads.

Icons

The icon is drawn at 40 by 40 pixels in the mod's details and smaller in the list. A square PNG of 64 by 64 looks good. If it is missing or is not a valid PNG, the Mods menu shows the first letter of the mod's name instead.

Limits

A package can have up to 4,096 files and 64 MB of files, unpacked.

More files

Split your code into files and load them with require. Use dots instead of slashes, and leave off .lua.

lib/helpers.lua:

local helpers = {}

function helpers.round(n)
  return math.floor(n + 0.5)
end

return helpers

main.lua:

local helpers = require("lib.helpers")

hud.add(function(ctx)
  if not player.exists() then return end
  ctx:text("X: " .. helpers.round(player.x()), 4, 4, "white")
end)

require("lib.helpers") looks for lib/helpers.lua, then lib/helpers/init.lua. Each file only runs once. Every require after the first gets the same table back.

Images load with textures.load (see Drawing), and any other file can be read with mod.read (see Settings and storage).

Permissions

Some parts of the API could be misused, so a mod has to ask for them. The install prompt shows players what a mod asks for before they install it.

PermissionWhat it unlocks
networkhttp.get, to download things from the internet
clipboardclipboard.get, to read what the player copied

Without the permission, those functions throw an error that says which permission is missing. Copying to the clipboard with clipboard.set needs no permission.

If your mod draws with WebGL, list gl too, so players know. The prompt shows it as "draw with raw WebGL".

Dependencies

If your mod needs another mod, list its id under dependencies. Zeus loads that mod first, so anything it exports is ready when your code runs. You can write them as an object, like { "other_mod_id": "*" }, or a plain list, like ["other_mod_id"]. Zeus does not check versions, so the value after the id does not matter.

If a dependency is missing, turned off or broken, your mod does not load, and its Log says which mod it needs. After you install or turn on the missing mod, click Reload on yours. Turning off or reloading a mod does the same to every mod that depends on it.

Never make two mods depend on each other.

Share code with other mods

A mod can give other mods functions and data. Put them in mod.export.

mod.export = {
  version = 2,
  greet = function(name)
    return "Hello, " .. name
  end,
}

Another mod reads them with mods.get and the first mod's id.

local cool = mods.get("coolhud")
if cool then
  chat.print(cool.greet("Steve"))
end

mods.get returns nil when that mod is not running, so always check. A few more functions describe the mods a player has:

FunctionWhat it gives you
mods.list()every installed mod, running or not, in the order of the Mods list
mods.info(id)one mod's id, name, version, enabled, active and runtime ("lua" or "wasm"), or nil
mods.has(id)true if that mod is installed and running

Your own mod's details are in mod.id, mod.name, mod.version, mod.description and mod.authors. mod.minecraft is the version of the game it is running in.

API versions

"api": 1 says your mod was written for version 1 of the Zeus API, which is the version today. Zeus keeps version 1 working on future game versions, so a mod you write now keeps working. A mod that asks for a newer API than the game has is refused with a message that says so.