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

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:

mob-power-generator:
  enabled: true
  ignore-custom-spawn: true
  default-level: '15~60'
  max-level: 400
  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.

• 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:

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

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, Power Conditions, and Power Modifiers.

Entity scanner optimization

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.