Skip to main content
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

Cancellable: YesCalled 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
Cancellable: YesCalled 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
Cancellable: NoCalled 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
Cancellable: NoCalled 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
Cancellable: YesCalled 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

Cancellable: YesCalled 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
Cancellable: NoCalled when a player jumps.
public function onJump(PlayerJumpEvent $event) : void {
    $player = $event->getPlayer();
    $player->sendTip("You jumped!");
}
Cancellable: YesCalled 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
Cancellable: YesCalled when a player starts or stops sneaking.Methods:
  • isSneaking() - Returns whether the player is starting to sneak
Cancellable: YesCalled when a player starts or stops sprinting.Methods:
  • isSprinting() - Returns whether the player is starting to sprint
Cancellable: YesCalled when a player starts or stops gliding with elytra.Methods:
  • isGliding() - Returns whether the player is starting to glide
Cancellable: YesCalled when a player starts or stops swimming.Methods:
  • isSwimming() - Returns whether the player is starting to swim

​
Interaction Events

Cancellable: YesCalled 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
Cancellable: YesCalled 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
Cancellable: YesCalled 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)
Cancellable: YesCalled 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
Cancellable: YesCalled 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
Cancellable: YesCalled 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

Cancellable: NoCalled 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
Cancellable: NoCalled 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

Cancellable: YesCalled 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
Cancellable: YesCalled when a player uses an emote.Methods:
  • getEmoteId() - Returns the emote ID

​
Game State Events

Cancellable: YesCalled 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
Cancellable: YesCalled 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
Cancellable: YesCalled 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

Build docs developers (and LLMs) love

Get started for freeTalk to us