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)
| Line | What it sets |
|---|---|
name | the name players see |
id | the mod's id. Made from the name if you leave it out |
version | your version, 1.0.0 if you leave it out |
author | who made it. Separate several names with commas |
description | a line or two about the mod |
permissions | extra 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"]
}
| Field | Default | What it is |
|---|---|---|
id | made from name | the mod's unique id |
name | the id | the name players see |
version | "1.0.0" | your version. Zeus shows it but never compares versions |
description | a line or two about the mod | |
authors | a 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 |
api | 1 | the Zeus API version your mod was written for |
minecraft | any | the game versions your mod supports |
dependencies | none | other mods yours needs |
permissions | none | extra powers your mod needs |
homepage, license | kept 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.
| Permission | What it unlocks |
|---|---|
network | http.get, to download things from the internet |
clipboard | clipboard.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:
| Function | What 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.



