> 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/info/2.0.0-migration.md).

# Migrating to 2.0.0

EnchantedMobs 2.0.0 is a major power-system rewrite. Existing power selection fields such as `apply-rules`, `placeholder`, and top-level `limit` remain familiar, but event execution now uses one consistent structure.

{% hint style="warning" %}
Back up `plugins/EnchantedMobs` before upgrading. Keep the old files outside the active `powers` folder while converting them so an invalid legacy file cannot interrupt loading.
{% endhint %}

## New execution model

Every trigger section now follows this order:

```yaml
on-attack:
  conditions:
    condition-id:
      type: health_percent
      target: SOURCE
      max: 50
  modifiers:
    modifier-id:
      type: damage
      operation: MULTIPLY
      value: 1.25
  abilities:
    ability-id:
      type: particle
      particle: CRIT
```

1. All trigger `conditions` must match.
2. `modifiers` update the trigger result in configuration order.
3. `abilities` execute in configuration order.

The keys such as `condition-id`, `modifier-id`, and `ability-id` are user-defined and only need to be unique inside their section.

## Required configuration changes

### Replace old event conditions with typed conditions

Legacy event-specific fields such as this:

```yaml
on-damage:
  conditions:
    min-damage: 5
    damage-cause:
      - FIRE
```

must be represented by typed condition entries:

```yaml
on-damage:
  conditions:
    enough-damage:
      type: damage_value
      min: 5
    caused-by-fire:
      type: damage_cause
      causes:
        - FIRE
```

Every condition entry requires `type`. Conditions are combined with logical AND by default. Use `type: any`, `type: not`, or a `conditional` ability for more advanced branching.

### Replace `modifier` with `modifiers`

The old singular section is no longer the documented 2.0.0 format:

```yaml
on-damage:
  modifier:
    damage: '{original} * 0.8'
```

Use typed modifiers:

```yaml
on-damage:
  modifiers:
    reduce-damage:
      type: damage
      operation: MULTIPLY
      value: 0.8
```

All value modifiers support `SET`, `ADD`, `SUBTRACT`, `MULTIPLY`, `DIVIDE`, `MIN`, and `MAX`. The current value is available as `{original}`.

### Review attack triggers

`on-attack` and `on-melee-attack` now have deliberately different meanings:

* `on-attack` handles outgoing damage owned by the powered monster, including direct melee, projectiles, TNT, area-effect clouds, and evoker fangs.
* `on-melee-attack` only handles cases where the powered monster itself is the direct Bukkit damager.

A 1.x power that expected arrows or other indirect damage inside `on-melee-attack` should normally rename that section to `on-attack`.

### Choose the correct incoming-damage trigger

* `on-damage` receives all incoming damage causes, including environmental damage.
* `on-damage-by-entity` only receives incoming damage caused by an entity.

Use typed `damage_cause`, `damage_origin`, `melee`, and `match_entity` conditions to narrow the event further.

## Projectile behavior

Projectile powers now retain a snapshot of the power IDs activated for that shot.

* `on-shoot-bow` handles bow/crossbow shooting and exposes bow-specific context.
* `on-projectile-launch` handles any Bukkit projectile launch from a monster.
* `on-projectile-tick` and `on-projectile-hit` continue only the captured powers.
* Top-level power limits are not rolled again for each tracked projectile tick or hit.
* If a modifier replaces the projectile, the tracking record moves to the replacement entity.
* The hit trigger removes the tracking record and stops its tick task.

This makes multi-stage projectile powers deterministic and prevents unrelated powers gained later from joining an existing projectile.

## Ability-level limits and conditions

Every ability may now directly use:

```yaml
conditions: {}
random: 0.5
cooldown: 5
times: 3
```

Legacy nested aliases under `limit` are still read by the common ability implementation, but the direct fields are recommended for new files.

Cooldown and usage state are tracked per configured ability path, so give sibling abilities unique YAML keys.

## New 2.0.0 features to review

* `any_of`: weighted selection of one or more child abilities without replacement.
* `experience`: add or remove player experience with a signed `amount`.
* `set_food`: set player food and saturation.
* `set_velocity`: set, add, multiply, or scale velocity.
* `swap_health`: swap source and target health percentages.
* `swap_locations`: exchange source and target locations.
* `swap_potion_effects`: transfer or swap selected potion effects.
* New typed power conditions and modifiers.
* `on-projectile-launch`, `on-damage-by-entity`, and `on-attack` triggers.
* `interval` support for `on-tick` and `on-target-tick`.
* Extension registries for abilities, modifiers, conditions, and custom triggers.

## Changes added after the initial 2.0.0 rewrite

The latest 2.0.0 code also includes:

* `summon.entities`: randomly select one entity type from an equal-weight list.
* `summon.set-target`: assign the spawned mob a `SOURCE`, `SKILL`, or `TARGET` combat target.
* `summon.set-none-drops`: remove normal loot and equipment drop chances and disable item pickup.
* `hide-name`: exclude a power from mob-name and BossBar power lists without disabling it.

The bundled `HealthMultiplier` power has `hide-name: true`; other bundled powers default to visible.

## Recommended conversion workflow

1. Start from the bundled 2.0.0 powers generated by a clean installation.
2. Convert one custom power at a time.
3. Replace legacy conditions and modifiers with typed entries.
4. Verify whether `on-melee-attack` should become `on-attack`.
5. Check selectors (`SOURCE`, `SKILL`, and `TARGET`) for every ability and condition.
6. Reload and review the console for unknown registry keys or malformed YAML.
7. Test projectile, cooldown, and usage-count behavior with a freshly spawned mob.