🧬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

• set_health

• 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 the base value of one Bukkit attribute on a living entity.

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

Fields

Field	Default	Description
attribute	max_health	Namespaced attribute key such as minecraft:max_health.
value	1	New base value; supports {now} for current base and {max} for the implementation comparison 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.

---

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_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.

---