Player

The player wrapper provides access to a connected player. Players are obtained via mc.players, world.players, or as event handler arguments.

Player extends Entity — all entity properties and methods are available on players. Only player-specific additions are listed here.

Metatable name: "player"

Properties

Identity

• player.name (string) — Username. Read-only.
• player.uuid (string) — UUID. Read-only.
• player.displayName (string) — Read-only.
• player.customName (string or nil)
• player.isOp (boolean) — Operator status. Read-only.
• player.ping (number) — Latency in ms. Read-only.

Movement

• player.isFlying (boolean) — Read-only.
• player.selectedSlot (number) — Hotbar slot 0–8. Read-only.

Health & Stats

• player.food (number)
• player.saturation (number) — Read-only.
• player.xpLevel (number) — Read-only.
• player.xpProgress (number) — Progress to next level (0–1). Read-only.

Other

• player.gamemode (string) — "survival", "creative", "adventure", "spectator".
• player.data (table) — Persistent per-player data. See Storage.

Methods

Entity methods inherited: raycast(), addEffect(), removeEffect(), hasEffect(), setOnFireFor(). damage() is overridden for players (always uses generic damage source, no source parameter).

player:sendMessage(text)

Sends a chat message.

• text (string) — Message text

player:sendMessage("Hello!")

player:sendActionBar(text)

Sends an action bar message.

• text (string) — Message text

player:sendActionBar("&eHotbar message")

player:sendTitle(title, subtitle?)

player:sendTitle({title, subtitle?, fadeIn?, stay?, fadeOut?})

Sends a title. Two forms:

Positional form — fixed fade timing (20/60/20 ticks):

Param	Type	Description
title	string	Title text
subtitle	string	Subtitle text

player:sendTitle("&cWarning", "&7Danger zone")

Table form — custom timing:

Field	Type	Default	Description
title	string	""	Title text
subtitle	string	""	Subtitle text
fadeIn	number	20	Fade-in ticks
stay	number	60	Stay ticks
fadeOut	number	20	Fade-out ticks

player:sendTitle({ title = "&aVictory!", subtitle = "&7You won!", fadeIn = 10, stay = 40 })

player:teleport(x, y, z, world?)

Teleports to coordinates.

• x, y, z (number) — Target coordinates
• world (string, optional) — Target world name (e.g. "minecraft:overworld")

player:teleport(0, 64, 0)
player:teleport(0, 64, 0, "minecraft:the_nether")

player:heal(amount)

Restores health.

• amount (number) — Health to restore

player:heal(20)

player:kick(reason)

Kicks the player.

• reason (string) — Kick message

player:kick("You have been kicked!")

player:hasPermission(node)

Checks a permission node.

• node (string) — Permission node

if player:hasPermission("myplugin.admin") then end

player:playSound(id, volume?, pitch?)

Plays a sound.

• id (string) — Sound identifier
• volume (number, default 1.0) — Volume
• pitch (number, default 1.0) — Pitch

player:playSound("minecraft:entity.ender_dragon.growl", 1.0, 1.0)

player:give(item[, count])

Gives an item to the inventory. Accepts an ItemStack wrapper or an item ID string.

• item (ItemStack or string) — Item to give, or item ID
• count (number, optional) — Stack size (only with string ID)

player:give(mc.createItem("diamond", 1))
player:give("diamond", 16)

player:setItem(slot, item)

Sets an item in a slot.

• slot (number) — Slot index
• item (ItemStack or nil) — Item or nil to clear

player:getItem(slot)

Gets the item in a slot.

• slot (number) — Slot index

player:clear()

Clears the inventory.

player:clear()

Sidebar

Each player has a per-player sidebar.

player.sidebar = {...}

Creates or updates the sidebar. Auto-shows on first creation. Partial updates merge.

player.sidebar = {
  title = "&6My Server",
  lines = { "&aWelcome!", "", "&7Players: " .. mc.onlineCount }
}
player.sidebar = { title = "&6Updated Title" }
player.sidebar = { lines = { "Line 1", "Line 2" } }
player.sidebar = { visible = false }
player.sidebar = nil  -- destroy

sb.title

type: string

Current title. Assign to update.

sb.lines

type: table

Lines array (strings). Assign to replace all lines.

sb.visible

type: boolean

Whether shown. Read-only.

sb.lineCount

type: number

Number of lines. Read-only.

sb:setLine(n, text)

Sets a specific line (1‑indexed).

• n (number) — Line index
• text (string) — Line text

sb:show()

Shows the sidebar.

sb:hide()

Hides the sidebar.

sb:destroy()

Destroys the sidebar permanently.

local sb = player.sidebar
sb.title = "Updated Title"
sb.lines = { "Line A", "Line B", "Line C" }
sb:setLine(2, "Modified Line B")
sb:hide() sb:show() sb:destroy()