Events

Mythic Dungeons fires Bukkit-style events for every important dungeon and party state change. Listen to them the same way you'd listen to any vanilla event. Register a Listener and add @EventHandler-annotated methods. See Introduction to API for the registration boilerplate.

Package roots:

• net.playavalon.mythicdungeons.api.events.dungeon: dungeon-lifecycle and trigger events
• net.playavalon.mythicdungeons.api.events.dungeon.rooms: procedural room events
• net.playavalon.mythicdungeons.api.events.party: party-system events

Every event on this page is constructed and dispatched by the plugin. There is no dead event class in the API.

Inheritance overview

Most dungeon events extend a common abstract base, giving listeners these inherited accessors:

So every event documented below as extends DungeonEvent automatically exposes getInstance() and getDungeon(), and every MythicPartyEvent exposes getParty().

getInstance() is null when the event was built from the dungeon-only constructor DungeonEvent(AbstractDungeon), which PlayerStartDungeonEvent and PlayerFinishDungeonEvent both expose. The instance constructor also tolerates a null instance, in which case getDungeon() is null too. Null-check both before dereferencing.

Both bases own the HandlerList for their whole family, and no subclass declares its own. Register your handler against the exact subclass you care about, or against DungeonEvent / MythicPartyEvent to receive every event in that family. A handler declared for one concrete subclass is never invoked for a sibling subclass, despite the shared list.

MythicPartyEvent has a second constructor, MythicPartyEvent(MythicParty party, boolean isAsync), for subclasses that need to be dispatched asynchronously. AsyncMythicPartyChatEvent is the only event that uses it.

HotbarSetEvent is the one exception to all of the above: it extends org.bukkit.event.Event directly and owns its own HandlerList.

Types used below: MythicPlayer is net.playavalon.mythicdungeons.player.MythicPlayer, MythicParty is net.playavalon.mythicdungeons.player.party.partysystem.MythicParty, IDungeonParty is net.playavalon.mythicdungeons.api.party.IDungeonParty, Hotbar is net.playavalon.mythicdungeons.player.Hotbar, DungeonDifficulty is net.playavalon.mythicdungeons.api.parents.DungeonDifficulty, AbstractDungeon is net.playavalon.mythicdungeons.api.parents.dungeons.AbstractDungeon, AbstractInstance and InstancePlayable are in net.playavalon.mythicdungeons.api.parents.instances, DungeonTrigger is net.playavalon.mythicdungeons.api.parents.elements.DungeonTrigger, and InstanceRoom / ConnectorDoor / DoorAction / RoomEmptyCause live in net.playavalon.mythicdungeons.api.generation.rooms.

All events at a glance

AsyncMythicPartyChatEvent is the only event flagged async. The one caveat is DungeonDisposeEvent: it is a synchronous event, but while the plugin is shutting down an off-thread dispose() no longer hops to the main thread, so it can be dispatched on the calling thread.

Dungeon Events

DungeonStartEvent

Fired once per instance, at the end of the instance's startGame(). That happens when the Start Dungeon function's ready-check completes (lobby dungeons), one tick after the world loads (classic dungeons without a lobby, and all procedural dungeons), or when a player re-enters onto a save point. Never fired for edit instances.

Extends: DungeonEvent | Cancellable: No

new DungeonStartEvent(AbstractInstance instance, List<MythicPlayer> mythicPlayers)

Getters:

• List<MythicPlayer> getMythicPlayers(): the instance's live player list, not a snapshot. Copy it if you need it later, or it will shrink under you as players leave.
• Collection<Player> getPlayers(): a fresh ArrayList of the same players as Bukkit Players, rebuilt on every call.

At this point functions are initialised, every player has been teleported to the start point with a dungeon respawn set, the participant list has been recorded, the time limit is computed, and the instance ticker is already scheduled.

DungeonEndEvent

Fired as the last player is being removed from the instance, whatever caused the removal (timeout, leave, kick, finish). It fires before that player is removed and before PlayerLeaveDungeonEvent, so getGamePlayers() still contains them. An instance nobody ever entered never fires it.

Extends: DungeonEvent | Cancellable: No

new DungeonEndEvent(AbstractInstance instance)

Getters:

• List<MythicPlayer> getGamePlayers(): the instance's live player list, including the player currently leaving. Copy it if you need it after the event; read a tick later it will be empty.
• List<Player> getPlayers(): a snapshot of the same players as Bukkit Players, built once when the event is constructed.
• IDungeonParty getParty(): the dungeon party of the first player in that list, if they have one.
• boolean isEditInstance(): true when the instance was in edit mode.
• boolean isPlayInstance(): true when the instance was a play instance.

Note: If a listener cancels the PlayerLeaveDungeonEvent that follows, this event has already been delivered even though the dungeon keeps running.

