Scripting
Citron runs Lua 5.4 scripts inside the game. A script can read your player and everyone around you, switch and tune modules, load configs, press keys, draw on the screen and in the world, and send requests to websites.
This page covers how scripts work. The Scripting API pages list every function, and Examples has whole scripts to start from.
The Scripts page
Section titled “The Scripts page”The Scripts page, in the launcher or in the Click GUI’s dock, lists your scripts.
- The switch beside a script runs or stops it. A script that was stopped by errors says stopped by an error under its name.
- New makes a script. Hover a script and click the bin to delete it.
- Each script shows both as Blocks, a Scratch-like editor where you drag blocks from the palette and they snap together, and as Code, its Lua. The two are the same script, so you can build it in blocks and finish it in code.
- Save, or Ctrl+S in the editor, writes the file. Saving a running script starts it again.
- Lua API in the Code view lists every function beside the editor, and the editor completes names as you type.
- The console under the editor shows what your scripts
print, and their errors. Clear empties it.
The scripts folder
Section titled “The scripts folder”Scripts are .lua files in %APPDATA%\CitronV2\scripts. Open, under Scripts folder, opens it in File Explorer.
You can also write scripts in an editor of your own. A running script is started again within a second of its file changing.
The first time the Scripts page opens, it puts four examples in the folder, all switched off: auto_config.lua, low_health.lua, enemy_marker.lua and session_stats.lua. They are the quickest way to see the API in use. See Examples.
The folder also holds the files scripts use: .wav sounds for client.sound, other scripts for require, and each script’s storage in scripts\data.
How a script runs
Section titled “How a script runs”- When you switch a script on, its file runs once from top to bottom. Everything after that happens in handlers you add with
events.on, and in timers (timer.after,timer.every). - Every handler and timer runs as a coroutine.
client.wait(seconds)pauses it without stopping the game, andworld.blockAtpauses it for one frame while the game reads the block. Neither can pause a coroutine you made yourself. - Each script has its own Lua state, so scripts cannot see each other’s variables. To pass something to another script, use
events.emit. To keep a value between sessions, usestorage. - When a script stops, every key it held is let go and its
unloadhandler runs.
A first script:
-- a notification every time you join a serverevents.on("join", function(srv) local name = srv.name() if name == "" then name = srv.address() end client.notify("Joined " .. name)end)Limits
Section titled “Limits”Scripts run in a sandbox:
- Lua’s own
string,table,math,utf8andcoroutinelibraries are there.io,debug,package,dofileandloadfileare not, andoshas onlyos.time,os.clockandos.date. loadtakes Lua text only, never compiled chunks.require("name")runsname.luafrom the scripts folder once and gives back what it returned. A dot means a subfolder:require("lib.util")loadslib\util.lua.printwrites to the console on the Scripts page.
And a script that misbehaves is stopped:
- A script may use up to 64 MB of memory.
- A handler, a timer or the first run that goes on for 80 ms without pausing is stopped with an error. A long loop should call
client.waitnow and then. - A script that errors 8 times within 5 seconds is switched off.
- A script that is not valid Lua stays off until you change it.
- A script can have up to 512 handlers and 256 timers.
Values
Section titled “Values”- Positions are in blocks. A function that gives a position returns three numbers:
local x, y, z = player.position(). - Angles are degrees as the game counts them: yaw 0 faces south (+Z), yaw 90 faces west (-X), and a positive pitch looks down.
- Colours are
0xRRGGBB,0xAARRGGBB,"#RRGGBB","#AARRGGBB"or{r, g, b, a}with each part 0 to 255. - Screen positions are pixels from the top left corner.
- Times are in seconds.
- Names of modules, settings, keys and players ignore case and spaces:
"Auto Clicker"and"autoclicker"are the same module.
Functions that read the game return nothing while you are not in a world, so check the result before you use it:
local hp = player.health()if not hp then return endEvents
Section titled “Events”Add a handler with events.on(name, fn). The function gets the event’s arguments.
events.on("hurt", function(amount, health) if health < 6 then client.sound("SystemExclamation") endend)| Event | Arguments | When |
|---|---|---|
tick |
Every game tick, 20 times a second. | |
frame |
dt |
Every frame. dt is the seconds since the last one. |
render2d |
ctx |
Every frame, to draw on the screen. ctx is the draw table. |
render3d |
Every frame, to draw in the world with draw3d. |
|
chat |
message, sender, raw |
A chat line arrives. For a player’s message, message is what they wrote and sender is their name. For the server’s own lines, sender is nil and message is the whole line. raw is always the whole line. |
title |
text |
A title or action bar text shows. |
key |
key |
You press a key or mouse button while you play: "G", "F4", "LMB", "MB4". Not sent while Citron’s GUI has your keyboard. |
keyup |
key |
You let go of one. |
attack |
target, reach |
One of your hits lands. target is a player table and reach is how far the hit reached. |
hurt |
amount, health |
You lose health: how much, and how much is left. |
death |
Your health reaches 0. | |
spawn |
You come into a world, or respawn. | |
join |
srv |
You join a server. srv is the server table. |
leave |
You leave a server. | |
module |
id, on, name |
A module is switched on or off, by you or by a script. |
config |
name |
Another config is loaded. |
playerjoin |
name |
Someone joins the server’s player list. |
playerleave |
name |
Someone leaves it. |
gui |
open |
Citron’s GUI opens (true) or closes (false). |
unload |
The script is about to stop. | |
| any other name | what was sent | A script sent it with events.emit. |
"render" also works as a name for render2d.
Event functions
Section titled “Event functions”| Function | What it does |
|---|---|
events.on(name, fn) |
Runs fn every time the event happens. Returns an id. |
events.once(name, fn) |
Runs fn the next time only. Returns an id. |
events.off(id) |
Removes a handler. Returns true if it was there. |
events.emit(name, ...) |
Sends an event of your own to the handlers of every running script, this one included, once the frame’s own events are done. Up to 16 values: numbers, strings, booleans and tables. Tables are copied, and functions in them are left out. |
The API
Section titled “The API”Everything a script can call is in a global table:
- Player and world:
player,world,combat,input. - Modules and configs:
modules,config,server,friends,cosmetics. - Drawing:
drawanddraw3d. - Client and utilities:
client,timer,storage,http,json,chat,util. - Examples: whole scripts to start from.
Share your scripts in the Discord’s #client-scripts channel.