Player API - PocketMine-MP

Overview

The Player API provides comprehensive control over player entities, including inventory management, permissions, teleportation, UI interactions, and more.

Player Class

The Player class represents a connected player. Namespace: pocketmine\player\Player

Identity & Authentication

getName

public function getName() : string

Returns the player’s username.

return

string

The player’s username

// Example: Get player name
$name = $player->getName();
$player->sendMessage("Hello, $name!");

getDisplayName

public function getDisplayName() : string

Returns the player’s display name (used in chat).

return

string

The display name

setDisplayName

public function setDisplayName(string $name) : void

Sets the player’s display name.

name

string

required

New display name

// Example: Set custom display name
$player->setDisplayName("§6[VIP] " . $player->getName());

getUniqueId

public function getUniqueId() : UuidInterface

Returns the player’s UUID.

return

UuidInterface

The player’s UUID

// Example: Store player UUID
$uuid = $player->getUniqueId();
$uuidString = $uuid->toString();
// Store in database, etc.

getXuid

public function getXuid() : string

Returns the Xbox Live user ID (XUID) if logged into Xbox Live.

return

string

XUID, or empty string if not logged in

isAuthenticated

public function isAuthenticated() : bool

Returns whether the player is authenticated with Xbox Live.

Communication

sendMessage

public function sendMessage(Translatable|string $message) : void

Sends a message to the player.

message

Translatable|string

required

Message to send

// Example: Send messages
$player->sendMessage("§aWelcome to the server!");
$player->sendMessage("§cYou don't have permission!");

// Send multiple lines
$player->sendMessage("Line 1\nLine 2\nLine 3");

sendPopup

public function sendPopup(string $message) : void

Sends a popup message (appears above hotbar).

message

string

required

Popup message

// Example: Show popup
$player->sendPopup("§eCoins: " . $coins);

sendTip

public function sendTip(string $message) : void

Sends a tip message (appears above hotbar, replacing popup).

sendTitle

public function sendTitle(string $title, string $subtitle = "", int $fadeIn = -1, int $stay = -1, int $fadeOut = -1) : void

Sends a title to the player.

title

string

required

Main title text

subtitle

string

default:""

Subtitle text

fadeIn

int

default:"-1"

Fade in duration in ticks (-1 = default)

stay

int

default:"-1"

Stay duration in ticks (-1 = default)

fadeOut

int

default:"-1"

Fade out duration in ticks (-1 = default)

// Example: Show title
$player->sendTitle("§6Welcome!", "§eTo our server", 10, 40, 10);

// Example: Clear title
$player->sendTitle("", "", 0, 0, 0);

sendActionBarMessage

public function sendActionBarMessage(string $message) : void

Sends an action bar message (appears above hotbar).

message

string

required

Action bar message

// Example: Show action bar
$player->sendActionBarMessage("§eHealth: §c" . $player->getHealth());

Connection & Session

isOnline

public function isOnline() : bool

Returns whether the player is connected.

isConnected

public function isConnected() : bool

Returns whether the player is connected.

kick

public function kick(Translatable|string $reason = "", ?Translatable|string $quitMessage = null) : bool

Kicks the player from the server.

reason

Translatable|string

default:""

Kick reason shown to player

quitMessage

Translatable|string|null

Custom quit message (null = default)

// Example: Kick player
$player->kick("You have been banned!");

// Kick with custom quit message
$player->kick("Server restart", "Player left");

transfer

public function transfer(string $address, int $port = 19132, Translatable|string $message = "") : bool

Transfers the player to another server.

address

string

required

Server IP address

port

int

default:"19132"

Server port

message

Translatable|string

default:""

Transfer message

// Example: Transfer to lobby
$player->transfer("lobby.example.com", 19132, "Transferring to lobby...");

Inventory & Items

getInventory

public function getInventory() : PlayerInventory

Returns the player’s inventory.

return

PlayerInventory

The player’s inventory

use pocketmine\item\VanillaItems;

// Example: Give items
$player->getInventory()->addItem(VanillaItems::DIAMOND()->setCount(64));

// Example: Clear inventory
$player->getInventory()->clearAll();

// Example: Get held item
$heldItem = $player->getInventory()->getItemInHand();

getArmorInventory

public function getArmorInventory() : ArmorInventory

Returns the player’s armor inventory.

return

ArmorInventory

The armor inventory

use pocketmine\item\VanillaItems;

// Example: Give armor
$armor = $player->getArmorInventory();
$armor->setHelmet(VanillaItems::DIAMOND_HELMET());
$armor->setChestplate(VanillaItems::DIAMOND_CHESTPLATE());
$armor->setLeggings(VanillaItems::DIAMOND_LEGGINGS());
$armor->setBoots(VanillaItems::DIAMOND_BOOTS());

getEnderInventory

public function getEnderInventory() : PlayerEnderInventory

