Player Events

Events related to player actions, connections, movement, and interactions

Player events are fired when players perform actions or undergo state changes. All player events extend the PlayerEvent base class.

PlayerEvent Base Class

All player events inherit from this class:

getPlayer() · Player

Returns the player involved in the event

Connection Events

PlayerPreLoginEvent

Cancellable: Yes

Called before a player is authenticated. Use this for custom authentication or IP bans.

public function onPreLogin(PlayerPreLoginEvent $event) : void {
    $playerInfo = $event->getPlayerInfo();
    $ip = $event->getIp();
    
    if ($this->isIpBanned($ip)) {
        $event->setKickFlag(PlayerPreLoginEvent::KICK_FLAG_BANNED, "You are banned");
    }
}

Methods:

• getPlayerInfo() - Returns player information
• getIp() - Returns player’s IP address
• getPort() - Returns connection port
• setKickFlag(int $flag, Translatable|string $reason) - Kicks the player with a reason

PlayerLoginEvent

Cancellable: Yes

Called when a player logs in, after authentication but before they spawn.

public function onLogin(PlayerLoginEvent $event) : void {
    $player = $event->getPlayer();
    
    if (!$this->isWhitelisted($player->getName())) {
        $event->setKickMessage("You are not whitelisted");
        $event->cancel();
    }
}

Methods:

• getPlayer() - Returns the player
• setKickMessage(Translatable|string $message) - Sets kick message
• getKickMessage() - Gets kick message

PlayerJoinEvent

Cancellable: No

Called when a player spawns in the world after logging in.

public function onJoin(PlayerJoinEvent $event) : void {
    $player = $event->getPlayer();
    $event->setJoinMessage("§e" . $player->getName() . " joined the game");
}

Methods:

• getJoinMessage() - Returns the join message
• setJoinMessage(Translatable|string $message) - Sets the join message

PlayerQuitEvent

Cancellable: No

Called when a player disconnects from the server.

public function onQuit(PlayerQuitEvent $event) : void {
    $player = $event->getPlayer();
    $event->setQuitMessage($player->getName() . " left the game");
    $this->savePlayerData($player);
}

Methods:

• getQuitMessage() - Returns the quit message
• setQuitMessage(Translatable|string $message) - Sets the quit message
• getDisconnectReason() - Returns the disconnect reason

PlayerKickEvent

Cancellable: Yes

Called when a player is kicked from the server.

public function onKick(PlayerKickEvent $event) : void {
    $reason = $event->getDisconnectReason();
    
    if ($reason === "Flying is not enabled") {
        $event->cancel(); // Forgive the player
    }
}

Methods:

• getDisconnectReason() - Returns the kick reason
• getQuitMessage() - Returns the quit message
• setQuitMessage(Translatable|string $message) - Sets the quit message
• getDisconnectScreenMessage() - Returns message shown to kicked player

Movement Events

PlayerMoveEvent

Cancellable: Yes

Called when a player moves. Warning: This event is called very frequently!

public function onMove(PlayerMoveEvent $event) : void {
    $from = $event->getFrom();
    $to = $event->getTo();
    
    if ($this->isProtectedArea($to)) {
        $event->cancel(); // Prevent movement
    }
}

Methods:

• getFrom() - Returns the location the player is moving from
• getTo() - Returns the location the player is moving to
• setTo(Location $to) - Changes the destination location

PlayerJumpEvent

Cancellable: No

Called when a player jumps.

public function onJump(PlayerJumpEvent $event) : void {
    $player = $event->getPlayer();
    $player->sendTip("You jumped!");
}

PlayerToggleFlightEvent

Cancellable: Yes

Called when a player toggles flight mode.

public function onToggleFlight(PlayerToggleFlightEvent $event) : void {
    $player = $event->getPlayer();
    
    if ($event->isFlying() && !$player->hasPermission("myplugin.fly")) {
        $event->cancel();
        $player->sendMessage("You don't have permission to fly");
    }
}

Methods:

