Skip to content

Client and utilities

Function What it does
client.notify(text) Shows a Citron notification. client.toast(text) is the same.
client.wait(seconds) Pauses this handler for seconds, then carries on. The game keeps running.
client.time() Returns the seconds on Citron’s clock. Use it to measure the time between two things.
client.epoch() Returns the current Unix time, in seconds.
client.fps() Returns the frame rate.
client.screen() Returns the screen’s width and height.
client.playing() Returns true while you are in a world with no game screen open and Citron’s GUI closed.
client.focused() Returns true while Minecraft is the window in front.
client.guiOpen() Returns true while Citron’s GUI is open.
client.sound(name) Plays a Windows sound, such as "SystemAsterisk" or "SystemExclamation", or a .wav file from the scripts folder: client.sound("ding.wav").
client.copy(text) Puts text on the clipboard.
client.paste() Returns the text on the clipboard.
client.stop() Switches this script off.
client.name() Returns this script’s file name: "auto_config.lua".
client.streamHidden() Returns true while Stream Hide is on.

client.wait pauses the handler it is called in, not the whole script: other handlers and timers keep running meanwhile.

-- press G for a 30 second reminder
events.on("key", function(key)
if key ~= "G" then return end
client.notify("Timer started")
client.wait(30)
client.notify("30 seconds are up")
end)
Function What it does
timer.after(seconds, fn) Runs fn once, after seconds. Returns an id.
timer.every(seconds, fn) Runs fn every seconds, at least 0.01. Returns an id.
timer.cancel(id) Stops a timer. Returns true if it was there.

Values a script keeps between sessions. Each script has its own storage, kept in scripts\data\<script name>.json and saved about a second after a change.

Function What it does
storage.get(key, default) Returns the stored value, or default when there is none.
storage.set(key, value) Stores a number, string, boolean or table. A nil value removes the key.
storage.all() Returns everything stored, as a table.
storage.clear() Removes everything.
local joins = storage.get("joins", 0)
events.on("join", function()
joins = joins + 1
storage.set("joins", joins)
end)

Requests run in the background. When the answer comes, your function gets fn(status, body, err): the HTTP status code, the answer’s text, and err, which is nil unless the request failed.

Function What it does
http.get(url, fn) Sends a GET request.
http.post(url, body, contentType, fn) Sends a POST request. A table body is sent as JSON. contentType can be left out, http.post(url, body, fn), and is then text/plain.
http.webhook(url, text, fn) Posts text as a message to a Discord webhook (its first 1900 characters). fn can be left out.
  • Links must start with http:// or https://.
  • A script can have 4 requests waiting for an answer at once, and all scripts together 16. Starting one more is an error.
  • An answer can be up to 1 MB.
  • A request gives up when the server does not answer within about 10 seconds.
http.get("https://api.github.com/repos/center2055/CitronClicker", function(status, body, err)
if status == 200 then
local repo = json.decode(body)
print(repo.full_name, repo.stargazers_count)
else
print("failed", status, err)
end
end)
Function What it does
json.encode(value, pretty) Returns a Lua value as JSON text, indented when pretty is true. A table with keys 1 to n becomes an array, any other an object.
json.decode(text) Returns JSON text as a Lua value, or nil when the text is not JSON. A JSON null becomes nil.
Function What it does
chat.send(text) The same as player.chat(text).
chat.command(cmd) The same as player.command(cmd).
Function Returns
util.stripCodes(text) text without its § colour codes.
util.distance(x1, y1, z1, x2, y2, z2) The distance between two points.
util.split(text, separator) The parts of text between each separator (a space unless you say), as a list.
util.trim(text) text without the spaces and line breaks at its ends.
util.startsWith(text, prefix) true if text starts with prefix.
util.endsWith(text, suffix) true if text ends with suffix.
util.clamp(x, low, high) x, kept between low and high.
util.lerp(a, b, t) The point t of the way from a to b: a + (b - a) * t.
util.round(x, digits) x rounded to digits decimal places, 0 unless you say.