Returns the player’s ender chest inventory.

getCursorInventory

public function getCursorInventory() : PlayerCursorInventory

Returns the cursor inventory (item being held by cursor).

Game Mode

getGamemode

public function getGamemode() : GameMode

Returns the player’s current game mode.

return

GameMode

The game mode

setGamemode

public function setGamemode(GameMode $gameMode) : void

Sets the player’s game mode.

gameMode

GameMode

required

New game mode

use pocketmine\player\GameMode;

// Example: Set game mode
$player->setGamemode(GameMode::CREATIVE());
$player->setGamemode(GameMode::SURVIVAL());
$player->setGamemode(GameMode::ADVENTURE());
$player->setGamemode(GameMode::SPECTATOR());

isCreative

public function isCreative(bool $includeSpectator = false) : bool

Returns whether the player is in creative mode.

includeSpectator

bool

default:"false"

Whether to include spectator mode

isSurvival

public function isSurvival(bool $includeAdventure = true) : bool

Returns whether the player is in survival mode.

isSpectator

public function isSpectator() : bool

Returns whether the player is in spectator mode.

isAdventure

public function isAdventure(bool $includeSurvival = false) : bool

Returns whether the player is in adventure mode.

Movement & Teleportation

teleport

public function teleport(Vector3|Position|Location $pos, ?float $yaw = null, ?float $pitch = null) : bool

Teleports the player to a location.

pos

Vector3|Position|Location

required

Destination position

yaw

float|null

New yaw rotation

pitch

float|null

New pitch rotation

// Example: Teleport player
$player->teleport(new Vector3(100, 64, 100));

// Teleport to spawn
$player->teleport($world->getSafeSpawn());

// Teleport with rotation
$player->teleport($pos, 90.0, 0.0);

getAllowFlight

public function getAllowFlight() : bool

Returns whether the player is allowed to toggle flight.

setAllowFlight

public function setAllowFlight(bool $value) : void

Sets whether the player can toggle flight.

value

bool

required

Whether to allow flight

// Example: Enable flight
$player->setAllowFlight(true);
$player->setFlying(true);

isFlying

public function isFlying() : bool

Returns whether the player is flying.

setFlying

public function setFlying(bool $value) : void

Sets whether the player is flying.

value

bool

required

Whether the player should be flying

setFlightSpeedMultiplier

public function setFlightSpeedMultiplier(float $flightSpeedMultiplier) : void

Sets the player’s flight speed multiplier.

flightSpeedMultiplier

float

required

Flight speed multiplier (default: 0.05)

// Example: Increase flight speed
$player->setFlightSpeedMultiplier(0.1); // 2x speed

getFlightSpeedMultiplier

public function getFlightSpeedMultiplier() : float

Returns the flight speed multiplier.

Permissions

hasPermission

public function hasPermission(string|Permission $name) : bool

Returns whether the player has a permission.

name

string|Permission

required

Permission name or object

// Example: Check permission
if($player->hasPermission("server.command.admin")){
    // Player has permission
}

addAttachment

public function addAttachment(Plugin $plugin, ?string $name = null, ?bool $value = null) : PermissionAttachment

Adds a permission attachment.

plugin

Plugin

required

Plugin adding the attachment

name

string|null

Permission name

value

bool|null

Permission value

// Example: Add temporary permission
$attachment = $player->addAttachment($this);
$attachment->setPermission("custom.permission", true);

// Remove later
$player->removeAttachment($attachment);

isOp

public function isOp() : bool

Returns whether the player is an operator.

setOp

public function setOp(bool $value) : void

Sets the player’s operator status.

Experience & Levels

getXpLevel

public function getXpLevel() : int

Returns the player’s experience level.

setXpLevel

public function setXpLevel(int $level) : void

Sets the player’s experience level.

level

int

required

Experience level to set

// Example: Set level
$player->setXpLevel(50);

getXpProgress

public function getXpProgress() : float

Returns progress to next level (0.0-1.0).

setXpProgress

public function setXpProgress(float $progress) : void

Sets progress to next level.

progress

float

required

Progress value (0.0-1.0)

getCurrentTotalXp

public function getCurrentTotalXp() : int

Returns total XP points.

setCurrentTotalXp

public function setCurrentTotalXp(int $amount) : void

Sets total XP points.

addXpLevels

public function addXpLevels(int $amount) : void

Adds experience levels.

amount

int

required

Levels to add (can be negative)

// Example: Give XP
$player->addXpLevels(5);

// Remove XP
$player->addXpLevels(-5);

Hunger & Health

getHungerManager

public function getHungerManager() : HungerManager

Returns the hunger manager.

return

HungerManager

The hunger manager

// Example: Manage hunger
$hunger = $player->getHungerManager();
$hunger->setFood(20);
$hunger->setSaturation(20.0);
$hunger->setExhaustion(0.0);

