🧬Entity State Abilities

Every registered ability on this page is documented as a complete reference entry. All entries also support the common ability fields from the Abilities page.

Registry keys on this page

• set_attribute

• refresh_attribute

• set_health

• set_absorption

• set_air

• set_food

• set_velocity

• set_invulnerable

• potion_effect

• remove_potion_effect

• extend_potion_effects

• potion_cloud

• freeze

• fire

• experience

---

set_attribute

Purpose: Sets one Bukkit attribute base value or one EnchantmentReform custom attribute value.

Context: Default target: SOURCE; selected entity must expose the requested attribute.

Fields

Field	Default	Description
attribute	max_health	Bukkit attribute key such as minecraft:max_health, or a custom attribute ID.
value	1	New value; supports {now} for the current value and {max} for its maximum.

Example

type: set_attribute
target: SOURCE
attribute: minecraft:max_health
value: '{max} * 1.25'

Behavior and limits

• When changing maximum health, current health is adjusted/bounded by the platform implementation.

• This changes the base value rather than adding a temporary modifier.

• A custom attribute target must be a player. The resulting integer is clamped to the custom attribute's configured range and stored in player PDC.

---

refresh_attribute

Purpose: Adds or refreshes one temporary attribute modifier without stacking duplicate copies.

Context: Default target: SOURCE; target must be living and expose the requested attribute.

Fields

Field	Default	Description
attribute	minecraft:max_health	Namespaced Bukkit attribute key or custom attribute ID.
operation	ADD_NUMBER	Accepts ADD_VALUE, ADD_MULTIPLIED_BASE, and ADD_MULTIPLIED_TOTAL; legacy Bukkit names ADD_NUMBER, ADD_SCALAR, and MULTIPLY_SCALAR_1 are also accepted.
amount	0	Modifier amount.
duration	source lifetime	Optional lifetime in ticks, clamped to at least 2. The modifier is also removed early if its enchantment or custom item stops being active.

Example

type: refresh_attribute
target: SOURCE
attribute: minecraft:movement_speed
operation: ADD_NUMBER
amount: 0.03
duration: 100

Behavior and limits

• Identity is based on entity UUID, power ID, ability path, source slot, and attribute, so re-running the same source refreshes its modifier while duplicate sources can stack independently.

• A generation check prevents an older scheduled removal from deleting a refreshed modifier.

• A modifier is removed when its enchantment or custom item stops being active, even when duration is configured. When duration is omitted, source deactivation is its normal lifetime boundary.

• Modifiers are also removed on entity unload/plugin unload; health is clamped when maximum health falls.

• For a custom attribute, the target must be a player. A runtime-only modifier is refreshed and removed on expiry or source deactivation; it does not persist in PDC.

---

set_health

Purpose: Sets a living entity's current health.

Context: Default target: SOURCE; target must be living and alive.

Fields

Field	Default	Description
amount	1	New health; supports current/max-health and trigger-damage placeholders documented by the implementation.

Example

type: set_health
target: SOURCE
amount: 'min({max-health}, {health} + 6)'

Behavior and limits

• The value is clamped to the legal health range and hard-capped by the implementation.

• A value of zero may kill the entity.

---

set_absorption

Purpose: Sets a damageable entity's absorption amount.

Context: Default target: SOURCE; target must be damageable and alive.

Fields

Field	Default	Description
amount	10	New absorption value; supports {health} for current absorption and {max-health} for maximum absorption.

Example

type: set_absorption
target: SOURCE
amount: 'min({max-health}, {health} + 4)'

Behavior and limits

• Values are hard-capped at 2048 and then capped by the entity's maximum absorption.

• Dead or zero-health entities are skipped.

---

set_air

Purpose: Sets remaining air ticks.

Context: Default target: TARGET; selected entity must be living.

Fields

Field	Default	Description
amount	current air	New remaining air; supports {air} and {max-air}.

Example

type: set_air
target: TARGET
amount: 0

Behavior and limits

• The value is clamped between the implementation's lower bound and maximum air.

• Negative air can immediately continue drowning behavior when supported.

---

set_food

Purpose: Sets a player's food and saturation.

Context: Default target: SOURCE; selected entity must be a player.

Fields

Field	Default	Description
food	1	New food level, clamped to 0..20; {original} is current food.
saturation	0	New saturation, clamped to 0..20; {original} is current saturation.

Example

type: set_food
target: SOURCE
food: 20
saturation: 5

Behavior and limits

• Both fields are applied whenever the ability runs.

---

set_velocity

Purpose: Sets or modifies an entity's velocity.

Context: Default target: TARGET; directional modes may also require SOURCE.

Fields

Field	Default	Description
operation	SET	SET, ADD, MULTIPLY, or SCALE.
direction	VECTOR	VECTOR, LOOK, SOURCE_TO_TARGET, TARGET_TO_SOURCE, or UP.
x / y / z	0	Configured vector for VECTOR.
strength	1	Magnitude for directional modes.
vertical	0	Value added to generated Y velocity.
multiplier	1	Scalar for SCALE.

Example

