Player Context Table

A player context table is passed to event callbacks and returned by server.getPlayer() / server.getPlayers(). It wraps a live ServerPlayerEntity and exposes the fields and methods below.

---

Identity Fields

Field	Type	Description
player.name	string	Player's display name
player.uuid	string	Player's UUID as a string
player.gamemode	string	Current game mode ("survival", "creative", "adventure", "spectator")
player.pos	{x, y, z}	Current position table

---

Health

player.getHealth() → number

Returns the player's current health (0.0–max).

player.getMaxHealth() → number

Returns the player's maximum health.

player.setHealth(hp)

Sets the player's health. Values are clamped by the game.

player.setHealth(20)   -- full health (default 20)

---

Hunger & Saturation

player.getFoodLevel() → int

Returns the hunger bar value (0–20).

player.setFoodLevel(food)

Sets the hunger bar value.

player.getSaturation() → number

Returns the saturation level.

player.setSaturation(sat)

Sets the saturation level.

---

Experience

player.getXpLevel() → int

Returns the player's current XP level.

player.addXp(amount)

Adds experience points (not levels) to the player.

player.setXpLevel(level)

Sets the player's XP level directly and resets XP progress to 0.

---

Inventory

player.getMainHandItem() → string

Returns the item identifier held in the main hand, e.g. "minecraft:diamond_sword". Returns "minecraft:air" if empty.

player.give(itemId, count)

Gives the player the specified item. If the inventory is full, the item is dropped at their feet.

player.give("minecraft:diamond", 5)

player.clearInventory()

Clears the player's entire inventory.

---

Movement

player.teleport(x, y, z)

Teleports the player to the given coordinates in their current dimension.

player.teleport(0, 64, 0)

---

Game Mode

player.setGamemode(mode)

Sets the player's game mode. Accepts "survival", "creative", "adventure", or "spectator".

player.setGamemode("creative")

---

Status Effects

player.addEffect(effectId [, durationTicks [, amplifier]])

Applies a status effect. durationTicks defaults to 200 (10 seconds), amplifier defaults to 0 (level I).

player.addEffect("minecraft:speed", 400, 1)    -- Speed II for 20 seconds
player.addEffect("minecraft:slowness")          -- Slowness I for 10 seconds

player.removeEffect(effectId)

Removes a status effect from the player.

player.removeEffect("minecraft:poison")

player.getEffects() → table

Returns a sequential table of active effects, each with id, duration, and amplifier fields.

for _, eff in ipairs(player.getEffects()) do
  print(eff.id, eff.duration, eff.amplifier)
end

---

Advancements

player.grantAdvancement(id)

Grants all criteria of the specified advancement to the player.

player.grantAdvancement("minecraft:story/mine_diamond")

player.revokeAdvancement(id)

Revokes all criteria of the specified advancement.

---

Messaging

player.tell(message)

Sends a plain-text chat message to the player.

player.tell("Hello, " .. player.name .. "!")

player.sendActionBar(text)

Shows text above the player's hotbar (does not appear in chat).

player.sendActionBar("§cYou are taking damage!")

player.sendTitle(title, subtitle [, fadeIn [, stay [, fadeOut]]])

Displays a title and subtitle on the player's screen.

Parameter	Default	Description
title	""	Main title text
subtitle	""	Subtitle text (shown below title)
fadeIn	10	Fade-in ticks
stay	70	Stay ticks
fadeOut	20	Fade-out ticks

player.sendTitle("§6Welcome!", "§eTo the server", 10, 70, 20)

player.kick(reason)

Disconnects the player with the given reason message.

player.kick("You have been banned.")