Entity Events

Entity events are fired when entities perform actions or change state. All entity events extend the EntityEvent base class.

EntityEvent Base Class

All entity events inherit from this class:

getEntity()

Entity

Returns the entity involved in the event

Damage Events

EntityDamageEvent

Cancellable: YesCalled when an entity takes damage from any source.

public function onEntityDamage(EntityDamageEvent $event) : void {
    $entity = $event->getEntity();
    $cause = $event->getCause();
    $damage = $event->getFinalDamage();
    
    // Prevent fall damage
    if ($cause === EntityDamageEvent::CAUSE_FALL) {
        $event->cancel();
        return;
    }
    
    // Reduce damage
    $event->setBaseDamage($event->getBaseDamage() * 0.5);
    
    // Modify damage modifiers
    if ($event->isApplicable(EntityDamageEvent::MODIFIER_ARMOR)) {
        $event->setModifier(
            $event->getModifier(EntityDamageEvent::MODIFIER_ARMOR) * 2.0,
            EntityDamageEvent::MODIFIER_ARMOR
        );
    }
}

Damage Causes:

CAUSE_CONTACT (0) - Contact with cactus, etc.
CAUSE_ENTITY_ATTACK (1) - Entity melee attack
CAUSE_PROJECTILE (2) - Projectile hit
CAUSE_SUFFOCATION (3) - Suffocating in blocks
CAUSE_FALL (4) - Fall damage
CAUSE_FIRE (5) - Standing in fire
CAUSE_FIRE_TICK (6) - Being on fire
CAUSE_LAVA (7) - Standing in lava
CAUSE_DROWNING (8) - Drowning
CAUSE_BLOCK_EXPLOSION (9) - Block explosion (TNT)
CAUSE_ENTITY_EXPLOSION (10) - Entity explosion (Creeper)
CAUSE_VOID (11) - Void damage
CAUSE_SUICIDE (12) - /kill command
CAUSE_MAGIC (13) - Magic/potion damage
CAUSE_CUSTOM (14) - Custom damage
CAUSE_STARVATION (15) - Hunger
CAUSE_FALLING_BLOCK (16) - Hit by falling block

Damage Modifiers:

MODIFIER_ARMOR (1) - Armor protection
MODIFIER_STRENGTH (2) - Strength effect
MODIFIER_WEAKNESS (3) - Weakness effect
MODIFIER_RESISTANCE (4) - Resistance effect
MODIFIER_ABSORPTION (5) - Absorption hearts
MODIFIER_ARMOR_ENCHANTMENTS (6) - Protection enchantments
MODIFIER_CRITICAL (7) - Critical hit
MODIFIER_TOTEM (8) - Totem of Undying
MODIFIER_WEAPON_ENCHANTMENTS (9) - Sharpness, etc.
MODIFIER_PREVIOUS_DAMAGE_COOLDOWN (10) - Damage cooldown
MODIFIER_ARMOR_HELMET (11) - Helmet specific

Methods:

getCause() - Returns the damage cause
getBaseDamage() - Returns base damage before modifiers
setBaseDamage(float $damage) - Sets base damage
getOriginalBaseDamage() - Returns original base damage
getModifiers() - Returns all damage modifiers
getModifier(int $type) - Returns specific modifier
setModifier(float $damage, int $type) - Sets a modifier
isApplicable(int $type) - Checks if modifier is applicable
getFinalDamage() - Returns final damage after modifiers
canBeReducedByArmor() - Returns whether armor can reduce this damage
getAttackCooldown() - Returns attack cooldown in ticks
setAttackCooldown(int $cooldown) - Sets attack cooldown

EntityDamageByEntityEvent

Cancellable: YesCalled when an entity takes damage from another entity. Extends EntityDamageEvent.

public function onDamageByEntity(EntityDamageByEntityEvent $event) : void {
    $entity = $event->getEntity();
    $damager = $event->getDamager();
    
    if ($damager instanceof Player) {
        // Player attacked the entity
        $damager->sendMessage("You hit " . $entity->getName());
    }
    
    // Modify knockback
    $event->setKnockBack(2.0); // Stronger knockback
    $event->setVerticalKnockBackLimit(0.5);
}

Methods:

getDamager() - Returns the attacking entity (or null if dead)
getKnockBack() - Returns knockback force
setKnockBack(float $force) - Sets knockback force
getVerticalKnockBackLimit() - Returns max upward velocity
setVerticalKnockBackLimit(float $limit) - Sets max upward velocity
All methods from EntityDamageEvent

EntityDamageByChildEntityEvent

Cancellable: YesCalled when an entity takes damage from a child entity (e.g., arrow shot by skeleton).

public function onDamageByChild(EntityDamageByChildEntityEvent $event) : void {
    $victim = $event->getEntity();
    $projectile = $event->getChild(); // The arrow
    $shooter = $event->getDamager(); // The skeleton
    
    if ($shooter instanceof Skeleton && $victim instanceof Player) {
        // Skeleton shot a player
    }
}

Methods:

getChild() - Returns the child entity (e.g., arrow)
All methods from EntityDamageByEntityEvent