• isFlying() - Returns whether the player is starting to fly

PlayerToggleSneakEvent

Cancellable: Yes

Called when a player starts or stops sneaking.

Methods:

• isSneaking() - Returns whether the player is starting to sneak

PlayerToggleSprintEvent

Cancellable: Yes

Called when a player starts or stops sprinting.

Methods:

• isSprinting() - Returns whether the player is starting to sprint

PlayerToggleGlideEvent

Cancellable: Yes

Called when a player starts or stops gliding with elytra.

Methods:

• isGliding() - Returns whether the player is starting to glide

PlayerToggleSwimEvent

Cancellable: Yes

Called when a player starts or stops swimming.

Methods:

• isSwimming() - Returns whether the player is starting to swim

Interaction Events

PlayerInteractEvent

Cancellable: Yes

Called when a player interacts with a block (left or right click).

public function onInteract(PlayerInteractEvent $event) : void {
    $player = $event->getPlayer();
    $block = $event->getBlock();
    $item = $event->getItem();
    
    if ($event->getAction() === PlayerInteractEvent::RIGHT_CLICK_BLOCK) {
        if ($block instanceof Door) {
            // Player right-clicked a door
        }
    }
}

Constants:

• LEFT_CLICK_BLOCK (0) - Player left-clicked
• RIGHT_CLICK_BLOCK (1) - Player right-clicked

Methods:

• getAction() - Returns the action type
• getItem() - Returns the item in hand
• getBlock() - Returns the block that was touched
• getTouchVector() - Returns the exact position touched
• getFace() - Returns the block face that was touched
• useItem() - Returns whether the item may react
• setUseItem(bool $use) - Sets whether the item may react
• useBlock() - Returns whether the block may react
• setUseBlock(bool $use) - Sets whether the block may react

PlayerItemUseEvent

Cancellable: Yes

Called when a player uses an item (right-clicks while holding it).

public function onItemUse(PlayerItemUseEvent $event) : void {
    $item = $event->getItem();
    
    if ($item instanceof EnderPearl) {
        // Player used an ender pearl
    }
}

Methods:

• getItem() - Returns the item being used
• getDirectionVector() - Returns the direction the player is facing

PlayerItemHeldEvent

Cancellable: Yes

Called when a player changes their held item slot.

public function onItemHeld(PlayerItemHeldEvent $event) : void {
    $player = $event->getPlayer();
    $newSlot = $event->getSlot();
    $item = $event->getItem();
    
    $player->sendTip("Selected: " . $item->getName());
}

Methods:

• getItem() - Returns the item being held
• getSlot() - Returns the hotbar slot number (0-8)

PlayerItemConsumeEvent

Cancellable: Yes

Called when a player finishes consuming an item (eating food, drinking potions).

public function onConsume(PlayerItemConsumeEvent $event) : void {
    $item = $event->getItem();
    
    if ($item instanceof GoldenApple) {
        $event->getPlayer()->sendMessage("Yummy!");
    }
}

Methods:

• getItem() - Returns the item being consumed

PlayerDropItemEvent

Cancellable: Yes

Called when a player drops an item.

public function onDrop(PlayerDropItemEvent $event) : void {
    $item = $event->getItem();
    
    if ($item->hasTag("no_drop")) {
        $event->cancel();
    }
}

Methods:

• getItem() - Returns the dropped item entity

PlayerEntityInteractEvent

Cancellable: Yes

Called when a player interacts with an entity.

public function onEntityInteract(PlayerEntityInteractEvent $event) : void {
    $entity = $event->getEntity();
    
    if ($entity instanceof Villager) {
        // Player interacted with a villager
    }
}

Methods:

• getEntity() - Returns the entity that was interacted with
• getTouchVector() - Returns the touch position

Combat Events

PlayerDeathEvent

Cancellable: No

Called when a player dies.

public function onDeath(PlayerDeathEvent $event) : void {
    $player = $event->getPlayer();
    $event->setDeathMessage($player->getName() . " died");
    $event->setDrops([]); // Clear drops
}

