> For the complete documentation index, see [llms.txt](https://enchantedmobs.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://enchantedmobs.superiormc.cn/configs/info-of-abilities/entity-state.md).

# 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](https://enchantedmobs.superiormc.cn/configs/info-of-abilities.md) page.

## Registry keys on this page

* `set_attribute`
* `refresh_attribute`
* `set_health`
* `set_absorption`
* `set_air`
* `set_food`
* `set_item_cooldown`
* `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

```yaml
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.

***

## `refresh_attribute`

**Purpose:** Adds or refreshes a Bukkit attribute modifier without changing the attribute's base value.

**Context:** Default `target`: `SOURCE`; selected entity must be living and expose the requested attribute.

### Fields

| Field       | Default                | Description                                                                                                                                          |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `attribute` | `minecraft:max_health` | Bukkit attribute registry key.                                                                                                                       |
| `amount`    | `0`                    | Modifier amount; supports the normal numeric placeholders.                                                                                           |
| `operation` | `ADD_NUMBER`           | `ADD_NUMBER`, `ADD_SCALAR`, or `MULTIPLY_SCALAR_1`. Modern aliases `ADD_VALUE`, `ADD_MULTIPLIED_BASE`, and `ADD_MULTIPLIED_TOTAL` are also accepted. |
| `duration`  | unset                  | Optional lifetime in ticks. Re-running the same configured ability refreshes this lifetime.                                                          |

### Example

```yaml
type: refresh_attribute
target: SOURCE
attribute: minecraft:movement_speed
amount: 0.25
operation: ADD_MULTIPLIED_BASE
duration: 100
```

### Behavior and limits

* Re-running the same ability replaces its previous modifier instead of stacking duplicates.
* Omitting `duration` keeps the modifier until the entity or plugin unloads.
* Timed removal and unload cleanup also clamp current health to the resulting maximum health.
* This ability supports Bukkit attributes only; it does not depend on EnchantmentReform custom attributes.

***

## `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

```yaml
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

```yaml
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

```yaml
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

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

### Behavior and limits

* Both fields are applied whenever the ability runs.

***

## `set_item_cooldown`

**Purpose:** Sets or clears a player's vanilla cooldown for one material.

**Context:** Default `target`: `TARGET`; selected entity must be a player.

### Fields

| Field      | Default              | Description                                                    |
| ---------- | -------------------- | -------------------------------------------------------------- |
| `target`   | `TARGET`             | Player selector.                                               |
| `material` | `SHIELD`             | Bukkit or namespaced material whose cooldown group is changed. |
| `ticks`    | `duration`, then `0` | Cooldown length in ticks; zero clears the cooldown.            |
| `duration` | `0`                  | Alias used when `ticks` is absent.                             |

### Example

```yaml
type: set_item_cooldown
target: TARGET
material: minecraft:shield
ticks: 100
```

### Behavior and limits

* Uses Bukkit `Player#setCooldown(Material, int)` and therefore follows the material's vanilla cooldown group.
* Non-player targets and invalid or air materials are skipped.
* Negative durations are clamped to zero.

***

## `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`, `LOOK_HORIZONTAL`, `RANDOM_HORIZONTAL_SIDE`, `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`.                                                                                             |
| `preserve-vertical`   | `false`   | Uses the target's current Y velocity instead of the generated vector's Y component.                             |
| `minimum-vertical`    | unlimited | Minimum Y velocity used while preserving vertical motion.                                                       |
| `reset-fall-distance` | `false`   | Resets the entity's fall distance after applying velocity.                                                      |

### Example

```yaml
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.
* `LOOK_HORIZONTAL` ignores look pitch and uses the normalized horizontal look direction.
* `RANDOM_HORIZONTAL_SIDE` selects the target's horizontal left or right side with equal probability; `RANDOM_SIDE` is an alias.

***

## `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

```yaml
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

```yaml
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

```yaml
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:** Scales 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 applied to each selected effect's current remaining duration; negative values shorten it.          |
| `multiplier`  | unset     | Non-negative duration multiplier; when present, overrides `percentage`. Zero removes selected finite effects. |
| `max-effects` | `-1`      | Maximum effects changed; negative means unlimited.                                                            |

### Example

```yaml
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, removed when the result is zero, and saturate at the integer maximum.
* Negative or `NaN` multipliers are ignored; positive overflow saturates 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

```yaml
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

```yaml
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

```yaml
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 or fixed experience levels to a player.

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

### Fields

| Field    | Default  | Description                                                                     |
| -------- | -------- | ------------------------------------------------------------------------------- |
| `amount` | `1`      | Experience amount to grant; negative values follow platform behavior.           |
| `mode`   | `POINTS` | `POINTS` grants raw experience points; `LEVELS` grants fixed experience levels. |

### Example

```yaml
type: experience
target: SOURCE
amount: 5
mode: POINTS
```

### Behavior and limits

* `POINTS` calls Bukkit `Player#giveExp`; `LEVELS` calls `Player#giveExpLevels`.

***