EntityDamageByBlockEvent

Cancellable: YesCalled when an entity takes damage from a block (cactus, magma).Methods:

getDamager() - Returns the damaging block
All methods from EntityDamageEvent

Life Cycle Events

EntitySpawnEvent

Cancellable: YesCalled when an entity spawns in the world.

public function onEntitySpawn(EntitySpawnEvent $event) : void {
    $entity = $event->getEntity();
    
    // Prevent zombie spawning
    if ($entity instanceof Zombie) {
        $event->cancel();
    }
}

EntityDespawnEvent

Cancellable: NoCalled when an entity is despawned (removed from the world).

public function onEntityDespawn(EntityDespawnEvent $event) : void {
    $entity = $event->getEntity();
    $entityType = $event->getEntityType();
    
    // Log entity despawn
    $this->getLogger()->info("Entity despawned: " . $entityType->getName());
}

Methods:

getEntityType() - Returns the EntityTypeInterface

EntityDeathEvent

Cancellable: NoCalled when an entity dies.

public function onEntityDeath(EntityDeathEvent $event) : void {
    $entity = $event->getEntity();
    $drops = $event->getDrops();
    
    // Add extra drops
    $drops[] = VanillaItems::DIAMOND()->setCount(5);
    $event->setDrops($drops);
    
    // Modify XP
    $event->setXpDropAmount(100);
}

Methods:

getDrops() - Returns array of dropped items
setDrops(array $drops) - Sets dropped items
getXpDropAmount() - Returns XP to drop
setXpDropAmount(int $amount) - Sets XP to drop

Movement Events

EntityTeleportEvent

Cancellable: YesCalled when an entity teleports.

public function onEntityTeleport(EntityTeleportEvent $event) : void {
    $entity = $event->getEntity();
    $from = $event->getFrom();
    $to = $event->getTo();
    
    // Prevent teleporting to certain worlds
    if ($to->getWorld()->getFolderName() === "nether") {
        $event->cancel();
    }
    
    // Modify destination
    $event->setTo($to->add(0, 10, 0)); // Teleport 10 blocks higher
}

Methods:

getFrom() - Returns origin position
getTo() - Returns destination position
setTo(Position $to) - Sets destination position

EntityMotionEvent

Cancellable: YesCalled when an entity’s motion changes.

public function onEntityMotion(EntityMotionEvent $event) : void {
    $entity = $event->getEntity();
    $motion = $event->getVector();
    
    // Limit upward motion
    if ($motion->y > 2.0) {
        $event->setVector(new Vector3($motion->x, 2.0, $motion->z));
    }
}

Methods:

getVector() - Returns the motion vector
setVector(Vector3 $motion) - Sets the motion vector

Status Effects

EntityEffectAddEvent

Cancellable: YesCalled when an effect is added to an entity.

public function onEffectAdd(EntityEffectAddEvent $event) : void {
    $entity = $event->getEntity();
    $effect = $event->getEffect();
    
    // Prevent poison
    if ($effect->getType() === VanillaEffects::POISON()) {
        $event->cancel();
    }
}

Methods:

getEffect() - Returns the EffectInstance
getOldEffect() - Returns previous effect (or null)

EntityEffectRemoveEvent

Cancellable: YesCalled when an effect is removed from an entity.Methods:

getEffect() - Returns the EffectInstance being removed

Combat Events

EntityRegainHealthEvent

Cancellable: YesCalled when an entity regains health.

public function onRegainHealth(EntityRegainHealthEvent $event) : void {
    $entity = $event->getEntity();
    $amount = $event->getAmount();
    $reason = $event->getRegainReason();
    
    if ($reason === EntityRegainHealthEvent::CAUSE_EATING) {
        // Double healing from food
        $event->setAmount($amount * 2.0);
    }
}

Causes:

CAUSE_SATURATION - Saturation effect
CAUSE_EATING - Eating food
CAUSE_MAGIC - Instant Health potion
CAUSE_REGEN - Regeneration effect
CAUSE_CUSTOM - Custom healing

Methods:

getAmount() - Returns health regained
setAmount(float $amount) - Sets health regained
getRegainReason() - Returns the cause

EntityShootBowEvent

Cancellable: YesCalled when an entity shoots a bow.

public function onShootBow(EntityShootBowEvent $event) : void {
    $shooter = $event->getEntity();
    $projectile = $event->getProjectile();
    $force = $event->getForce();
    
    // Increase arrow speed
    $projectile->setMotion($projectile->getMotion()->multiply(2.0));
}

Methods:

getBow() - Returns the bow item
getProjectile() - Returns the projectile entity
getForce() - Returns shot force (0.0-1.0)

Combustion Events

EntityCombustEvent

Cancellable: YesCalled when an entity catches fire.

public function onCombust(EntityCombustEvent $event) : void {
    $entity = $event->getEntity();
    $duration = $event->getDuration();
    
    // Prevent zombies from burning
    if ($entity instanceof Zombie) {
        $event->cancel();
    }
}

Methods:

getDuration() - Returns burn duration in seconds
setDuration(int $duration) - Sets burn duration

