Core Events

Getting Started

Follow these steps to listen to events in your plugin.

1

Register Event Listeners

Create a listener class that implements Listener.

DungeonEventListener.java

import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class DungeonEventListener implements Listener {
    
    private final JavaPlugin plugin;
    
    public DungeonEventListener(JavaPlugin plugin) {
        this.plugin = plugin;
    }
}

2

Register with Event Manager

In your plugin's onEnable, register the listener.

MainPlugin.java

@Override
public void onEnable() {
    Listener eventListener = new DungeonEventListener(this);
    getServer().getPluginManager().registerEvents(eventListener, this);
    getLogger().info("Event listeners registered!");
}

Note: Ensure PhantomDungeons is listed in your plugin.yml dependencies so events are properly fired.

3

Safe Async Handling

Some events fire asynchronously. Use proper thread-safety when accessing Bukkit APIs.

AsyncHandlerExample.java

@EventHandler
public void onAsyncEvent(PlayerDamageEvent event) {
    // This event is ASYNC - don't access Bukkit APIs directly
    
    double currentDamage = event.getDamage();
    // Safe: modifying event data
    event.setDamage(currentDamage * 2);
}

Global Events

PlayerDamageEvent

Fired before each auto-hit damage is applied to a mob. Modify damage value or cancel the hit entirely.

PlayerDamageHandler.java

@EventHandler
public void onPlayerDamage(PlayerDamageEvent event) {
    Player player = event.getPlayer();
    double damage = event.getDamage();
    
    // Double damage for premium players
    if (player.hasPermission("360.skibidi.toilet.rizz")) {
        event.setDamage(damage * 2);
        player.sendMessage("§6hi mr rizzler");
    }
    
    // Cancel specific mob hits
    if (event.getMobId().equals("boogey-man")) {
        event.setCancelled(true);
        player.sendMessage("§cnope");
    }
}

---

PlayerAutoHitStartEvent

Fired when a player starts auto-hitting a mob. Customize the attack speed or prevent auto-hit entirely.

AutoHitStartHandler.java

@EventHandler
public void onAutoHitStart(PlayerAutoHitStartEvent event) {
    Player player = event.getPlayer();
    
    // Speed up attacks for cool people
    if (player.hasPermission("andrew.tate")) {
        event.setAttacksPerSecond(5.0);
        player.sendMessage("§6bugatti");
    }
    
    // Cancel for specific mobs
    if (event.getMobId().equals("untouchable-mob")) {
        event.setCancelled(true);
    }
}

---

PlayerSwingEvent

Fired when a player swings their sword. Batches multiple swings into one event for performance.

PlayerSwingHandler.java

@EventHandler
public void onPlayerSwing(PlayerSwingEvent event) {
    Player player = event.getPlayer();
    int swingCount = event.getSwingCount();
    
    if (event.isBatched() && swingCount > 10) {
        player.sendMessage("§aYou're on fire! " + swingCount + " swings!");
    }
    
    if (hasSilenceEffect(player)) {
        event.setCancelled(true);
    }
}

PlayerLevelUpEvent

Fired when a player levels up in any progression system (sword-level, prestige, etc.). Fully modifiable for boosters and reward multipliers.

PlayerLevelUpHandler.java

@EventHandler
public void onPlayerLevelUp(PlayerLevelUpEvent event) {
    Player player = event.getPlayer();
    String progression = event.getProgressionId();
    
    if (hasLevelBooster(player)) {
        event.setLevelMultiplier(2.0);
        player.sendMessage("§6Booster: Double level gains!");
    }
    
    if (event.getNewLevel() == 100) {
        player.sendMessage("§l§6MAX LEVEL ACHIEVED!");
        giveSuperReward(player);
    }
    
    if (progression.equals("prestige") && event.getNewLevel() > 50) {
        event.setCancelled(true);
        player.sendMessage("§cPrestige is capped at level 50!");
    }
}

PlayerCurrencyGainEvent

Fired before a player gains any currency (money, souls, essence, etc.). Modify rewards or cancel entirely.

CurrencyGainHandler.java

@EventHandler
public void onCurrencyGain(PlayerCurrencyGainEvent event) {
    Player player = event.getPlayer();
    String currency = event.getCurrencyId();
    double amount = event.getOriginalAmount();
    
 
    if (isNightTime()) {
        event.setMultiplier(BigDecimal.valueOf(1.5));
    }
    
  
    if (isRestrictedZone(player)) {
        event.setCancelled(true);
    }
    
 
    if (amount > 10000) {
        Bukkit.getLogger().info(player.getName() + " gained " + amount + " " + currency);
    }
}

---

EntityDeathEvent

Fired when a mob dies. Control respawning, modify currency rewards, or trigger custom logic.

Key Features:

• Contains zone, stage, and mob information

• Rewards can be modified before being added

• Can prevent respawn

EntityDeathHandler.java

@EventHandler
public void onEntityDeath(EntityDeathEvent event) {
    Player killer = event.getKiller();
    String mobId = event.getMob().getId();
    
    // Triple money drops for boss mobs
    if (mobId.contains("boss")) {
        event.multiplyCurrencyReward("money", 3.0);
        killer.sendMessage("§6§lBOSS DEFEATED! 3x rewards!");
    }
    
    // Prevent respawn for legendary mobs
    if (mobId.equals("mythic-dragon")) {
        event.setShouldRespawn(false);
    }
    
    // Apply currency penalties for low-level players
    if (killer.getLevel() < 10) {
        event.multiplyCurrencyReward("money", 0.5);
    }
}