getExperienceManager

public function getExperienceManager() : ExperienceManager

Returns the experience manager.

Spawn & Death

getSpawn

public function getSpawn() : Position

Returns the player’s spawn position.

setSpawn

public function setSpawn(?Position $pos) : void

Sets the player’s spawn position.

pos

Position|null

required

Spawn position (null to use world spawn)

// Example: Set spawn at current position
$player->setSpawn($player->getPosition());

// Reset to world spawn
$player->setSpawn(null);

respawn

public function respawn() : void

Respawns the player.

// Example: Force respawn
if(!$player->isAlive()){
    $player->respawn();
}

View Distance

getViewDistance

public function getViewDistance() : int

Returns the player’s view distance.

setViewDistance

public function setViewDistance(int $distance) : void

Sets the player’s view distance.

distance

int

required

View distance in chunks

// Example: Set view distance
$player->setViewDistance(8);

Forms & UI

sendForm

public function sendForm(Form $form) : void

Sends a form to the player.

form

Form

required

Form to send

use pocketmine\form\SimpleForm;

// Example: Send simple form
$form = new SimpleForm(function(Player $player, ?int $data){
    if($data === null){
        // Form closed
        return;
    }
    
    // Button clicked
    $player->sendMessage("You clicked button $data");
});

$form->setTitle("Example Form");
$form->setContent("Choose an option:");
$form->addButton("Option 1");
$form->addButton("Option 2");

$player->sendForm($form);

Window Management

getCurrentWindow

public function getCurrentWindow() : ?Inventory

Returns the currently open window.

removeCurrentWindow

public function removeCurrentWindow() : void

Closes the current window.

// Example: Close current window
if($player->getCurrentWindow() !== null){
    $player->removeCurrentWindow();
}

Visibility

canSee

public function canSee(Player $player) : bool

Returns whether this player can see another player.

hidePlayer

public function hidePlayer(Player $player) : void

Hides another player from this player.

player

Player

required

Player to hide

// Example: Hide player
$player->hidePlayer($otherPlayer);

showPlayer

public function showPlayer(Player $player) : void

Shows a previously hidden player.

player

Player

required

Player to show

// Example: Show player
$player->showPlayer($otherPlayer);

Locale & Language

getLocale

public function getLocale() : string

Returns the player’s locale (e.g., “en_US”).

return

string

The locale string

// Example: Check locale
$locale = $player->getLocale();
if($locale === "es_ES"){
    $player->sendMessage("¡Hola!");
} else {
    $player->sendMessage("Hello!");
}

Timing & Statistics

getFirstPlayed

public function getFirstPlayed() : ?int

Returns timestamp of first join.

return

int|null

Unix timestamp in milliseconds

getLastPlayed

public function getLastPlayed() : ?int

Returns timestamp of last join.

hasPlayedBefore

public function hasPlayedBefore() : bool

Returns whether the player has played before.

Common Usage Patterns

Welcome Message

use pocketmine\event\player\PlayerJoinEvent;

public function onJoin(PlayerJoinEvent $event) : void{
    $player = $event->getPlayer();
    
    if(!$player->hasPlayedBefore()){
        $player->sendTitle("§6Welcome!", "§eTo our server");
        $player->sendMessage("§aWelcome to the server, " . $player->getName() . "!");
    } else {
        $player->sendMessage("§aWelcome back!");
    }
}

Kit System

use pocketmine\item\VanillaItems;

public function giveKit(Player $player, string $kitName) : void{
    switch($kitName){
        case "starter":
            $player->getInventory()->addItem(
                VanillaItems::STONE_SWORD(),
                VanillaItems::STONE_PICKAXE(),
                VanillaItems::BREAD()->setCount(16)
            );
            break;
            
        case "warrior":
            $player->getInventory()->addItem(
                VanillaItems::DIAMOND_SWORD(),
                VanillaItems::BOW(),
                VanillaItems::ARROW()->setCount(64)
            );
            
            $armor = $player->getArmorInventory();
            $armor->setHelmet(VanillaItems::DIAMOND_HELMET());
            $armor->setChestplate(VanillaItems::DIAMOND_CHESTPLATE());
            $armor->setLeggings(VanillaItems::DIAMOND_LEGGINGS());
            $armor->setBoots(VanillaItems::DIAMOND_BOOTS());
            break;
    }
    
    $player->sendMessage("§aKit '$kitName' received!");
}

use pocketmine\network\mcpe\protocol\RemoveObjectivePacket;
use pocketmine\network\mcpe\protocol\SetDisplayObjectivePacket;
use pocketmine\network\mcpe\protocol\SetScorePacket;
use pocketmine\network\mcpe\protocol\types\ScorePacketEntry;