PlayerStartDungeonEvent

Fired as the last step of adding a player to a play instance, once they are fully inside. Edit instances use a different code path, so this event never fires for them.

Extends: DungeonEvent | Cancellable: No

new PlayerStartDungeonEvent(InstancePlayable instance, MythicPlayer mPlayer)
new PlayerStartDungeonEvent(AbstractDungeon dungeon, MythicPlayer mPlayer)

Getters:

• MythicPlayer getMPlayer(): the entering player as a Mythic Dungeons player.
• Player getPlayer(): the same player as a Bukkit Player.

By the time listeners run, the player is in the instance roster, their instance reference is set, their inventory has been saved (or protected from a Multiverse swap), they have been teleported to their save point, their gamemode has been applied and their lives have been seeded.

The AbstractDungeon constructor is part of the public API and is not used inside the plugin. An event built that way has a null getInstance().

PlayerFinishDungeonEvent

Fired when a player formally completes the dungeon. Two producers: the Finish Dungeon function (only for targets still in the instance) and the dungeoncomplete mechanic (aliases dcomplete, dwin).

Extends: DungeonEvent | Cancellable: No

new PlayerFinishDungeonEvent(InstancePlayable instance, MythicPlayer mPlayer)
new PlayerFinishDungeonEvent(AbstractDungeon dungeon, MythicPlayer mPlayer)

Getters:

• MythicPlayer getMPlayer()
• Player getPlayer()

Both producers fire it before the player is marked as having finished, before loot cooldowns are applied, before rewards are pushed and before the optional removal from the instance. As with the start event, the AbstractDungeon constructor leaves getInstance() null.

PlayerLeaveDungeonEvent

Fired when a player is removed from a dungeon instance by any means (finish, manual leave, kick, disconnect, time limit, reload).

Extends: DungeonEvent | Cancellable: Yes

new PlayerLeaveDungeonEvent(AbstractInstance instance, MythicPlayer mPlayer)

Getters:

• MythicPlayer getMPlayer()
• Player getPlayer()
• boolean isEditMode(): true if the player was leaving an edit-mode instance.

Cancelling this event only blocks the leave on the three paths that ask for it: the Leave Dungeon function, the /leave command, and the dungeonkick mechanic run with silent=true. Every other exit path (disconnect, party removal, time limit, Finish Dungeon, dungeonkick without silent, /md admin commands, reload and shutdown) removes the player regardless of the cancel flag.

DungeonDisposeEvent

Fired right before an instance is disposed (world unloaded, files cleaned up). Cancel to keep the instance alive, for example, if you're still serializing state.

Extends: DungeonEvent | Cancellable: Yes

new DungeonDisposeEvent(AbstractInstance instance)

No additional getters beyond the inherited getInstance() / getDungeon().

It only fires when the instance has no players left and is not already disposing, and only after the instance has been detached from its dungeon. Cancelling re-attaches it and aborts the disposal; a later dispose() call fires the event again. Mythic Dungeons itself listens to this event to admit the next party from the queue.

Note: Disposal normally hops to the main thread first, but that hop is skipped while the plugin is disabling, so during a shutdown this event can arrive on whatever thread called dispose().

TriggerFireEvent

Fired every time a dungeon trigger is about to run its function chain. Cancel to stop the function from running and to suppress the trigger's own onTrigger handling.

Extends: DungeonEvent | Cancellable: Yes

new TriggerFireEvent(InstancePlayable instance, DungeonTrigger trigger)
new TriggerFireEvent(MythicPlayer dPlayer, DungeonTrigger trigger)

Getters:

• DungeonTrigger getTrigger(): the trigger that fired.
• MythicPlayer getDPlayer(): the player who caused the trigger, null for instance-scope firings.
• @Nullable Player getPlayer(): same as above as a Bukkit Player, or null.

The event object is created before the trigger's conditions are evaluated and is handed to those conditions first. It is only dispatched once the whole condition set passes and the trigger's configured delay has elapsed. With "Wait For Conditions" on and "Allow Retrigger" off, the trigger keeps re-checking once per second until the conditions pass, and dispatch happens on the pass, not on the original stimulus.

RemoteTriggerEvent

Fired by the Signal Sender function and by the dungeonsignal mechanic (alias dsignal). Signal Receiver triggers listen to it and fire when the signal name, the range and the room all match.

Extends: DungeonEvent | Cancellable: Yes

new RemoteTriggerEvent(@NotNull String triggerName, DungeonTrigger trigger, @NotNull InstancePlayable instance)
new RemoteTriggerEvent(@NotNull String triggerName, DungeonTrigger trigger, @NotNull InstancePlayable instance, double range, @Nullable Location origin)
new RemoteTriggerEvent(@NotNull String triggerName, DungeonTrigger trigger, @NotNull InstancePlayable instance, double range, @Nullable Location origin, @Nullable MythicPlayer triggerPlayer)

