> 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/orchestration.md).

# Control-flow 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

* `delay`
* `conditional`
* `any_of`
* `limit`
* `repeat`
* `state`

***

## `delay`

**Purpose:** Runs nested abilities after a scheduled delay.

**Context:** Child abilities reuse the original `PowerContext`.

### Fields

| Field       | Default        | Description                               |
| ----------- | -------------- | ----------------------------------------- |
| `ticks`     | `delay` or `1` | Delay in server ticks, minimum 1.         |
| `delay`     | `1`            | Legacy alias used when `ticks` is absent. |
| `abilities` | required       | Nested ability entries.                   |

### Example

```yaml
type: delay
ticks: 20
abilities:
  strike:
    type: lightning
    target: TARGET
```

### Behavior and limits

* Entities and items can become invalid before execution.
* Scheduling follows the appropriate entity/region scheduler.

***

## `conditional`

**Purpose:** Executes every matching case and otherwise runs fallback abilities.

**Context:** Child conditions and abilities reuse the same context.

### Fields

| Field                   | Default | Description                                  |
| ----------------------- | ------- | -------------------------------------------- |
| `cases`                 | empty   | Map of case sections.                        |
| `cases.<id>.conditions` | empty   | AND condition group.                         |
| `cases.<id>.abilities`  | empty   | Children for a matching case.                |
| `else-abilities`        | empty   | Children executed once when no case matches. |

### Example

```yaml
type: conditional
cases:
  wounded:
    conditions:
      low:
        type: health_percent
        target: SOURCE
        max: 25
    abilities:
      heal:
        type: set_health
        target: SOURCE
        amount: 10
else-abilities:
  sound:
    type: sound
    sound: BLOCK_NOTE_BLOCK_BASS
```

### Behavior and limits

* Cases are evaluated in configuration order.
* All matching cases execute; matching does not stop after the first.
* Cancellation from any child is propagated.

***

## `any_of`

**Purpose:** Selects one or more weighted child abilities without replacement.

**Context:** Children reuse the same context.

### Fields

| Field                 | Default  | Description                             |
| --------------------- | -------- | --------------------------------------- |
| `amount`              | `1`      | Number of different children to select. |
| `abilities`           | required | Child map.                              |
| `abilities.<id>.rate` | `1`      | Positive finite relative weight.        |

### Example

```yaml
type: any_of
amount: 1
abilities:
  fire:
    type: fire
    rate: 5
    fire-ticks: 80
  lightning:
    type: lightning
    rate: 1
```

### Behavior and limits

* Invalid/non-positive weights are excluded.
* A selected child still runs its own checks; failure does not cause a replacement draw.
* Cancellation from selected children is propagated.

***

## `limit`

**Purpose:** Wraps nested abilities with one shared ability-level chance, cooldown, and execution count.

**Context:** Children reuse the same context.

### Fields

| Field       | Default  | Description                                  |
| ----------- | -------- | -------------------------------------------- |
| `abilities` | required | Nested abilities.                            |
| `random`    | `1`      | Wrapper probability.                         |
| `cooldown`  | `0`      | Wrapper cooldown in seconds.                 |
| `times`     | `0`      | Maximum wrapper attempts; zero is unlimited. |

### Example

```yaml
type: limit
cooldown: 10
times: 3
abilities:
  sound:
    type: sound
    sound: ENTITY_ENDERMAN_SCREAM
```

### Behavior and limits

* Children keep their own independent limits in addition to wrapper limits.
* Cancellation from children is propagated.

***

## `repeat`

**Purpose:** Executes nested abilities immediately and then repeatedly for a configured duration.

**Context:** Children reuse the original context.

### Fields

| Field            | Default                 | Description                                      |
| ---------------- | ----------------------- | ------------------------------------------------ |
| `abilities`      | required                | Nested abilities.                                |
| `duration`       | `duration-ticks` or `0` | Total duration; non-positive executes only once. |
| `duration-ticks` | `0`                     | Alias for duration.                              |
| `interval`       | `period` or `20`        | Ticks between executions, minimum 1.             |
| `period`         | `20`                    | Alias for interval.                              |

### Example

```yaml
type: repeat
duration: 100
interval: 20
abilities:
  pulse:
    type: particle
    particle: SONIC_BOOM
```

### Behavior and limits

* The first execution is immediate.
* Scheduled children must tolerate invalid entities/items/locations.

***

## `state`

**Purpose:** Stores numeric state scoped to the current power and optionally target, then triggers children at a threshold.

**Context:** Requires stable power/source identity. Triggered children receive the original context plus state-result placeholders.

### Fields

| Field                   | Default   | Description                                                                   |
| ----------------------- | --------- | ----------------------------------------------------------------------------- |
| `owner`                 | `SOURCE`  | Entity selector for the state owner.                                          |
| `key`                   | `default` | State-pool name.                                                              |
| `per-target`            | `false`   | Include target identity in the key.                                           |
| `state-target`          | `TARGET`  | Entity selector used as the per-target identity when `per-target` is enabled. |
| `operation`             | `ADD`     | `ADD`, `SET`, `SUBTRACT`, or `CLEAR`.                                         |
| `amount`                | `1`       | Operand.                                                                      |
| `maximum`               | unlimited | Maximum stored value.                                                         |
| `duration`              | `0`       | State lifetime in seconds; non-positive means no timed expiry.                |
| `trigger-at`            | unlimited | Threshold for child execution.                                                |
| `trigger-abilities`     | empty     | Children executed when the updated state reaches the threshold.               |
| `on-increase`           | empty     | Children executed when the stored value increases.                            |
| `on-decrease`           | empty     | Children executed when the stored value decreases.                            |
| `on-unchanged`          | empty     | Children executed when clamping leaves the value unchanged.                   |
| `clear-on-trigger`      | `true`    | Remove the state after execution when grouped consumption is disabled.        |
| `consume-trigger-value` | `false`   | Consume complete threshold groups and retain only the remainder.              |

Triggered children and the matching change callback receive `{state_previous}`, `{state_current}`, `{state_trigger_count}`, and `{state_remainder}`.

### Example

```yaml
type: state
key: combo
per-target: true
amount: 1
maximum: 5
duration: 4
trigger-at: 5
trigger-abilities:
  burst:
    type: damage_entity
    amount: 8
```

### Behavior and limits

* `CLEAR` removes state immediately.
* The `state_value` condition must use the same `key` and `per-target` setting, while its selectors must resolve to the same owner and per-target entity UUIDs. Selector names may differ across trigger contexts.
* Change callbacks run after `trigger-abilities` and only after the threshold is reached.
* Grouped consumption executes children once per update; scale effects with `{state_trigger_count}`.
* State is stored in memory and cleaned during runtime unload/entity cleanup.

***
