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

# Mechanic

EnchantedMobs derives a level from nearby players, assigns powers through a weighted level-budget system, and executes those powers through the 2.0 trigger runtime.

## Player strength

Player strength is configured in `plugins/EnchantedMobs/player-power.yml`.

```yaml
placeholderapi-cache-ticks: 20
formula: '{equipment_sum} + {backpack_max} * 0.8 + {backpack_avg} * 0.2'
incremental-slot-update: true

rules:
  diamond-sword:
    match-item:
      material:
        - DIAMOND_SWORD
    add-weight: 50
```

### Built-in formula variables

* `{equipment_sum}`: total rule weight of equipped armor slots.
* `{backpack_sum}`: total rule weight of non-equipment inventory items.
* `{backpack_max}`: highest non-equipment item weight.
* `{backpack_avg}`: average non-equipment item weight.
* `{backpack_count}`: number of counted non-equipment items.

Numeric PlaceholderAPI placeholders may also be used when PlaceholderAPI is installed.

### Item rules

Each entry under `rules` has a unique ID, a `match-item` section, and `add-weight`.

* The normal Match Item format is supported.
* One item may match multiple rules; matching weights are accumulated.
* Rules can target materials, enchantments, custom-item integrations, names, lore, tags, and other documented item conditions.

### Update and cache settings

* `incremental-slot-update: true` calculates the full inventory when a player joins and then updates changed slots incrementally.
* `false` recalculates the full inventory after supported inventory changes.
* `placeholderapi-cache-ticks` caches the final power value when PlaceholderAPI participates in the formula. `0` disables that cache.

Use `/enchantedmobs power [player]` to inspect a calculated value. With PlaceholderAPI installed, `%enchantedmobs_player_power%` exposes it to other plugins.

## Automatic powered mobs

The generator is controlled by `config.yml`:

```yaml
mob-power-generator:
  enabled: true
  ignore-custom-spawn: true
  default-level: '15~60'
  max-level: 400
  max-powers: 0
  spawn-chance: '5~25'
  player-scan-range: 48
  disabled-worlds: []
  disabled-entity:
    entity-types:
      - WARDEN
      - WITHER
```

### Generation checks

When a supported monster spawns, the plugin checks:

1. whether automatic generation is enabled;
2. whether the world is disabled;
3. whether the entity matches `disabled-entity`;
4. whether a custom/plugin spawn should be ignored;
5. whether `spawn-chance` succeeds.

Peaceful mobs and internally unsupported entity categories are not turned into powered monsters by the automatic generator.

### Level selection

* Players are scanned within `player-scan-range` around the spawn location.
* When players are found, their power values are averaged and used as the mob level reference.
* When no player is found, `default-level` is used.
* The result is capped by `max-level`.
* `max-powers` caps the total number of assigned powers; `0` or a negative value means unlimited.
* `default-level` accepts an integer or inclusive integer range such as `15~60`.

`/enchantedmobs chunkpower` displays the nearby average used as a useful generation reference.

### Spawn chance

`spawn-chance` accepts either:

* a decimal probability from `0` to `1`, such as `0.25`;
* a percentage-like number greater than `1`, such as `25`;
* an inclusive integer range such as `5~25`, resolved before conversion to a probability.

The final probability is clamped from `0` to `1`.

## Power candidate selection

Each enabled power contributes an `apply-rules` candidate:

```yaml
apply-rules:
  group: ranged_projectile
  group-unique: true
  always-select: false
  weight: 5
  level-weight: 15
  conflicts:
    - Flying
  match-entity:
    equip:
      main-hand:
        material:
          - BOW
          - CROSSBOW
          - TRIDENT
```

A power is eligible only when:

* it is enabled;
* `match-entity` matches the mob;
* its resolved `level-weight` is greater than `0`;
* it does not conflict with an already selected power;
* its cost fits the remaining level budget during normal selection.

### Groups

* `group` selects a candidate pool; the default is `default`.
* The generator shuffles group order each round.
* It attempts one weighted choice from each available group per round.
* A non-unique group can participate again in later rounds while budget remains.
* `group-unique: true` consumes the group after one selected power.

### Weight and cost

* `weight` is the relative probability inside the current group.
* `level-weight` is the budget cost of normal selection.
* Dynamic numeric values, formulas, ranges, and `{level}` may be used where supported by the power resolver.
* Selection stops when `max-powers` is reached, the level budget is exhausted, no candidate can fit, or no group can make progress.

### Always-selected powers

`always-select: true` or its alias `always-pick: true` selects the candidate before normal weighted rounds.

* Always-selected candidates are processed in stable power-ID order.
* They still respect entity matching, enabled state, positive `level-weight`, conflicts, and unique groups.
* They count toward `max-powers` and stop being added once that limit is reached.
* They do not reduce the normal remaining level budget in the current implementation.

The bundled hidden `HealthMultiplier` power uses this mechanism so health scaling can be applied independently of visible combat-power selection.

### Conflicts

Both `conflicts` and `conflict-with` are accepted. Conflict IDs are normalized case-insensitively with hyphens treated as underscores.

Conflict checks are bidirectional: if either selected candidate declares the other, they cannot coexist.

## Power display

Assigned power IDs are stored on the entity and cached by the scanner. Visible powers are rendered through:

* `mob-display.name` for the custom mob name;
* `mob-display.bossbar` for nearby players.

Each display can be disabled independently with its `enabled` option. Both are enabled by default.

A power with `hide-name: true` remains assigned and fully functional but is excluded from both visible power lists. The default health-scaling power is hidden.

## Trigger execution

When a built-in or API trigger fires for a powered mob:

1. the trigger captures owner/source/skill/target/location context;
2. top-level power limits are checked;
3. every typed trigger condition must match;
4. modifiers update the trigger result in order;
5. abilities execute in order;
6. the final trigger result is applied to the Bukkit event or tracked runtime object.

Tracked projectile tick/hit continuation uses only the powers captured for that projectile and does not reroll top-level limits on every continuation event.

See [Mob Powers](/configs/mob-powers.md), [Power Conditions](https://github.com/ManyouTeam/EnchantedMobs2/tree/master/docs/configs/power-conditions.md), and [Power Modifiers](https://github.com/ManyouTeam/EnchantedMobs2/tree/master/docs/configs/power-modifiers.md).

## Entity scanner optimization

```yaml
optimize:
  enabled-entity-scanner-cache: true
  enabled-projectile-tick: true
```

The entity scanner cache tracks powered living entities as they load, spawn, die, and unload instead of performing a full-world search every tick. Paper generally provides the most complete event behavior; Folia support remains experimental and uses scheduler-safe paths where implemented.