Action Types

All 46 action types available for use in enchantment YAML files. Each action is defined inside the actions section with a unique key and a type field.

actions:
  my_key:
    type: action_type_name
    # ... parameters

---

potion_effect

Applies a potion effect to the target.

Parameter	Type	Required	Default	Description
effect	string	yes	--	Potion effect type (lowercase, e.g. poison, strength, slowness)
duration	ScalingFunction	yes	--	Duration in ticks (20 ticks = 1 second)
amplifier	ScalingFunction	yes	--	Effect amplifier (0 = level I, 1 = level II, etc.)
particles	boolean	no	true	Show potion particles
icon	boolean	no	true	Show effect icon on HUD

actions:
  poison:
    type: potion_effect
    effect: poison
    duration:
      base: 40
      per_level: 20
    amplifier:
      scaling: fixed
      value: 0
    particles: true
    icon: true

---

bonus_damage

Deals additional damage or multiplies existing damage.

Parameter	Type	Required	Default	Description
amount	ScalingFunction	yes	--	Damage amount (or multiplier if multiplier is true)
multiplier	boolean	no	false	If true, amount multiplies the existing damage
conditions.sneaking	boolean	no	false	Only activate while sneaking
conditions.night_time	boolean	no	false	Only activate at night
conditions.low_health	double	no	0.0	Only activate below this health
conditions.dimension	string	no	--	Only activate in this dimension (e.g. the_nether)
conditions.target_types	list	no	--	Only activate against these entity types
conditions.passive_mobs	boolean	no	false	Only activate against passive mobs

actions:
  extra_dmg:
    type: bonus_damage
    amount:
      base: 2.0
      per_level: 1.0
    multiplier: false
    conditions:
      night_time: true

---

healthsteal

Steals health from the target and heals the player.

Parameter	Type	Required	Default	Description
amount	ScalingFunction	yes	--	Health points to steal

actions:
  steal:
    type: healthsteal
    amount:
      base: 1.0
      per_level: 0.5

---

lightning

Strikes lightning at the target's location.

Parameter	Type	Required	Default	Description
damage	boolean	no	true	Whether the lightning deals damage

actions:
  strike:
    type: lightning
    damage: true

---

teleport

Teleports the player forward in the direction they're looking.

Parameter	Type	Required	Default	Description
range	ScalingFunction	yes	--	Maximum teleport distance in blocks

actions:
  blink:
    type: teleport
    range:
      base: 5.0
      per_level: 3.0

---

explosion

Creates an explosion at the target's location.

Parameter	Type	Required	Default	Description
power	ScalingFunction	yes	--	Explosion power
fire	boolean	no	false	Create fire
break_blocks	boolean	no	false	Destroy blocks

actions:
  boom:
    type: explosion
    power:
      base: 2.0
      per_level: 1.0
    fire: false
    break_blocks: false

---

velocity

Applies velocity (knockback/launch) to the player or target.

Parameter	Type	Required	Default	Description
direction	string	yes	--	Direction: UP, DOWN, FORWARD, BACKWARD, LOOK, AWAY
power	ScalingFunction	yes	--	Velocity magnitude
apply_to	string	no	SELF	Who to apply to: SELF or TARGET
no_fall_damage	boolean	no	false	Cancel the next fall damage event caused by this launch

Directions:

• UP / DOWN — absolute vertical

• FORWARD / BACKWARD — along the player's look direction

• LOOK — same as FORWARD

• AWAY — away from the target (requires a resolved target)

actions:
  launch:
    type: velocity
    direction: UP
    power:
      base: 0.8
      per_level: 0.3
    apply_to: SELF
    no_fall_damage: true

---

shockwave

Pushes nearby entities away from the player.

Parameter	Type	Required	Default	Description
radius	ScalingFunction	yes	--	Effect radius in blocks
power	ScalingFunction	yes	--	Knockback power

actions:
  push:
    type: shockwave
    radius:
      base: 5.0
      per_level: 2.0
    power:
      base: 1.0
      per_level: 0.5

---

set_fire

Sets entities on fire. If radius is set, affects all nearby entities.

Parameter	Type	Required	Default	Description
duration	ScalingFunction	yes	--	Fire duration in ticks
radius	double	no	0.0	Area of effect radius (0 = single target)

actions:
  fire:
    type: set_fire
    duration:
      base: 40
      per_level: 20
    radius: 5.0

---

glow

Makes the target glow (outline visible through walls).

Parameter	Type	Required	Default	Description
duration	ScalingFunction	yes	--	Glow duration in ticks

actions:
  outline:
    type: glow
    duration:
      base: 60
      per_level: 20

