Reference
API reference
Every library and function in the Zeus mod API on one page, with what each one takes and what it gives back.
This page lists everything a mod can use. The guides explain how to put it together; this is the place to look something up.
Two things to know when reading it:
- "Gives back x, y, z" means the function returns several values at once. Catch them with
local x, y, z = player.pos(). It does not return a table. - "World only" means the function throws an error when there is no world, for example on the title screen. Check
player.exists()orworld.exists()first.
Jump to: events, timer, hud, ctx, ui, screens, game, player, camera, world, chat, commands, keys, mouse, sound, textures, settings, storage, mod, mods, json, util, clipboard, http, gl and matrix, Lua extras.
events
| Function | What it does |
|---|---|
on(name, fn, priority) | the same as events.on |
events.on(name, fn, priority) | calls fn every time the event happens. priority is a whole number, 0 by default, and higher runs first. Gives back a handle with :remove() |
events.once(name, fn, priority) | the same, but only for the next time |
events.off(handle) | stops a listener, the same as handle:remove() |
events.emit(name, ...) | sends your own event to every mod, including yours, and runs every listener right away |
Every event and what it gives you is listed in Events and timers. Cancel a cancellable event with e:cancel().
timer
| Function | What it does |
|---|---|
timer.after(seconds, fn) | runs fn once, later. Gives back a timer |
timer.every(seconds, fn) | runs fn over and over. seconds has to be more than 0. Gives back a timer |
t:cancel() | stops a timer |
t.active | true until a timer has finished or been cancelled |
timer.time() | the current time in seconds, with milliseconds |
timer.ticks() | the number of game ticks since the game started |
async(fn, ...) | runs fn as a task that can wait. Lua only |
wait(seconds) | inside async, waits that many seconds |
waitTicks(n) | inside async, waits n game ticks. n has to be a whole number |
hud
| Function | What it does |
|---|---|
hud.add(name, fn, options) | draws fn(ctx, partialTick) every frame. name and options are optional. options can be { before = id } or { after = id } |
hud.removeLayer(name) | removes your panels with that name. Gives back true if it removed any |
hud.before(id, fn), hud.after(id, fn) | draws fn right before or after one part of the HUD |
hud.hide(id) | hides one part of the HUD. hud.remove is the same |
hud.show(id) | undoes your mod's hide and replace for that part. hud.restore is the same |
hud.replace(id, fn) | draws fn(ctx, partialTick, drawOriginal) instead of that part |
hud.isHidden(id) | true if any mod hides that part |
hud.elements() | a list of every part's name |
The part names are listed in The HUD.
ctx
The drawing context. Positions are in GUI pixels. Colors left out are white.
| Method | What it does |
|---|---|
ctx.width, ctx.height | the screen size in GUI pixels |
ctx:rect(x, y, w, h, color) | a filled box |
ctx:fill(x1, y1, x2, y2, color) | a filled box between two corners |
ctx:gradient(x1, y1, x2, y2, top, bottom) | a box that fades from top (white) to bottom (black) |
ctx:outline(x, y, w, h, color) | a 1 pixel border inside the box |
ctx:line(x1, y1, x2, y2, color, thickness) | a line. thickness is 1 by default |
ctx:circle(x, y, r, color, filled) | a circle, filled unless filled is false |
ctx:text(value, x, y, color, shadow) | text with a shadow unless shadow is false. Gives back the width |
ctx:centeredText(value, cx, y, color) | text centered on cx |
ctx:wrappedText(value, x, y, width, color) | text wrapped to width. Gives back the height |
ctx:textWidth(value) | the width of some text |
ctx:fontHeight() | the height of one line of text |
ctx:image(texture, x, y, w, h, u0, v0, u1, v1, tint) | an image from textures.load. Everything after y is optional |
ctx:item(id, x, y, scale) | an item icon. scale is 1 (16 pixels) by default |
ctx:tooltip(text, x, y) | a tooltip box. Only shows on screens |
ctx:clip(x1, y1, x2, y2, fn) | runs fn, cutting off anything drawn outside the box |
ctx:pushClip(x1, y1, x2, y2), ctx:popClip() | the same as clip, without a function |
ctx:push(), ctx:pop() | saves and restores the position, scale and rotation |
ctx:translate(x, y) | moves everything drawn after it |
ctx:scale(sx, sy) | scales everything drawn after it. sy is sx if you leave it out |
ctx:rotate(degrees) | rotates everything drawn after it |
Colors are explained in Drawing.
ui
| Function | What it does |
|---|---|
ui.screen(options) | makes a screen. Gives back the screen |
ui.open(screen) | shows a screen |
ui.close(screen) | closes that screen. With nothing, closes whichever mod screen is open |
ui.notify(title, message) | shows a popup. A new one replaces the old one |
The screen options, screen methods and every widget are in Screens and menus.
screens
The game's own screens.
| Function | What it does |
|---|---|
screens.current() | the open screen, or nil |
screens.close() | closes the open screen |
screens.openMods() | opens the Mods menu |
screens.addButton(screen, options) | the same as screen:button(options) |
A game screen has id, title, width, height and isOpen, and these methods: screen:widgets(), screen:find(text), screen:button(options) and screen:close(). See Screens and menus.
game
| Function | What it gives back |
|---|---|
game.version | the game version. A field, not a function |
game.fps() | frames per second |
game.width(), game.height() | the screen size in GUI pixels |
game.scale() | the GUI scale |
game.isPaused() | true while the game is paused |
game.inWorld() | true while you are in a world |
game.isSingleplayer() | true in a singleplayer world |
game.screen() | the id of the open screen, or nil |
game.option(name) | the value of a game option |
game.setOption(name, value) | changes a game option |
game.openChat(text) | opens the chat box with text already typed |
Options you can read and change:
| Option | Value |
|---|---|
fov | a whole number from 30 to 110 |
gamma (or brightness) | 0 to 1 |
renderDistance | a whole number of chunks, from 2 |
sensitivity | 0 to 1 |
guiScale | read only. 0 means auto |
viewBobbing | true or false |
fovEffects | 0 to 1 |
framerateLimit | 10 to 260 in steps of 10. 260 means unlimited |
chatOpacity | 0 to 1 |
subtitles | true or false |
masterVolume, musicVolume | 0 to 1 |
A value outside the range does not get clamped. The game resets the option to its default instead.
player
World only, except exists, gamemode and lookingAt.
| Function | What it gives back |
|---|---|
player.exists() | true if there is a player, in a world |
player.name() | your username |
player.uuid() | your UUID |
player.pos() | gives back x, y, z, the position of your feet |
player.x(), player.y(), player.z() | one part of the position |
player.blockPos() | gives back x, y, z of the block you stand in, as whole numbers |
player.eyePos() | gives back x, y, z of your eyes |
player.velocity() | gives back x, y, z, in blocks per tick |
player.setVelocity(x, y, z) | changes your velocity |
player.yaw(), player.pitch() | where you are looking, in degrees |
player.setRotation(yaw, pitch) | turns you |
player.facing() | "north", "south", "east" or "west" |
player.health(), player.maxHealth() | health, where 20 is ten hearts |
player.food(), player.saturation() | hunger |
player.armor() | armor points |
player.xpLevel(), player.xpProgress() | your level, and how far you are to the next one (0 to 1) |
player.isOnGround(), player.isSneaking(), player.isSprinting(), player.isSwimming(), player.isFlying() | true or false |
player.setSprinting(on) | starts or stops sprinting |
player.gamemode() | "survival", "creative", "adventure" or "spectator", or nil |
player.dimension() | like "minecraft:overworld" |
player.biome() | like "minecraft:plains", or nil |
player.heldItem(), player.offhandItem() | an item, or nil when your hand is empty |
player.selectedSlot() | the hotbar slot you have selected, from 1 to 9 |
player.selectSlot(n) | selects hotbar slot n, from 1 to 9 |
player.inventory() | a list of every item you have |
player.effects() | a list of your status effects |
player.jump() | jumps, if you are on the ground |
player.swing() | swings your hand |
player.lookingAt() | the block or entity you are looking at, or nil |
An item is a table with id (like "minecraft:diamond_sword"), count, name (the name shown in game), damage and maxDamage.
Items in player.inventory() also have a slot: 1 to 9 is the hotbar, 10 to 36 the rest of the inventory, 37 to 40 your armor (feet, legs, chest, head) and 41 your offhand. Empty slots are left out.
An effect is a table with id, amplifier (1 is level I) and duration (in ticks).
player.lookingAt() gives back one of these:
- a block:
{ type = "block", x, y, z, id, side }, wheresideis the face you are looking at, like"up"or"north" - an entity:
{ type = "entity", entity, name, uuid, x, y, z, isPlayer, health, maxHealth, distance }, whereentityis its type, like"minecraft:zombie"
camera
| Function | What it gives back |
|---|---|
camera.pos() | gives back x, y, z of the camera |
camera.yaw(), camera.pitch() | where the camera looks, in degrees |
camera.project(x, y, z) | gives back the screen position x, y (in GUI pixels) and a depth for a spot in the world, or nil if it is behind you |
world
World only, except exists.
| Function | What it gives back |
|---|---|
world.exists() | true in a world |
world.block(x, y, z) | the block id at a position, like "minecraft:stone" |
world.light(x, y, z) | the light level, 0 to 15 |
world.biome(x, y, z) | the biome id, or nil |
world.time() | the world clock, in ticks |
world.day() | which day it is |
world.timeOfDay() | the time within the day, 0 to 23999 |
world.weather() | "clear", "rain" or "thunder" |
world.players() | every player in the world, you included |
world.entities(radius) | entities near you, not including you. radius is 64 by default, and you get at most 512 |
An entity is a table with type, name, uuid, x, y, z, isPlayer and distance. Living things also have health and maxHealth.
chat
| Function | What it does |
|---|---|
chat.print(...) | shows a message only you can see. Joins everything with spaces |
chat.send(text) | sends a chat message. World only |
chat.command(command) | runs a game command. The slash is optional. World only |
commands
| Function | What it does |
|---|---|
commands.register(name, fn, description) | adds /name. fn gets args (a list of words) and raw (everything after the name) |
commands.unregister(name) | removes one of your commands |
commands.list() | every mod command, as tables with name, description and mod |
keys
| Function | What it does |
|---|---|
keys.bind(options) | adds a keybind. Options: id, label, default, description, onPress, onRelease, inScreens |
keys.isDown(name) | true while a keyboard key is held |
keys.code(name) | the key's number, or nil |
keys.name(code) | the key's name, or "unknown" |
Key names are listed in Commands and keys.
mouse
| Function | What it gives back |
|---|---|
mouse.x(), mouse.y() | where the mouse is, in GUI pixels |
mouse.isDown(button) | true while "left", "right" or "middle" is held |
sound
| Function | What it does |
|---|---|
sound.play(id, volume, pitch) | plays a game sound, like "entity.experience_orb.pickup". Volume and pitch are 1 by default |
textures
| Function | What it does |
|---|---|
textures.load(path) | loads a PNG from your mod. Gives back a texture with width and height. Each call makes a new one, so load once |
textures.release(texture) | frees a texture early |
settings
| Function | What it does |
|---|---|
settings.toggle(key, options) | an on and off setting |
settings.slider(key, options) | a number between min and max |
settings.choice(key, options) | one of a list of options |
settings.text(key, options) | some text |
settings.key(key, options) | a key |
settings.color(key, options) | a color |
settings.button(key, options) | a button that runs onClick |
settings.enabled | reads the setting whose key is enabled. Assign to it to change it |
settings.get(key), settings.set(key, value) | reads or changes a setting |
settings.reset(key) | puts a setting back to its default |
settings.all() | a table of every setting's value |
settings.onChange(fn) | calls fn(key, value, old) when a setting changes |
settings.open() | opens your settings page |
Every setting function takes label, description and default, and gives back the setting's current value. See Settings and storage for each type's options.
storage
storage is a table that is saved for you. See Settings and storage.
mod
Your own mod.
| Name | What it is |
|---|---|
mod.id, mod.name, mod.version, mod.description, mod.authors | your mod's details |
mod.minecraft | the game version your mod is running in |
mod.export | what other mods get from mods.get |
mod.log(...), mod.warn(...), mod.error(...) | writes to your Log at that level. mod.error does not stop your code |
mod.read(path) | the contents of a file in your mod, or nil |
mod.exists(path) | true if your mod has that file |
mod.files(prefix) | every file in your mod whose path starts with prefix |
mod.save() | saves settings and storage now |
mod.reload() | reloads your mod |
mod.disable() | turns your mod off |
mods
Other mods.
| Function | What it gives back |
|---|---|
mods.get(id) | that mod's mod.export, or nil if it is not running |
mods.has(id) | true if that mod is installed and running |
mods.info(id) | { id, name, version, enabled, active, runtime }, or nil |
mods.list() | the info for every installed mod |
json
| Function | What it does |
|---|---|
json.encode(value, pretty) | turns a value into JSON text |
json.decode(text) | turns JSON text into a value. Comments and trailing commas are fine |
json.null | stands for JSON's null |
A table with keys 1 to n becomes a JSON array, and any other table becomes an object. An empty table becomes [].
util
| Function | What it gives back |
|---|---|
util.color(r, g, b, a) | a color from 0 to 255 values. a is 255 by default. util.rgb is the same |
util.hsv(h, s, v, a) | a color from a hue in degrees and a saturation and value from 0 to 1 |
util.rgba(color) | gives back r, g, b, a of a color |
util.alpha(color, a) | the same color with alpha a, from 0 to 1 |
util.lerp(a, b, t) | the value t of the way from a to b |
util.clamp(value, min, max) | value, kept between min and max |
util.round(value, decimals) | value rounded. decimals is 0 by default |
util.formatTime(seconds) | a time like "4:05" or "1:04:05" |
util.split(text, separator) | a list of the pieces. separator is "," by default and is plain text, not a pattern |
util.trim(text) | text without spaces at the ends |
util.startsWith(text, prefix), util.endsWith(text, suffix) | true or false |
util.now() | the current time in milliseconds |
util.uuid() | a new random UUID |
util.bytes(text) | the length of text in bytes |
clipboard
| Function | What it does |
|---|---|
clipboard.set(text) | copies text |
clipboard.get() | the text on the clipboard. Needs the clipboard permission |
http
| Function | What it does |
|---|---|
http.get(url, fn) | downloads url, then calls fn(body), or fn(nil, error) if it failed. Needs the network permission |
gl and matrix
gl is the browser's WebGL 2 API, and matrix builds 4x4 matrices for it. Both are covered in WebGL.
Lua extras
| Function | What it does |
|---|---|
print(...) | writes to your Log, joined with tabs |
log(...) | writes to your Log, joined with spaces |
require(name) | loads another Lua file from your mod (see Packaging) |
The rest of the standard Lua library is in How mods run.



