Event API

EmakiGem exposes Bukkit events that external plugins can listen to in order to intercept or modify gem operations. Event classes live in the emaki.jiuwu.craft.gem.api.event package and use the standard HandlerList boilerplate. Every event fires before any cost is charged or the outcome is rolled.

Event	When it fires	Cancellable	Mutable
GemInlayEvent	Before the inlay success roll	Yes	setSuccessChance
GemUpgradeEvent	Before the upgrade cost and roll	Yes	setSuccessChance
GemExtractEvent	Before extraction cost and removal	Yes	Cancel only
GemSocketOpenEvent	Before opening a slot and consuming the opener	Yes	Cancel only

Actor accessor difference

GemInlayEvent, GemExtractEvent, and GemSocketOpenEvent use getActor() for the acting player, while GemUpgradeEvent uses getPlayer().

GemInlayEvent

Fires before the inlay success roll. Use it to intercept the inlay or change the success chance.

Event behavior

• It is cancellable. If cancelled, the inlay does not happen.
• The success chance can be changed with setSuccessChance, expressed as a percentage from 0 to 100.
• Fired only when the acting player is owned by the current thread; otherwise the event is skipped and the operation continues.

Main methods

Method	Return	Description
getActor()	Player	Player performing the inlay.
getEquipment()	ItemStack	Equipment receiving the gem.
getGemItem()	ItemStack	Gem item being inlaid.
getSlotIndex()	int	Target slot index.
getGemId()	String	Gem definition id.
getGemLevel()	int	Gem level.
getSuccessChance()	double	Success chance used for the roll (0-100).
setSuccessChance(double)	void	Change the success chance.
isCancelled()	boolean	Whether the event is cancelled.
setCancelled(boolean)	void	Cancel or restore the event.

Example

@EventHandler
public void onGemInlay(GemInlayEvent event) {
    // VIP players always succeed
    if (event.getActor().hasPermission("server.vip")) {
        event.setSuccessChance(100.0);
    }
}

GemUpgradeEvent

Fires before the gem upgrade cost is charged and the success roll is decided.

Event behavior

• It is cancellable. If cancelled, no cost is charged and no upgrade happens.
• The success chance can be changed with setSuccessChance, expressed as a percentage from 0 to 100.
• Fired only when the acting player is owned by the current thread; otherwise the event is skipped and the operation continues.

Main methods

Method	Return	Description
getPlayer()	Player	Player performing the upgrade.
getGemItem()	ItemStack	Gem item being upgraded; the equipment when upgrading an inlaid gem.
getGemId()	String	Gem definition id.
getCurrentLevel()	int	Level before the upgrade.
getTargetLevel()	int	Level after success.
getSlotIndex()	int	Slot index for an inlaid upgrade; -1 when upgrading a gem item directly.
getSuccessChance()	double	Success chance used for the roll (0-100).
setSuccessChance(double)	void	Change the success chance.
isCancelled()	boolean	Whether the event is cancelled.
setCancelled(boolean)	void	Cancel or restore the event.

Example

@EventHandler
public void onGemUpgrade(GemUpgradeEvent event) {
    // Disallow upgrading already-inlaid gems
    if (event.getSlotIndex() >= 0) {
        event.setCancelled(true);
    }
}

GemExtractEvent

Fires before extraction cost is charged and the gem is removed from its socket.

Event behavior

• It is cancellable. If cancelled, extraction does not happen.
• Fired only when the acting player is owned by the current thread; otherwise the event is skipped and the operation continues.

Main methods

Method	Return	Description
getActor()	Player	Player performing the extraction.
getEquipment()	ItemStack	Equipment the gem is removed from.
getSlotIndex()	int	Slot index being cleared.
getGemId()	String	Gem definition id.
getGemLevel()	int	Gem level.
getReturnMode()	String	Configured return mode (such as destroy, downgrade, return).
isCancelled()	boolean	Whether the event is cancelled.
setCancelled(boolean)	void	Cancel or restore the event.

GemSocketOpenEvent

Fires before the slot is opened and the opener item is consumed.

Event behavior

• It is cancellable. If cancelled, no slot is opened and the opener is not consumed.
• Fired only when the acting player is owned by the current thread; otherwise the event is skipped and the operation continues.

Main methods

Method	Return	Description
getActor()	Player	Player opening the slot.
getEquipment()	ItemStack	Equipment receiving the new slot.
getOpenerItem()	ItemStack	Opener item used, may be null.
getOpenerId()	String	Opener item configuration id.
getSlotIndex()	int	Resolved slot index.
getItemDefinitionId()	String	Gem item definition id of the equipment.
isCancelled()	boolean	Whether the event is cancelled.
setCancelled(boolean)	void	Cancel or restore the event.

Notes

• Changing the success chance applies only to GemInlayEvent and GemUpgradeEvent; extraction and socket-open events can only be cancelled.
• Success chance is always a percentage from 0 to 100.