---

disarm

Forces the target player to drop their held item.

No parameters.

actions:
  drop:
    type: disarm

---

break_armor

Damages a random piece of the target player's armor.

Parameter	Type	Required	Default	Description
damage	ScalingFunction	yes	--	Durability damage to apply

actions:
  shatter:
    type: break_armor
    damage:
      base: 10
      per_level: 10

---

thanos

Instantly kills the target with a 50% chance per hit. Only works on entities.

No parameters.

actions:
  snap:
    type: thanos

---

drop_head

Drops the killed entity's head as an item.

No parameters.

actions:
  head:
    type: drop_head

---

cancel_damage

Cancels the incoming damage event. Can be conditional.

Parameter	Type	Required	Default	Description
conditions.low_health	double	no	0.0	Only cancel when player health is at or below this value (0 = always)

actions:
  resist:
    type: cancel_damage
    conditions:
      low_health: 4.0

---

attribute_modifier

Applies a persistent attribute modifier while the item is equipped. Used with PASSIVE trigger.

Parameter	Type	Required	Default	Description
attribute	string	yes	--	Attribute name: MAX_HEALTH, MOVEMENT_SPEED, ATTACK_DAMAGE, JUMP_STRENGTH, KNOCKBACK_RESISTANCE, ARMOR_TOUGHNESS
amount	ScalingFunction	yes	--	Modifier amount
operation	string	yes	--	ADD_NUMBER, ADD_SCALAR, or MULTIPLY_SCALAR_1
key	string	yes	--	Unique modifier key

actions:
  speed_boost:
    type: attribute_modifier
    attribute: "MOVEMENT_SPEED"
    amount:
      base: 0.02
      per_level: 0.01
    operation: "ADD_NUMBER"
    key: "speed"

Note: Attribute modifiers are automatically removed when the item is unequipped.

---

multi_break

Breaks blocks in a radius around the mined block (3x3, 5x5 pattern).

Parameter	Type	Required	Default	Description
radius	ScalingFunction	yes	--	Break radius

actions:
  excavate:
    type: multi_break
    radius:
      base: 1
      per_level: 1

---

autosmelt

Automatically smelts block drops (e.g. iron ore drops iron ingot).

No parameters.

actions:
  smelt:
    type: autosmelt

---

veinmine

Mines connected blocks of the same type.

Parameter	Type	Required	Default	Description
max_blocks	ScalingFunction	yes	--	Maximum blocks to mine

actions:
  mine:
    type: veinmine
    max_blocks:
      base: 8
      per_level: 4

---

timber

Chops connected log blocks (tree felling).

Parameter	Type	Required	Default	Description
max_blocks	ScalingFunction	yes	--	Maximum blocks to chop

actions:
  chop:
    type: timber
    max_blocks:
      base: 16
      per_level: 8

---

replant

Automatically replants crops after harvesting.

No parameters. Works with wheat, carrots, potatoes, beetroots, and nether wart.

actions:
  plant:
    type: replant

---

xp_bonus

Multiplies XP dropped from broken blocks.

Parameter	Type	Required	Default	Description
multiplier	ScalingFunction	yes	--	XP multiplier

actions:
  xp:
    type: xp_bonus
    multiplier:
      base: 1.5
      per_level: 0.5

---

multi_arrow

Shoots additional arrows alongside the main arrow.

Parameter	Type	Required	Default	Description
extra_arrows	ScalingFunction	yes	--	Number of extra arrows
spread	ScalingFunction	yes	--	Spread angle of extra arrows

actions:
  volley:
    type: multi_arrow
    extra_arrows:
      base: 1
      per_level: 1
    spread:
      base: 5
      per_level: 2

---

explode_projectile

Creates an explosion where the projectile lands.

Parameter	Type	Required	Default	Description
power	ScalingFunction	yes	--	Explosion power
fire	boolean	no	false	Create fire
break_blocks	boolean	no	false	Destroy blocks

actions:
  impact:
    type: explode_projectile
    power:
      base: 2.0
      per_level: 1.0
    fire: false
    break_blocks: false

---

fireball_arrow

Replaces arrows with fireballs.

No parameters.

actions:
  fireball:
    type: fireball_arrow

---

arrow_rain

Spawns a rain of arrows from the sky at the target location.

Parameter	Type	Required	Default	Description
arrows	ScalingFunction	yes	--	Number of arrows
radius	ScalingFunction	yes	--	Spread radius

actions:
  rain:
    type: arrow_rain
    arrows:
      base: 5
      per_level: 3
    radius:
      base: 3
      per_level: 1

---

bonus_drops

