Player and world
These tables read your player and the world around you, and act for you. Functions that read the game return nothing while you are not in a world. See Values for how positions, angles and colours are written.
player
Section titled “player”Reading
Section titled “Reading”| Function | Returns |
|---|---|
player.name() |
Your name, without colour codes. |
player.position() |
The x, y, z of the middle of your feet. player.pos() is the same. |
player.eye() |
The x, y, z of your eyes. |
player.velocity() |
Your x, y, z speed in blocks per tick. |
player.speed() |
Your horizontal speed in blocks per second. |
player.rotation() |
Your yaw and pitch. |
player.health() |
Your health. |
player.maxHealth() |
Your maximum health. |
player.absorption() |
Your absorption health. |
player.food() |
Your hunger bar. |
player.saturation() |
Your saturation. |
player.level() |
Your experience level. |
player.xp() |
Your progress toward the next level. |
player.air() |
Your air while under water. |
player.gamemode() |
"survival", "creative", "adventure" or "spectator". |
player.heldItem() |
The id and count of what you hold: "minecraft:diamond_sword", 1. An empty hand gives "" and 0. |
player.held() |
What you hold, as an item table, or nil. |
player.offhand() |
Your offhand item as an item table, or nil. |
player.armor() |
Your four armour slots as item tables, nil where a slot is empty. |
player.hotbar() |
Your 9 hotbar slots as item tables, false for an empty slot. |
player.inventory() |
All 36 inventory slots the same way. Slots 1 to 9 are the hotbar. |
player.slot() |
The selected hotbar slot, 1 to 9. |
player.findItem(text) |
The first hotbar slot whose item id contains text, or nil: player.findItem("pearl"). |
player.onGround() |
true while you stand on something. |
player.isSprinting(), player.isSneaking() |
true while you sprint, or sneak. |
player.isUsingItem() |
true while you use an item: eat, drink, draw a bow. |
player.isGliding(), player.isSwimming(), player.isOnFire() |
true while you glide, swim, or burn. |
player.effects() |
Your active effects, as a list of {id, amplifier, seconds, total}. seconds is -1 for an endless effect. |
player.team() |
Your team’s colour: "red", "blue", "green", "yellow", "purple", "white" or "black", or "" without a team. |
player.target() |
The player Citron’s combat modules are going for, as a player table, or nil. |
player.lookingAt() |
The player under your crosshair, or nil. |
Acting
Section titled “Acting”| Function | What it does |
|---|---|
player.chat(text) |
Sends a chat message, up to 512 characters. player.say(text) is the same. |
player.command(cmd) |
Runs a command. The / is optional: player.command("spawn"). |
player.setRotation(yaw, pitch) |
Turns your view. Pitch stays between -90 and 90. |
player.lookAt(p) |
Turns your view to a player table’s eyes. |
player.lookAt(x, y, z) |
Turns your view to a point. |
player.setSlot(n) |
Selects hotbar slot n, 1 to 9. |
player.jump() |
Taps jump. |
player.sneak(on) |
Holds sneak. player.sneak(false) lets go. |
player.sprint(on) |
Holds sprint. player.sprint(false) lets go. |
player.move(direction, on) |
Holds a movement key: "forward", "back", "left" or "right". false lets go. |
player.key(name, down) |
Presses a key or one of your binds (below). true holds it, false lets go, and leaving down out taps it. |
player.stop() |
Lets go of every key this script holds. |
player.click(button) |
Clicks once: "left", the default, or "right". |
player.attack() |
The same as player.click("left"). |
player.use() |
The same as player.click("right"). |
player.drop() |
Taps drop. |
Presses go through your own binds in Minecraft, the same way Citron’s modules press them: player.jump() presses whatever you bound jump to. A key a script holds stays down until the script lets go, calls player.stop() or stops.
player.setRotation and player.lookAt turn your real view, the one the server sees, all the way at once. See Aiming from a script for a smooth turn.
Key names
Section titled “Key names”player.key takes one of your binds by name: "jump", "sneak", "sprint", "forward", "back", "strafeleft", "straferight", "attack", "use", "drop", "inventory" or "perspective".
Or a key: a letter or digit ("G", "4"), "F1" to "F24", "Space", "Shift", "LShift", "RShift", "Ctrl", "LCtrl", "RCtrl", "Alt", "LAlt", "RAlt", "Tab", "Enter", "Escape", "Backspace", the arrow keys "Up", "Down", "Left" and "Right", and the mouse buttons "LMB", "RMB", "MMB", "MB4" and "MB5".
| Function | Returns |
|---|---|
world.players(radius) |
Every player within radius blocks except you, as a list of player tables. Leave radius out for everyone Citron sees. |
world.nearestPlayer(options) |
The nearest player, or nil. enemies = true leaves out your friends and teammates, the way the combat modules do, and range limits the distance: world.nearestPlayer({ enemies = true, range = 8 }). |
world.playersWithin(radius, enemiesOnly) |
How many players are within radius, then the list: local n, list = world.playersWithin(6, true). |
world.player(name) |
A player by name, or nil. Case, spaces and colour codes do not matter. |
world.entities(kind, radius) |
Everything of one kind around you: "player", "mob", "item", "tnt" or "other". Leave kind out for all of them. |
world.blockAt(x, y, z) |
The name of the block there: "stone", "air". Pauses the handler for one frame unless the block was read a moment ago. |
While a script runs, Citron keeps track of players within 128 blocks, mobs within 48 and dropped items within 24.
Player tables
Section titled “Player tables”world.players, world.nearestPlayer, player.target, the attack event and others give players as tables with these fields:
| Field | What it holds |
|---|---|
name |
Their name, without colour codes. |
x, y, z |
The middle of their feet. |
eyeY |
The height of their eyes. |
height |
How tall their hitbox is. |
distance |
How far they are from you, in blocks. |
id |
A number that stays the same while they are in your world. Use it to recognise someone from one frame to the next. |
kind |
"player". |
xuid |
Their Xbox user id, when the server shares it. |
team |
Their team’s colour, the same names as player.team(). |
friend |
true if they are on your Friend List. |
target |
true if they are on your Target List. |
teammate |
true if Citron counts them as your teammate. |
invisible |
true while they are invisible. |
nicked |
true when Citron knows they play under a nickname. realName then holds their real name. |
held, offhand |
The ids of the items in their hands. |
armor |
The ids of their four armour pieces. |
health |
Their health, when Citron knows it. |
Mobs, dropped items and TNT from world.entities have name, x, y, z, eyeY, height, distance and id too, and:
| Field | What it holds |
|---|---|
kind |
"mob", "item", "tnt" or "other". |
type |
The entity’s type. |
hostile |
true for a hostile mob. |
health, maxHealth |
Its health, when Citron knows it. |
item, count |
For a dropped item: its id and how many. |
fuse |
For lit TNT: the seconds until it goes off. |
Item tables
Section titled “Item tables”| Field | What it holds |
|---|---|
id |
The item’s id: "minecraft:diamond_sword". |
count |
How many. |
aux |
The item’s data value. |
name |
Its name as the game shows it, without colour codes. |
combat
Section titled “combat”| Function | Returns |
|---|---|
combat.target() |
The same as player.target(). |
combat.lookingAt() |
The same as player.lookingAt(). |
combat.cps() |
Your clicks per second: left, then right. |
combat.reach() |
The reach Citron is using now, in blocks. |
| Function | Returns |
|---|---|
input.isKeyDown(name) |
true while you hold that key or mouse button: "R", "F4", "LAlt", "LShift", "Tab", "LMB", "RMB", "MMB", "MB4", "MB5". |
input.mouse() |
The x, y of the mouse cursor on the screen. |