Skip to content

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.

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

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.

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