Methods:

• getDeathMessage() - Returns the death message
• setDeathMessage(Translatable|string $message) - Sets the death message
• getDrops() - Returns array of dropped items
• setDrops(array $drops) - Sets the dropped items
• getXpDropAmount() - Returns XP to drop
• setXpDropAmount(int $amount) - Sets XP to drop

PlayerRespawnEvent

Cancellable: No

Called when a player respawns after death.

public function onRespawn(PlayerRespawnEvent $event) : void {
    $spawn = $this->getCustomSpawn();
    $event->setRespawnPosition($spawn);
}

Methods:

• getRespawnPosition() - Returns the respawn position
• setRespawnPosition(Position $position) - Sets the respawn position

Communication Events

PlayerChatEvent

Cancellable: Yes

Called when a player sends a chat message.

public function onChat(PlayerChatEvent $event) : void {
    $message = $event->getMessage();
    
    if ($this->containsBadWords($message)) {
        $event->cancel();
        $event->getPlayer()->sendMessage("Watch your language!");
        return;
    }
    
    // Modify the message
    $event->setMessage(strtoupper($message));
}

Methods:

• getMessage() - Returns the chat message
• setMessage(string $message) - Sets the chat message
• getRecipients() - Returns array of CommandSenders who will receive the message
• setRecipients(array $recipients) - Sets the message recipients
• getFormatter() - Returns the chat formatter
• setFormatter(ChatFormatter $formatter) - Sets the chat formatter

PlayerEmoteEvent

Cancellable: Yes

Called when a player uses an emote.

Methods:

• getEmoteId() - Returns the emote ID

Game State Events

PlayerGameModeChangeEvent

Cancellable: Yes

Called when a player’s game mode changes.

public function onGameModeChange(PlayerGameModeChangeEvent $event) : void {
    $newGameMode = $event->getNewGameMode();
    
    if ($newGameMode === GameMode::CREATIVE() && 
        !$event->getPlayer()->hasPermission("myplugin.creative")) {
        $event->cancel();
    }
}

Methods:

• getNewGameMode() - Returns the new GameMode

PlayerExperienceChangeEvent

Cancellable: Yes

Called when a player’s experience changes.

Methods:

• getExpDifference() - Returns the XP change amount
• setExpDifference(int|float $amount) - Sets the XP change amount
• getOldProgress() - Returns old progress to next level
• getOldLevel() - Returns old XP level

PlayerExhaustEvent

Cancellable: Yes

Called when a player’s food exhaustion increases.

Methods:

• getAmount() - Returns exhaustion amount
• setAmount(float $amount) - Sets exhaustion amount
• getCause() - Returns the exhaustion cause

Complete Event List

Other player events not detailed above:

• PlayerBedEnterEvent - Player enters a bed
• PlayerBedLeaveEvent - Player leaves a bed
• PlayerBlockPickEvent - Player picks a block (middle-click)
• PlayerBucketEmptyEvent - Player empties a bucket
• PlayerBucketFillEvent - Player fills a bucket
• PlayerChangeSkinEvent - Player changes their skin
• PlayerCreationEvent - Before player object is created
• PlayerDataSaveEvent - Before player data is saved
• PlayerDisplayNameChangeEvent - Player’s display name changes
• PlayerDuplicateLoginEvent - Player tries to login while already online
• PlayerEditBookEvent - Player edits a book
• PlayerEnchantingOptionsRequestEvent - Player opens enchanting table
• PlayerEntityPickEvent - Player picks an entity (middle-click)
• PlayerItemEnchantEvent - Player enchants an item
• PlayerMissSwingEvent - Player swings at air
• PlayerPostChunkSendEvent - After chunk is sent to player
• PlayerResourcePackOfferEvent - Server offers resource pack to player
• PlayerRespawnAnchorUseEvent - Player uses a respawn anchor
• PlayerTransferEvent - Player is transferred to another server
• PlayerViewDistanceChangeEvent - Player’s view distance changes