public function updateScoreboard(Player $player) : void{
    // Remove old scoreboard
    $pk = new RemoveObjectivePacket();
    $pk->objectiveName = "sidebar";
    $player->getNetworkSession()->sendDataPacket($pk);
    
    // Create new scoreboard
    $pk = new SetDisplayObjectivePacket();
    $pk->displaySlot = "sidebar";
    $pk->objectiveName = "sidebar";
    $pk->displayName = "§6Server Stats";
    $pk->criteriaName = "dummy";
    $pk->sortOrder = 0;
    $player->getNetworkSession()->sendDataPacket($pk);
    
    // Add lines
    $lines = [
        "§7-------------------",
        "§eName: §f" . $player->getName(),
        "§eLevel: §f" . $player->getXpLevel(),
        "§7-------------------"
    ];
    
    $pk = new SetScorePacket();
    $pk->type = SetScorePacket::TYPE_CHANGE;
    
    foreach($lines as $i => $line){
        $entry = new ScorePacketEntry();
        $entry->objectiveName = "sidebar";
        $entry->type = ScorePacketEntry::TYPE_FAKE_PLAYER;
        $entry->customName = $line;
        $entry->score = count($lines) - $i;
        $entry->scoreboardId = $i;
        $pk->entries[] = $entry;
    }
    
    $player->getNetworkSession()->sendDataPacket($pk);
}

Permission Management

public function giveTemporaryPermission(Player $player, string $permission, int $duration) : void{
    $attachment = $player->addAttachment($this);
    $attachment->setPermission($permission, true);
    
    $player->sendMessage("§aYou have been granted temporary permission: $permission");
    
    // Remove after duration
    $this->getScheduler()->scheduleDelayedTask(new ClosureTask(
        function() use ($player, $attachment, $permission) : void{
            if($player->isOnline()){
                $player->removeAttachment($attachment);
                $player->sendMessage("§cYour temporary permission has expired: $permission");
            }
        }
    ), $duration * 20); // Convert seconds to ticks
}

Completed World & Gameplay API pages in api/ directory

Core API

World & Gameplay

Events

Utilities

​Overview

​Player Class

​Identity & Authentication

​getName

​getDisplayName

​setDisplayName

​getUniqueId

​getXuid

​isAuthenticated

​Communication

​sendMessage

​sendPopup

​sendTip

​sendTitle

​sendActionBarMessage

​Connection & Session

​isOnline

​isConnected

​kick

​transfer

​Inventory & Items

​getInventory

​getArmorInventory

​getEnderInventory

​getCursorInventory

​Game Mode

​getGamemode

​setGamemode

​isCreative

​isSurvival

​isSpectator

​isAdventure

​Movement & Teleportation

​teleport

​getAllowFlight

​setAllowFlight

​isFlying

​setFlying

​setFlightSpeedMultiplier

​getFlightSpeedMultiplier

​Permissions

​hasPermission

​addAttachment

​isOp

​setOp

​Experience & Levels

​getXpLevel

​setXpLevel

​getXpProgress

​setXpProgress

​getCurrentTotalXp

​setCurrentTotalXp

​addXpLevels

​Hunger & Health

​getHungerManager

​getExperienceManager

​Spawn & Death

​getSpawn

​setSpawn

​respawn

​View Distance

​getViewDistance

​setViewDistance

​Forms & UI

​sendForm

​Window Management

​getCurrentWindow

​removeCurrentWindow

​Visibility

​canSee

​hidePlayer

​showPlayer

​Locale & Language

​getLocale

​Timing & Statistics

​getFirstPlayed

Overview

Player Class

Identity & Authentication

getName

getDisplayName

setDisplayName

getUniqueId

getXuid

isAuthenticated

Communication

sendMessage

sendPopup

sendTip

sendTitle

sendActionBarMessage

Connection & Session

isOnline

isConnected

kick

transfer

Inventory & Items

getInventory

getArmorInventory

getEnderInventory

getCursorInventory

Game Mode

getGamemode

setGamemode

isCreative

isSurvival

isSpectator

isAdventure

Movement & Teleportation

teleport

getAllowFlight

setAllowFlight

isFlying

setFlying

setFlightSpeedMultiplier

getFlightSpeedMultiplier

Permissions

hasPermission

addAttachment

isOp

setOp

Experience & Levels

getXpLevel

setXpLevel

getXpProgress

setXpProgress

getCurrentTotalXp

setCurrentTotalXp

addXpLevels

Hunger & Health

getHungerManager

getExperienceManager

Spawn & Death

getSpawn

setSpawn

respawn

View Distance

getViewDistance

setViewDistance

Forms & UI

sendForm

Window Management

getCurrentWindow

removeCurrentWindow

Visibility

canSee

hidePlayer

showPlayer

Locale & Language

getLocale

Timing & Statistics

getFirstPlayed

getLastPlayed

hasPlayedBefore

Common Usage Patterns

Welcome Message