type: set_velocity
target: TARGET
operation: SET
direction: SOURCE_TO_TARGET
strength: 1.2
vertical: 0.35

Behavior and limits

• Cross-world source/target directional vectors produce no useful direction.

• MULTIPLY is component-wise multiplication.

---

set_invulnerable

Purpose: Enables or disables entity invulnerability, optionally temporarily.

Context: Default target: SOURCE; requires an entity.

Fields

Field	Default	Description
value	true	Desired invulnerable state.
duration	0	Duration in ticks; non-positive uses persistent behavior.

Example

type: set_invulnerable
target: SOURCE
value: true
duration: 60

Behavior and limits

• Temporary restoration is scheduled by the ability utility and requires the entity to remain valid.

---

potion_effect

Purpose: Applies one potion effect to a living entity.

Context: Default target: TARGET; requires a living entity.

Fields

Field	Default	Description
potion	SLOWNESS	Potion-effect registry key.
duration	100	Duration in ticks.
infinite-duration-threshold	999999	Positive threshold that converts duration to infinite; zero disables conversion.
amplifier	0	Effect amplifier, minimum 0.
ambient	false	Ambient flag.
particles	true	Show particles.
icon	true	Show HUD icon.
accumulate	false	Add existing duration and retain higher amplifier.

Example

type: potion_effect
target: TARGET
potion: SLOWNESS
duration: 120
amplifier: 1
accumulate: true

Behavior and limits

• Finite duration is clamped to at least 1 tick.

• Accumulated duration saturates at the integer maximum.

---

remove_potion_effect

Purpose: Removes selected active potion effects from a living entity.

Context: Default target: TARGET; requires a living entity.

Fields

Field	Default	Description
potion	unset	Single exact effect or selector.
potions	empty	Ordered selectors; supports exact keys and categories such as ALL, BENEFICIAL, HARMFUL, and NEUTRAL.
max-effects	-1	Maximum effects removed; negative means unlimited.

Example

type: remove_potion_effect
target: TARGET
potions:
  - HARMFUL
  - minecraft:slowness
max-effects: 2

Behavior and limits

• Effects are selected deterministically by registry key within selector rules.

---

extend_potion_effects

Purpose: Extends the remaining duration of selected active potion effects.

Context: Default target: TARGET; requires a living entity.

Fields

Field	Default	Description
potion	HARMFUL	Single exact effect or category selector.
potions	empty	Ordered selectors; supports ALL, BENEFICIAL, HARMFUL, NEUTRAL, and exact effect keys.
percentage	0	Percentage added to each selected effect's current remaining duration.
multiplier	unset	Direct duration multiplier; when present, overrides percentage and is clamped to at least 1.
max-effects	-1	Maximum effects extended; negative means unlimited.

Example

type: extend_potion_effects
target: TARGET
potions:
  - minecraft:poison
  - minecraft:slowness
percentage: 20

Behavior and limits

• The amplifier, ambient flag, particles, and icon of each effect are preserved.

• Infinite effects are left unchanged.

• Finite durations are rounded to the nearest tick and saturate at the integer maximum.

• Effects are selected deterministically by registry key within selector rules.

---

potion_cloud

Purpose: Spawns an area-effect cloud with one custom potion effect.

Context: Default target: TARGET; cloud position uses the resolved trigger location.

Fields

Field	Default	Description
radius	3.0	Cloud radius.
duration	120	Cloud lifetime in ticks.
potion	POISON	Potion-effect key.
potion-duration	100	Effect duration.
potion-amplifier	1	Effect amplifier.
accumulate	false	Add sampled existing duration and keep higher amplifier.

Example

type: potion_cloud
potion: POISON
radius: 4
duration: 160
potion-duration: 100
potion-amplifier: 0

Behavior and limits

• Accumulation samples existing nearby effect state when the cloud is created; it is not recalculated independently for each future victim.

---

freeze

Purpose: Changes a living entity's freeze ticks.

Context: Default target: TARGET; requires a living entity.

Fields

Field	Default	Description
freeze-ticks	60	Configured freeze ticks, clamped to at least 0.
accumulate	false	Current implementation: false adds existing ticks; true replaces existing ticks.

Example

type: freeze
target: TARGET
freeze-ticks: 80
accumulate: false

Behavior and limits

• The historical accumulate option name is inverted relative to current implementation behavior.

---

fire

Purpose: Changes a living entity's fire ticks.

Context: Default target: TARGET; requires a living entity.

Fields

Field	Default	Description
fire-ticks	60	Configured fire ticks, clamped to at least 0.
accumulate	false	Current implementation: false adds existing ticks; true replaces existing ticks.

Example

type: fire
target: TARGET
fire-ticks: 100
accumulate: false

Behavior and limits

• The historical accumulate option name is inverted relative to current implementation behavior.

---

experience

Purpose: Gives raw experience points to a player.

Context: Default target: SOURCE; selected entity must be a player.

Fields

Field	Default	Description
amount	1	Points passed to Bukkit Player#giveExp; negative values follow platform behavior.

Example

type: experience
target: SOURCE
amount: 5

Behavior and limits

• This changes raw experience points, not a fixed number of levels.

---