Triggers and Targets

Triggers

Triggers define when an enchantment activates. Set the trigger field in your enchantment YAML.

Trigger	Description	Listener	Checked Slots
ATTACK_ENTITY	When the player deals melee damage to an entity	CombatListener	Main hand
KILL_ENTITY	When the player kills an entity	CombatListener	Main hand
TAKE_DAMAGE	When the player takes damage	CombatListener	Armor slots
RIGHT_CLICK	When the player right-clicks	InteractListener	Main hand, Armor slots
BLOCK_BREAK	When the player breaks a block	BlockListener	Main hand
BOW_SHOOT	When the player shoots a bow/crossbow	ProjectileListener	Main hand
PROJECTILE_HIT	When the player's projectile hits an entity	ProjectileListener/CombatListener	Main hand (via metadata)
FISHING	When the player catches something while fishing	FishingListener	Main hand
FISH_BITE	When a fish bites the hook	FishingListener	Main hand
PASSIVE	Periodically while the item is equipped	PassiveListener	All equipment slots
SNEAK	When the player first presses sneak	SneakListener	All equipment slots
SNEAK_HOLD	Every 4 ticks while the player holds sneak	SneakListener	All equipment slots
DEATH	When the player dies	DeathListener	All equipment slots
BLOCK_PLACE	When the player places a block	BlockListener	Main hand
RESPAWN	When the player respawns after death	DeathListener	All armor slots
ITEM_SWAP	When the player swaps the item to their main hand (F key)	SwapListener	Swapped item

Trigger Details

ATTACK_ENTITY Fires on EntityDamageByEntityEvent. Handles both direct melee hits and projectile damage (for bow enchants using ATTACK_ENTITY instead of PROJECTILE_HIT). The target in ActionContext is the damaged entity.

TAKE_DAMAGE Fires on EntityDamageByEntityEvent where the player is the victim. Checks armor slots. The target in ActionContext is the attacker (if applicable).

RIGHT_CLICK Fires on PlayerInteractEvent. Checks the item in the main hand and all armor slots, so enchants on boots, chestplates, etc. can use RIGHT_CLICK as their trigger.

PASSIVE Runs on a repeating timer (default every 20 ticks / 1 second). AttributeModifierAction types are handled separately from other passive actions — attribute modifiers are applied/removed based on current equipment state each tick.

SNEAK Fires once when the player first presses the sneak key (PlayerToggleSneakEvent with isSneaking = true). Use this for one-shot sneak abilities.

SNEAK_HOLD Fires every 4 ticks for as long as the player holds sneak. The repeating task is started on sneak press and cancelled automatically when sneak is released or the player goes offline. Use this for sustained effects like flight or continuous boosts. Enchant-level cooldown is applied to each individual tick, so a cooldown: 0 enchant fires every 4 ticks.

PROJECTILE_HIT Fires when an arrow/trident from the player hits an entity. The bow's enchantments are stored as metadata on the projectile at shoot time.

---

Targets

Targets define who the enchantment affects when it fires. Set the target field in your enchantment YAML.

Target	Description
SELF	Affects only the player who has the enchantment
PLAYERS	Affects nearby players
MOBS	Affects nearby mobs (non-player entities)
ALL_ENTITIES	Affects all nearby entities (players and mobs)
NONE	No target resolution (used for block-related enchants)

How Targets Work

The EnchantProcessor resolves targets based on the trigger context:

• For ATTACK_ENTITY / PROJECTILE_HIT: The target is the entity being hit. The target setting determines if the enchant can affect that type of entity.

• For TAKE_DAMAGE: The target is typically the attacker. SELF means the effect applies to the player wearing the armor.

• For PASSIVE / SNEAK: SELF means the player themselves. Other targets would affect entities in a radius.

• For BLOCK_BREAK: NONE is typical since the action operates on blocks, not entities.

• For KILL_ENTITY: SELF applies the effect to the player. ALL_ENTITIES can affect the killed entity (pre-death effects).

Common Combinations

Enchant Type	Trigger	Target	Example
Offensive melee	ATTACK_ENTITY	ALL_ENTITIES	Venom, Lightning
Defensive armor	TAKE_DAMAGE	SELF	Berserk, Fortify
Passive stat boost	PASSIVE	SELF	Speed, Growth
Bow effect	PROJECTILE_HIT	ALL_ENTITIES	Entangle, Ignite
Mining	BLOCK_BREAK	NONE	Veinminer, Autosmelt
On-kill reward	KILL_ENTITY	SELF	Spirit Link
One-shot ability	RIGHT_CLICK	SELF	Dash, Ascend
Sustained ability	SNEAK_HOLD	SELF	Jetpack
On-sneak burst	SNEAK	SELF	Explosive
Block placement	BLOCK_PLACE	SELF	Mason
On-respawn	RESPAWN	SELF	Rebirth
Hand swap	ITEM_SWAP	SELF	Quick Draw

---

BLOCK_PLACE

Fires on BlockPlaceEvent when the player places a block. The item checked is the one currently in the player's main hand. The placed block is available in ActionContext via block. Useful for enchants that reward the player for building or placing specific blocks.

Common use: Granting haste, speed, or other buffs while actively building.

RESPAWN

Fires on PlayerRespawnEvent, delayed by 1 tick so the player is fully loaded at their respawn location. Checks all armor slots. The ActionContext does not contain a target entity. Useful for granting temporary buffs on respawn.

Common use: Post-death survival enchants that grant strength, regeneration, or other effects to help the player recover.

ITEM_SWAP

Fires on PlayerSwapHandItemsEvent (the F key by default). The item being moved to the main hand (previously in the offhand) is checked for enchants. The ActionContext does not contain a target entity or block. Useful for quick-access abilities activated by swapping weapons.

Common use: Speed boosts or other buffs triggered when switching to a specific weapon or tool.