players global · type Players
A room's players and their events: the players global, or room.players.
Functions 18
players.on_join(fn: (player: Player) -> ()) → ConnectionCalls fn when a player arrives: on the globals when a client connects, on a room's table each time a player moves into it.
players.on_leave(fn: (player: Player) -> ()) → ConnectionThe same player value on_join had; it can no longer be sent to.
players.list() → { Player }Returns every player in the room.
players.get(name: string) → Player?Returns the player with this name, or nil.
players.count() → numberReturns how many players are in the room.
players.near(pos: Vec3, radius: number) → { Player }Who is within a radius of a point, and who is inside a box of blocks.
players.within(from: Vec3, to: Vec3) → { Player }Returns every player inside a box of blocks, corners included.
players.on_click(fn: (player: Player, hit: Hit) -> ()) → ConnectionCalls fn on a left or right click; hit holds the button and the entity, player, block and face it met.
players.on_sneak(fn: (player: Player, down: boolean) -> ()) → ConnectionCalls fn once per sneak press and release; down is true on the press.
players.on_slot(fn: (player: Player, slot: number) -> ()) → ConnectionCalls fn when a player picks a hotbar slot, 1..9.
players.on_chat(fn: (player: Player, text: string) -> boolean?) → ConnectionReturn false and the line is not said.
players.on_pickup(fn: (player: Player?, item: string, count: number) -> ()) → ConnectionA stack taken off the ground, and one that landed on it. player is nil where the world dropped it, or where they have already left.
players.on_drop(fn: (player: Player?, item: string, count: number) -> ()) → ConnectionCalls fn when a stack lands on the ground; player is nil where the world dropped it or they have left.
players.on_death(fn: (player: Player?, cause: string, message: string, by: Player?) -> ()) → ConnectionCalls fn when a player dies, with the cause (fall, drown, void, lava, ...) and the line broadcast; player is nil once they have left.
players.on_respawn(fn: (player: Player?) -> ()) → ConnectionCalls fn when a player respawns; player is nil once they have left.
players.on_break(fn: (player: Player?, pos: Vec3, block: string) -> boolean?) → ConnectionCancellable. Return false to stop it; return nothing to let it through. These are asked *before* the world changes and the engine waits milliseconds for the answer, so they must be quick and must never task.wait. Timeout, error, overflow and disabled handlers deny the action. Across packs any false wins. See docs/luau-api.md, "saying no".
players.on_place(fn: (player: Player?, pos: Vec3, block: string) -> boolean?) → ConnectionAsks fn before a player puts a block down; return false to cancel it. A missed deadline denies the place.
players.on_damage(fn: (player: Player?, hit: DamageHit) -> boolean?) → ConnectionAsks fn before damage lands on a player; return false to refuse it. A missed deadline denies it. A pack's own player:damage is not asked about.