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.

flying: boolean — Read/Write

Indicates whether the player is flying. Assign true to take off, which the game only allows where the player may fly: in creative and spectator mode, or where a mod allows it; elsewhere nothing happens. A bot takes off like a player who presses jump twice. Landing ends flying, except in spectator mode.

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: Skin? — Read/Write

The skin the player wears, or nil for a default skin. Assign a Skin to put it on, like one that Skin:lookup or Skin:load gave: the player only borrows it, their name and UUID stay their own. All players see it at once; the player's own view flickers for a moment while it is redrawn. It stays on through death and respawn, and is gone when the player logs out. Assign nil to put on a default skin, like Steve or Alex. A player's own skin reads as a Skin too, unless it is a default skin: keep it to put it back on later, without a lookup.

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

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.