EntityCombustByBlockEvent

Cancellable: YesCalled when an entity is set on fire by a block (lava, fire).Methods:

getCombustor() - Returns the block causing combustion

EntityCombustByEntityEvent

Cancellable: YesCalled when an entity is set on fire by another entity.Methods:

getCombustor() - Returns the entity causing combustion

EntityExtinguishEvent

Cancellable: YesCalled when an entity’s fire is extinguished.

Explosion Events

EntityExplodeEvent

Cancellable: YesCalled when an entity explodes (Creeper, TNT, etc.).

public function onEntityExplode(EntityExplodeEvent $event) : void {
    $entity = $event->getEntity();
    $blockList = $event->getBlockList();
    
    if ($entity instanceof Creeper) {
        // Prevent creeper explosions from destroying blocks
        $event->setBlockList([]);
    }
}

Methods:

getBlockList() - Returns blocks that will be destroyed
setBlockList(array $blocks) - Sets blocks to destroy
getYieldDrops() - Returns whether blocks drop items
setYieldDrops(bool $yield) - Sets whether blocks drop items

EntityPreExplodeEvent

Cancellable: YesCalled before an entity explosion, allows modifying affected blocks.Methods:

getAffectedBlocks() - Returns blocks that will be affected
setAffectedBlocks(array $blocks) - Sets blocks to affect

Item Entity Events

ItemSpawnEvent

Cancellable: YesCalled when an item entity spawns.

public function onItemSpawn(ItemSpawnEvent $event) : void {
    $item = $event->getEntity();
    $itemStack = $item->getItem();
    
    // Prevent diamond drops
    if ($itemStack->getTypeId() === ItemTypeIds::DIAMOND) {
        $event->cancel();
    }
}

ItemDespawnEvent

Cancellable: YesCalled when an item entity despawns after 5 minutes.

public function onItemDespawn(ItemDespawnEvent $event) : void {
    $item = $event->getEntity();
    
    // Prevent important items from despawning
    if ($item->getItem()->hasTag("important")) {
        $event->cancel();
    }
}

ItemMergeEvent

Cancellable: YesCalled when two item entities merge into one.Methods:

getTarget() - Returns the other item entity

EntityItemPickupEvent

Cancellable: YesCalled when an entity picks up an item.

public function onItemPickup(EntityItemPickupEvent $event) : void {
    $entity = $event->getEntity();
    $item = $event->getItem();
    $origin = $event->getOrigin();
    
    if ($entity instanceof Player) {
        $entity->sendMessage("You picked up " . $item->getItem()->getName());
    }
}

Methods:

getOrigin() - Returns the item entity
getItem() - Returns the item stack
getInventory() - Returns the receiving inventory

Projectile Events

ProjectileLaunchEvent

Cancellable: YesCalled when a projectile is launched.

public function onProjectileLaunch(ProjectileLaunchEvent $event) : void {
    $projectile = $event->getEntity();
    
    if ($projectile instanceof Arrow) {
        // Modify arrow properties
        $projectile->setOnFire(20 * 100); // Set on fire
    }
}

ProjectileHitEvent

Cancellable: NoBase event called when a projectile hits something.Methods:

getRayTraceResult() - Returns the ray trace hit result

ProjectileHitBlockEvent

Cancellable: NoCalled when a projectile hits a block.Methods:

getBlockHit() - Returns the hit block
getRayTraceResult() - Returns hit details

ProjectileHitEntityEvent

Cancellable: NoCalled when a projectile hits an entity.Methods:

getEntityHit() - Returns the hit entity
getRayTraceResult() - Returns hit details

Special Events

EntityBlockChangeEvent

Cancellable: YesCalled when an entity changes a block (enderman picking up blocks, sheep eating grass).Methods:

getBlock() - Returns the affected block
getTo() - Returns the new block state

EntityTrampleFarmlandEvent

Cancellable: YesCalled when an entity tramples farmland into dirt.Methods:

getBlock() - Returns the farmland block

EntityFrostWalkerEvent

Cancellable: YesCalled when an entity with Frost Walker creates ice.Methods:

getBlockPositions() - Returns positions that will turn to ice

AreaEffectCloudApplyEvent

Cancellable: YesCalled when an area effect cloud applies effects to entities.Methods:

getRecipients() - Returns affected entities
setRecipients(array $entities) - Sets affected entities

Core API

World & Gameplay

Events

Utilities

EntityEvent Base Class

Damage Events

Life Cycle Events

Movement Events

Status Effects

Combat Events

Combustion Events

Explosion Events

Item Entity Events

Projectile Events

Special Events

Build docs developers (and LLMs) love

Core API

World & Gameplay

Events

Utilities

​EntityEvent Base Class

​Damage Events

​Life Cycle Events

​Movement Events

​Status Effects

​Combat Events

​Combustion Events

​Explosion Events

​Item Entity Events

​Projectile Events

​Special Events

Build docs developers (and LLMs) love

EntityEvent Base Class

Damage Events

Life Cycle Events

Movement Events

Status Effects

Combat Events

Combustion Events

Explosion Events

Item Entity Events

Projectile Events

Special Events