Player type
A player in the room: what players.on_join and every player event hand you.
Functions 34
player:ride(thing: MountTarget, opts: { seat: number?, locked: boolean? }?) → booleanThe player's name. The account's own id: the one name for a player a rename does not change. Where they stand now. Your own table, kept on the player for as long as they are connected. A player is one value while connected: a == b and t[player] work. The Room the player is in; nil while they move between rooms. Degrees: yaw sideways, pitch up or down; live, read only. True while the player sneaks; live. attack is the left button held on a block in reach (see player.reach); a client says nothing about a button held on air. True while the player sits on something; live. Seat 1 drives a vehicle; locked keeps a sneak from getting them off. false when somebody sits in that seat; keeps the current ride on failure. Works immediately after creating the target. Repeating the same ride keeps the seat; no delay or extra movement is needed.
player:dismount()Gets the player off what they ride; sneaking does the same, as off a horse.
player:message(text: Text, color: Ink?)What shows on this player's screen: the calls ui has, for them alone, plus their own menu and overlay. Sends a chat line to this player alone; color is for the words that did not pick one. Chat is not part of the screen, so it is not in ui.
player:sound(name: string, opts: { at: Vec3?, volume: number?, pitch: number?, category: string?, }?)Plays a sound by name to this player only, with an optional position, volume, pitch and category.
player:teleport(pos: Vec3, rotation: BodyRotation?)Yaw and pitch left out keep the way they face.
player:move_to(room: Room)Moves the player to another room; the client swaps worlds in place.
player:travel(dimension: string, pos: Vec3?)Sends the player to another world of the group, at pos or its spawn.
player:give(item: ItemSpec)One item: "stone", or { item = "arrow", count = 16 }.
player:held() → InventorySlot?Returns the stack in hand ({ item, count }, plus id for a pack item and damage for a worn tool), or nil.
player:inventory() → { InventorySlot }Returns one { item, count } row per filled slot.
player:take(item: ItemMatch, count: number?) → numberUp to count (1 unless you say) of what matches, the hand first; answers how many it took.
player:set_held(item: (ItemSpec | false)?)The stack in hand, replaced; nil or false empties the hand.
player:hotbar(slots: { [number]: ItemTable })Replaces the nine hotbar slots; a missing index is empty.
player:wear(pieces: Worn)The four armour slots; a piece left out is bare.
player:kill() → boolean0..20, or nil where the game version has no food bar. The food saturation, or nil where the game version has no food bar. True while the player is on the death screen. Kills the player; returns false on a version with no damage rules.
player:hide(other: Player)This player stops seeing other, or sees them again.
player:show(other: Player)This player sees other again after a hide.
player:can_see(other: Player) → booleanTrue unless other is not visible or is hidden from this player.
player:effect(name: string, opts: { level: number?, duration: number?, particles: boolean? }?)A potion effect by its modern name; duration in seconds, math.huge for ever.
player:clear_effect(name: string)Takes a potion effect off the player, by its modern name.
player:push(velocity: Vec3)A shove in blocks per tick, on top of what they are doing.
player:damage(amount: number) → booleanA hit in half-hearts: the flash, the sound, the resistance window. false on a version with no damage rules.
player:look_at(pos: Vec3)Turns the player's head to a point, where they stand.
player:stop_sound(name: string?)Where their view is from: the camera they look out of, or their eyes. One sound by name, or every sound; 1.13 and later.
player:kick(reason: Text?)Disconnects the player, with that text on their screen.
player:connect(server: string)Asks Minefort to move the player to another server by name: an instance's id, the network's name (its default member) or "hub". Minefort decides and does not answer; a player still here was not moved.
player:count(item: ItemMatch) → numberReturns how many of an item the player carries, across every slot.
player:has(node: string) → booleanTrue if the player's groups give them this permission node; operators have every node.
player:groups() → { string }Returns the player's groups; default is not listed.
player:add_group(group: string)Puts the player in a group until they leave; errors on a group citadel.yml does not define.
player:remove_group(group: string)Takes the player out of a group.
player:supports(feature: Feature) → booleanTrue if this player's client can show the feature.
player:look() → Vec3Returns the unit vector the player faces.
player:set_slot(n: number)Selects hotbar slot 1..9.
Fields 11
player.gamemode: numberThe hotbar slot in hand, 1..9; live. 0 survival, 1 creative, 2 adventure, 3 spectator; writable.
player.spawn_point: Vec3?The player's own respawn point (the block of the position), or nil for the room's. Writable; a point a pack sets needs no bed. nil clears it, a bed's point too.
player.max_health: number?Their health now, 0 to max_health; nil where the game version has no damage rules. Writable: set outright, no flash; 0 is a death; a number above max_health stops there. The most health they can have: 20 unless a pack set it; nil where the game version has no damage rules. Writable, 1 to 1024; nil gives the game's own back. A lower maximum takes health down to it. It lasts for the session. Every Java client draws its hearts; Bedrock draws none.
player.speed: numberThe body: what a pack sets on a player. See docs/luau-api.md, "Body and movement". Walk speed as a multiple of normal; 0 pins them.
player.can_fly: booleanMay fly in a mode that cannot.
player.visible: boolean?false: no other player is sent this body. The tab line stays. true or nil shows the body again.
player.scale: number1/16 to 16; 1.20.5 and later, older clients stay as they are.
player.reach: numberHow far a block can be clicked or dug, 0 to 64 blocks (4.5 by default); 1.20.5 and later. Measured from the camera when there is one.
player.level: numberThe experience bar: the number over it, and how full it is (0..1).
player.xp: numberHow full the experience bar is, 0..1.
player.camera: (Camera | false)?What they look out of: a camera from camera.fixed/free/orbit/chase, or nil or false for their own eyes. No delay is needed after creating its target. Ends when the target is destroyed or the player leaves the room.