Multiplies drops from killed entities, broken blocks, or caught fish.

Parameter	Type	Required	Default	Description
multiplier	ScalingFunction	yes	--	Drop multiplier
crops_only	boolean	no	false	(Block break only) Restrict to crop blocks: wheat, carrots, potatoes, beetroots, nether wart, melon, pumpkin, sugar cane, cocoa, sweet berry bush, pitcher crop, torchflower crop
exclude_seeds	boolean	no	false	(Block break only) Skip seed items when duplicating drops (wheat seeds, beetroot seeds, melon seeds, pumpkin seeds, torchflower seeds, pitcher pod)

actions:
  loot:
    type: bonus_drops
    crops_only: true      # Only triggers on crop blocks
    exclude_seeds: true   # Don't duplicate seeds
    multiplier:
      base: 2.0
      per_level: 1.0

---

magnet

Attracts nearby dropped items to the player.

Parameter	Type	Required	Default	Description
radius	ScalingFunction	yes	--	Pickup radius

actions:
  pull:
    type: magnet
    radius:
      base: 5
      per_level: 3

---

consume

Consumes XP from the player to repair the item's durability.

Parameter	Type	Required	Default	Description
amount	ScalingFunction	yes	--	Durability restored per activation

actions:
  repair:
    type: consume
    amount:
      base: 1
      per_level: 1

---

unbreakable

Prevents the item from taking durability damage.

No parameters. Use with PASSIVE trigger and PlayerItemDamageEvent.

actions:
  protect:
    type: unbreakable

---

hook

Pulls the target entity toward the player (grapple).

Parameter	Type	Required	Default	Description
power	ScalingFunction	yes	--	Pull strength

actions:
  pull:
    type: hook
    power:
      base: 1.0
      per_level: 0.5

---

lava_walker

Converts lava blocks around the player to obsidian temporarily.

Parameter	Type	Required	Default	Description
radius	ScalingFunction	yes	--	Conversion radius

actions:
  walk:
    type: lava_walker
    radius:
      base: 2
      per_level: 1

Note: Obsidian reverts to lava after 5 seconds.

---

feast

Restores hunger/saturation to the player.

Parameter	Type	Required	Default	Description
amount	ScalingFunction	yes	--	Food points to restore

actions:
  feed:
    type: feast
    amount:
      base: 2
      per_level: 1

---

deflect

Deflects incoming projectiles (arrows, etc.) away from the player.

No parameters. Use with TAKE_DAMAGE trigger.

actions:
  block:
    type: deflect

---

piercing

Allows projectiles to pierce through multiple entities.

Parameter	Type	Required	Default	Description
max_pierces	ScalingFunction	yes	--	Maximum entities to pierce

actions:
  pierce:
    type: piercing
    max_pierces:
      base: 1
      per_level: 1

---

gravity

Pulls nearby entities toward the player.

Parameter	Type	Required	Default	Description
radius	ScalingFunction	yes	--	Pull radius
power	ScalingFunction	yes	--	Pull strength

actions:
  pull:
    type: gravity
    radius:
      base: 5
      per_level: 2
    power:
      base: 0.5
      per_level: 0.2

---

auto_reel

Automatically reels in fish and generates loot without needing to reel manually.

No parameters. Use with FISH_BITE trigger.

actions:
  reel:
    type: auto_reel

---

lifeline

Prevents lethal damage, leaving the player at 1 HP instead.

No parameters. Use with TAKE_DAMAGE trigger.

actions:
  save:
    type: lifeline

---

till

Tills dirt/grass blocks in a radius when using a hoe.

Parameter	Type	Required	Default	Description
radius	ScalingFunction	yes	--	Tilling radius

actions:
  farm:
    type: till
    radius:
      base: 1
      per_level: 1

---

reflect_damage

Reflects a percentage of incoming melee damage back to the attacker.

Parameter	Type	Required	Default	Description
percentage	ScalingFunction	yes	--	Fraction of damage to reflect (e.g. 0.10 = 10%)

actions:
  reflect:
    type: reflect_damage
    percentage:
      base: 0.10
      per_level: 0.05

Note: Only works with melee damage (requires EntityDamageByEntityEvent). Does not reduce incoming damage.

---

command

Runs a server command as the player or as the console.

Parameter	Type	Required	Default	Description
command	string	yes	--	Command to run (without leading /). Supports placeholders.
run_as	string	no	PLAYER	Who runs the command: PLAYER or CONSOLE

Placeholders:

Placeholder	Replaced with
{player}	The player's name
{target}	The target entity's name (empty string if none)
{level}	The enchantment level

