Wikis / MythicRPG / A P I / Events

Events

API Events

MythicRPG fires Bukkit events for the major RPG actions — leveling, archetype swaps, point changes, reagent usage, spell casting, and talent investment. They're useful for plugin integrations that need to react to (or veto) what MythicRPG is doing.

Most events are in the io.lumine.mythicrpg.events package and extend either MythicProfileEvent (read-only) or MythicCancellableProfileEvent (cancellable). The waystone events instead live in io.lumine.mythicrpg.waypoints.events, and the two lifecycle events extend Bukkit's Event directly (so they don't share the common API below).

Common API

Every event exposes:

Method	Returns	Description
`getPlayer()`	`Player`	The player the event concerns.
`getProfile()`	`Profile`	The MythicRPG profile the event concerns.
`isCancelled()`	`boolean`	(Cancellable events only) Whether a listener cancelled.
`setCancelled(b)`	`void`	(Cancellable events only) Cancel / un-cancel the event.

Lifecycle Events

These fire as a player's data loads. They extend Bukkit's Event directly rather than MythicProfileEvent, so the common API above does not apply; each getter is listed below.

`MythicRPGPlayerLoadedEvent`

Not cancellable. Fires once a player's RPG profile wrapper has been loaded and attached (on join).

Method	Returns	Description
`getPlayer()`	`Player`	The player whose profile finished loading.
`getProfileWrapper()`	`ProfileWrapper`	The player's loaded profile wrapper.

`MythicRPGProfileLoadedEvent`

Not cancellable. Fires when an individual profile finishes initializing.

Method	Returns	Description
`getPlayer()`	`Player`	The player the profile belongs to.
`getProfileWrapper()`	`ProfileWrapper`	The player's profile wrapper.
`getProfile()`	`Profile`	The specific profile that finished loading.

Archetype Events

`MythicArchetypeChangeEvent`

Cancellable. Fires before a player swaps archetypes within a group.

Method	Returns	Description
`getGroup()`	`ArchetypeGroup`	The archetype group the swap is happening in.
`getPreviousArchetype()`	`Archetype`	The archetype the player is leaving (may be `null` for first selection).
`getNewArchetype()`	`Archetype`	The archetype the player is moving to.

`MythicArchetypeUnlockEvent`

Cancellable. Fires when an archetype is unlocked / learned (without necessarily becoming active).

Method	Returns	Description
`getGroup()`	`ArchetypeGroup`	The archetype's group.
`getArchetype()`	`Archetype`	The archetype being unlocked.
`getArchetypeData()`	`ProfileArchetypeData`	The mutable data record for that archetype on the profile.
`getSource()`	`ArchetypeSource`	What caused the unlock (admin, mechanic, command, etc.).
`getSourceData()`	`String`	Free-form source-specific detail.

`MythicArchetypeForgetEvent`

Not cancellable. Fires when an archetype is removed from a profile.

Method	Returns	Description
`getGroup()`	`ArchetypeGroup`	The archetype's group.
`getArchetype()`	`Archetype`	The archetype being forgotten.
`getArchetypeData()`	`ProfileArchetypeData`	The pre-removal data record.

`MythicArchetypeLevelUpEvent`

Cancellable. Fires when an archetype gains a level.

Method	Returns	Description
`getArchetype()`	`Archetype`	The archetype levelling up.
`getArchetypeData()`	`ProfileArchetypeData`	The archetype's data record.
`getPreviousLevel()`	`int`	The level before this event.
`getNewLevel()`	`int`	The level after this event.

Experience Events

`MythicExperienceGainEvent`

Cancellable. Fires when an archetype is about to gain XP.

Method	Returns	Description
`getSourceGroup()`	`ExperienceSourceGroup`	Which experience-source group produced this XP (e.g. `BlockBreak`, `Damaging`).
`getArchetype()`	`Archetype`	The archetype receiving XP.
`getArchetypeData()`	`ProfileArchetypeData`	The archetype's mutable data record.
`getAmount()`	`double`	The XP amount about to be added.
`setAmount(double)`	`void`	Modify the XP that will actually be added.
`getPreviousExperience()`	`double`	XP before the gain.
`getPreviousLevel()`	`int`	Level before the gain.
`getNewExperience()`	`double`	Convenience getter: `previousExperience + amount`.

`MythicExperienceLossEvent`

