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.

Anzeige

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() or world.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

FunctionWhat 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

FunctionWhat 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.activetrue 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

FunctionWhat 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.

MethodWhat it does
ctx.width, ctx.heightthe 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

FunctionWhat 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.

FunctionWhat 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

FunctionWhat it gives back
game.versionthe 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:

OptionValue
fova whole number from 30 to 110
gamma (or brightness)0 to 1
renderDistancea whole number of chunks, from 2
sensitivity0 to 1
guiScaleread only. 0 means auto
viewBobbingtrue or false
fovEffects0 to 1
framerateLimit10 to 260 in steps of 10. 260 means unlimited
chatOpacity0 to 1
subtitlestrue or false
masterVolume, musicVolume0 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.

FunctionWhat 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 }, where side is the face you are looking at, like "up" or "north"
  • an entity: { type = "entity", entity, name, uuid, x, y, z, isPlayer, health, maxHealth, distance }, where entity is its type, like "minecraft:zombie"

camera

FunctionWhat 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.

FunctionWhat 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

FunctionWhat 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

FunctionWhat 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

FunctionWhat 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

FunctionWhat 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

FunctionWhat it does
sound.play(id, volume, pitch)plays a game sound, like "entity.experience_orb.pickup". Volume and pitch are 1 by default

textures

FunctionWhat 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

FunctionWhat 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.enabledreads 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.

NameWhat it is
mod.id, mod.name, mod.version, mod.description, mod.authorsyour mod's details
mod.minecraftthe game version your mod is running in
mod.exportwhat 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.

FunctionWhat 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

FunctionWhat 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.nullstands 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

FunctionWhat 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

FunctionWhat it does
clipboard.set(text)copies text
clipboard.get()the text on the clipboard. Needs the clipboard permission

http

FunctionWhat 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

FunctionWhat 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.