actions:
  announce:
    type: command
    run_as: CONSOLE
    command: "say {player} triggered the enchant at level {level}!"

actions:
  reward:
    type: command
    run_as: CONSOLE
    command: "give {player} diamond 1"

Note: PLAYER runs the command with the player's own permissions. Use CONSOLE for commands that require operator-level access.

---

timer

Repeatedly executes a set of sub-actions on a fixed interval for a set duration. Useful for damage-over-time, sustained effects, or multi-stage abilities.

Parameter	Type	Required	Default	Description
interval	integer (ticks)	no	5	Ticks between each execution (20 ticks = 1 second)
duration	integer (ticks)	no	100	Total ticks to run before stopping
actions	section	yes	--	Sub-actions to run on each tick, same format as top-level actions

actions:
  burning_effect:
    type: timer
    interval: 5      # fire 4 times per second
    duration: 100    # run for 5 seconds
    actions:
      damage:
        type: bonus_damage
        amount: 1.0
      fire:
        type: set_fire
        duration: 10

Notes:

• The timer starts immediately when the enchantment triggers and runs asynchronously via the Bukkit scheduler.

• The timer stops early if the player goes offline.

• Sub-actions support any action type including nested timer actions.

• The level passed to sub-actions is the same level as the parent enchantment.

---

particle

Spawns particles at a specified location. Useful for adding visual feedback to enchantments as an action (rather than the enchant-level particle: section).

Parameter	Type	Required	Default	Description
particle_type	string	yes	--	Particle enum name (e.g. CLOUD, FLAME, ELECTRIC_SPARK)
count	int	no	10	Number of particles to spawn
spread	double	no	0.5	XYZ spread radius
speed	double	no	0.1	Particle speed
location	string	no	SELF	Where to spawn: SELF, TARGET, or BLOCK

actions:
  sparks:
    type: particle
    particle_type: ELECTRIC_SPARK
    count: 20
    spread: 0.3
    speed: 0.05
    location: TARGET

Notes:

• TARGET requires a resolved target entity; if none exists the particle is skipped.

• BLOCK requires a block in the ActionContext; if none exists the particle is skipped.

• Particle names match the Bukkit Particle enum (uppercase, e.g. SNOWFLAKE, PORTAL, TOTEM_OF_UNDYING).

---

sound

Plays a sound at the player's location or at the target's location.

Parameter	Type	Required	Default	Description
sound_type	string	yes	--	Sound registry key in dot notation (e.g. entity.enderman.teleport)
volume	double	no	1.0	Sound volume (0.0–2.0)
pitch	double	no	1.0	Sound pitch (0.5–2.0)
play_at_target	boolean	no	false	If true, plays at the target's location instead of the player's

actions:
  thunder:
    type: sound
    sound_type: entity.lightning_bolt.thunder
    volume: 1.0
    pitch: 0.8
    play_at_target: true

Notes:

• Sound keys use Minecraft's dot notation (e.g. entity.generic.explode, block.glass.break). Entity names with underscores keep them (e.g. entity.lightning_bolt.thunder).

• If play_at_target is true and no target exists, the sound plays at the player's location.

---

send_message

Sends a MiniMessage-formatted message to the player or to nearby players.

Parameter	Type	Required	Default	Description
message	string	yes	--	MiniMessage text. Supports {player}, {target}, {level} placeholders
radius	double	no	0.0	If > 0, broadcasts to all players within this radius

actions:
  notify:
    type: send_message
    message: "<gold>{player}</gold> <gray>hit</gray> <red>{target}</red> <gray>with a level {level} enchant!"
    radius: 0.0

Notes:

• {player} is replaced with the enchant-user's name.

• {target} is replaced with the target entity's name, or empty string if no target.

• {level} is replaced with the enchantment level.

• When radius > 0, all online players within that radius receive the message.

---

spawn_entity

Spawns one or more entities at a specified location.

Parameter	Type	Required	Default	Description
entity_type	string	yes	--	EntityType enum name (e.g. ZOMBIE, SKELETON, WOLF)
count	int	no	1	Number of entities to spawn
location	string	no	SELF	Where to spawn: SELF or TARGET
baby	boolean	no	false	If true, spawns entity as a baby (if the entity supports it)

actions:
  summon:
    type: spawn_entity
    entity_type: ZOMBIE
    count: 2
    location: TARGET
    baby: false

Notes:

• Entity names match the Bukkit EntityType enum (uppercase, e.g. CREEPER, WOLF, VILLAGER).

• baby only applies to entities that implement Ageable (e.g. zombies, cows, pigs).

• Entities spawn at the exact target location; they behave normally after spawning.