Event API

EmakiLevel exposes Bukkit events that external plugins can listen to in order to intercept, modify, or record level and experience flows. Event classes live in the emaki.jiuwu.craft.level.api.event package and use the standard HandlerList boilerplate.

Event	When it fires	Cancellable	Mutable
PlayerExpGainEvent	Before experience is written	Yes	setAmount
PlayerLevelUpEvent	After an experience-driven level up	No	Read-only
PlayerLevelChangeEvent	After any level change	No	Read-only
PlayerMaxLevelReachedEvent	When the max level is reached for the first time	No	Read-only

PlayerExpGainEvent

Fires before experience is written to the player. amount is the value after multipliers and daily caps are applied, before it is added to the player.

Event behavior

• It is cancellable. If cancelled, no experience is gained.
• The amount can be changed with setAmount. A value of 0 or less suppresses the gain.
• Fired on the main thread; asynchronous paths skip the event.

Main methods

Method	Return	Description
getPlayer()	Player	Player gaining experience, may be null.
getTypeId()	String	Level type id.
getCurrentLevel()	int	Level before this gain.
getCurrentExp()	double	Experience before this gain.
getReason()	String	Source reason marker.
getAmount()	double	Experience to add unless changed or cancelled.
setAmount(double)	void	Change the experience amount; a value of 0 or less suppresses the gain.
isCancelled()	boolean	Whether the event is cancelled.
setCancelled(boolean)	void	Cancel or restore the event.

Example

@EventHandler
public void onExpGain(PlayerExpGainEvent event) {
    // Double experience event
    event.setAmount(event.getAmount() * 2);
}

PlayerLevelUpEvent

Fires after an experience-driven level up completes. The level has been applied, and rewards and success actions have run.

Event behavior

• Not cancellable; purely informational.
• Covers only experience-driven level ups (direct level changes via command or API use PlayerLevelChangeEvent).

Main methods

Method	Return	Description
getPlayer()	Player	Player who leveled up, may be null.
getTypeId()	String	Level type id.
getOldLevel()	int	Level before the level up.
getNewLevel()	int	Level after the level up.
getCause()	LevelUpCause	Cause of the level up (emaki.jiuwu.craft.level.api.LevelUpCause), may be null.

PlayerLevelChangeEvent

Fires after any level change, covering direct level changes via command or API (as opposed to the experience-only PlayerLevelUpEvent). The change has already been applied and cannot be reverted.

Event behavior

• Not cancellable; purely informational.
• Covers add, set, level up, reset, and other level operations.

Main methods

Method	Return	Description
getPlayer()	Player	Affected player, may be null when offline.
getTypeId()	String	Level type id.
getOldLevel()	int	Level before the change.
getNewLevel()	int	Level after the change.
getOperationType()	LevelOperationType	Operation that caused the change (emaki.jiuwu.craft.level.api.LevelOperationType).
isIncrease()	boolean	Whether the level increased (new level greater than old level).

PlayerMaxLevelReachedEvent

A milestone event fired once when a player reaches the configured max level for the first time via experience.

Event behavior

• Not cancellable; purely informational.
• Fires once per level type the first time max level is reached.

Main methods

Method	Return	Description
getPlayer()	Player	Player who reached max level, may be null.
getTypeId()	String	Level type id.
getMaxLevel()	int	Configured max level.
getCause()	LevelUpCause	Cause of the level up (LevelUpCause), may be null.

Example

@EventHandler
public void onMaxLevel(PlayerMaxLevelReachedEvent event) {
    Player player = event.getPlayer();
    if (player != null) {
        Bukkit.broadcastMessage(player.getName()
            + " has maxed out " + event.getTypeId() + "!");
    }
}

Notes

• getPlayer() may return null when offline; check for null before use.
• PlayerLevelUpEvent only fires for experience-driven level ups; listen to PlayerLevelChangeEvent for direct level changes via command or API.
• LevelUpCause and LevelOperationType are enums exposed by the EmakiLevel API, located in the emaki.jiuwu.craft.level.api package.