Cancellable. Fires when an archetype is about to lose XP (e.g. from Death Control's ExperienceLoss rules).

Method	Returns	Description
`getArchetype()`	`Archetype`	The archetype losing XP.
`getArchetypeData()`	`ProfileArchetypeData`	The archetype's mutable data record.
`getAmountLost()`	`double`	The amount about to be deducted.
`setAmountLost(double)`	`void`	Modify the deduction amount.
`getPreviousExperience()`	`double`	XP before the loss.
`getPreviousLevel()`	`int`	Level before the loss.
`getNewExperience()`	`double`	`max(0, previousExperience - amountLost)`.

Point Events

`MythicPointChangeEvent`

Cancellable. Fires whenever a player's earned-or-spent point totals are about to change.

Method	Returns	Description
`getPointType()`	`PointType`	The point type (talent, stat, etc.).
`getPointTypeKey()`	`String`	The point type's id.
`getOldEarnedPoints()`	`int`	Earned points before this change.
`getNewEarnedPoints()`	`int`	Earned points after this change.
`getOldSpentPoints()`	`int`	Spent points before this change.
`getNewSpentPoints()`	`int`	Spent points after this change.
`getCause()`	`ChangeCause`	One of `ADD`, `SET`, `REMOVE`, `SPEND`.
`getEarnedPointsChanged()`	`int`	Convenience: `newEarnedPoints - oldEarnedPoints`.
`getSpentPointsChanged()`	`int`	Convenience: `newSpentPoints - oldSpentPoints`.

Reagent Events

`MythicReagentChangeEvent`

Cancellable. Fires when a reagent value is about to change (regen, manual set, etc.).

Method	Returns	Description
`getResource()`	`SkillResource`	The reagent.
`getOldAmount()`	`double`	Reagent value before the change.
`getNewAmount()`	`double`	Reagent value after the change.
`setNewAmount(double)`	`void`	Modify what the reagent will be set to.
`getCause()`	`ChangeCause`	One of `SET`, `MODIFY`.
`getAmountChanged()`	`double`	Convenience: `newAmount - oldAmount`.

`MythicReagentUseEvent`

Not cancellable. Fires when a reagent is spent (e.g. paying a spell cost).

Method	Returns	Description
`getResource()`	`SkillResource`	The reagent that was spent.
`getAmount()`	`double`	The amount that was spent.

Spell Events

`MythicSpellCastEvent`

Cancellable. Fires before a spell's skills are executed (after cast time, after cost / cooldown checks).

Method	Returns	Description
`getLearnedSkill()`	`LearnedSkill`	The player's learned-spell record (level, sources, etc.).
`getSpell()`	`Spell`	The spell about to cast.
`getLevel()`	`int`	The level at which the spell will cast.
`getMetadata()`	`SkillMetadata`	The Mythic skill metadata being passed to the cast.

`MythicSpellLearnEvent`

Cancellable. Fires when a player learns a spell or upgrades its level.

Method	Returns	Description
`getSpell()`	`Spell`	The spell being learned.
`getLevel()`	`int`	The level being granted.
`getSource()`	`SpellSource`	Where the learn came from (archetype, talent, mechanic, ...).
`getSourceData()`	`String`	Source-specific detail.
`getPreviousLevel()`	`int`	The player's prior level in this spell (`0` if first time).
`isNewSpell()`	`boolean`	`true` if the player did not previously know the spell.

`MythicSpellForgetEvent`

Cancellable. Fires when a spell source is removed (talent refund, archetype change, etc.).

Method	Returns	Description
`getSpell()`	`Spell`	The spell being forgotten.
`getSpellName()`	`String`	The internal id (kept even when `getSpell()` returns `null` because the spell was removed from config).
`getSource()`	`SpellSource`	Which source is being removed.
`getSourceData()`	`String`	Source-specific detail.
`getPreviousLevel()`	`int`	The player's level in this spell before the removal.
`isForgettingAllSources()`	`boolean`	`true` if every source for this spell is being removed.
`isSpellWillBeForgotten()`	`boolean`	`true` if the spell will be entirely forgotten (no other sources granting it).

Talent Events

`MythicTalentInvestEvent`

Cancellable. Fires when a player invests points into a talent.

Method	Returns	Description
`getTalent()`	`Talent`	The talent being invested in.
`getPreviousPoints()`	`int`	Points invested before this event.
`getNewPoints()`	`int`	Points invested after this event.
`getPointCost()`	`int`	Total cost of this investment.

`MythicTalentDivestEvent`

Cancellable. Fires when points are removed from a talent (refund, full clear, ...).

Method	Returns	Description
`getTalent()`	`Talent`	The talent being divested.
`getPreviousPoints()`	`int`	Points invested before this event.
`getNewPoints()`	`int`	Points invested after this event.
`getRefundedPointCost()`	`int`	Total points refunded.
`isClearing()`	`boolean`	`true` when the talent is being fully cleared (vs. a partial refund).

Waystone Events

`MythicWaystoneDiscoverEvent`

Cancellable. Fires when a player discovers a waystone (transitioning out of UNDISCOVERED). Cancelling stops the discovery.

Method	Returns	Description
`getWaystone()`	`Waystone`	The waystone being discovered.

`MythicWaystoneTeleportEvent`

Cancellable. Fires before a player teleports between waystones. Cancelling stops the teleport.

Method	Returns	Description
`getSource()`	`Waystone`	The waystone teleported from.
`getDestination()`	`Waystone`	The waystone teleported to.

`MythicWaystoneStateChangeEvent`

Not cancellable. Fires after a waystone's state changes for a player.

Method	Returns	Description
`getWaystone()`	`Waystone`	The waystone whose state changed.
`getPreviousState()`	`WaystoneState`	The state before the change (`UNDISCOVERED`, `DISCOVERED`, or `ACTIVE`).
`getNewState()`	`WaystoneState`	The state after the change.

Example listener

@EventHandler
public void onArchetypeChange(MythicArchetypeChangeEvent event) {
    if (event.getNewArchetype().getInternalName().equalsIgnoreCase("hardcore")) {
        if (!event.getPlayer().hasPermission("myserver.hardcore")) {
            event.setCancelled(true);
            event.getPlayer().sendMessage("You haven't unlocked Hardcore yet.");
        }
    }
}

@EventHandler
public void onXpGain(MythicExperienceGainEvent event) {
    // Double XP weekend
    if (isDoubleXpActive()) {
        event.setAmount(event.getAmount() * 2);
    }
}

Core Plugins

API Events

Common API

Lifecycle Events

MythicRPGPlayerLoadedEvent

MythicRPGProfileLoadedEvent

Archetype Events

MythicArchetypeChangeEvent

MythicArchetypeUnlockEvent

MythicArchetypeForgetEvent

MythicArchetypeLevelUpEvent

Experience Events

MythicExperienceGainEvent

MythicExperienceLossEvent

Point Events

MythicPointChangeEvent