Getters:

• String getTriggerName(): the signal name being dispatched.
• DungeonTrigger getTrigger(): the source trigger object. The dungeonsignal mechanic passes null here.
• double getRange() / setRange(double): radius for receivers; 0 means dungeon-wide.
• @Nullable Location getOrigin(): origin location for radius checks.
• @Nullable MythicPlayer getMythicPlayer(): the player who caused the signal, if there was one.
• @Nullable Player getPlayer(): same as a Bukkit Player, or null.

Note: This event implements Cancellable, but Signal Receiver triggers never read the cancel flag, and neither does the shared dispatcher that invokes them. Cancelling does not suppress a receiver at any event priority. The flag is only useful to other plugins' listeners.

The Mythic Signal function does not fire this event. It signals nearby Mythic Mobs directly.

DungeonStatusChangeEvent

Fired when the instance's status string changes, via the Dungeon Status function or InstancePlayable#setStatus(String). Not fired when the new value equals the old one. Always delivered on the main thread, one tick later if the change came from an async thread.

Extends: DungeonEvent | Cancellable: No

new DungeonStatusChangeEvent(InstancePlayable instance, @Nullable String previousStatus, @Nullable String newStatus)

Getters:

• @Nullable String getPreviousStatus()
• @Nullable String getNewStatus()

The instance already carries the new status when listeners run.

DungeonDifficultyChangeEvent

Fired when the instance's difficulty changes: via the Dungeon Difficulty function, via InstancePlayable#setDifficulty(DungeonDifficulty), and once per instance when a newly created instance is stamped with the difficulty the players picked. Not fired when the new value equals the old one. Same main-thread dispatch as DungeonStatusChangeEvent.

Extends: DungeonEvent | Cancellable: No

new DungeonDifficultyChangeEvent(InstancePlayable instance, @Nullable DungeonDifficulty previousDifficulty, @Nullable DungeonDifficulty newDifficulty)

Getters:

• @Nullable DungeonDifficulty getPreviousDifficulty(): null on the initial stamp.
• @Nullable DungeonDifficulty getNewDifficulty()

DungeonGenerateLootEvent

Fired once per item rolled by a Loot Table Rewards function, after Mythic Mobs item resolution and before the item is placed in the reward chest GUI. Not fired by the Rewards or Random Rewards functions, and not fired at all in an edit instance or when the player has already claimed that chest.

Extends: DungeonEvent | Cancellable: Yes

new DungeonGenerateLootEvent(AbstractInstance instance, Player player, ItemStack item, String lootTableNamespace)

Getters:

• Player getPlayer(): the player the loot is being rolled for.
• ItemStack getGeneratedItem() / setGeneratedItem(ItemStack): the rolled item. Replace it to change the drop; setting it to null skips it.
• String getLootTableNamespace(): the name of the loot table the item came from.

Cancelling skips this item only; the rest of the roll continues.

HotbarSetEvent

Fired when a player's edit-mode hotbar is about to be replaced, for example, when switching between trigger-edit and function-edit hotbars. Cancel to keep the current hotbar.

Extends: Event (NOT DungeonEvent) | Cancellable: Yes

new HotbarSetEvent(Hotbar hotbar, MythicPlayer aPlayer)

Getters:

• @Nullable Hotbar getOldHotbar(): the top of the player's previous-hotbar stack, if any. This is not necessarily the hotbar they are wearing right now.
• Hotbar getNewHotbar(): the hotbar being applied. It is null on the restore path, before the player has ever had a hotbar saved and again after a restore has consumed the saved one.
• void setNewHotbar(Hotbar): other listeners see the replacement, but the hotbar actually given to the player is unaffected. Use cancellation rather than substitution.
• MythicPlayer getMythicPlayer()
• Player getPlayer()

Cancelling stops the swap on all three of the plugin's call sites. Two of those three fire one tick after the hotbar change was requested.

Room Events

Rooms only exist in procedural dungeons.

RoomDoorChangeEvent

Fired when a connector door in a procedural room is opened or closed.

Extends: DungeonEvent | Cancellable: No

new RoomDoorChangeEvent(AbstractInstance instance, InstanceRoom room, ConnectorDoor door, DoorAction action)

Getters:

• InstanceRoom getRoom(): the room containing the door.
• ConnectorDoor getDoor(): the door itself.
• DoorAction getAction(): OPEN or CLOSE.

This event is notification-only: the blocks have already been changed and the sound has already played when it fires. It is also skipped entirely when the door cannot resolve its instance, so do not treat it as a guaranteed record of every door movement.

