Skip to content

Player

Inherits from: LivingEntity

Represents a player entity in the game, inheriting from LivingEntity and adding player-specific attributes and actions.

NBT and the client: writing a player's NBT (putNbt, removeNbt, assigning nbt) only updates the server. Position, rotation, velocity, game mode and abilities written this way are not sent to the player's client. Use teleport, pos, yaw, pitch, velocity and gamemode instead.

Fields

blockInteractionRange: number — Read/Write

The maximum distance at which the player can interact with blocks.

foodLevel: number — Read/Write

The player's food level, an integer from 0 to 20. See Hunger.

gamemode: GameMode — Read/Write

The player's current game mode.

inventory: PlayerInventory — Read-Only

A reference to the player’s inventory.

mainHandItem: Item? — Read/Write

A copy of the item currently held in the player's main hand, or nil if the hand is empty.

online: boolean — Read-Only

Indicates whether the player is online. false once the player has left, was kicked, or the server stopped; a dead player is still online. A reference follows a player through respawn, but not through logout: a player who logs in again is a new player, and an old reference stays offline.

permissionLevel: number — Read-Only

The player's permission level, typically between 0 and 4. A value of 0 means no special permissions.

saturation: number — Read/Write

The player's saturation, from 0 up to the food level: a larger value is cut down to it. See Saturation.

skin: string? — Read-Only

The name of the player whose skin this player wears, spelled as that player's account spells it, or nil for a default skin. See setSkin.

Methods

sendCommandTree()

Sends the current command tree to the player's Minecraft client.

This forces the Minecraft command system (Brigadier) to rebuild and send the player's available command tree. It is useful when command permissions have changed, particularly for dynamic commands or custom permission checks.

A common use case is when a custom Lua interceptor of the PermissionCheckEvent modifies permission results for specific commands, and the players should immediately see the updated list of accessible commands in their client.

Example: Custom permission checker spell

spell:intercept({"PermissionCheckEvent"}, function(event)
  if instanceOf(Player, event.entity) and event.permission == "my.custom.command" then
    event.allowed = true
  end
end)

-- Refresh the command tree for all online players
for _, player in ipairs(Server.players) do
  ---@cast player Player
  player:sendCommandTree()
end

-- Keep the spell alive so the interceptor stays active
while true do sleep(20) end

setSkin(name: string?, timeout?: number) → ok: boolean, reason: SkinReason?

Puts on the skin of another player, also in the middle of a game. The player only borrows the skin: their name and UUID stay their own. All players see the new skin at once; the player's own view flickers for a moment while it is redrawn. The skin stays on through death and respawn, and is gone when the player logs out.

The skin is looked up at Mojang, which needs internet access, and this function waits until it arrives, usually less than a second, or until the timeout. The same skin again comes at once: lookups are remembered for some minutes. Because it waits, it can't be called in an event interceptor.

Example

local ok, reason = spell.owner:setSkin("jeb_")
if not ok then
  print("No skin: " .. reason)
end
sleep(200)
spell.owner:setSkin(nil) -- back to the own skin

Parameters

  • name: string? — The name of the player whose skin to put on, or nil for the player's own skin, which needs no lookup.
  • timeout?: number — The most ticks to wait for the skin, an integer. Defaults to waiting until the lookup ends.

Returns

  • ok: boolean — true once the player wears the skin.
  • reason: SkinReason? — Why the player doesn't wear the skin. They keep the one they had, unless the skin still comes after a "timeout".

teleport(world: World, pos: Vec3, yaw?: number, pitch?: number) → player: Player

Teleports the player to a specified location in the given world. If yaw or pitch are not provided, the player's current rotation is used.

Example: Teleport with direction

local player = spell.owner
local destination = Vec3:new(100, 64, 100)
player:teleport(player.world, destination, 90, 45)  -- Teleports the player facing west and looking slightly down

Example: Teleport using current rotation

player:teleport(player.world, destination)  -- Teleports the player with current yaw and pitch

Parameters

  • world: World — The world to teleport the player to.
  • pos: Vec3 — The target position.
  • yaw?: number — Yaw angle in degrees. Defaults to the player’s current yaw.
  • pitch?: number — Pitch angle in degrees. Defaults to the player’s current pitch.

Returns

  • player: Player — A reference to the player after teleportation.