PlayerEnchantProcAttemptEvent

Fired before an enchant's proc chance is rolled. Modify proc chance for custom logic or boosters.

EnchantProcHandler.java

@EventHandler
public void onEnchantProcAttempt(PlayerEnchantProcAttemptEvent event) {
    Player player = event.getPlayer();
    String enchantId = event.getEnchantId();
    
    if (hasEnchantBooster(player, enchantId)) {
        double boosted = event.getProcChance() * 1.5;
        event.setProcChance(Math.min(100.0, boosted)); 
        player.sendMessage("§e✦ " + enchantId + " chance boosted!");
    }
    
    if (isOnCooldown(player, enchantId)) {
        event.setProcChance(event.getProcChance() * 0.5);
    }
}

PlayerEnterZoneEvent

Fired when a player enters a zone. Can be cancelled to prevent entry.

EnterZoneHandler.java

@EventHandler
public void onPlayerEnterZone(PlayerEnterZoneEvent event) {
    Player player = event.getPlayer();
    String zoneId = event.getZoneId();
    int stage = event.getStageNumber();
    

    if (zoneId.equals("inferno") && getPlayerLevel(player) < 50) {
        event.setCancelled(true);
        player.sendMessage("§cYou must be level 50 to enter the Inferno!");
    }
    
    player.sendMessage("§e➤ Entering " + zoneId + " (Stage " + stage + ")");
}

---

PlayerLeaveZoneEvent

Fired when a player leaves a zone. Not cancellable (just informational).

LeaveZoneHandler.java

@EventHandler
public void onPlayerLeaveZone(PlayerLeaveZoneEvent event) {
    Player player = event.getPlayer();
    String zoneId = event.getZoneId();
    int stagesCompleted = event.getLastStageNumber();
    
    addZoneCompletion(player, zoneId, stagesCompleted);
    
    player.sendMessage("§e Zone progress saved!");
}

PlayerSwordUpgradeEvent

Fired when a player attempts to upgrade their sword. Modify cost, prevent upgrade, or trigger side effects.

SwordUpgradeHandler.java

@EventHandler
public void onSwordUpgrade(PlayerSwordUpgradeEvent event) {
    Player player = event.getPlayer();
    int targetTier = event.getTargetTier();
    

    if (player.hasPermission("dungeon.premium")) {
        event.setCostMultiplier(0.5);
        player.sendMessage("§6Premium: 50% cost reduction!");
    }
    
    if (isDungeonEventActive()) {
        event.setCancelled(true);
        event.setCancelMessage("§cUpgrades are disabled during events!");
    }
    
    // Track milestone upgrades
    if (event.isSwordUpgrade()) {
        Bukkit.broadcastMessage("§6" + player.getName() + " upgraded to a new sword!");
    }
}

Cool Event Stuff

Booster Multiplier Stack

Combine multiple event listeners to apply boosters:

BoosterStackHandler.java

@EventHandler(priority = EventPriority.HIGH)
public void applyBoostersToLevelUp(PlayerLevelUpEvent event) {
    Player player = event.getPlayer();
    
    // Check all active boosters
    double totalMultiplier = 1.0;
    if (hasBooster(player, "level-2x")) totalMultiplier *= 2.0;
    if (hasBooster(player, "level-1.5x")) totalMultiplier *= 1.5;
    if (hasBooster(player, "vip-bonus")) totalMultiplier *= 1.25;
    
    event.setLevelMultiplier(totalMultiplier);
}

Progressive Difficulty

Scale rewards and difficulty based on progression:

ProgressiveDifficultyHandler.java

@EventHandler
public void scaleRewardsByLevel(EntityDeathEvent event) {
    Player killer = event.getKiller();
    int level = getLevelingAPI().getLevel(killer, "sword-level");
    
    // Every 10 levels, increase drops by 10%
    double scaleFactor = 1.0 + (level / 10) * 0.1;
    event.multiplyCurrencyReward("money", scaleFactor);
}

Event Chaining

Perform sequential operations with futures:

EventChainingHandler.java

@EventHandler
public void onLevelUp(PlayerLevelUpEvent event) {
    Player player = event.getPlayer();
    
    if (event.getNewLevel() % 10 == 0) {
        giveRewardAsync(player)
            .thenAccept(success -> {
                if (success) {
                    player.sendMessage("§6Milestone reward earned!");
                }
            });
    }
}

FAQ

Can I cancel an event after it's processed?

No, cancellation must happen in the event handler itself.

Are all events thread-safe?

Events marked as async are not thread-safe for Bukkit APIs. Use Bukkit.getScheduler() to access them.

Do modifications persist across server restarts?

Event modifications only affect the current session. Use async methods to persist changes to the database.

Can I create custom events?

Yes! Extend Event and implement Cancellable if needed. Follow this guide's patterns.

What's the performance impact?

Minimal. Events are optimized. Monitor with /timings if concerned.