RoomTransitionEvent

Fired when a player enters or leaves a procedural room. FIRST_ENTER fires just before the matching ENTER, and EMPTIED just after the matching LEAVE, so a listener can pick whichever edge it needs. Driven by move, teleport, world change, quit and death, all observed at MONITOR.

Extends: DungeonEvent | Cancellable: No

new RoomTransitionEvent(AbstractInstance instance, InstanceRoom room, Player player, RoomTransitionEvent.Type type,
                        RoomEmptyCause cause, int playerCount, int previousPlayerCount)

Getters:

• InstanceRoom getRoom(): the room being entered or left.
• Player getPlayer(): the player who moved.
• RoomTransitionEvent.Type getType(): ENTER, LEAVE, FIRST_ENTER or EMPTIED.
• RoomEmptyCause getCause(): MOVE, TELEPORT, WORLD_CHANGE, QUIT or DEATH.
• int getPlayerCount() / int getPreviousPlayerCount(): room occupancy after and before the transition.

The room's occupancy counters are already updated when the event fires. Enter events require the player to be in a procedural instance, but the leave path is looser: a player who has a cached room and is no longer in a procedural instance (or in no instance at all) still gets a final LEAVE, carrying the room's own instance.

Party Events

These events belong to the built-in party system. They only fire when General.PartyPlugin in config.yml is Default or DungeonParties. With Parties, PartyAndFriends or Heroes selected, Mythic Dungeons wraps that plugin's parties instead and none of these are fired.

MythicPartyCreateEvent

Fired after a new dungeon party is created. Dispatch is deferred by one tick, so the party already exists and has its leader when listeners run.

Extends: MythicPartyEvent | Cancellable: No

new MythicPartyCreateEvent(MythicParty party, MythicPlayer host)

Getters:

• MythicPlayer getHostPlayer(): the player who created the party (also the initial leader).

MythicPartyJoinEvent

Fired when a player joins an existing party, synchronously, before the player is added. Cancel to block the join.

Extends: MythicPartyEvent | Cancellable: Yes

new MythicPartyJoinEvent(MythicParty party, MythicPlayer player)

Getters:

• MythicPlayer getJoiningPlayer(): the player joining the party.

Note: Removal from the player's previous party happens before this event on every join path, and that removal also ejects them from any dungeon they were running. Cancelling therefore leaves the player in no party at all, and out of their old dungeon, rather than restoring the previous state.

MythicPartyLeaveEvent

Fired whenever a player is removed from a party: /party leave, a kick, a disband, joining another party, the offline timeout, or the API removeFromParty. Dispatch is deferred by one tick, so the player is already out of the party when listeners run.

Extends: MythicPartyEvent | Cancellable: No

new MythicPartyLeaveEvent(MythicParty party, MythicPlayer leavingPlayer)

Getters:

• MythicPlayer getLeavingPlayer(): the player leaving the party.

MythicPartyKickEvent

Fired when a player is kicked from a party, synchronously, before the removal. In practice this means /party kick <name>. Cancel to block the kick.

Extends: MythicPartyEvent | Cancellable: Yes

new MythicPartyKickEvent(MythicParty party, MythicPlayer kickedPlayer, MythicPlayer whoKicked)

Getters:

• MythicPlayer getKickedPlayer(): the player being kicked.
• MythicPlayer getWhoKicked(): the party's current leader (kicks are always issued as the leader).

Note: Mythic Dungeons' own listener runs at NORMAL priority and never checks the cancel flag, so it pulls the kicked player out of their running dungeon whatever you do. Cancelling keeps them in the party but does not put them back in the dungeon, at any priority.

AsyncMythicPartyChatEvent

Fired when a player sends a message through party chat. Cancel to suppress the message, or mutate it via setMessage(...).

Extends: MythicPartyEvent | Cancellable: Yes | Async: Yes

new AsyncMythicPartyChatEvent(MythicParty party, String message)

Getters:

• String getMessage() / setMessage(String): the chat content. Colour codes have already been translated before the event is constructed, so this is the formatted text, not the player's raw input.

Cancelling suppresses delivery to party members, the console log line and any party-spy copies. setMessage(...) is honoured by all three.

Important: Because this is an async event, do not call Bukkit-thread-only APIs from your handler unless you bounce the work back to the main thread.

Deprecated helpers

DungeonTrigger#triggerPlayer(MythicPlayer) and DungeonTrigger#triggerParty(InstanceClassic) are marked @Deprecated and are not called anywhere in the plugin. Each builds a TriggerFireEvent and then discards it without dispatching, before delegating to trigger(), which fires the trigger with no player context. No listener sees a TriggerFireEvent from either of them. Do not use them to fire a trigger from your own plugin.