📡 Events

All events are standard Bukkit events, registered the usual way with @EventHandler. Crate events live in com.phoenixplugins.phoenixcrates.api.crate.events, item delivery in com.phoenixplugins.phoenixcrates.api.events.items.

#Event List

Event	Fires when	Cancellable
CratePlaceEvent	A player places a crate item in the world	Yes
CratePreviewOpenEvent	The rewards preview menu is about to open	Yes
CratePreOpenEvent	An opening has been requested, before any check runs	Yes
CrateOpenEvent	The opening has started	No
CrateRewardSelectionEvent	A random crate is choosing which reward to award	No
CrateSelectiveConfirmEvent	A player confirms a reward in Selective mode	Yes
CratePreRerollEvent	A reroll has been requested	Yes
CrateRerollEvent	A reroll has produced a new reward	No
CrateRewardWinItemsEvent	The item list for a win has been built, before it is given	No
CrateRewardPlayerEvent	A player has been awarded a reward	No
ItemDeliveryEvent	Items are about to be delivered to a player	No

Several of these are not cancellable but still let a listener change the outcome, which is covered per event below.

#CratePlaceEvent

Fired when a player places a crate item. Exposes getCrate() (the CrateType), getWhoPlaced() and getLocation().

#CratePreviewOpenEvent

Fired before the rewards preview opens. Exposes getCrateType(), getPlayer() and getPreviewMenu(), the name of the menu that is about to be used. Cancel it to block the preview.

#CratePreOpenEvent

Fired as soon as an opening is requested and before the plugin checks keys, permission, cooldown or cost. Cancel it to stop the opening with no key consumed. Exposes getCrate(), getPlayer() and getType().

This is the event to use for your own access rules. See Examples.

#CrateOpenEvent

Fired once an opening has passed every check and has started. Not cancellable, since the key has already been taken. Use it for logging and metrics, which is exactly what the built-in logger does.

#CrateRewardSelectionEvent

Fired while a crate in Random mode is picking a reward. Exposes getCrate(), getPlayer(), getKey() and getCandidates(), the rewards that are currently eligible for this player.

To choose the reward yourself, call setSelectedReward() and setHandled(true). Setting the reward without marking the event handled lets the normal selection run and replace your choice.

#CrateSelectiveConfirmEvent

Fired when a player confirms a reward on a crate in Selective (non RNG) mode. Exposes getCrate(), getPlayer() and getSelectedReward(). Cancel it to refuse the selection.

#CratePreRerollEvent

Fired when a player requests a reroll. Exposes getSession(), the active OpeningSession. Cancel it to refuse the reroll, or call setHandled(true) to tell the plugin your listener has taken over the reroll itself.

#CrateRerollEvent

Fired once a reroll has run and produced a new reward, so it is the counterpart to CratePreRerollEvent. Exposes getCrate(), getPlayer() and getReward(), the reward the reroll landed on.

A reroll in a normal opening replaces every reward, so the event fires once per new reward. A reroll from the Mass Opening menu targets one reward, so it fires once.

Use it for logging and metrics. To actually block or take over a reroll, use CratePreRerollEvent.

#CrateRewardWinItemsEvent

Fired after the final item list for a win has been built and before those items reach the player. Exposes getCrate(), getReward(), getPlayer() and a mutable getWinItems(), which setWinItems() can replace outright.

This is the place to add a bonus item, apply your own NBT, or swap items per player.

#CrateRewardPlayerEvent

Fired when a player is awarded a reward. Exposes getCrate(), getPlayer() and getReward(), which is settable.

#ItemDeliveryEvent

Fired whenever the plugin hands items to a player, whether from an opening or from a command. Exposes getPlayer(), getPlayerData(), getRemainingItems() and getSource(), which is one of KEY_GRANT, CRATE_GRANT or REWARD_GRANT.

Edit getRemainingItems() or call setRemainingItems() to change what is delivered, and consumeAll() to take responsibility for every item yourself, which is how the Crate Claim add-on stores items for offline players.

Use getRemainingItemsSnapshot() if you need a copy that is safe to hold onto.