Skip to content

player_api.md

Latest commit

 

History

History
501 lines (352 loc) · 8.43 KB

player_api.md

File metadata and controls

501 lines (352 loc) · 8.43 KB
Raw

Player API Documentation

The Player API provides Lua scripts with access to manipulate players in Minecraft, including teleporting, giving items, getting/setting health, food, experience, gamemode, and more.

Global Access

The API is accessed via the global PlayerApi table in Lua scripts.

Methods

teleport

Teleports a player to a new location.

Syntax:

PlayerApi:teleport(player, location)

Parameters:

  • player (userdata): The Player to teleport
  • location (userdata): The target Location

Example:

local newLoc = location:clone():add(0, 10, 0)
PlayerApi:teleport(player, newLoc)

giveItem

Gives an item to a player's inventory. If the inventory is full, leftover items are dropped naturally at the player's location.

Syntax:

PlayerApi:giveItem(player, itemStack)

Parameters:

  • player (userdata): The Player to give the item to
  • itemStack (userdata): An ItemStack object (from InventoryApi)

Example:

local item = InventoryApi:createItem("DIAMOND", 1)
PlayerApi:giveItem(player, item)

getHealth

Gets the player's current health.

Syntax:

local health = PlayerApi:getHealth(player)

Parameters:

  • player (userdata): The Player to query

Returns:

  • health (number): The player's current health

Example:

local health = PlayerApi:getHealth(player)
print("Health: " .. health)

setHealth

Sets the player's health.

Syntax:

PlayerApi:setHealth(player, health)

Parameters:

  • player (userdata): The Player to modify
  • health (number): The health value to set (clamped to [0, maxHealth])

Example:

PlayerApi:setHealth(player, 15)

getMaxHealth

Gets the player's maximum health.

Syntax:

local maxHealth = PlayerApi:getMaxHealth(player)

Parameters:

  • player (userdata): The Player to query

Returns:

  • maxHealth (number): The player's maximum health

Example:

local maxHealth = PlayerApi:getMaxHealth(player)
print("Max health: " .. maxHealth)

getFoodLevel

Gets the player's food level (hunger).

Syntax:

local foodLevel = PlayerApi:getFoodLevel(player)

Parameters:

  • player (userdata): The Player to query

Returns:

  • foodLevel (number): The player's food level (0-20)

Example:

local food = PlayerApi:getFoodLevel(player)
print("Food level: " .. food)

setFoodLevel

Sets the player's food level.

Syntax:

PlayerApi:setFoodLevel(player, foodLevel)

Parameters:

  • player (userdata): The Player to modify
  • foodLevel (number): The food level to set (clamped to 0-20)

Example:

PlayerApi:setFoodLevel(player, 15)

getExp

Gets the player's experience progress (0.0 to 1.0).

Syntax:

local exp = PlayerApi:getExp(player)

Parameters:

  • player (userdata): The Player to query

Returns:

  • exp (number): The player's experience progress (0.0-1.0)

Example:

local exp = PlayerApi:getExp(player)
print("Experience: " .. exp)

setExp

Sets the player's experience progress.

Syntax:

PlayerApi:setExp(player, exp)

Parameters:

  • player (userdata): The Player to modify
  • exp (number): The experience progress to set (clamped to 0.0-1.0)

Example:

PlayerApi:setExp(player, 0.5)

getLevel

Gets the player's experience level.

Syntax:

local level = PlayerApi:getLevel(player)

Parameters:

  • player (userdata): The Player to query

Returns:

  • level (number): The player's experience level

Example:

local level = PlayerApi:getLevel(player)
print("Level: " .. level)

setLevel

Sets the player's experience level.

Syntax:

PlayerApi:setLevel(player, level)

Parameters:

  • player (userdata): The Player to modify
  • level (number): The level to set (clamped to minimum 0)

Example:

PlayerApi:setLevel(player, 5)

getGameMode

Gets the player's current game mode.

Syntax:

local gameMode = PlayerApi:getGameMode(player)

Parameters:

  • player (userdata): The Player to query

Returns:

  • gameMode (string): The game mode name (e.g., "SURVIVAL", "CREATIVE", "ADVENTURE", "SPECTATOR")

Example:

local mode = PlayerApi:getGameMode(player)
print("Game mode: " .. mode)

setGameMode

Sets the player's game mode.

Syntax:

PlayerApi:setGameMode(player, gameMode)

Parameters:

  • player (userdata): The Player to modify
  • gameMode (string): The game mode name ("SURVIVAL", "CREATIVE", "ADVENTURE", "SPECTATOR")

Example:

PlayerApi:setGameMode(player, "CREATIVE")

getInventory

Gets the player's inventory.

Syntax:

local inventory = PlayerApi:getInventory(player)

Parameters:

  • player (userdata): The Player to query

Returns:

  • inventory (userdata): The player's Inventory object

Example:

local inv = PlayerApi:getInventory(player)

getName

Gets the player's name.

Syntax:

local name = PlayerApi:getName(player)

Parameters:

  • player (userdata): The Player to query

Returns:

  • name (string): The player's username

Example:

local name = PlayerApi:getName(player)
print("Player: " .. name)

getDisplayName

Gets the player's display name.

Syntax:

local displayName = PlayerApi:getDisplayName(player)

Parameters:

  • player (userdata): The Player to query

Returns:

  • displayName (userdata): A Component object

Example:

local name = PlayerApi:getDisplayName(player)

setDisplayName

Sets the player's display name.

Syntax:

PlayerApi:setDisplayName(player, displayName)

Parameters:

  • player (userdata): The Player to modify
  • displayName (userdata): A Component object (from AdventureApi)

Example:

local name = AdventureApi:parseMiniMessage("<gold>Test Player</gold>")
PlayerApi:setDisplayName(player, name)

getLocation

Gets the player's current location.

Syntax:

local location = PlayerApi:getLocation(player)

Parameters:

  • player (userdata): The Player to query

Returns:

  • location (userdata): The player's Location

Example:

local loc = PlayerApi:getLocation(player)
print(loc:getX(), loc:getY(), loc:getZ())

sendMessage

Sends a message to the player.

Syntax:

PlayerApi:sendMessage(player, messageComponent)

Parameters:

  • player (userdata): The Player to send the message to
  • messageComponent (userdata): A Component object (from AdventureApi)

Example:

local msg = AdventureApi:parseMiniMessage("<green>Hello!</green>")
PlayerApi:sendMessage(player, msg)

hasPermission

Checks if the player has a specific permission.

Syntax:

local hasPermission = PlayerApi:hasPermission(player, permission)

Parameters:

  • player (userdata): The Player to check
  • permission (string): The permission node to check

Returns:

  • hasPermission (boolean): true if the player has the permission, false otherwise

Example:

if PlayerApi:hasPermission(player, "minecraft.command.gamemode") then
    print("Player can change gamemode")
end

kick

Kicks the player from the server.

Syntax:

PlayerApi:kick(player, [reason])

Parameters:

  • player (userdata): The Player to kick
  • reason (userdata, optional): A Component object for the kick reason

Example:

PlayerApi:kick(player)
local reason = AdventureApi:parseMiniMessage("<red>Goodbye!</red>")
PlayerApi:kick(player, reason)

getOnlinePlayers

Gets a table of all online players.

Syntax:

local players = PlayerApi:getOnlinePlayers()

Returns:

  • players (table): A Lua table containing all online Player objects (1-indexed)

Example:

local onlinePlayers = PlayerApi:getOnlinePlayers()
for i = 1, #onlinePlayers do
    local p = onlinePlayers[i]
    print(PlayerApi:getName(p))
end

Notes

  • Health values are automatically clamped between 0 and the player's max health
  • Food level is clamped between 0 and 20
  • Experience progress is clamped between 0.0 and 1.0
  • Level is clamped to minimum 0
  • Game mode names are case-insensitive but must be valid Bukkit game modes
  • Display names use Adventure API Components for formatting
  • Leftover items from giveItem are dropped naturally at the player's location