# Welcome
Welcome to **EnchantedMobs 2**, a configurable plugin that adds level-scaled powers to naturally spawned monsters.
The plugin focuses on extending vanilla combat rather than replacing it:
* Monsters keep their normal AI and behavior.
* Powers are assembled from YAML using triggers, conditions, modifiers, and abilities.
* Visual effects are used selectively so ordinary enhanced mobs remain practical on production servers.
* Difficulty can scale with nearby players and coexist with custom items, enchantments, weapons, skills, and companion systems.
## What changed in 2.0.0?
Version 2.0.0 replaces the old per-event implementation with one unified execution model:
1. A **trigger** creates a runtime context.
2. Typed **conditions** decide whether the power continues.
3. Typed **modifiers** change event values such as damage, healing, projectile data, explosion yield, or revive health.
4. Ordered **abilities** apply the configured effects.
The update also adds reusable registries for abilities, conditions, modifiers, and custom triggers; new control-flow actions such as `any_of`; new player and movement actions; improved projectile tracking; many new bundled powers; and per-power display hiding with `hide-name`.
{% hint style="warning" %}
Custom power files written for 1.x may require changes. Read the [2.0.0 migration guide](/info/2.0.0-migration) before updating a production server.
{% endhint %}
## Recommended reading
* [2.0.0 migration guide](/info/2.0.0-migration)
* [Mob Powers](/configs/mob-powers)
* [Power conditions](/configs/power-conditions)
* [Power modifiers](/configs/power-modifiers)
* [Ability common options](/configs/info-of-abilities)
## Links
### Get the plugin
* **SpigotMC:** [Premium](https://www.spigotmc.org/resources/enchantedmobs-dynamic-mob-abilities-and-player-scaling-difficulty-1-21-3-26-1-1.133242/)
* **Polymart:** [Premium](https://voxel.shop/product/9464/enchantedmobs)
* **BuiltByBit:** [Premium](https://builtbybit.com/resources/enchantedmobs.97592/)
### Get support
Support is provided through the [Discord server](https://discord.gg/RZajEybhBw). Please read the server rules and plugin license before requesting assistance.
Users in mainland China who purchased the plugin may use QQ group `815351827` with proof of purchase.
# Requirements
## Java Version
* Basic Requirement: **Java21+**
## Server Software
| Server | Can work in your server | Can get offical support |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Spigot | ✅
Some features does not provide in Spigot servers
| ✅ |
| Paper/Purpur | ✅
Can provide subtle performance improvements.
| ✅ |
| Folia | ❓
Any problems only occurs in Folia servers may not be solved. Plugin is not designed for multi thread support.
| ❓
Folia's support is in the early testing stage and may be released in official versions or removed in the future. This support is not a guarantee.
|
| Other softwares | ❌ | ❌ |
## Server Version
| Version | Can work in your server | Can get offical support |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **Below 1.21.3** | ❌ | ❌ |
| **1.21.3 and above** | ✅
Using versions 1.21.5 and above is the most recommended, as you can enjoy the best features.
| ✅ |
* If you encounter errors while using a certain version, please join our Discord feedback.
{% hint style="info" %}
This documentation is written for game version **1.21.11**. Some content may differ on lower versions.
{% endhint %}
# Install
## Install
* Download the plugin from the official release site. The file name should be **EnchantedMobs-X.X.X.jar**, where X is the version number.
* Put the `.jar` file into your server's `plugins` folder.
* Stop your server and then restart it. Cannot load plugins in any other way while the server is starting.
* When updating plugins, please be sure to remove old versions.
* Previously, you used the free version, but now to upgrade to the paid version, you only need to install the paid version on the server and remove the free version. The configuration file of the plugin does not require any changes.
* When downgrading from **a new game version** to **an old version** on the server where the plugin is located, it is important to remove the `items` folder from the configuration file.
* Default configs are just helping you understand the config framework, you need modify them that meet your needs.
## Update
* When updating plugins, please be sure to remove old versions.
* You should always keep the plugin updated to the latest version.
* To prevent your custom config files from being overwritten or broken, the plugin does not auto-update existing configs. You can manually merge changes from new default configs, or regenerate fresh config files.
* Before every update, read the changelog carefully. If you skip multiple versions, review all changelogs in between. Major breaking changes will be noted there.
# Compatibility
EnchantedMobs loads integrations only when the corresponding plugin is present. Missing optional plugins do not prevent normal startup.
## Item providers
The default item-hook implementation directly supports:
* ItemsAdder
* Oraxen
* MMOItems
* EcoItems
* EcoArmor
* MythicMobs items
* eco
* NeigeItems
* ExecutableItems
* Nexo
* CraftEngine
These integrations are used by ItemFormat, saved items, item matching, equipment abilities, and configuration fields that request a provider item by plugin name and item ID.
See [ItemFormat™](/format/itemformat-tm) for the local item format reference.
## ItemBridge mode
`config.yml` can switch item resolution to ItemBridge:
```yaml
hook-item-method: ITEMBRIDGE
```
When enabled, the plugin asks ItemBridge to detect its supported providers. If ItemBridge cannot resolve an item, EnchantedMobs falls back to a directly registered item hook when available.
The default mode is:
```yaml
hook-item-method: DEFAULT
```
Use ItemBridge mode when you need one of its additional providers or standardized ID detection. Keep the default mode when the built-in hooks already cover the server and you prefer fewer integration layers.
## MythicMobs
MythicMobs integration provides:
* MythicMobs item resolution;
* the `mythicmobs` Match Entity rule;
* the `mythic_skill` ability for running a configured MythicMobs skill.
The relevant feature safely remains unavailable when MythicMobs is not loaded.
## LevelledMobs
When LevelledMobs is installed, the `levelledmobs` Match Entity rule is registered. This allows power selection rules and typed `match_entity` conditions to include LevelledMobs-specific matching.
## PlaceholderAPI
The expansion identifier is `enchantedmobs` and currently provides:
| Placeholder | Result |
| ------------------------------ | ----------------------------------------------------------------------------- |
| `%enchantedmobs_player_power%` | Calculated strength of the online player. |
| `%enchantedmobs_chunk_power%` | Nearby average player strength using `mob-power-generator.player-scan-range`. |
Offline or unavailable player context resolves to `0`.
PlaceholderAPI placeholders that return numbers may also be used in the `player-power.yml` formula. `placeholderapi-cache-ticks` controls caching of the final value when formula placeholders are involved.
## NBTAPI
When NBTAPI is installed, additional legacy NBT Match Item rules are registered.
Example:
```yaml
nbt:
string:
customNBT: Hello
int:
anotherNBTComponent.theNBTKey: 5
```
Supported value groups include:
* `byte`
* `short`
* `int`
* `long`
* `float`
* `double`
* `string`
For modern Minecraft item components, prefer the normal ItemFormat and native matching options where possible.
## Other declared optional dependencies
The plugin metadata also declares optional loading relationships for integrations such as MythicChanger and PacketEvents. Availability of a concrete feature still depends on the current implementation and installed plugin version; check startup logs to confirm that a hook was registered successfully.
# Configuration files
EnchantedMobs creates its data folder at `plugins/EnchantedMobs`.
The plugin generates the following configuration files, some of which will only be generated after you first use this feature.
* `items` folder: stores saved item files. Saved items created by the item commands.
* `languages` folder: stores language message files. Language files and translated power display text.
These two folders are less critical. Focus on the following:
* `powers` folder: stores all created power files. One YAML file per mob power. The filename without `.yml` is the power ID.
* `config.yml`: stores general plugin configuration, like power generation, display, optimization, language, math, and combat settings.
* `player-power.yml`: stores how player strength is calculated. Calculates player strength from inventory items, enchantments, and optional PlaceholderAPI values.
* `generated-item-format.yml`: Output from `/enchantedmobs generateitemformat`; created when the command is used.
{% hint style="info" %}
The bundled files in the latest JAR are the source of truth for defaults. When upgrading a major version, compare your existing files with the current repository resources instead of assuming newly added keys are injected automatically.
{% endhint %}
## Latest default files
* [`config.yml`](https://github.com/ManyouTeam/EnchantedMobs2/blob/master/plugin/src/main/resources/config.yml)
* [`player-power.yml`](https://github.com/ManyouTeam/EnchantedMobs2/blob/master/plugin/src/main/resources/player-power.yml)
* [`powers/`](https://github.com/ManyouTeam/EnchantedMobs2/tree/master/plugin/src/main/resources/powers/README.md)
## Current `config.yml` sections
```yaml
debug: false
display-spawn-message: false
optimize:
enabled-projectile-tick: true
enabled-entity-scanner-cache: true
powers:
temp-block-crack-animation:
enabled: true
start-at: 0.5
update-interval: 5
view-distance: 64
config-files:
language: en_US
per-player-language: true
force-parse-mini-message: true
debuild-item-method: LEGACY
hook-item-method: DEFAULT
math:
enabled: true
enable-function: true
mob-power-generator: {}
mob-display: {}
mob-combat: {}
```
### `debug`
Enables plugin debugging output. Leave disabled on normal production servers unless support asks for additional logs.
### `display-spawn-message`
When enabled, players with `enchantedmobs.nodify` can receive powered-mob spawn notifications.
### `optimize`
* `enabled-projectile-tick`: enables the tracked projectile tick runtime used by `on-projectile-tick`.
* `enabled-entity-scanner-cache`: caches powered living entities instead of repeatedly scanning every world.
Disabling an optimization can change performance substantially and should normally be used only for compatibility testing.
### `powers.temp-block-crack-animation`
Controls the client-side break animation for temporary blocks created by powers:
* `enabled`
* `start-at`: initial progress ratio before animation begins.
* `update-interval`: ticks between progress updates.
* `view-distance`: maximum viewer distance.
### `config-files`
* `language`: default language file ID.
* `per-player-language`: premium per-player language selection.
* `force-parse-mini-message`: parse supported text through MiniMessage formatting.
### Item serialization and hooks
* `debuild-item-method`: item deserialization compatibility mode.
* `hook-item-method`: item-provider integration method; current supported values include `DEFAULT` and `ITEMBRIDGE`.
### `math`
* `enabled`: enables configured formula evaluation.
* `enable-function`: enables registered math functions in formulas.
### `mob-power-generator`
```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
```
`max-powers` limits the total number of powers assigned to one mob. The generator stops adding powers when this limit or the `max-level` budget is reached first. Set it to `0` or a negative value for no power-count limit.
See [Mechanic](/configs/mechanic) for level calculation and power rolling.
### `mob-display`
```yaml
mob-display:
name:
enabled: true
format: '&6[{powers}] &f{mob}'
separator: ', '
max-show: 4
more: '...(+{count})'
bossbar:
enabled: true
min-powers: 2
keep-ticks: 20
radius: 16
color: RED
style: SOLID
title: '&c{entity} &7[{health}/{max-health}] &f{powers_full}'
```
Set `name.enabled` or `bossbar.enabled` to `false` to disable the corresponding display feature. Both options default to `true`.
Individual power files may set `hide-name: true` to remove that power from the visible name and BossBar power lists without disabling its behavior.
### `mob-combat`
```yaml
mob-combat:
disable-powered-mob-friendly-fire: false
disarm-auto-return-item: true
min-damage: 1
```
* `disable-powered-mob-friendly-fire`: cancel damage between powered monsters when enabled.
* `disarm-auto-return-item`: return an item dropped by the `disarm` ability when it would otherwise be removed.
* `min-damage`: minimum damage threshold used by the combat runtime.
## `player-power.yml`
The current default formula is:
```yaml
placeholderapi-cache-ticks: 20
formula: '{equipment_sum} + {backpack_max} * 0.8 + {backpack_avg} * 0.2'
incremental-slot-update: true
```
Built-in variables:
* `{equipment_sum}`
* `{backpack_sum}`
* `{backpack_max}`
* `{backpack_avg}`
* `{backpack_count}`
Numeric PlaceholderAPI placeholders may also be used when PlaceholderAPI is installed. Item rules use the normal Match Item format and matching rule weights are added together.
## Current player-powers.yml section.
{% code title="" %}
```yaml
# Built-in variables:
# {equipment_sum} {backpack_sum} {backpack_max} {backpack_avg} {backpack_count}
# PlaceholderAPI placeholders that resolve to numbers are also supported when PlaceholderAPI is installed.
# Built-in variables are refreshed when the player's inventory changes; PlaceholderAPI values are resolved in real time when power is read.
# Final player power value cache for PlaceholderAPI results, in ticks. 0 = disable cache.
placeholderapi-cache-ticks: 20
# Example:
# formula: "{equipment_sum} + %player_level% * 10"
formula: "{equipment_sum} + {backpack_max} * 0.8 + {backpack_avg} * 0.2"
incremental-slot-update: true
rules:
wooden-sword:
match-item:
material:
- WOODEN_SWORD
add-weight: 5
stone-sword:
match-item:
material:
- STONE_SWORD
add-weight: 10
golden-sword:
match-item:
material:
- GOLDEN_SWORD
add-weight: 15
iron-sword:
match-item:
material:
- IRON_SWORD
add-weight: 30
diamond-sword:
match-item:
material:
- DIAMOND_SWORD
add-weight: 50
netherite-sword:
match-item:
material:
- NETHERITE_SWORD
add-weight: 80
trident:
match-item:
material:
- TRIDENT
add-weight: 70
bow:
match-item:
material:
- BOW
add-weight: 35
crossbow:
match-item:
material:
- CROSSBOW
add-weight: 40
shield:
match-item:
material:
- SHIELD
add-weight: 15
leather-helmet:
match-item:
material:
- LEATHER_HELMET
add-weight: 5
leather-chestplate:
match-item:
material:
- LEATHER_CHESTPLATE
add-weight: 10
leather-leggings:
match-item:
material:
- LEATHER_LEGGINGS
add-weight: 8
leather-boots:
match-item:
material:
- LEATHER_BOOTS
add-weight: 7
golden-helmet:
match-item:
material:
- GOLDEN_HELMET
add-weight: 10
golden-chestplate:
match-item:
material:
- GOLDEN_CHESTPLATE
add-weight: 20
golden-leggings:
match-item:
material:
- GOLDEN_LEGGINGS
add-weight: 18
golden-boots:
match-item:
material:
- GOLDEN_BOOTS
add-weight: 15
chainmail-helmet:
match-item:
material:
- CHAINMAIL_HELMET
add-weight: 12
chainmail-chestplate:
match-item:
material:
- CHAINMAIL_CHESTPLATE
add-weight: 25
chainmail-leggings:
match-item:
material:
- CHAINMAIL_LEGGINGS
add-weight: 20
chainmail-boots:
match-item:
material:
- CHAINMAIL_BOOTS
add-weight: 18
iron-helmet:
match-item:
material:
- IRON_HELMET
add-weight: 15
iron-chestplate:
match-item:
material:
- IRON_CHESTPLATE
add-weight: 35
iron-leggings:
match-item:
material:
- IRON_LEGGINGS
add-weight: 30
iron-boots:
match-item:
material:
- IRON_BOOTS
add-weight: 25
diamond-helmet:
match-item:
material:
- DIAMOND_HELMET
add-weight: 20
diamond-chestplate:
match-item:
material:
- DIAMOND_CHESTPLATE
add-weight: 55
diamond-leggings:
match-item:
material:
- DIAMOND_LEGGINGS
add-weight: 40
diamond-boots:
match-item:
material:
- DIAMOND_BOOTS
add-weight: 35
netherite-helmet:
match-item:
material:
- NETHERITE_HELMET
add-weight: 30
netherite-chestplate:
match-item:
material:
- NETHERITE_CHESTPLATE
add-weight: 80
netherite-leggings:
match-item:
material:
- NETHERITE_LEGGINGS
add-weight: 60
netherite-boots:
match-item:
material:
- NETHERITE_BOOTS
add-weight: 50
sharpness:
match-item:
contains-enchants:
sharpness: 3
add-weight: 20
sharpness-high:
match-item:
contains-enchants:
sharpness: 4
add-weight: 35
smite:
match-item:
contains-enchants:
smite: 3
add-weight: 15
bane-of-arthropods:
match-item:
contains-enchants:
bane_of_arthropods: 3
add-weight: 15
fire-aspect:
match-item:
contains-enchants:
fire_aspect: [1,2]
add-weight: 10
knockback:
match-item:
contains-enchants:
knockback: [1,2]
add-weight: 8
sweeping-edge:
match-item:
contains-enchants:
sweeping_edge: [2,3]
add-weight: 10
looting:
match-item:
contains-enchants:
looting: [2,3]
add-weight: 8
protection:
match-item:
contains-enchants:
protection: 2
add-weight: 15
protection-high:
match-item:
contains-enchants:
protection: 3
add-weight: 25
fire-protection:
match-item:
contains-enchants:
fire_protection: [2,3,4]
add-weight: 12
blast-protection:
match-item:
contains-enchants:
blast_protection: [2,3,4]
add-weight: 12
projectile-protection:
match-item:
contains-enchants:
projectile_protection: [2,3,4]
add-weight: 12
thorns:
match-item:
contains-enchants:
thorns: [1,2,3]
add-weight: 10
feather-falling:
match-item:
contains-enchants:
feather_falling: [3,4]
add-weight: 10
depth-strider:
match-item:
contains-enchants:
depth_strider: [2,3]
add-weight: 8
soul-speed:
match-item:
contains-enchants:
soul_speed: [1,2,3]
add-weight: 8
power:
match-item:
contains-enchants:
power: 3
add-weight: 18
power-high:
match-item:
contains-enchants:
power: 4
add-weight: 30
punch:
match-item:
contains-enchants:
punch: [1,2]
add-weight: 10
flame:
match-item:
contains-enchants:
flame: 1
add-weight: 10
multishot:
match-item:
contains-enchants:
multishot: 1
add-weight: 12
piercing:
match-item:
contains-enchants:
piercing: [2,3,4]
add-weight: 10
quick-charge:
match-item:
contains-enchants:
quick_charge: [2,3]
add-weight: 8
loyalty:
match-item:
contains-enchants:
loyalty: [2,3]
add-weight: 10
riptide:
match-item:
contains-enchants:
riptide: [2,3]
add-weight: 8
impaling:
match-item:
contains-enchants:
impaling: [3,4,5]
add-weight: 15
channeling:
match-item:
contains-enchants:
channeling: 1
add-weight: 12
unbreaking:
match-item:
contains-enchants:
unbreaking: [2,3]
add-weight: 5
mending:
match-item:
contains-enchants:
mending: 1
add-weight: 8
```
{% endcode %}
# 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.
# Commands & Permissions
Main command: `/enchantedmobs`\
Aliases: `/em`, `/emobs`
All examples may use any alias. Console-only restrictions and required coordinates are noted below.
## Command permissions
Each subcommand uses `enchantedmobs.`:
| Command | Permission |
| -------------------- | ---------------------------------- |
| `reload` | `enchantedmobs.reload` |
| `saveitem` | `enchantedmobs.saveitem` |
| `givesaveitem` | `enchantedmobs.givesaveitem` |
| `generateitemformat` | `enchantedmobs.generateitemformat` |
| `spawnmob` | `enchantedmobs.spawnmob` |
| `spawnrandommob` | `enchantedmobs.spawnrandommob` |
| `power` | `enchantedmobs.power` |
| `chunkpower` | `enchantedmobs.chunkpower` |
`enchantedmobs.nodify` is separate and controls powered-mob spawn notifications when `display-spawn-message` is enabled.
## `reload`
```
/enchantedmobs reload
```
Reloads general configuration, language files, saved items, player-power configuration, powers, and related runtime state.
A full restart is still recommended after replacing the plugin JAR, dependencies, or server software.
## `saveitem`
```
/enchantedmobs saveitem [bukkit|itemformat]
```
Player only. Saves the item in the main hand under the specified ID.
* `bukkit` is the default serialization mode.
* `itemformat` uses the plugin's ItemFormat representation.
## `givesaveitem`
```
/enchantedmobs givesaveitem [player] [amount]
```
Gives a saved item to yourself or another online player. Console usage must include a player.
## `generateitemformat`
```
/enchantedmobs generateitemformat
```
Player only. Exports the main-hand item to `generated-item-format.yml`.
## `spawnmob`
```
/enchantedmobs spawnmob [world x y z]
```
Spawns a mob with an explicit level and power list.
* Players may omit coordinates to use their current location.
* Console usage requires world and coordinates.
* Power IDs must match loaded files in `plugins/EnchantedMobs/powers`.
## `spawnrandommob`
```
/enchantedmobs spawnrandommob [world x y z]
```
Spawns a mob and generates powers from the specified level budget.
* Players may omit coordinates to use their current location.
* Console usage requires world and coordinates.
## `power`
```
/enchantedmobs power [player]
```
Displays your calculated player strength or the value for a specified online player.
## `chunkpower`
```
/enchantedmobs chunkpower
```
Player only. Displays the nearby average player strength used as a reference for automatic mob-level generation.
# FAQ
### Reward/Drops/Block Totem Spawn
To ensure that the plugin is lightweight enough, it does not have built-in new rewards and drop mechanisms. However, you can achieve this through our [MythicRewards](https://www.spigotmc.org/resources/mythicrewards-boss-kill-reward-drop-plugin-with-custom-rule-support-1-20-5-1-21-11.129453/) plugin.\
In addition, if you are interested in using the block structure to summon EnchantedMobs and the Bonus Totem feature, you may want to check out our [MythicTotem](https://www.spigotmc.org/resources/mythictotem-custom-boss-spawn-totem-and-bonus-totem-all-in-1-1-20-5-1-21-11.102466/).
# ItemFormat™
The **Item Format** provided by **EnchantedMobs** are almost identical to those in UltimateShop. Therefore, they will not be elaborated on in this wiki. Please refer to UltimateShop's wiki for a detailed introduction about them. Click [here](https://ultimateshop.superiormc.cn/format) to view.
# Math Calculate Format
When `config.yml -> math.enabled` is enabled, supported numeric fields may use expressions instead of fixed values.
```yaml
value: '2 + {level} * 0.5'
random: '0.1 + {level} * 0.02'
```
The expression syntax is almost identical to UltimateShop's math format. See the [UltimateShop format documentation](https://ultimateshop.superiormc.cn/format) for the complete operator and function reference.
## Available values
Depending on the receiving field and current trigger, expressions may include:
* `level` or `{level}`;
* root power `variables`;
* runtime entity values such as `{owner_health}`, `{source_health}`, `{target_health_percent}`, and `{skill_fall_distance}`;
* `{distance}` between `SOURCE` and `TARGET` when both exist in the same world;
* numeric trigger context placeholders listed below;
* field-specific values such as `{original}`, `{now}`, `{max}`, or other values documented by that Ability, Power Condition, or Power Modifier;
* numeric PlaceholderAPI results when a player viewer is available.
## Numeric trigger context placeholders
Every numeric entry created through `BuiltinContextKeys` is automatically exposed using its key name inside braces. Only `Number` types such as `Double`, `Float`, and `Integer` are registered; booleans, entities, items, and enum values are not treated as mathematical variables.
| Placeholder | Number type | Context value |
| --------------------- | ----------- | --------------------------------------------------------------------- |
| `{original_damage}` | `Double` | Damage captured before compatible damage modifiers execute. |
| `{original_amount}` | `Double` | Original generic mutable amount, such as health-regain amount. |
| `{original_duration}` | `Float` | Original duration supplied by a duration-capable trigger. |
| `{original_yield}` | `Float` | Original explosion yield supplied by a compatible explosion trigger. |
| `{original_radius}` | `Float` | Original explosion radius supplied by a compatible explosion trigger. |
| `{minimum_damage}` | `Double` | Minimum-damage floor carried by compatible damage triggers. |
| `{bow_force}` | `Float` | Bow draw force supplied by a compatible ranged trigger. |
| `{target_count}` | `Integer` | Number of targets supplied by a compatible targeting context. |
A placeholder is replaced only when the active trigger supplied that value. An unavailable context value remains unresolved, so use each placeholder only with compatible triggers.
```yaml
on-attack:
abilities:
heal-from-damage:
type: set_health
target: OWNER
amount: 'min({owner_health} + {original_damage} * 0.25, {owner_max_health})'
```
The same placeholders work in context-aware text fields and in numeric fields resolved through `getDouble(...)` or `getInt(...)`.
## Variables and resolution order
Root power variables are resolved before numeric trigger context placeholders. A reusable variable may therefore reference runtime values:
```yaml
variables:
damage-bonus: '{original_damage} * (0.1 + {level} * 0.01)'
on-attack:
modifiers:
increase-damage:
type: damage
operation: ADD
value: '{damage-bonus}'
```
Resolution follows this order:
1. level and field-specific arguments;
2. root power variables;
3. numeric trigger context placeholders;
4. entity and distance placeholders;
5. PlaceholderAPI values.
Adding another numeric built-in `ContextKey` automatically creates a placeholder with the same key name; no separate expression-parser registration is required.
## Random ranges
```yaml
amount: 2~5
```
This selects a value between the two endpoints using the resolver expected by the field.
## Level selectors
```yaml
amount:
'==1': 2
'>=2;;<=4': '2 + {level}'
'>=5': 10
```
Entries are evaluated from top to bottom, and the first matching selector is used. Quote selector keys in YAML.
# Match Item Format
`MatchItemFormat` is the shared configuration format used whenever EnchantedMobs needs to test an `ItemStack`.
Common locations include `match-item` sections in `player-power.yml`, equipment matching inside `MatchEntityFormat`, and abilities that filter an item before acting on it.
```yaml
match-item:
material:
- diamond_sword
has-enchants:
- sharpness
```
The example matches a diamond sword that has Sharpness.
## Evaluation rules
A MatchItemFormat section does not use a `type` field. Each recognized key enables one rule.
```yaml
match-item:
material:
- diamond_sword
has-name: true
contains-name:
- Legendary
```
Rules on the same level use **AND**:
1. the item must be a diamond sword;
2. the item must have a custom display name;
3. that name must contain `Legendary`.
Within most list-based rules, entries use **OR**. For example, `material: [diamond_sword, netherite_sword]` accepts either material.
### Empty and invalid inputs
* A missing MatchItemFormat section matches everything.
* A missing item does not match.
* An item without `ItemMeta` does not match.
* An unrecognized key is ignored by the matcher.
* `none: true` forces the section to fail.
## Logical composition
Use `any` when one of several alternatives may match:
```yaml
match-item:
any:
1:
material:
- diamond_sword
has-enchants:
- sharpness
2:
items:
- mythic_sword
```
Each numbered group uses AND internally; the numbered groups use OR.
Use `not` to reject items that match any nested rule:
```yaml
match-item:
material-tag:
- minecraft:swords
not:
contains-name:
- Broken
```
See [Logical and NBT Rules](/format/match-item-format/logic-nbt) for both supported `any` layouts and the exact `not` behavior.
## Optional rule availability
| Rules | Requirement |
| ----------------------------------------------------------------- | ---------------------------------------------------------- |
| `contains-nbt`, `nbt-string`, `nbt-byte`, `nbt-int`, `nbt-double` | NBTAPI must be loaded when EnchantedMobs starts. |
| `rarity` | Minecraft/Paper 1.20.5 or newer. |
| External IDs in `items` | The corresponding supported item plugin must be installed. |
Unavailable optional rules are not registered. Their configuration keys are therefore ignored rather than treated as a failed match.
## Rule index
| Rule key | Reference |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `none` | [Basic and Metadata Rules](/format/match-item-format/basic-metadata#none) |
| `items` | [Basic and Metadata Rules](/format/match-item-format/basic-metadata#items) |
| `material` | [Basic and Metadata Rules](/format/match-item-format/basic-metadata#material) |
| `material-tag` | [Basic and Metadata Rules](/format/match-item-format/basic-metadata#material-tag) |
| `rarity` | [Basic and Metadata Rules](/format/match-item-format/basic-metadata#rarity) |
| `has-name` | [Basic and Metadata Rules](/format/match-item-format/basic-metadata#has-name) |
| `contains-name` | [Basic and Metadata Rules](/format/match-item-format/basic-metadata#contains-name) |
| `has-lore` | [Basic and Metadata Rules](/format/match-item-format/basic-metadata#has-lore) |
| `contains-lore` | [Basic and Metadata Rules](/format/match-item-format/basic-metadata#contains-lore) |
| `has-enchants` | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format#has-enchants) |
| `has-stored-enchants` | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format#has-stored-enchants) |
| `contains-enchants` | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format#contains-enchants) |
| `contains-enchants-amount` | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format#contains-enchants-amount) |
| `enchantable` | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format#enchantable) |
| `item-format` | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format#item-format) |
| `any` | [Logical and NBT Rules](/format/match-item-format/logic-nbt#any) |
| `not` | [Logical and NBT Rules](/format/match-item-format/logic-nbt#not) |
| `contains-nbt` | [Logical and NBT Rules](/format/match-item-format/logic-nbt#contains-nbt) |
| `nbt-string` | [Logical and NBT Rules](/format/match-item-format/logic-nbt#nbt-string) |
| `nbt-byte` | [Logical and NBT Rules](/format/match-item-format/logic-nbt#nbt-byte) |
| `nbt-int` | [Logical and NBT Rules](/format/match-item-format/logic-nbt#nbt-int) |
| `nbt-double` | [Logical and NBT Rules](/format/match-item-format/logic-nbt#nbt-double) |
## Complete example
```yaml
match-item:
material-tag:
- minecraft:swords
has-name: true
any:
1:
has-enchants:
- sharpness
2:
items:
- superior_sword
not:
contains-lore:
- Disabled
```
The item must be a sword with a name, must match either the Sharpness group or the external-ID group, and must not contain `Disabled` in its lore.
## Related references
* [MatchEntityFormat](/format/match-entity-format): entity matching and nested equipment matching.
* [ItemFormat™](/format/itemformat-tm): the serialized structure used by the `item-format` rule.
* [Abilities](/configs/info-of-abilities): abilities such as `disarm` that may use item matching.
# Basic and Metadata Rules
Every rule on this page is a key inside a [MatchItemFormat](/format/match-item-format) section.
***
## `none`
**Purpose:** Forces the entire MatchItemFormat section to fail.
**Context:** No item property is inspected.
### Fields
| Field | Default | Description |
| ------ | ------- | ------------------------------------------- |
| `none` | `false` | The rule is active only when set to `true`. |
### Example
```yaml
match-item:
none: true
```
### Behavior and limits
* Useful for explicitly disabling a configuration branch.
* `none: false` does not enable the rule and is ignored.
* Because same-level rules use AND, an active `none` makes every other rule irrelevant.
***
## `items`
**Purpose:** Matches the item ID returned by EnchantedMobs' item-plugin integration layer.
**Context:** Requires an item with metadata. External IDs require the corresponding supported plugin.
### Fields
| Field | Default | Description |
| ------------------- | ------- | --------------------------------------------------------------------------------------- |
| `items` | empty | Accepted item or material IDs. Entries use OR. |
| `use-tier-identify` | `false` | For integrations that support tiers, compare the tier ID instead of the normal item ID. |
### Example
```yaml
match-item:
items:
- diamond_sword
- superior_sword
use-tier-identify: false
```
### Behavior and limits
* The parsed item ID must equal one list entry.
* Vanilla items normally resolve to their material ID.
* MMOItems IDs are normally uppercase.
* ItemsAdder IDs require their namespace, for example `my_pack:flame_sword`.
* Tier identification is integration-dependent and is commonly used with MMOItems or EcoItems.
***
## `material`
**Purpose:** Matches the Bukkit material of the item.
**Context:** Works with any item that has metadata.
### Fields
| Field | Default | Description |
| ---------- | ------- | --------------------------------------- |
| `material` | empty | Accepted material keys. Entries use OR. |
### Example
```yaml
match-item:
material:
- diamond_sword
- NETHERITE_SWORD
```
### Behavior and limits
* Matching is case-insensitive because configured values are converted to lowercase.
* The implementation compares against the material key without a namespace, such as `diamond_sword`.
* Prefer `diamond_sword` or `DIAMOND_SWORD`, not `minecraft:diamond_sword`.
***
## `material-tag`
**Purpose:** Matches Bukkit item or block material tags.
**Context:** The tag must exist in the server's item-tag or block-tag registry.
### Fields
| Field | Default | Description |
| -------------- | ------- | -------------------------------------------------- |
| `material-tag` | empty | Accepted namespaced material tags. Entries use OR. |
### Example
```yaml
match-item:
material-tag:
- minecraft:swords
- minecraft:logs
```
### Behavior and limits
* Each value is resolved as a namespaced key.
* The item registry is checked first and the block registry is checked second.
* A missing or invalid tag does not match, but other entries are still tested.
* A material only needs to belong to one configured tag.
***
## `rarity`
**Purpose:** Matches the explicit Bukkit `ItemRarity` stored in the item's metadata.
**Context:** Registered only on Minecraft/Paper 1.20.5 or newer.
### Fields
| Field | Default | Description |
| -------- | ------- | ----------------------------------------------------------------------------- |
| `rarity` | unset | Expected `ItemRarity` enum name, or `NONE` when no explicit rarity is stored. |
### Example
```yaml
match-item:
rarity: EPIC
```
### Behavior and limits
* Comparison is case-insensitive.
* The rule reads explicit item metadata, not the color that happens to be displayed to a player.
* An item without an explicit rarity is represented as `NONE`.
* On older server versions the rule is not registered, so the key is ignored.
***
## `has-name`
**Purpose:** Checks whether the item has a custom display name.
**Context:** Uses Bukkit `ItemMeta#hasDisplayName`.
### Fields
| Field | Default | Description |
| ---------- | ------- | ----------------------------------------------------------------- |
| `has-name` | unset | `true` requires a display name; `false` requires no display name. |
### Example
```yaml
match-item:
has-name: true
```
### Behavior and limits
* This checks presence only; it does not compare the name text.
* Use `contains-name` when specific text is required.
* The rule is active whenever the key exists, including when its value is `false`.
***
## `contains-name`
**Purpose:** Matches text contained in the item's custom display name.
**Context:** The item must have a display name.
### Fields
| Field | Default | Description |
| --------------- | ------- | ---------------------------------------- |
| `contains-name` | empty | Accepted text fragments. Entries use OR. |
### Example
```yaml
match-item:
contains-name:
- Legendary
- Ancient
```
### Behavior and limits
* Formatting is removed from both the item name and configured fragment before comparison.
* The remaining substring comparison is case-sensitive.
* The default translated material name is not used; the item must have a custom display name.
* Only one configured fragment needs to occur.
***
## `has-lore`
**Purpose:** Checks whether the item has lore.
**Context:** Uses Bukkit `ItemMeta#hasLore`.
### Fields
| Field | Default | Description |
| ---------- | ------- | ----------------------------------------------- |
| `has-lore` | unset | `true` requires lore; `false` requires no lore. |
### Example
```yaml
match-item:
has-lore: false
```
### Behavior and limits
* This checks only whether lore exists.
* Use `contains-lore` to inspect lore text.
* The rule is active whenever the key exists, including when its value is `false`.
***
## `contains-lore`
**Purpose:** Matches text contained in any lore line.
**Context:** The item must have lore.
### Fields
| Field | Default | Description |
| --------------- | ------- | ------------------------------------------------------------------------ |
| `contains-lore` | empty | Accepted text fragments. Entries use OR across fragments and lore lines. |
### Example
```yaml
match-item:
contains-lore:
- Soulbound
- Cannot be traded
```
### Behavior and limits
* Formatting is removed from both lore lines and configured fragments.
* The remaining substring comparison is case-sensitive.
* A match in any one lore line is sufficient.
* The rule does not require every configured fragment to be present.
# Enchantment and ItemFormat Rules
Every rule on this page is a key inside a [MatchItemFormat](/format/match-item-format) section.
***
## `has-enchants`
**Purpose:** Checks whether an item directly contains one of the configured enchantments.
**Context:** Reads normal enchantments from `ItemMeta#getEnchants`.
### Fields
| Field | Default | Description |
| -------------- | ------- | ------------------------------------------------------------------------------ |
| `has-enchants` | empty | Accepted enchantment keys. Entries use OR. `*` accepts any direct enchantment. |
### Example
```yaml
match-item:
has-enchants:
- minecraft:sharpness
- minecraft:smite
```
### Behavior and limits
* Enchantment keys are resolved through Bukkit's enchantment registry.
* Names are converted to lowercase before resolution.
* This rule checks only presence, not enchantment level.
* Stored enchantments on enchanted books are not read by this rule; use `has-stored-enchants`.
* `*` matches when the direct enchantment map is not empty.
***
## `has-stored-enchants`
**Purpose:** Checks whether an enchanted book stores one of the configured enchantments.
**Context:** Requires `EnchantmentStorageMeta`, normally an enchanted book.
### Fields
| Field | Default | Description |
| --------------------- | ------- | ------------------------------------------------------------------------------------- |
| `has-stored-enchants` | empty | Accepted stored enchantment keys. Entries use OR. `*` accepts any stored enchantment. |
### Example
```yaml
match-item:
has-stored-enchants:
- minecraft:mending
```
### Behavior and limits
* A non-storage item immediately fails.
* This checks presence only, not level.
* Enchantment keys are resolved through Bukkit's registry.
* `*` matches when at least one stored enchantment exists.
***
## `contains-enchants`
**Purpose:** Matches a configured enchantment and its level requirement.
**Context:** Reads stored enchantments from enchanted books and direct enchantments from other items.
### Fields
| Field | Default | Description |
| --------------------------------- | ------- | ------------------------------------------------------------- |
| `contains-enchants.` | unset | A scalar minimum threshold or a list of exact allowed levels. |
### Examples
Require Sharpness above level 3:
```yaml
match-item:
contains-enchants:
minecraft:sharpness: 3
```
Accept exactly level 1, 3, or 5:
```yaml
match-item:
contains-enchants:
minecraft:sharpness:
- 1
- 3
- 5
```
### Behavior and limits
* A scalar uses a strict comparison: the actual level must be **greater than** the configured value. `3` therefore accepts level 4 or higher, not level 3.
* A YAML list uses exact-level membership.
* The current implementation returns after the first resolvable enchantment entry. Do not place several enchantment keys in one `contains-enchants` section expecting all or any of them to be evaluated.
* To express alternatives, place separate `contains-enchants` sections inside numbered `any` groups.
* Unknown enchantment keys are skipped until a resolvable entry is found.
***
## `contains-enchants-amount`
**Purpose:** Matches the number of enchantments on the item.
**Context:** Counts stored enchantments for enchanted books and direct enchantments for other items.
### Fields
| Field | Default | Description |
| -------------------------- | ------- | ------------------------------------------------------------- |
| `contains-enchants-amount` | unset | A scalar inclusive minimum or a list of exact allowed counts. |
### Examples
Require at least three enchantments:
```yaml
match-item:
contains-enchants-amount: 3
```
Accept exactly one, three, or five enchantments:
```yaml
match-item:
contains-enchants-amount:
- 1
- 3
- 5
```
### Behavior and limits
* A scalar uses `actual >= configured`.
* A list performs exact count matching.
* Direct and stored enchantments are never added together; the metadata type decides which map is counted.
***
## `enchantable`
**Purpose:** Checks whether at least one configured enchantment can normally enchant the item.
**Context:** Uses Bukkit `Enchantment#canEnchantItem`.
### Fields
| Field | Default | Description |
| ------------- | ------- | ----------------------------------------- |
| `enchantable` | empty | Enchantment keys to test. Entries use OR. |
### Example
```yaml
match-item:
enchantable:
- minecraft:sharpness
- minecraft:smite
```
### Behavior and limits
* This tests vanilla/Bukkit compatibility, not whether the item already has the enchantment.
* Registry keys are normalized to lowercase.
* Existing conflicting enchantments, anvil rules, plugin overrides, and unsafe-enchantment APIs are not considered by this matcher.
* One compatible enchantment is sufficient.
***
## `item-format`
**Purpose:** Compares selected serialized ItemFormat™ values against the current item.
**Context:** The current item is converted with EnchantedMobs' `DebuildItem` implementation before comparison.
### Fields
| Field | Default | Description |
| --------------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `item-format` | required | Expected ItemFormat™ subtree. |
| `item-format-settings.require-same-key` | `false` | Also require every non-ignored key on the actual item to exist in the configured format. |
| `item-format-settings.ignore-key` | empty | Exact flattened paths, or parent paths whose descendants should be ignored. |
### Example
```yaml
match-item:
item-format:
material: ENCHANTED_BOOK
stored-enchants:
mending: 1
item-format-settings:
require-same-key: false
ignore-key:
- damage
```
### Comparison modes
With `require-same-key: false`, the configured format is a required subset:
* every configured non-ignored leaf must exist on the item;
* the item may contain additional keys.
With `require-same-key: true`, the actual item may not contain additional non-ignored keys:
* every configured leaf must match;
* every actual leaf must also exist in the configured format.
### Behavior and limits
* `amount` is always ignored, even when it is not listed in `ignore-key`.
* An ignored path also ignores all descendants. Ignoring `stored-enchants` ignores entries such as `stored-enchants.mending`.
* String values fall back to case-insensitive comparison.
* Non-string leaf values use exact Java object equality, so YAML value types matter.
* Intermediate configuration sections are structural and are not compared as leaf values.
* Generate a starting format by holding an item and running `/em generateitemformat`.
* This is stricter and more expensive than simple `material`, `items`, or enchantment rules; use those simpler rules when possible.
# Logical and NBT Rules
Every rule on this page is a key inside a [MatchItemFormat](/format/match-item-format) section.
## Logical rules
***
## `any`
**Purpose:** Accepts an item when at least one nested alternative matches.
**Context:** Nested sections use the same MatchItemFormat rules.
### Fields
| Field | Default | Description |
| ----- | ------- | ----------------------------------------- |
| `any` | unset | A direct rule section or numbered groups. |
### Direct-rule layout
```yaml
match-item:
any:
material:
- diamond_sword
contains-name:
- Relic
```
When `any` does not contain a key named `1`, every directly nested rule is tested independently. The example matches a diamond sword **or** an item whose name contains `Relic`.
### Numbered-group layout
```yaml
match-item:
any:
1:
material:
- diamond_sword
has-enchants:
- sharpness
2:
items:
- superior_sword
```
When `any` contains a key named `1`, each child is treated as a complete MatchItemFormat group:
* rules inside one numbered group use AND;
* numbered groups use OR.
### Behavior and limits
* An empty `any` section returns true.
* The numbered form is detected specifically by the presence of key `1`; use consecutive numeric keys beginning with `1`.
* In the direct layout, keys are alternatives rather than an AND group.
* Use the numbered layout whenever one alternative needs several rules.
***
## `not`
**Purpose:** Rejects an item when any nested rule matches.
**Context:** Nested keys use the same MatchItemFormat rules.
### Fields
| Field | Default | Description |
| ----- | ------- | --------------------------------------- |
| `not` | unset | Rules whose matches should be rejected. |
### Example
```yaml
match-item:
material-tag:
- minecraft:swords
not:
contains-name:
- Broken
has-lore: false
```
### Behavior and limits
* Nested rules are tested as separate rejection alternatives.
* The example rejects the item if its name contains `Broken` **or** if it has no lore.
* `not` does not invert the AND result of all nested keys as one group.
* To reject a specific combination, place that combination in an `any` group outside the current matcher or restructure the surrounding configuration.
* An empty `not` section matches because no nested rule rejects the item.
## NBTAPI rules
The rules below are registered only when the plugin named `NBTAPI` is loaded during EnchantedMobs startup.
NBT paths use `;;` between compound names, the final key, operators, and values. Entries in each list use OR.
***
## `contains-nbt`
**Purpose:** Checks whether at least one NBT key exists.
**Context:** Requires NBTAPI.
### Fields
| Field | Default | Description |
| -------------- | ------- | ---------------------- |
| `contains-nbt` | unset | NBT key paths to test. |
### Example
```yaml
match-item:
contains-nbt:
- CustomModelData
- PublicBukkitValues;;myplugin:bound
```
### Behavior and limits
* A single segment checks a root key.
* Multiple segments traverse compounds and use the final segment as the required key.
* The value and NBT type are not checked.
* One existing key is sufficient.
* Missing compounds or keys do not match.
***
## `nbt-string`
**Purpose:** Matches an NBT string value exactly.
**Context:** Requires NBTAPI and an NBT string tag at the selected path.
### Fields
| Field | Default | Description |
| ------------ | ------- | ------------------------------------------------------------------- |
| `nbt-string` | unset | Entries in `path;;key;;value` form, or `key;;value` for a root key. |
### Example
```yaml
match-item:
nbt-string:
- owner;;Ming
- PublicBukkitValues;;myplugin:class;;warrior
```
### Behavior and limits
* Root syntax is `key;;expected-value`.
* Nested syntax is `compound[;;compound...];;key;;expected-value`.
* The tag must be NBT string type.
* String comparison is exact and case-sensitive.
* The delimiter cannot be escaped inside a compound, key, or expected value.
***
## `nbt-byte`
**Purpose:** Compares an NBT byte value.
**Context:** Requires NBTAPI and an NBT byte tag.
### Fields
| Field | Default | Description |
| ---------- | ------- | -------------------------------------------------------------------------------- |
| `nbt-byte` | unset | Entries in `path;;key;;operator;;value` form, or `key;;operator;;value` at root. |
### Example
```yaml
match-item:
nbt-byte:
- Unbreakable;;==;;1
- data;;enabled;;>=;;1
```
### Behavior and limits
* Supported operators are `>=`, `>`, `<=`, `<`, and `==`.
* The expected value must fit Java's byte range.
* Invalid operators or numbers do not match; malformed numeric values may also produce a configuration-time/runtime parsing error when evaluated.
* Comparison uses the actual NBT byte value, not a boolean conversion.
***
## `nbt-int`
**Purpose:** Compares an NBT integer value.
**Context:** Requires NBTAPI and an NBT integer tag.
### Fields
| Field | Default | Description |
| --------- | ------- | -------------------------------------------------------------------------------- |
| `nbt-int` | unset | Entries in `path;;key;;operator;;value` form, or `key;;operator;;value` at root. |
### Example
```yaml
match-item:
nbt-int:
- CustomModelData;;>=;;1000
- stats;;kills;;>;;25
```
### Behavior and limits
* Supported operators are `>=`, `>`, `<=`, `<`, and `==`.
* The tag must be NBT integer type; byte, long, and double tags do not match.
* Nested compounds may be chained with additional `;;` segments.
* Entries use OR.
***
## `nbt-double`
**Purpose:** Compares an NBT double value.
**Context:** Requires NBTAPI and an NBT double tag.
### Fields
| Field | Default | Description |
| ------------ | ------- | -------------------------------------------------------------------------------- |
| `nbt-double` | unset | Entries in `path;;key;;operator;;value` form, or `key;;operator;;value` at root. |
### Example
```yaml
match-item:
nbt-double:
- quality;;>=;;0.75
- stats;;critical_chance;;>;;0.2
```
### Behavior and limits
* Supported operators are `>=`, `>`, `<=`, `<`, and `==`.
* `==` uses Java double equality; it does not apply an epsilon tolerance.
* Integer or float NBT tags do not match an NBT double rule.
* Invalid paths, types, operators, or values do not produce a match.
# Match Entity Format
`MatchEntityFormat` is the shared configuration format used whenever EnchantedMobs needs to test a living entity.
It is used by power-generation `match-entity` sections, the `match_entity` Power Condition, and abilities such as `nearby_entities` that filter candidate entities.
```yaml
match-entity:
entity-types:
- ZOMBIE
- SKELETON
entity-health: 20
```
The example matches a zombie or skeleton whose current health is at least 20.
## Evaluation rules
A MatchEntityFormat section does not use a `type` field. Each recognized key enables one rule.
Rules on the same level use **AND**:
```yaml
match-entity:
monster: true
ranged: true
entity-health: 10
```
The entity must be a Bukkit monster, must satisfy the ranged check, and must currently have at least 10 health.
Within most list-based rules, entries use **OR**.
### Empty and invalid inputs
* A missing MatchEntityFormat section matches everything.
* A missing entity does not match.
* MatchEntityFormat accepts `LivingEntity`; non-living entities cannot be evaluated by this matcher.
* An unrecognized key is ignored.
* `none: true` forces the section to fail.
## Logical composition
Use numbered `any` groups for alternatives that contain several rules:
```yaml
match-entity:
any:
1:
entity-types:
- SKELETON
ranged: true
2:
mythicmobs:
- SkeletonKing
```
Use `not` to reject any entity matching a nested rule:
```yaml
match-entity:
monster: true
not:
entity-types:
- CREEPER
entity-tag:
- minecraft:bosses
```
See [Logical Rules](/format/match-entity-format/logic) for exact `any` and `not` behavior.
## Nested equipment matching
The `equip` rule contains one [MatchItemFormat](/format/match-item-format) section per equipment slot:
```yaml
match-entity:
equip:
main-hand:
material-tag:
- minecraft:swords
helmet:
material:
- carved_pumpkin
```
Configured equipment slots use OR: matching either the main hand or helmet is enough for the `equip` rule to pass.
## Optional rule availability
| Rule | Requirement |
| -------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `mythicmobs` | MythicMobs must be loaded when EnchantedMobs starts. |
| `levelled-mobs` | LevelledMobs must be loaded when EnchantedMobs starts. |
| Paper-specific `ranged` classification | On Paper, the entity must implement Paper's `RangedEntity` and hold a supported ranged weapon. |
Unavailable integration rules are not registered. Their keys are ignored rather than treated as a failed match.
## Rule index
| Rule key | Reference |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| `entity-types` | [Identity and State Rules](/format/match-entity-format/identity-state#entity-types) |
| `none` | [Identity and State Rules](/format/match-entity-format/identity-state#none) |
| `entity-contains-name` | [Identity and State Rules](/format/match-entity-format/identity-state#entity-contains-name) |
| `entity-health` | [Identity and State Rules](/format/match-entity-format/identity-state#entity-health) |
| `entity-tag` | [Identity and State Rules](/format/match-entity-format/identity-state#entity-tag) |
| `entity-pdc` | [Identity and State Rules](/format/match-entity-format/identity-state#entity-pdc) |
| `ranged` | [Identity and State Rules](/format/match-entity-format/identity-state#ranged) |
| `monster` | [Identity and State Rules](/format/match-entity-format/identity-state#monster) |
| `equip` | [Equipment and Integration Rules](/format/match-entity-format/equipment-integrations#equip) |
| `mythicmobs` | [Equipment and Integration Rules](/format/match-entity-format/equipment-integrations#mythicmobs) |
| `levelled-mobs` | [Equipment and Integration Rules](/format/match-entity-format/equipment-integrations#levelled-mobs) |
| `any` | [Logical Rules](/format/match-entity-format/logic#any) |
| `not` | [Logical Rules](/format/match-entity-format/logic#not) |
## Complete example
```yaml
match-entity:
monster: true
entity-health: 20
any:
1:
ranged: true
equip:
main-hand:
material:
- bow
- crossbow
2:
mythicmobs:
- SkeletonKing
not:
entity-types:
- CREEPER
```
The entity must be a monster with at least 20 current health. It must either be a ranged bow/crossbow user or the MythicMob `SkeletonKing`, and it must not be a creeper.
## Related references
* [MatchItemFormat](/format/match-item-format): item rules used by `equip`.
* [Power Conditions](/configs/power-conditions): the `match_entity` condition selects a trigger-context entity and applies this format.
* [Abilities](/configs/info-of-abilities): `nearby_entities` uses MatchEntityFormat to filter nearby living entities.
* [Mechanics](/configs/mechanic): power generation uses `apply-rules.match-entity`.
# Identity and State Rules
Every rule on this page is a key inside a [MatchEntityFormat](/format/match-entity-format) section.
***
## `entity-types`
**Purpose:** Matches the Bukkit entity type.
**Context:** The candidate must be a living entity.
### Fields
| Field | Default | Description |
| -------------- | ------- | -------------------------------------------------------- |
| `entity-types` | empty | Accepted Bukkit `EntityType` enum names. Entries use OR. |
### Example
```yaml
match-entity:
entity-types:
- ZOMBIE
- WITHER_SKELETON
```
### Behavior and limits
* Comparison is case-insensitive.
* Values are compared with Bukkit enum names, not namespaced registry keys.
* One matching entity type is sufficient.
***
## `none`
**Purpose:** Forces the MatchEntityFormat section to fail.
**Context:** No entity property is inspected.
### Fields
| Field | Default | Description |
| ------ | ------- | ---------------------------------------------------------------- |
| `none` | unset | Presence of this key activates the always-fail rule. Use `true`. |
### Example
```yaml
match-entity:
none: true
```
### Behavior and limits
* Useful for disabling a branch without deleting it.
* Because same-level rules use AND, an active `none` makes the whole section fail.
* The current implementation contains two internal handlers for this key; use only `none: true` and do not rely on `none: false` as an inversion rule.
***
## `entity-contains-name`
**Purpose:** Matches text contained in the entity's resolved name.
**Context:** Uses EnchantedMobs' entity-name resolver, which can include a custom name.
### Fields
| Field | Default | Description |
| ---------------------- | ------- | ---------------------------------------- |
| `entity-contains-name` | empty | Accepted name fragments. Entries use OR. |
### Example
```yaml
match-entity:
entity-contains-name:
- Elite
- Guardian
```
### Behavior and limits
* Formatting is removed from both the entity name and configured text.
* The remaining substring comparison is case-sensitive.
* One fragment is sufficient.
* Prefer stable tags, PDC, entity types, or plugin IDs when names can be localized or changed by another plugin.
***
## `entity-health`
**Purpose:** Requires a minimum current health value.
**Context:** Reads the living entity's current health, not maximum health or health percentage.
### Fields
| Field | Default | Description |
| --------------- | ------- | --------------------------------- |
| `entity-health` | unset | Inclusive minimum current health. |
### Example
```yaml
match-entity:
entity-health: 40
```
### Behavior and limits
* The comparison is `current health >= configured value`.
* There is no built-in maximum or percentage form in this rule.
* For more complex runtime checks inside a power, use the typed health Power Conditions.
***
## `entity-tag`
**Purpose:** Matches a Bukkit entity-type tag or the special monster classification.
**Context:** Uses the server's entity-type tag registry.
### Fields
| Field | Default | Description |
| ------------ | ------- | ---------------------------------------------------------------------------------- |
| `entity-tag` | empty | Accepted namespaced entity tags. Entries use OR. The literal `monster` is special. |
### Example
```yaml
match-entity:
entity-tag:
- minecraft:skeletons
- monster
```
### Behavior and limits
* The exact lowercase value `monster` checks `entity instanceof org.bukkit.entity.Monster`.
* Other values are parsed as namespaced keys and looked up in Bukkit's entity-type tag registry.
* A missing or invalid tag does not match, but later entries are still checked.
* One matching tag is sufficient.
***
## `entity-pdc`
**Purpose:** Matches values stored in the entity's Bukkit `PersistentDataContainer`.
**Context:** Keys must be valid namespaced keys and must be stored as a supported Bukkit persistent-data type.
### Fields
| Field | Default | Description |
| ----------------------------- | ------- | ----------------------------------------------------------------------- |
| `entity-pdc.` | unset | Expected string, numeric expression, or boolean. Different keys use OR. |
### Examples
```yaml
match-entity:
entity-pdc:
myplugin:class: warrior
myplugin:level: '>=10'
myplugin:boss: true
```
Numeric range:
```yaml
match-entity:
entity-pdc:
myplugin:level: '10~20'
```
String wildcard:
```yaml
match-entity:
entity-pdc:
myplugin:variant: 'fire_*'
```
### Supported stored types
| Stored type | Matching behavior |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `STRING` | Case-insensitive equality or containment; `*` enables a case-insensitive regular-expression-style wildcard. |
| `INTEGER`, `DOUBLE`, `LONG`, `FLOAT` | Numeric comparison. |
| `BYTE` | Treated as boolean: zero is `false`, non-zero is `true`. |
Numeric rules support:
* `5~10` — inclusive range;
* `>=5`, `>5`, `<=5`, `<5`;
* `=5` or `5` — equality with a `0.0001` tolerance.
### Behavior and limits
* Configured PDC keys use OR; the first matching key passes the rule.
* For string values, plain text also performs case-insensitive substring matching. Configuring `war` matches `warrior`.
* `*` is converted directly to `.*`; other regular-expression characters are not escaped.
* Unsupported PDC types such as arrays and nested containers do not match.
* Invalid numeric expressions fail safely.
***
## `ranged`
**Purpose:** Checks whether the entity is treated as a ranged attacker.
**Context:** Inspects the main-hand item and, on Paper, the `RangedEntity` interface.
### Fields
| Field | Default | Description |
| -------- | ------- | --------------------------------------------------------------------- |
| `ranged` | unset | `true` requires ranged classification; `false` requires the opposite. |
### Example
```yaml
match-entity:
ranged: true
```
### Behavior and limits
* A supported ranged weapon is `BOW`, `CROSSBOW`, or `TRIDENT` in the main hand.
* On Paper, an entity that does not implement Paper's `RangedEntity` is not considered ranged even when holding one of those items.
* On non-Paper implementations, the main-hand weapon check is used without the Paper interface requirement.
* The rule describes current equipment/classification, not whether the entity is currently attacking at range.
***
## `monster`
**Purpose:** Checks Bukkit's hostile-monster class.
**Context:** Uses `entity instanceof org.bukkit.entity.Monster`.
### Fields
| Field | Default | Description |
| --------- | ------- | ------------------------------------------------------------------------ |
| `monster` | unset | `true` requires a monster; `false` requires a non-monster living entity. |
### Example
```yaml
match-entity:
monster: false
```
### Behavior and limits
* This is a Bukkit class check, not a check for aggression, target state, or team hostility.
* Some dangerous or boss entities may not implement Bukkit's `Monster` interface; use `entity-types` or `entity-tag` when exact coverage matters.
* The rule is active whenever the key exists, including when set to `false`.
# Equipment and Integration Rules
Every rule on this page is a key inside a [MatchEntityFormat](/format/match-entity-format) section.
***
## `equip`
**Purpose:** Matches one of the entity's configured equipment slots using MatchItemFormat.
**Context:** The entity must expose Bukkit `EntityEquipment`; each configured slot contains a [MatchItemFormat](/format/match-item-format) section.
### Fields
| Field | Default | Description |
| ------------------ | ------- | -------------------------- |
| `equip.main-hand` | unset | Match the main-hand item. |
| `equip.off-hand` | unset | Match the off-hand item. |
| `equip.helmet` | unset | Match the helmet item. |
| `equip.chestplate` | unset | Match the chestplate item. |
| `equip.leggings` | unset | Match the leggings item. |
| `equip.boots` | unset | Match the boots item. |
### Example
```yaml
match-entity:
equip:
main-hand:
material:
- bow
- crossbow
helmet:
contains-name:
- Commander
```
### Behavior and limits
* Configured slots use **OR**. The example passes when either the main hand is a bow/crossbow or the helmet name contains `Commander`.
* Rules inside one slot's MatchItemFormat use their normal same-level AND behavior.
* An entity without an equipment object fails this rule.
* A missing/empty slot normally fails that slot's MatchItemFormat.
* To require several equipment slots simultaneously, place each slot requirement in separate surrounding MatchEntityFormat checks; one `equip` block cannot express slot-level AND by itself.
***
## `mythicmobs`
**Purpose:** Matches a MythicMobs internal mob ID.
**Context:** Registered only when MythicMobs is loaded. The entity must be an active MythicMob instance.
### Fields
| Field | Default | Description |
| ------------ | ------- | --------------------------------------------------- |
| `mythicmobs` | empty | Accepted MythicMobs internal names. Entries use OR. |
### Example
```yaml
match-entity:
mythicmobs:
- SkeletonKing
- FlameGuardian
```
### Behavior and limits
* IDs are compared case-insensitively with `MythicMob#getInternalName`.
* Display names are not used.
* A normal Bukkit entity that is not an active MythicMob does not match.
* If MythicMobs is absent during startup, this rule is not registered and the key is ignored.
***
## `levelled-mobs`
**Purpose:** Matches the level stored by LevelledMobs.
**Context:** Registered only when LevelledMobs is loaded. The level is read from LevelledMobs' `level` integer PDC key; missing data is treated as level `0`.
### Fields
| Field | Default | Description |
| --------------- | ------- | ------------------------------------------------------------ |
| `levelled-mobs` | unset | Exact level, inclusive range, `>=` minimum, or `<=` maximum. |
### Examples
```yaml
match-entity:
levelled-mobs: '10~20'
```
```yaml
match-entity:
levelled-mobs: '>=5'
```
```yaml
match-entity:
levelled-mobs: '<=50'
```
```yaml
match-entity:
levelled-mobs: '15'
```
### Behavior and limits
* `10~20` is inclusive at both ends.
* Only `>=`, `<=`, range, and exact forms are implemented; standalone `>` and `<` are not supported.
* The expected values must parse as integers.
* If LevelledMobs is absent during startup, the rule is not registered and the key is ignored.
* **Current implementation limitation:** matching reads `levelled-mobs` as a scalar string, but rule-presence detection uses `getStringList`. On standard Bukkit configuration a scalar may therefore be treated as absent and skipped. Verify this rule on the target build before relying on it.
# Logical Rules
Every rule on this page is a key inside a [MatchEntityFormat](/format/match-entity-format) section.
***
## `any`
**Purpose:** Accepts an entity when at least one nested alternative matches.
**Context:** Nested sections use the same MatchEntityFormat rules.
### Fields
| Field | Default | Description |
| ----- | ------- | ----------------------------------------- |
| `any` | unset | A direct rule section or numbered groups. |
### Direct-rule layout
```yaml
match-entity:
any:
entity-types:
- ZOMBIE
entity-contains-name:
- Boss
```
When `any` does not contain a key named `1`, every directly nested rule is tested independently. The example matches a zombie **or** an entity whose name contains `Boss`.
### Numbered-group layout
```yaml
match-entity:
any:
1:
entity-types:
- SKELETON
ranged: true
2:
mythicmobs:
- SkeletonKing
```
When `any` contains a key named `1`, each child is a complete MatchEntityFormat group:
* rules inside one group use AND;
* groups use OR.
### Behavior and limits
* A missing or empty `any` section returns true when evaluated.
* Numbered-group mode is detected specifically by key `1`; begin numbering at `1`.
* The direct layout treats rules as alternatives, not as one AND group.
* Use numbered groups when one alternative needs multiple simultaneous requirements.
* Optional integration rules that are not registered are skipped inside `any`, just as they are at the top level.
***
## `not`
**Purpose:** Rejects an entity when any nested rule matches.
**Context:** Nested keys use the same MatchEntityFormat rules.
### Fields
| Field | Default | Description |
| ----- | ------- | --------------------------------------- |
| `not` | unset | Rules whose matches should be rejected. |
### Example
```yaml
match-entity:
monster: true
not:
entity-types:
- CREEPER
entity-contains-name:
- Protected
```
### Behavior and limits
* Nested rules are separate rejection alternatives.
* The example rejects creepers **or** entities whose name contains `Protected`.
* `not` does not combine all nested rules with AND and then invert the combined result.
* An empty `not` section passes because no nested rule rejects the entity.
* For complex accepted alternatives, use numbered `any` groups outside `not` and structure the surrounding matcher explicitly.
# 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), [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.
# Mob Powers
A mob power is one YAML file that defines:
* which mobs may receive the power;
* how the power is displayed;
* when the power may activate;
* what its triggers do.
Power files are stored in:
```
plugins/EnchantedMobs/powers
```
The filename without `.yml` is the power ID. For example, `WebArrow.yml` creates the power ID `WebArrow`.
{% hint style="warning" %}
EnchantedMobs 2.0.0 uses typed `conditions`, typed `modifiers`, and typed `abilities`. Read the [2.0.0 migration guide](/info/2.0.0-migration) before reusing a 1.x custom power.
{% endhint %}
## Quick start
```yaml
enabled: true
placeholder: 'Flame Touch'
apply-rules:
weight: 10
on-melee-attack:
abilities:
ignite-target:
type: fire
target: TARGET
fire-ticks: 100
```
This power may be selected during power generation. When its owner directly attacks an entity, the target burns for 100 ticks.
## Power file structure
```yaml
# Display and availability
enabled: true
hide-name: false
placeholder: '{lang:power.example}'
# Reusable values
variables:
damage-multiplier: '1 + {level} * 0.02'
# Power generation
apply-rules:
group: attack
group-unique: true
weight: 10
level-weight: 20
conflicts:
- OtherPower
match-entity:
entity-types:
- ZOMBIE
- SKELETON
# Power-wide activation limits
limit:
random: 1
cooldown: 0
times: 0
no-attack-ticks: 0
# Trigger sections
on-attack:
conditions: {}
modifiers: {}
abilities: {}
```
| Section | Purpose |
| ------------- | --------------------------------------------------------------------------- |
| `enabled` | Enables or disables the power. |
| `hide-name` | Hides the power from mob-name and BossBar power lists without disabling it. |
| `placeholder` | Defines the visible power name. |
| `variables` | Defines reusable dynamic values. |
| `apply-rules` | Controls mob matching, weight, cost, groups, and conflicts. |
| `limit` | Controls power-wide chance, cooldown, usage count, and idle-target timing. |
| `on-...` | Defines one trigger's conditions, modifiers, and abilities. |
## Execution flow
When a matching trigger fires, EnchantedMobs processes the power in this order:
```
power limit
→ trigger conditions
→ trigger modifiers
→ trigger abilities
→ final event result
```
* Conditions must all match.
* Modifiers execute in YAML order.
* Abilities execute in YAML order.
* Power effects do not recursively trigger new EnchantedMobs power events.
See [Power Triggers](/configs/triggers) for every built-in trigger, its `SOURCE` / `SKILL` / `TARGET` context, compatible result data, and projectile-continuation behavior.
## Display and availability
```yaml
enabled: true
hide-name: false
placeholder: '{lang:power.example}'
```
### `enabled`
When `false`, the power does not participate in generation or execute.
### `placeholder`
Controls the power text shown in mob names and BossBars. It supports language placeholders and supported dynamic values such as `{level}`.
### `hide-name`
When `true`, the power remains active but is omitted from:
* `{powers}` in mob-name formats;
* `{powers_full}` in BossBar titles;
* the visible-power count used by name truncation.
If every assigned power is hidden, the entity keeps its base mob or custom name. The bundled `HealthMultiplier` power is hidden by default.
## Variables and dynamic values
Variables avoid repeating the same formula:
```yaml
variables:
damage-multiplier:
'<20': 1.1
'>=20;;<50': 1.25
'>=50': 1.5
on-attack:
modifiers:
scale-damage:
type: damage
operation: MULTIPLY
value: '{damage-multiplier}'
```
Depending on the field, values may support:
* `{level}`;
* power variables such as `{damage-multiplier}`;
* formulas such as `4 + {level} * 0.5`;
* ranges such as `1~3` or `0.5~1.5`;
* level selector maps;
* runtime placeholders such as `{source_health}`, `{target_health_percent}`, and `{distance}`;
* PlaceholderAPI when a player viewer is available.
```yaml
value:
'<=10': 2
'>10;;<30': '{level} * 0.25'
'>=30': 10
```
See [Math Calculate Format](/format/math-calculate-format) for expression syntax.
## Power generation rules
`apply-rules` controls whether the power is eligible and how it is selected:
```yaml
apply-rules:
group: ranged_projectile
group-unique: true
weight: 5
level-weight: 15
conflicts:
- AnotherProjectilePower
match-entity:
equip:
main-hand:
material:
- BOW
- CROSSBOW
```
Common responsibilities include:
* matching entity type, equipment, health, tags, plugins, and other entity properties;
* setting normal and level-based selection weights;
* assigning a level cost;
* preventing duplicate selections from one group;
* defining conflicting powers;
* forcing a power to be selected.
See [Mechanics](/configs/mechanic) for the complete generation process and field reference.
## Power-wide limits
```yaml
limit:
random: 0.5
cooldown: 8
times: 3
no-attack-ticks: 100
```
| Field | Default | Description |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------- |
| `random` | `1` | Activation chance. `1` means 100%. |
| `cooldown` | `0` | Shared power cooldown in seconds. |
| `times` | `0` | Maximum successful top-level activations. `0` means unlimited. |
| `no-attack-ticks` | `0` | Requires the owner to have a target without successfully attacking it for at least this many ticks. |
These settings apply to the whole power. Individual modifiers and abilities may also have their own conditions, chance, and cooldown. Abilities additionally support their own `times` limit.
Tracked projectile tick and hit executions use the powers captured at launch and do not reroll these top-level limits.
## Trigger section
Every trigger uses the same layout:
```yaml
on-damage:
conditions:
fire-damage:
type: damage_cause
values:
- FIRE
- FIRE_TICK
modifiers:
reduce-fire-damage:
type: damage
operation: MULTIPLY
value: 0.5
abilities:
smoke:
type: particle
target: TARGET
particle: SMOKE
count: 10
```
### `conditions`
Conditions decide whether the trigger continues. Entries use logical AND and each entry requires a unique key and a `type`.
See [Power Condition Reference](/configs/power-conditions).
### `modifiers`
Modifiers change supported event result data before abilities run. They execute in YAML order.
Use the plural key `modifiers`, not the legacy singular key `modifier`.
See [Power Modifier Reference](/configs/power-modifiers).
### `abilities`
Abilities perform actions in YAML order. Each entry requires a unique key and a `type`.
See [Ability Reference](/configs/info-of-abilities).
## Complete example: web projectile
```yaml
enabled: true
placeholder: '{lang:power.web_arrow}'
apply-rules:
group: ranged_projectile
group-unique: true
weight: 5
level-weight: 15
match-entity:
equip:
main-hand:
material:
- BOW
- CROSSBOW
- TRIDENT
limit:
random:
'>=15;;<23': 0.3
'>=23': 0.6
cooldown:
'>=15;;<22': 10
'>=22': 5
on-shoot-bow:
abilities:
capture-power:
type: mark
on-projectile-tick:
abilities:
trail:
type: particle
target: SKILL
particle: WHITE_ASH
count: 6
offset-x: 0.05
offset-y: 0.05
offset-z: 0.05
on-projectile-hit:
abilities:
place-web:
type: place_block
block: COBWEB
duration: '{level} * 4'
sound:
type: sound
sound: BLOCK_WOOL_PLACE
particles:
type: particle
particle: BLOCK
count: 20
block: COBWEB
remove-projectile:
type: remove
target: SKILL
```
The launch trigger captures the power for the projectile. The tick trigger creates its trail, and the hit trigger places a temporary cobweb at the hit location.
## Related references
* [Power Triggers](/configs/triggers): trigger contexts, event differences, result compatibility, and projectile continuity.
* [Mechanics](/configs/mechanic): power generation, weights, levels, groups, and conflicts.
* [Power Condition Reference](/configs/power-conditions): every built-in condition.
* [Power Modifier Reference](/configs/power-modifiers): every built-in modifier.
* [Ability Reference](/configs/info-of-abilities): every built-in ability.
# Power Triggers
A trigger is an `on-...` section inside a mob power. It decides when the power runs and creates the context consumed by Power Conditions, Power Modifiers, and Abilities.
```yaml
on-attack:
conditions: {}
modifiers: {}
abilities: {}
```
EnchantedMobs registers **18 built-in triggers**.
## Reference pages
* [Tick and Lifecycle Triggers](/configs/triggers/lifecycle)
* [Combat, Damage, and Death Triggers](/configs/triggers/combat)
* [Projectile and Ranged Triggers](/configs/triggers/projectiles)
* [Block and Interaction Triggers](/configs/triggers/blocks-interactions)
* [Item, Enchanting, and Equipment Triggers](/configs/triggers/items-equipment)
* [Movement and Input Triggers](/configs/triggers/movement-input)
* [Effects, Air, Food, and Experience Triggers](/configs/triggers/player-state)
* [Fishing and Trading Triggers](/configs/triggers/fishing-trading)
* [Targeting and Special-Entity Triggers](/configs/triggers/targeting-special)
## Common context
| Context | Meaning |
| ---------- | ------------------------------------------------------------------------------- |
| `OWNER` | The powered mob that owns the power. |
| `SOURCE` | Entity responsible for the current action. |
| `SKILL` | Direct carrier or intermediate entity such as a projectile or exploding entity. |
| `TARGET` | Final affected or inspected entity. |
| `LOCATION` | Main event location. |
| `EVENT` | Underlying Bukkit/Paper event. |
| `TICK` | Runtime tick for periodic triggers. |
Missing or incompatible context causes dependent conditions, modifiers, or abilities to fail or skip safely.
## Numeric trigger context
Numeric trigger extras are available to context-aware string and mathematical fields as `{key_name}` placeholders. For example, compatible damage triggers provide `{original_damage}`, ranged triggers may provide `{bow_force}`, and targeting contexts may provide `{target_count}`.
A placeholder exists only when the current trigger supplied that value. See [Math Calculate Format](/format/math-calculate-format#numeric-trigger-context-placeholders) for the complete list, value types, resolution order, and examples.
## Trigger list
### Tick and Lifecycle Triggers
* [`on-tick`](/configs/triggers/lifecycle#on-tick)
* [`on-target-tick`](/configs/triggers/lifecycle#on-target-tick)
* [`on-spawn`](/configs/triggers/lifecycle#on-spawn)
### Combat, Damage, and Death Triggers
* [`on-attack`](/configs/triggers/combat#on-attack)
* [`on-melee-attack`](/configs/triggers/combat#on-melee-attack)
* [`on-damage`](/configs/triggers/combat#on-damage)
* [`on-damage-by-entity`](/configs/triggers/combat#on-damage-by-entity)
* [`on-regain`](/configs/triggers/combat#on-regain)
* [`on-combust`](/configs/triggers/combat#on-combust)
* [`on-death`](/configs/triggers/combat#on-death)
### Projectile and Ranged Triggers
* [`on-shoot-bow`](/configs/triggers/projectiles#on-shoot-bow)
* [`on-projectile-launch`](/configs/triggers/projectiles#on-projectile-launch)
* [`on-projectile-tick`](/configs/triggers/projectiles#on-projectile-tick)
* [`on-projectile-hit`](/configs/triggers/projectiles#on-projectile-hit)
### Block and Interaction Triggers
*No built-in triggers.*
### Item, Enchanting, and Equipment Triggers
*No built-in triggers.*
### Movement and Input Triggers
*No built-in triggers.*
### Effects, Air, Food, and Experience Triggers
*No built-in triggers.*
### Fishing and Trading Triggers
*No built-in triggers.*
### Targeting and Special-Entity Triggers
* [`on-target`](/configs/triggers/targeting-special#on-target)
* [`on-untag`](/configs/triggers/targeting-special#on-untag)
* [`on-explode`](/configs/triggers/targeting-special#on-explode)
* [`on-creeper-explode`](/configs/triggers/targeting-special#on-creeper-explode)
## Projectile continuity
`on-shoot-bow` and `on-projectile-launch` can capture exact power IDs for a projectile. `on-projectile-tick` and `on-projectile-hit` run only those captured powers and do not reroll the top-level power limit. Replacing a projectile transfers tracking only when the replacement is another projectile.
# Tick and Lifecycle Triggers
Each trigger section uses the same Context terminology as the [Power Triggers](/configs/triggers) index.
## `on-tick`
Runs periodically for a powered mob.
| Context | Value |
| ------------------- | --------------------------------------------------------------------------------- |
| Entity roles | `OWNER`, `SOURCE`, `SKILL`, and `TARGET` are the powered mob. `TICK` is supplied. |
| Event-specific data | Supports `interval`, clamped to at least one tick. |
***
## `on-target-tick`
Runs periodically while the powered mob has a target.
| Context | Value |
| ------------------- | ----------------------------------------------------------------------------------------- |
| Entity roles | `OWNER`/`SOURCE`/`SKILL` are the mob; `TARGET` is its current target. `TICK` is supplied. |
| Event-specific data | Supports `interval`; does not fire without a target. |
***
## `on-spawn`
Runs when powers are assigned to a mob.
| Context | Value |
| ------------------- | -------------------------------------------------------------------------- |
| Entity roles | All entity roles resolve to the powered mob; location is the mob location. |
| Event-specific data | This is power-assignment lifecycle, not every Bukkit spawn event. |
# Combat, Damage, and Death Triggers
Each trigger section uses the same Context terminology as the [Power Triggers](/configs/triggers) index.
## `on-attack`
Runs when the powered mob is responsible for damage, including owned indirect damage.
| Context | Value |
| ------------------- | ---------------------------------------------------------------------------------------- |
| Entity roles | `SOURCE` is the powered attacker; `SKILL` is the direct damager; `TARGET` is the victim. |
| Event-specific data | Provides mutable damage and damage cause/origin context. |
***
## `on-melee-attack`
Runs only when the powered mob is the direct damager.
| Context | Value |
| ------------------- | --------------------------------------------------------- |
| Entity roles | `SOURCE` and `SKILL` are the mob; `TARGET` is the victim. |
| Event-specific data | Provides mutable damage and melee context. |
***
## `on-damage`
Runs when the powered mob receives any damage.
| Context | Value |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Entity roles | `TARGET` is the powered mob; `SOURCE` is the resolved attacker when present; `SKILL` is direct damager or owner fallback. |
| Event-specific data | Includes environmental damage and mutable damage context. |
***
## `on-damage-by-entity`
Runs when the powered mob receives entity-caused damage.
| Context | Value |
| ------------------- | -------------------------------------------------------------------------------------- |
| Entity roles | `TARGET` is the powered mob; `SOURCE` is resolved attacker; `SKILL` is direct damager. |
| Event-specific data | Does not run for environment-only damage. |
***
## `on-regain`
Runs when the powered mob regains health.
| Context | Value |
| ------------------- | -------------------------------------------- |
| Entity roles | All entity roles resolve to the powered mob. |
| Event-specific data | Provides mutable regain amount. |
***
## `on-combust`
Runs when the powered mob is combusted.
| Context | Value |
| ------------------- | ------------------------------------------------ |
| Entity roles | All entity roles resolve to the powered mob. |
| Event-specific data | Provides mutable duration and combustion origin. |
***
## `on-death`
Runs when the powered mob dies.
| Context | Value |
| ------------------- | ------------------------------------------------------------------------ |
| Entity roles | All entity roles resolve to the powered mob. |
| Event-specific data | Provides death result, drops/experience, and supported revival behavior. |
# Projectile and Ranged Triggers
Each trigger section uses the same Context terminology as the [Power Triggers](/configs/triggers) index.
## `on-shoot-bow`
Runs when the powered mob fires a bow/crossbow projectile.
| Context | Value |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| Entity roles | `SOURCE` is shooter; `SKILL`/`TARGET` are projectile. |
| Event-specific data | Provides bow, consumable, hand, force, and projectile context; can capture continuation powers. |
***
## `on-projectile-launch`
Runs for a projectile launched by the powered mob.
| Context | Value |
| ------------------- | ----------------------------------------------------- |
| Entity roles | `SOURCE` is shooter; `SKILL`/`TARGET` are projectile. |
| Event-specific data | Provides projectile and location context. |
***
## `on-projectile-tick`
Runs for each tracked projectile update.
| Context | Value |
| ------------------- | ----------------------------------------------------------------- |
| Entity roles | `SOURCE` is shooter; `SKILL`/`TARGET` are tracked projectile. |
| Event-specific data | Only captured power IDs execute; top-level limit is not rerolled. |
***
## `on-projectile-hit`
Runs when a tracked projectile hits.
| Context | Value |
| ------------------- | -------------------------------------------------------------------------------- |
| Entity roles | `SOURCE` is shooter; `SKILL` is projectile; `TARGET` is hit entity when present. |
| Event-specific data | Hit location/block is supplied and tracking ends. |
# Block and Interaction Triggers
Each trigger section uses the same Context terminology as the [Power Triggers](/configs/triggers) index.
{% hint style="info" %}
EnchantedMobs does not register a built-in trigger in this category. The page is kept so both Manyou power plugins use the same documentation structure.
{% endhint %}
# Item, Enchanting, and Equipment Triggers
Each trigger section uses the same Context terminology as the [Power Triggers](/configs/triggers) index.
{% hint style="info" %}
EnchantedMobs does not register a built-in trigger in this category. The page is kept so both Manyou power plugins use the same documentation structure.
{% endhint %}
# Movement and Input Triggers
Each trigger section uses the same Context terminology as the [Power Triggers](/configs/triggers) index.
{% hint style="info" %}
EnchantedMobs does not register a built-in trigger in this category. The page is kept so both Manyou power plugins use the same documentation structure.
{% endhint %}
# Effects, Air, Food, and Experience Triggers
Each trigger section uses the same Context terminology as the [Power Triggers](/configs/triggers) index.
{% hint style="info" %}
EnchantedMobs does not register a built-in trigger in this category. The page is kept so both Manyou power plugins use the same documentation structure.
{% endhint %}
# Fishing and Trading Triggers
Each trigger section uses the same Context terminology as the [Power Triggers](/configs/triggers) index.
{% hint style="info" %}
EnchantedMobs does not register a built-in trigger in this category. The page is kept so both Manyou power plugins use the same documentation structure.
{% endhint %}
# Targeting and Special-Entity Triggers
Each trigger section uses the same Context terminology as the [Power Triggers](/configs/triggers) index.
## `on-target`
Runs when the powered mob selects a target.
| Context | Value |
| ------------------- | ----------------------------------------------------------------- |
| Entity roles | `SOURCE`/`SKILL` are the powered mob; `TARGET` is the new target. |
| Event-specific data | Provides target reason. |
***
## `on-untag`
Runs when the powered mob loses its target.
| Context | Value |
| ------------------- | ------------------------------------------------------------------------------ |
| Entity roles | `SOURCE`/`SKILL` are the mob; target role follows the implementation fallback. |
| Event-specific data | Provides target reason. |
***
## `on-explode`
Runs for a generic entity explosion owned by the powered mob.
| Context | Value |
| ------------------- | -------------------------------------------------------------------------------------------- |
| Entity roles | `SOURCE` is exploding entity or resolved shooter; `SKILL`/`TARGET` are the exploding entity. |
| Event-specific data | Provides mutable explosion yield. |
***
## `on-creeper-explode`
Runs when a powered creeper primes its explosion.
| Context | Value |
| ------------------- | ------------------------------------------ |
| Entity roles | `SOURCE`/`SKILL`/`TARGET` are the creeper. |
| Event-specific data | Provides mutable explosion radius. |
# Power Conditions
Power Conditions decide whether a trigger, modifier, or ability may continue. A normal `conditions` mapping is logical **AND**: every named child must match.
This reference documents **52 built-in condition keys** registered by EnchantedMobs.
## Reference pages
* [Logical and Random Conditions](/configs/power-conditions/logical-random)
* [Entity and State Conditions](/configs/power-conditions/entity-state)
* [Environment and Location Conditions](/configs/power-conditions/environment)
* [Trigger-data Conditions](/configs/power-conditions/trigger-data)
## Common format
```yaml
conditions:
unique-entry-id:
type: health_percent
target: TARGET
max: 50
not: false
```
## Common fields
| Field | Default | Description |
| -------- | ------------- | ------------------------------------------------------------------------------------------- |
| `type` | required | Registered condition key. Keys are case-insensitive and `-` is normalized to `_`. |
| `not` | `false` | Inverts the final result returned by the condition. |
| `target` | type-specific | Entity selector such as `SOURCE`, `SKILL`, or `TARGET` when the implementation exposes one. |
A condition returns `false` when its required entity, item, block, location, event, or mutable result is missing. The category pages state the exact required context and every supported type-specific field.
## Evaluation timing
Trigger-level conditions run before modifiers and abilities. Conditions attached to a modifier or ability run when that entry is reached. A result-reading condition can therefore observe changes made by earlier modifiers in the same trigger section.
## Type index
| Type | Reference |
| ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `any` | [Logical and Random Conditions](/configs/power-conditions/logical-random#any) |
| `not` | [Logical and Random Conditions](/configs/power-conditions/logical-random#not) |
| `random` | [Logical and Random Conditions](/configs/power-conditions/logical-random#random) |
| `headshot` | [Entity and State Conditions](/configs/power-conditions/entity-state#headshot) |
| `height` | [Entity and State Conditions](/configs/power-conditions/entity-state#height) |
| `sneaking` | [Entity and State Conditions](/configs/power-conditions/entity-state#sneaking) |
| `not_sneaking` | [Entity and State Conditions](/configs/power-conditions/entity-state#not-sneaking) |
| `min_attack_cooldown` | [Entity and State Conditions](/configs/power-conditions/entity-state#min-attack-cooldown) |
| `blocking` | [Entity and State Conditions](/configs/power-conditions/entity-state#blocking) |
| `perfect_guard` | [Entity and State Conditions](/configs/power-conditions/entity-state#perfect-guard) |
| `swimming` | [Entity and State Conditions](/configs/power-conditions/entity-state#swimming) |
| `flying` | [Entity and State Conditions](/configs/power-conditions/entity-state#flying) |
| `climbing` | [Entity and State Conditions](/configs/power-conditions/entity-state#climbing) |
| `riding` | [Entity and State Conditions](/configs/power-conditions/entity-state#riding) |
| `game_mode` | [Entity and State Conditions](/configs/power-conditions/entity-state#game-mode) |
| `health` | [Entity and State Conditions](/configs/power-conditions/entity-state#health) |
| `health_percent` | [Entity and State Conditions](/configs/power-conditions/entity-state#health-percent) |
| `has_potion` | [Entity and State Conditions](/configs/power-conditions/entity-state#has-potion) |
| `distance` | [Entity and State Conditions](/configs/power-conditions/entity-state#distance) |
| `bounding_box_distance` | [Entity and State Conditions](/configs/power-conditions/entity-state#bounding-box-distance) |
| `food_level` | [Entity and State Conditions](/configs/power-conditions/entity-state#food-level) |
| `gliding` | [Entity and State Conditions](/configs/power-conditions/entity-state#gliding) |
| `on_ground` | [Entity and State Conditions](/configs/power-conditions/entity-state#on-ground) |
| `in_air` | [Entity and State Conditions](/configs/power-conditions/entity-state#in-air) |
| `falling` | [Entity and State Conditions](/configs/power-conditions/entity-state#falling) |
| `fall_distance` | [Entity and State Conditions](/configs/power-conditions/entity-state#fall-distance) |
| `match_entity` | [Entity and State Conditions](/configs/power-conditions/entity-state#match-entity) |
| `first_attack_against_entity` | [Entity and State Conditions](/configs/power-conditions/entity-state#first-attack-against-entity) |
| `in_water` | [Environment and Location Conditions](/configs/power-conditions/environment#in-water) |
| `in_lava` | [Environment and Location Conditions](/configs/power-conditions/environment#in-lava) |
| `in_rain` | [Environment and Location Conditions](/configs/power-conditions/environment#in-rain) |
| `in_sunlight` | [Environment and Location Conditions](/configs/power-conditions/environment#in-sunlight) |
| `in_structure` | [Environment and Location Conditions](/configs/power-conditions/environment#in-structure) |
| `light_level` | [Environment and Location Conditions](/configs/power-conditions/environment#light-level) |
| `clear_weather` | [Environment and Location Conditions](/configs/power-conditions/environment#clear-weather) |
| `storm` | [Environment and Location Conditions](/configs/power-conditions/environment#storm) |
| `thunder` | [Environment and Location Conditions](/configs/power-conditions/environment#thunder) |
| `world` | [Environment and Location Conditions](/configs/power-conditions/environment#world) |
| `night` | [Environment and Location Conditions](/configs/power-conditions/environment#night) |
| `environment` | [Environment and Location Conditions](/configs/power-conditions/environment#environment) |
| `damage_value` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#damage-value) |
| `state_value` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#state-value) |
| `damage_cause` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#damage-cause) |
| `damage_origin` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#damage-origin) |
| `melee` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#melee) |
| `spawn_reason` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#spawn-reason) |
| `combust_duration` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#combust-duration) |
| `regain_amount` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#regain-amount) |
| `explosion_yield` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#explosion-yield) |
| `explosion_radius` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#explosion-radius) |
| `target_reason` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#target-reason) |
| `cooldown` | [Trigger-data Conditions](/configs/power-conditions/trigger-data#cooldown) |
# Logical and Random Conditions
Every registered condition on this page is documented as an independent reference entry. All entries also support the common condition fields documented on the [Power Conditions](/configs/power-conditions) page.
## Registry keys on this page
* `any`
* `not`
* `random`
***
## `any`
**Purpose:** Matches when at least one nested typed condition matches.
**Context:** Nested conditions reuse the same `PowerContext`; the nested mapping is evaluated as logical OR.
### Fields
| Field | Default | Description |
| ------------ | -------- | ------------------------------------------------------------------------------- |
| `conditions` | required | Nested condition entries. Each child keeps its own type, selectors, and fields. |
### Example
```yaml
type: any
conditions:
wet:
type: in_water
target: SOURCE
raining:
type: in_rain
target: SOURCE
```
### Behavior and limits
* A missing nested section is treated as an allowed group by the condition manager, so avoid an empty `conditions` section.
* The common `not: true` field inverts the final OR result.
***
## `not`
**Purpose:** Matches when a nested logical-AND condition group does not fully match.
**Context:** Nested conditions reuse the same `PowerContext` and are evaluated using the normal all-must-pass rule before inversion.
### Fields
| Field | Default | Description |
| ------------ | -------- | ------------------------------------------------- |
| `conditions` | required | Nested typed conditions evaluated as logical AND. |
### Example
```yaml
type: not
conditions:
in-lava:
type: in_lava
target: SOURCE
burning:
type: has_potion
target: SOURCE
potion: minecraft:fire_resistance
```
### Behavior and limits
* For one child, the child condition's common `not: true` field is usually shorter.
* Applying both `type: not` and common `not: true` inverts twice.
***
## `random`
**Purpose:** Performs a fresh probability roll.
**Context:** No entity, event, block, or item context is required.
### Fields
| Field | Default | Description |
| ------- | ------- | -------------------------------------------------------------- |
| `value` | `1` | Probability from `0` to `1`; values are clamped to that range. |
### Example
```yaml
type: random
value: 0.25
```
### Behavior and limits
* Every evaluation rolls independently.
* This is separate from power-, modifier-, and ability-level `random` fields.
***
# Entity and State Conditions
Every registered condition on this page is documented as an independent reference entry. All entries also support the common condition fields documented on the [Power Conditions](/configs/power-conditions) page.
## Registry keys on this page
* `headshot`
* `height`
* `sneaking`
* `not_sneaking`
* `min_attack_cooldown`
* `blocking`
* `perfect_guard`
* `swimming`
* `flying`
* `climbing`
* `riding`
* `game_mode`
* `health`
* `health_percent`
* `has_potion`
* `distance`
* `bounding_box_distance`
* `food_level`
* `gliding`
* `on_ground`
* `in_air`
* `falling`
* `fall_distance`
* `match_entity`
* `first_attack_against_entity`
***
## `headshot`
**Purpose:** Checks whether the current projectile is vertically close to the target's eye position.
**Context:** Requires a living `TARGET` and projectile `SKILL`; these roles are fixed by the implementation.
### Fields
| Field | Default | Description |
| ----------- | ------- | ---------------------------------------------------------------------------------- |
| `tolerance` | `0.45` | Maximum absolute Y difference between projectile location and target eye location. |
### Example
```yaml
type: headshot
tolerance: 0.4
```
### Behavior and limits
* Only vertical position is checked; this is not an exact hitbox intersection test.
* Use it on projectile damage or hit triggers that provide both roles.
***
## `height`
**Purpose:** Checks the block Y coordinate of the resolved trigger location.
**Context:** Uses `PowerContext.location()` rather than an entity selector.
### Fields
| Field | Default | Description |
| ----- | --------------- | -------------------- |
| `min` | minimum integer | Inclusive minimum Y. |
| `max` | maximum integer | Inclusive maximum Y. |
### Example
```yaml
type: height
min: 60
max: 100
```
### Behavior and limits
* This condition uses only `min` and `max`; it does not use the shared numeric `compare` form.
***
## `sneaking`
**Purpose:** Checks whether a selected player is sneaking.
**Context:** Default `target`: `TARGET`; the selected entity must be a player.
### Fields
| Field | Default | Description |
| -------- | -------- | ------------------------ |
| `target` | `TARGET` | Entity selector. |
| `value` | `true` | Expected sneaking state. |
### Example
```yaml
type: sneaking
target: SOURCE
value: true
```
### Behavior and limits
* Non-player entities do not match.
***
## `not_sneaking`
**Purpose:** Matches a selected player that is not sneaking.
**Context:** Default `target`: `TARGET`; the selected entity must be a player.
### Fields
| Field | Default | Description |
| -------- | -------- | ---------------- |
| `target` | `TARGET` | Entity selector. |
### Example
```yaml
type: not_sneaking
target: SOURCE
```
### Behavior and limits
* Equivalent to `sneaking` with `value: false` for player targets.
***
## `health`
**Purpose:** Checks current or maximum health with the shared numeric-comparison syntax.
**Context:** Default `target`: `TARGET`; requires a living entity.
### Fields
| Field | Default | Description |
| ----------------- | --------- | ------------------------------------------------- |
| `target` | `TARGET` | Entity selector. |
| `mode` | `CURRENT` | `CURRENT`, `MAX`, or `MAXIMUM`. |
| `min / max` | unbounded | Inclusive numeric range. |
| `compare / value` | unset | Alternative comparison such as `>=`, `<`, or `=`. |
### Example
```yaml
type: health
target: SOURCE
mode: CURRENT
compare: '<='
value: 10
```
### Behavior and limits
* The checked value is exposed as `{original}` and `{current}` while resolving numeric fields.
***
## `health_percent`
**Purpose:** Checks current health as a percentage of maximum health.
**Context:** Default `target`: `TARGET`; requires a living entity.
### Fields
| Field | Default | Description |
| ---------------- | --------- | --------------------------------------- |
| `target` | `TARGET` | Entity selector. |
| `min` | `0` | Inclusive minimum percent. |
| `max` | `100` | Inclusive maximum percent. |
| `min-max-health` | `0` | Inclusive minimum maximum-health value. |
| `max-max-health` | unbounded | Inclusive maximum maximum-health value. |
### Example
```yaml
type: health_percent
target: TARGET
min: 0
max: 25
min-max-health: 20
```
### Behavior and limits
* Percentage is calculated as current health divided by maximum health times 100.
* This condition does not use `compare` / `value`.
***
## `has_potion`
**Purpose:** Checks whether a living entity has a specific active potion effect.
**Context:** Default `target`: `TARGET`; requires a living entity.
### Fields
| Field | Default | Description |
| -------- | -------- | ---------------------------------------------------------- |
| `target` | `TARGET` | Entity selector. |
| `potion` | empty | Potion-effect namespaced key or supported enum-style name. |
### Example
```yaml
type: has_potion
target: TARGET
potion: minecraft:poison
```
### Behavior and limits
* An invalid or empty effect key does not match.
* Use common `not: true` to require that the effect is absent.
***
## `distance`
**Purpose:** Checks Euclidean distance between two context entities.
**Context:** Default `source`: `SOURCE`; default `target`: `TARGET`; both entities must exist in the same world.
### Fields
| Field | Default | Description |
| ----------------- | --------- | ------------------------------- |
| `source` | `SOURCE` | First entity selector. |
| `target` | `TARGET` | Second entity selector. |
| `min / max` | unbounded | Inclusive distance range. |
| `compare / value` | unset | Alternative numeric comparison. |
### Example
```yaml
type: distance
source: SOURCE
target: TARGET
min: 4
max: 16
```
### Behavior and limits
* Cross-world entities do not match.
***
## `bounding_box_distance`
Checks the shortest distance from one selected entity position to another entity's bounding box. `source` defaults to `SOURCE`, `target` to `TARGET`, and `source-eye` to `false`. It supports the shared numeric `min`, `max`, `compare`, and `value` fields.
```yaml
type: bounding_box_distance
source: SOURCE
target: TARGET
source-eye: true
min: 3
max: 6.5
```
Points inside the target hitbox have distance `0`; cross-world entities do not match.
***
## `food_level`
**Purpose:** Checks a player's current food level.
**Context:** Default `target`: `TARGET`; selected entity must be a player.
### Fields
| Field | Default | Description |
| ----------------- | --------- | ------------------------------- |
| `target` | `TARGET` | Entity selector. |
| `min / max` | unbounded | Inclusive range. |
| `compare / value` | unset | Alternative numeric comparison. |
### Example
```yaml
type: food_level
target: SOURCE
max: 6
```
### Behavior and limits
* Food level is the integer Bukkit value from 0 to 20.
***
## `gliding`
**Purpose:** Checks a living entity's gliding state.
**Context:** Default `target`: `TARGET`; requires a living entity.
### Fields
| Field | Default | Description |
| -------- | -------- | ---------------- |
| `target` | `TARGET` | Entity selector. |
| `value` | `true` | Expected state. |
### Example
```yaml
type: gliding
target: SOURCE
value: true
```
### Behavior and limits
* Non-living entities do not match.
***
## `on_ground`
**Purpose:** Checks an entity's on-ground state.
**Context:** Default `target`: `TARGET`; requires an entity.
### Fields
| Field | Default | Description |
| -------- | -------- | ---------------- |
| `target` | `TARGET` | Entity selector. |
| `value` | `true` | Expected state. |
### Example
```yaml
type: on_ground
target: TARGET
value: true
```
### Behavior and limits
* The value comes from Bukkit's current on-ground flag.
***
## `in_air`
**Purpose:** Checks the inverse of an entity's on-ground state.
**Context:** Default `target`: `TARGET`; requires an entity.
### Fields
| Field | Default | Description |
| -------- | -------- | ------------------------ |
| `target` | `TARGET` | Entity selector. |
| `value` | `true` | Expected airborne state. |
### Example
```yaml
type: in_air
target: TARGET
value: true
```
### Behavior and limits
* The selected entity must exist.
***
## `falling`
Checks whether a selected entity is airborne and moving downward. `target` defaults to `TARGET`, `maximum-y` defaults to `0`, and `value` defaults to `true`.
```yaml
type: falling
target: SOURCE
maximum-y: 0
value: true
```
***
## `fall_distance`
Compares a selected entity's accumulated Bukkit fall distance. It supports `min`, `max`, `compare`, and `value`.
```yaml
type: fall_distance
target: SOURCE
min: 3
```
***
## `match_entity`
**Purpose:** Runs the normal Match Entity rule engine against a selected living entity.
**Context:** Default `target`: `TARGET`; selected entity must be living.
### Fields
| Field | Default | Description |
| -------- | -------- | --------------------------------------- |
| `target` | `TARGET` | Entity selector. |
| `match` | required | Nested MatchEntityFormat configuration. |
### Example
```yaml
type: match_entity
target: TARGET
match:
entity-types:
- PLAYER
entity-health:
min: 1
```
### Behavior and limits
* A missing `match` section fails.
* The nested rules are the same rules used by the plugin's normal entity-matching system.
***
## `first_attack_against_entity`
**Purpose:** Matches only the first qualifying source-player/target pair for this condition path.
**Context:** Requires player `SOURCE`, living `TARGET`, and a non-cancelled current result.
### Fields
*No type-specific fields.*
### Example
```yaml
type: first_attack_against_entity
```
### Behavior and limits
* State identity includes attacker UUID, power ID, configuration path, and target UUID.
* The first successful evaluation stores state immediately; state is cleared by runtime cleanup.
***
## `min_attack_cooldown`
Checks a selected player's current attack cooldown strength. `target` defaults to `TARGET`; `value` is the inclusive minimum and defaults to `0`.
```yaml
type: min_attack_cooldown
target: SOURCE
value: 0.9
```
***
## `blocking`
Checks whether the selected living entity is actively blocking with a shield. `target` defaults to `TARGET` and boolean `value` defaults to `true`. Players use Bukkit's active blocking state; other living entities match while raising a hand with a shield equipped.
```yaml
type: blocking
target: TARGET
value: true
```
***
## `perfect_guard`
Matches a target player who is blocking within a short window after raising a shield. `target` defaults to `TARGET`, `window-millis` defaults to `120`, and `consume` defaults to `true`.
```yaml
type: perfect_guard
target: TARGET
window-millis: 180
consume: true
```
This is useful on a mob's attack trigger when its target is a player. With `consume: true`, one shield raise can match only once.
***
## `swimming`
Checks a selected player's swimming state. `target` defaults to `TARGET` and boolean `value` defaults to `true`.
```yaml
type: swimming
target: TARGET
value: true
```
***
## `flying`
Checks a selected player's flying state. `target` defaults to `TARGET` and boolean `value` defaults to `true`.
```yaml
type: flying
target: TARGET
value: true
```
***
## `climbing`
Checks a selected living entity's climbing state. `target` defaults to `TARGET` and boolean `value` defaults to `true`.
```yaml
type: climbing
target: TARGET
value: true
```
***
## `riding`
Checks whether the selected entity is riding another entity. `target` defaults to `TARGET` and boolean `value` defaults to `true`.
```yaml
type: riding
target: TARGET
value: true
```
***
## `game_mode`
Checks the selected player's game mode. `target` defaults to `TARGET`; use `mode` for one mode or `modes` for a list.
```yaml
type: game_mode
target: TARGET
modes:
- SURVIVAL
- ADVENTURE
```
***
# Environment and Location Conditions
Every registered condition on this page is documented as an independent reference entry. All entries also support the common condition fields documented on the [Power Conditions](/configs/power-conditions) page.
## Registry keys on this page
* `in_water`
* `in_lava`
* `in_rain`
* `in_sunlight`
* `in_structure`
* `light_level`
* `clear_weather`
* `storm`
* `thunder`
* `world`
* `night`
* `environment`
***
## `in_water`
**Purpose:** Checks Bukkit's `Entity#isInWater` state.
**Context:** Default `target`: `TARGET`; requires an entity.
### Fields
| Field | Default | Description |
| -------- | -------- | ---------------- |
| `target` | `TARGET` | Entity selector. |
| `value` | `true` | Expected state. |
### Example
```yaml
type: in_water
target: SOURCE
value: true
```
### Behavior and limits
* The selected entity must exist.
***
## `in_lava`
**Purpose:** Checks whether the block at the selected entity's feet is lava.
**Context:** Default `target`: `TARGET`; requires an entity.
### Fields
| Field | Default | Description |
| -------- | -------- | ---------------- |
| `target` | `TARGET` | Entity selector. |
| `value` | `true` | Expected state. |
### Example
```yaml
type: in_lava
target: SOURCE
value: true
```
### Behavior and limits
* This checks the current feet block material.
***
## `in_rain`
**Purpose:** Checks Bukkit's `Entity#isInRain` state.
**Context:** Default `target`: `TARGET`; requires an entity.
### Fields
| Field | Default | Description |
| -------- | -------- | ---------------- |
| `target` | `TARGET` | Entity selector. |
| `value` | `true` | Expected state. |
### Example
```yaml
type: in_rain
target: SOURCE
value: true
```
### Behavior and limits
* The selected entity must exist.
***
## `in_sunlight`
**Purpose:** Checks a simplified daylight and sky-light exposure rule.
**Context:** Default `target`: `TARGET`; requires an entity.
### Fields
| Field | Default | Description |
| -------- | -------- | ---------------- |
| `target` | `TARGET` | Entity selector. |
| `value` | `true` | Expected state. |
### Example
```yaml
type: in_sunlight
target: SOURCE
value: true
```
### Behavior and limits
* Sunlight is true when world time is below 12300 and sky light at the entity block is at least 15.
* Weather is not checked directly.
***
## `in_structure`
**Purpose:** Checks whether a location lies inside one of the configured generated-structure bounding boxes.
**Context:** Default `target`: `TARGET`; if the entity is unavailable, the trigger location is used.
### Fields
| Field | Default | Description |
| ------------ | -------- | -------------------------------- |
| `target` | `TARGET` | Entity selector. |
| `structure` | empty | Single namespaced structure key. |
| `structures` | empty | List of accepted structure keys. |
### Example
```yaml
type: in_structure
target: SOURCE
structures:
- minecraft:fortress
- minecraft:bastion_remnant
```
### Behavior and limits
* Only structures reported for the current chunk are inspected.
* The resolved point must be inside the generated structure bounding box.
***
## `light_level`
**Purpose:** Checks total block light.
**Context:** Uses the source/location required by the implementation; no configurable selector in the shared implementation.
### Fields
| Field | Default | Description |
| ----- | ------- | ------------------------------ |
| `min` | `0` | Inclusive minimum light level. |
| `max` | `15` | Inclusive maximum light level. |
### Example
```yaml
type: light_level
min: 0
max: 7
```
### Behavior and limits
* Reads the combined block light value.
***
## `clear_weather`
**Purpose:** Checks whether the context world has no storm.
**Context:** Requires a resolved location and world.
### Fields
| Field | Default | Description |
| ------- | ------- | ----------------------------- |
| `value` | `true` | Expected clear-weather state. |
### Example
```yaml
type: clear_weather
value: true
```
### Behavior and limits
* `value: false` requires stormy weather but does not specifically require thunder.
***
## `storm`
**Purpose:** Checks whether the context world has a storm.
**Context:** Requires a resolved location and world.
### Fields
| Field | Default | Description |
| ------- | ------- | --------------------- |
| `value` | `true` | Expected storm state. |
### Example
```yaml
type: storm
value: true
```
### Behavior and limits
* A missing location or world does not match.
***
## `thunder`
**Purpose:** Checks whether the context world is thundering.
**Context:** Requires a resolved location and world.
### Fields
| Field | Default | Description |
| ------- | ------- | -------------------------- |
| `value` | `true` | Expected thundering state. |
### Example
```yaml
type: thunder
value: true
```
### Behavior and limits
* A missing location or world does not match.
***
## `world`
**Purpose:** Matches the world name at the trigger location.
**Context:** Requires a resolved location and world.
### Fields
| Field | Default | Description |
| -------- | ------- | ----------------------------- |
| `world` | empty | Single world name. |
| `worlds` | empty | List of accepted world names. |
### Example
```yaml
type: world
worlds:
- world
- world_nether
```
### Behavior and limits
* At least one name is required.
* Matching uses the actual Bukkit world name.
***
## `night`
**Purpose:** Checks a fixed vanilla-style night time range.
**Context:** Requires a valid world from the source/context.
### Fields
| Field | Default | Description |
| ------- | ------- | --------------------- |
| `value` | `true` | Expected night state. |
### Example
```yaml
type: night
value: true
```
### Behavior and limits
* Night is defined as world time 12300 through 23850 inclusive.
* Weather and sky visibility are not considered.
***
## `environment`
**Purpose:** Matches a world dimension and optionally a biome.
**Context:** Default `target`: `SOURCE`; selected entity must exist.
### Fields
| Field | Default | Description |
| ----------- | -------- | ------------------------------------------------------------------ |
| `target` | `SOURCE` | Entity selector. |
| `dimension` | empty | Bukkit world environment such as `NORMAL`, `NETHER`, or `THE_END`. |
| `biomes` | empty | Accepted biome enum names or namespaced keys. |
### Example
```yaml
type: environment
target: SOURCE
dimension: NETHER
biomes:
- BASALT_DELTAS
- minecraft:soul_sand_valley
```
### Behavior and limits
* If `dimension` is configured it must match before biome checks.
* When both dimension and biome lists are empty, the condition fails.
***
# Trigger-data Conditions
Every registered condition on this page is documented as an independent reference entry. All entries also support the common condition fields documented on the [Power Conditions](/configs/power-conditions) page.
## Registry keys on this page
* `damage_value`
* `state_value`
* `damage_cause`
* `damage_origin`
* `melee`
* `spawn_reason`
* `combust_duration`
* `regain_amount`
* `explosion_yield`
* `explosion_radius`
* `target_reason`
* `cooldown`
***
## `damage_value`
**Purpose:** Checks the current mutable damage result.
**Context:** Requires a damage-backed trigger and result.
### Fields
| Field | Default | Description |
| ----------------- | --------- | ------------------------------- |
| `min / max` | unbounded | Inclusive numeric range. |
| `compare / value` | unset | Alternative numeric comparison. |
### Example
```yaml
type: damage_value
min: 1
max: 10
```
### Behavior and limits
* When evaluated after earlier modifiers, it reads the already-modified result.
* Unrelated triggers do not match.
***
## `state_value`
**Purpose:** Reads a numeric value previously written to the current power's configured state pool.
**Context:** Uses the selected state owner and current power ID. The writer must produce the same owner, power, key, and optional per-target entity identities.
### Fields
| Field | Default | Description |
| ----------------- | --------- | -------------------------------------------------------------------------------- |
| `owner` | `SOURCE` | Entity selector for the state owner. |
| `key` | `default` | State-pool name. |
| `per-target` | `false` | Whether the current target participates in the state key; must match the writer. |
| `state-target` | `TARGET` | Entity selector used as the per-target identity; must match the writer. |
| `min / max` | unbounded | Inclusive saved-state range. Missing and expired states read as `0`. |
| `compare / value` | unset | Alternative numeric comparison. |
### Example
```yaml
type: state_value
key: enraged
min: 1
```
### Behavior and limits
* State is isolated by selected owner UUID and power ID, so another power may safely reuse the same `key`.
* The selector names may differ from the writer across trigger contexts, but they must resolve to the same owner and per-target entity UUIDs.
* This condition reads state only; it does not create or refresh an entry.
***
## `damage_cause`
**Purpose:** Matches the captured Bukkit `EntityDamageEvent.DamageCause`.
**Context:** Requires damage-cause event context.
### Fields
| Field | Default | Description |
| -------- | ------- | ------------------------------ |
| `value` | empty | Single damage-cause enum name. |
| `values` | empty | Accepted cause names. |
### Example
```yaml
type: damage_cause
values:
- PROJECTILE
- ENTITY_ATTACK
```
### Behavior and limits
* Matching is case-insensitive after the plugin's value normalization.
* The condition fails when no damage cause is available.
***
## `damage_origin`
**Purpose:** Classifies damage by its captured origin.
**Context:** Requires damage-origin context.
### Fields
| Field | Default | Description |
| ------- | ------- | ------------------------------------- |
| `value` | `ANY` | `ANY`, `ENTITY`, `BLOCK`, or `OTHER`. |
### Example
```yaml
type: damage_origin
value: ENTITY
```
### Behavior and limits
* `OTHER` means neither entity-origin nor block-origin.
* Unknown values behave as `ANY` in the shared implementation.
***
## `melee`
**Purpose:** Checks the trigger's captured melee flag.
**Context:** Requires a trigger that supplies melee event context.
### Fields
| Field | Default | Description |
| ------- | ------- | -------------------- |
| `value` | `true` | Expected melee flag. |
### Example
```yaml
type: melee
value: true
```
### Behavior and limits
* The condition fails when the trigger did not provide a melee flag.
***
## `spawn_reason`
**Purpose:** Matches an entity's Bukkit spawn reason.
**Context:** Default `target`: `TARGET`; the selected entity must expose a spawn reason.
### Fields
| Field | Default | Description |
| --------- | -------- | ---------------------------------------- |
| `target` | `TARGET` | Entity selector. |
| `reason` | empty | Single `CreatureSpawnEvent.SpawnReason`. |
| `reasons` | empty | Accepted reason list. |
### Example
```yaml
type: spawn_reason
target: SOURCE
reasons:
- NATURAL
- REINFORCEMENTS
```
### Behavior and limits
* Values are compared with enum names.
* The entity's stored spawn reason may be inspected outside the spawn trigger.
***
## `combust_duration`
**Purpose:** Checks the current combustion-duration result.
**Context:** Requires a combust-event result.
### Fields
| Field | Default | Description |
| ----------------- | --------- | ------------------------------- |
| `min / max` | unbounded | Inclusive numeric range. |
| `compare / value` | unset | Alternative numeric comparison. |
### Example
```yaml
type: combust_duration
min: 1
max: 10
```
### Behavior and limits
* When evaluated after earlier modifiers, it reads the already-modified result.
* Unrelated triggers do not match.
***
## `regain_amount`
**Purpose:** Checks the current health-regain result.
**Context:** Requires a regain-event result.
### Fields
| Field | Default | Description |
| ----------------- | --------- | ------------------------------- |
| `min / max` | unbounded | Inclusive numeric range. |
| `compare / value` | unset | Alternative numeric comparison. |
### Example
```yaml
type: regain_amount
min: 1
max: 10
```
### Behavior and limits
* When evaluated after earlier modifiers, it reads the already-modified result.
* Unrelated triggers do not match.
***
## `explosion_yield`
**Purpose:** Checks the current explosion-yield result.
**Context:** Requires an entity-explosion result.
### Fields
| Field | Default | Description |
| ----------------- | --------- | ------------------------------- |
| `min / max` | unbounded | Inclusive numeric range. |
| `compare / value` | unset | Alternative numeric comparison. |
### Example
```yaml
type: explosion_yield
min: 1
max: 10
```
### Behavior and limits
* When evaluated after earlier modifiers, it reads the already-modified result.
* Unrelated triggers do not match.
***
## `explosion_radius`
**Purpose:** Checks the current primed-explosion radius.
**Context:** Requires an explosion-prime result.
### Fields
| Field | Default | Description |
| ----------------- | --------- | ------------------------------- |
| `min / max` | unbounded | Inclusive numeric range. |
| `compare / value` | unset | Alternative numeric comparison. |
### Example
```yaml
type: explosion_radius
min: 1
max: 10
```
### Behavior and limits
* When evaluated after earlier modifiers, it reads the already-modified result.
* Unrelated triggers do not match.
***
## `target_reason`
**Purpose:** Matches the captured Bukkit entity-target reason.
**Context:** Requires target/untag event context.
### Fields
| Field | Default | Description |
| -------- | ------- | ------------------------ |
| `value` | empty | Single reason enum name. |
| `values` | empty | Accepted reason list. |
### Example
```yaml
type: target_reason
values:
- CLOSEST_PLAYER
- TARGET_ATTACKED_ENTITY
```
### Behavior and limits
* Matching is case-insensitive after normalization.
* The condition fails when no target reason is present.
***
## `cooldown`
**Purpose:** Acquires a condition-scoped runtime cooldown and matches only when it can be acquired.
### Fields
| Field | Default | Description |
| ------------ | ------- | ------------------------------------------------------------- |
| `seconds` | `0` | Cooldown length in seconds; non-positive values always match. |
| `owner` | `OWNER` | Cooldown owner: `OWNER`, `SOURCE`, `SKILL`, or `TARGET`. |
| `per-target` | `false` | Keep an independent cooldown for each current target. |
### Example
```yaml
type: cooldown
owner: OWNER
seconds: 3
per-target: true
```
The key includes owner identity, power identity, and the condition's configuration path. This condition changes runtime state and should normally be placed after read-only conditions.
***
# Power Modifiers
EnchantedMobs registers **10 built-in modifier keys**. Modifiers run in YAML order after trigger conditions and before abilities.
## Reference pages
* [Result and Resource Modifiers](/configs/power-modifiers/result-values)
* [Combat and State Modifiers](/configs/power-modifiers/combat-state)
* [Event and Drop Modifiers](/configs/power-modifiers/event-drops)
* [Projectile Modifiers](/configs/power-modifiers/projectiles)
* [Fishing and Trading Modifiers](/configs/power-modifiers/fishing-trading)
## Common format
```yaml
modifiers:
unique-entry-id:
type: damage
conditions: {}
random: 1
cooldown: 0
operation: MULTIPLY
value: 1.25
```
## Common fields
| Field | Default | Description |
| ------------ | -------- | -------------------------------------------------------------------------------- |
| `type` | required | Registered modifier key. Keys are case-insensitive and `-` is normalized to `_`. |
| `conditions` | empty | Typed Power Conditions; every child must pass. |
| `random` | `1` | Application probability. |
| `cooldown` | `0` | Per-source, per-power, per-config-path cooldown in seconds. |
Common checks run in this order: conditions, probability, then cooldown acquisition. A modifier whose event-specific implementation later finds incompatible context may still have acquired its common cooldown.
## Shared numeric operations
| Operation | Result |
| ---------- | --------------------------------------- |
| `SET` | operand |
| `ADD` | original + operand |
| `SUBTRACT` | original - operand |
| `MULTIPLY` | original × operand |
| `DIVIDE` | original ÷ operand; zero keeps original |
| `MIN` | minimum of original and operand |
| `MAX` | maximum of original and operand |
## Type index
| Type | Reference |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| `damage` | [Result and Resource Modifiers](/configs/power-modifiers/result-values#damage) |
| `heal` | [Result and Resource Modifiers](/configs/power-modifiers/result-values#heal) |
| `duration` | [Result and Resource Modifiers](/configs/power-modifiers/result-values#duration) |
| `yield` | [Result and Resource Modifiers](/configs/power-modifiers/result-values#yield) |
| `radius` | [Result and Resource Modifiers](/configs/power-modifiers/result-values#radius) |
| `armor_pierce` | [Combat and State Modifiers](/configs/power-modifiers/combat-state#armor-pierce) |
| `stack_damage_modifier` | [Combat and State Modifiers](/configs/power-modifiers/combat-state#stack-damage-modifier) |
| `revive` | [Combat and State Modifiers](/configs/power-modifiers/combat-state#revive) |
| `modify_projectile` | [Projectile Modifiers](/configs/power-modifiers/projectiles#modify-projectile) |
| `replace_projectile` | [Projectile Modifiers](/configs/power-modifiers/projectiles#replace-projectile) |
# Result and Resource Modifiers
Every modifier on this page is documented independently. All entries also support the common modifier fields from the [Power Modifiers](/configs/power-modifiers) page.
## Registry keys on this page
* `damage`
* `heal`
* `duration`
* `yield`
* `radius`
***
## `damage`
**Purpose:** Changes the current mutable damage result.
**Context:** Damage-producing triggers such as incoming/outgoing damage.
### Fields
| Field | Default | Description |
| ----------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `value` | current value | Operand; `{original}` is the current result before this modifier. |
| `operation` | `SET` | `SET`, `ADD`, `SUBTRACT`, `MULTIPLY`, `DIVIDE`, `MIN`, or `MAX`; division by zero keeps the original. |
### Example
```yaml
type: damage
operation: MULTIPLY
value: 1.25
```
### Behavior and limits
* Earlier modifiers in YAML order affect `{original}`.
* Final damage is applied after matching powers finish.
***
## `heal`
**Purpose:** Changes the current health-regain amount.
**Context:** `on-regain` or another trigger with a regain result.
### Fields
| Field | Default | Description |
| ----------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `value` | current value | Operand; `{original}` is the current result before this modifier. |
| `operation` | `SET` | `SET`, `ADD`, `SUBTRACT`, `MULTIPLY`, `DIVIDE`, `MIN`, or `MAX`; division by zero keeps the original. |
### Example
```yaml
type: heal
operation: ADD
value: 2
```
### Behavior and limits
* Earlier modifiers in YAML order affect `{original}`.
* The value is written back to the regain event result.
***
## `duration`
**Purpose:** Changes the current combustion duration.
**Context:** `on-combust` or another trigger with a combustion-duration result.
### Fields
| Field | Default | Description |
| ----------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `value` | current value | Operand; `{original}` is the current result before this modifier. |
| `operation` | `SET` | `SET`, `ADD`, `SUBTRACT`, `MULTIPLY`, `DIVIDE`, `MIN`, or `MAX`; division by zero keeps the original. |
### Example
```yaml
type: duration
operation: MULTIPLY
value: 2
```
### Behavior and limits
* Earlier modifiers in YAML order affect `{original}`.
* The result is later applied to the combustion event.
***
## `yield`
**Purpose:** Changes explosion yield.
**Context:** An entity-explosion trigger with mutable yield.
### Fields
| Field | Default | Description |
| ----------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `value` | current value | Operand; `{original}` is the current result before this modifier. |
| `operation` | `SET` | `SET`, `ADD`, `SUBTRACT`, `MULTIPLY`, `DIVIDE`, `MIN`, or `MAX`; division by zero keeps the original. |
### Example
```yaml
type: yield
operation: ADD
value: 2
```
### Behavior and limits
* Earlier modifiers in YAML order affect `{original}`.
* Explosion yield affects block drops; it is not explosion radius.
***
## `radius`
**Purpose:** Changes primed-explosion radius.
**Context:** `on-creeper-explode` / `ExplosionPrimeEvent`.
### Fields
| Field | Default | Description |
| ----------- | ------------- | ----------------------------------------------------------------------------------------------------- |
| `value` | current value | Operand; `{original}` is the current result before this modifier. |
| `operation` | `SET` | `SET`, `ADD`, `SUBTRACT`, `MULTIPLY`, `DIVIDE`, `MIN`, or `MAX`; division by zero keeps the original. |
### Example
```yaml
type: radius
operation: ADD
value: 2
```
### Behavior and limits
* Earlier modifiers in YAML order affect `{original}`.
* The radius is changed before the explosion is created.
***
# Combat and State Modifiers
Every modifier on this page is documented independently. All entries also support the common modifier fields from the [Power Modifiers](/configs/power-modifiers) page.
## Registry keys on this page
* `armor_pierce`
* `stack_damage_modifier`
* `revive`
***
## `armor_pierce`
**Purpose:** Increases the current damage result to approximate ignoring a percentage of target armor.
**Context:** Requires living `TARGET` and a damage result.
### Fields
| Field | Default | Description |
| --------- | ------- | -------------------------------------------------- |
| `percent` | `0` | Armor penetration percentage, clamped to `0..100`. |
### Example
```yaml
type: armor_pierce
percent: 35
```
### Behavior and limits
* The target's armor and toughness attributes are read but never changed.
* This compensates for vanilla armor reduction; it is not a separate true-damage channel.
***
## `stack_damage_modifier`
**Purpose:** Stores stack state and converts it into a percentage damage increase or decrease.
**Context:** Requires a stable owner and a damage result for actual modification; matching `pool` values can share state across trigger sections.
### Fields
| Field | Default | Description |
| ------------------------ | ------------- | ---------------------------------------------------------------- |
| `damage-type` | `DEALT` | `DEALT` or `TAKEN`; controls default scope and message metadata. |
| `stack-action` | `ADD` | `ADD`, `READ`, `CONSUME`, or `CLEAR`. |
| `stack-value` | `CURRENT` | For `ADD`, apply `CURRENT` or `PREVIOUS` stack count. |
| `operation` | `INCREASE` | `INCREASE`, `DECREASE`, or `NONE`. |
| `pool` | current path | State-pool name. |
| `max-stacks` | `5` | Maximum stored stacks, minimum 1. |
| `stack-amount` | `1` | Amount added by `ADD`. |
| `percent-per-stack` | `5` | Damage percentage per effective stack. |
| `maximum-percent` | derived | Final percentage cap. |
| `scope.per-target` | `false` | Separate pools by selected target. |
| `scope.target` | type-specific | Default `TARGET` for dealt and `SOURCE` for taken. |
| `scope.per-damage-cause` | `false` | Separate pools by Bukkit damage cause. |
| `reset.seconds` | `5` | Expiry refreshed by `ADD`; non-positive disables timed expiry. |
| `reset.clear-on` | empty | `AFTER_APPLY`, `AFTER_DAMAGE_DEALT`, or `AFTER_DAMAGE_TAKEN`. |
| `messages.*` | empty | Optional lifecycle messages and recipient/throttle settings. |
### Example
```yaml
type: stack_damage_modifier
pool: combo
damage-type: DEALT
stack-action: ADD
operation: INCREASE
max-stacks: 5
stack-amount: 1
percent-per-stack: 6
reset:
seconds: 4
scope:
per-target: true
```
### Behavior and limits
* `ADD` updates state; `READ` applies without changing it; `CONSUME` removes and applies; `CLEAR` only removes.
* State and scheduled messages are cleared on reload/unload and relevant entity unload.
***
## `revive`
**Purpose:** Requests revival during a supported death trigger.
**Context:** Intended for `on-death`; successful application depends on trigger/platform support.
### Fields
| Field | Default | Description |
| ---------- | ------- | ------------------------------------------------------------------------------- |
| `health` | `20` | Revive health, capped at source maximum health; `{original}` is maximum health. |
| `no-drops` | `false` | Clear death drops when revival is applied. |
### Example
```yaml
type: revive
health: '{original} * 0.5'
no-drops: true
```
### Behavior and limits
* Use a power- or entry-level count limit when revival should happen only once.
* When source is not living, the fallback maximum for expression resolution is 20.
***
# Event and Drop Modifiers
This repository does not register a built-in Power Modifier in this category. The page is retained so the Configs hierarchy stays identical across the two plugins.
# Projectile Modifiers
Every modifier on this page is documented independently. All entries also support the common modifier fields from the [Power Modifiers](/configs/power-modifiers) page.
## Registry keys on this page
* `modify_projectile`
* `replace_projectile`
***
## `modify_projectile`
**Purpose:** Edits the current projectile in place.
**Context:** Uses projectile `SKILL`, falling back to projectile `TARGET`; normally used on shoot, launch, or projectile-tick triggers.
### Fields
| Field | Default | Description |
| ----------------------- | --------- | ---------------------------------------------------------------------------- |
| `speed-multiplier` | `1` | Multiplies current velocity. |
| `draw-speed-multiplier` | unset | Scales velocity relative to captured bow force when available. |
| `spread-degrees` | unset | Random X/Y angular spread. |
| `accuracy` | unset | Blends direction toward source living entity look direction; clamped `0..1`. |
| `gravity` | unchanged | Enable or disable gravity. |
| `fire-ticks` | unchanged | Set projectile fire ticks, minimum 0. |
| `damage-multiplier` | `1` | Multiplies `AbstractArrow` base damage. |
| `critical` | current | Sets arrow critical state. |
| `pierce-level` | current | Sets pierce level, clamped `0..127`. |
### Example
```yaml
type: modify_projectile
speed-multiplier: 1.25
spread-degrees: 3
gravity: false
damage-multiplier: 1.5
pierce-level: 2
```
### Behavior and limits
* Absent options leave their property unchanged, except neutral speed/damage multipliers.
* `accuracy` aims along the shooter's look direction, not directly at `TARGET`.
***
## `replace_projectile`
**Purpose:** Removes the current projectile and replaces it with TNT or another projectile type while preserving core motion and ownership.
**Context:** Reads the old projectile from `SKILL` or captured projectile context and writes the replacement as the new skill entity.
### Fields
| Field | Default | Description |
| --------------------- | -------- | ---------------------------------------------------------------- |
| `projectile` | required | `TNT` aliases or a spawnable Bukkit projectile type. |
| `fuse` | `40` | TNT fuse ticks, minimum 1. |
| `fireball-yield` | `1` | Yield for fireball replacements. |
| `fireball-incendiary` | `true` | Incendiary state for fireballs. |
| `potion-type` | unset | Base potion type for thrown potions. |
| `potion-effects` | unset | Custom potion effects with `duration` (100) and `amplifier` (0). |
### Example
```yaml
type: replace_projectile
projectile: SPLASH_POTION
potion-type: HARMING
potion-effects:
slowness:
duration: 80
amplifier: 1
```
### Behavior and limits
* Velocity and gravity are copied to projectile replacements.
* The captured living source becomes shooter.
* Replacing with a projectile transfers tracking; TNT/non-projectile replacement ends projectile continuation.
* TNT velocity is multiplied by 1.2.
***
# Fishing and Trading Modifiers
This repository does not register a built-in Power Modifier in this category. The page is retained so the Configs hierarchy stays identical across the two plugins.
# Abilities
Abilities run after trigger conditions and Power Modifiers. Each category page provides purpose, exact context, complete type-specific fields with defaults, a runnable YAML example, and behavior/limits.
EnchantedMobs registers **57 built-in ability keys**.
## Reference pages
* [Fundamental and Visual Abilities](/configs/info-of-abilities/fundamentals)
* [Entity State Abilities](/configs/info-of-abilities/entity-state)
* [Combat and Movement Abilities](/configs/info-of-abilities/combat)
* [Projectile Abilities](/configs/info-of-abilities/projectiles)
* [Inventory and Equipment Abilities](/configs/info-of-abilities/inventory-equipment)
* [Control-flow Abilities](/configs/info-of-abilities/orchestration)
* [Integration and Targeting Abilities](/configs/info-of-abilities/integration)
* [Block and World Abilities](/configs/info-of-abilities/blocks-world)
## Common format
```yaml
abilities:
unique-entry-id:
type: damage_entity
target: TARGET
amount: '2 + level'
conditions: {}
random: 1
cooldown: 0
times: 0
```
## Common fields
| Field | Default | Description |
| ----------------------- | ------------------- | ------------------------------------------------------------------------------- |
| `type` | required | Registered ability key. Keys are case-insensitive and `-` is normalized to `_`. |
| `target` | ability-specific | Selects an entity role such as `SOURCE`, `SKILL`, or `TARGET`. |
| `source` | `SOURCE` where used | Attribution, direction, shooter, owner, or another source role. |
| `conditions` | empty | Typed Power Conditions; every child must pass. |
| `random` | `1` | Execution probability. |
| `cooldown` | `0` | Per-source, per-power, per-config-path cooldown in seconds. |
| `times` | `0` | Maximum successful attempts for this configured path; zero is unlimited. |
| `location.offset-x/y/z` | `0` | Offset applied to the trigger-resolved location. |
## Common execution order
1. Ability-local typed conditions.
2. Usage-count check.
3. Existing cooldown check.
4. Random roll.
5. Cooldown acquisition.
6. Usage-count increment.
7. Type-specific implementation.
Because common cooldown/count state is acquired before type-specific execution, an ability can consume an attempt and then skip when required event/entity/item/block/integration context is unavailable.
## Dynamic values
Supported fields may resolve `level`, power variables, level selector maps, numeric ranges, runtime placeholders, and PlaceholderAPI where a player context exists. Each entry documents important explicit placeholders.
## Type index
| Type | Reference |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `mark` | [Fundamental and Visual Abilities](/configs/info-of-abilities/fundamentals#mark) |
| `cancel_event` | [Fundamental and Visual Abilities](/configs/info-of-abilities/fundamentals#cancel-event) |
| `remove` | [Fundamental and Visual Abilities](/configs/info-of-abilities/fundamentals#remove) |
| `place_block` | [Fundamental and Visual Abilities](/configs/info-of-abilities/fundamentals#place-block) |
| `particle` | [Fundamental and Visual Abilities](/configs/info-of-abilities/fundamentals#particle) |
| `sound` | [Fundamental and Visual Abilities](/configs/info-of-abilities/fundamentals#sound) |
| `vanilla_animation` | [Fundamental and Visual Abilities](/configs/info-of-abilities/fundamentals#vanilla-animation) |
| `set_attribute` | [Entity State Abilities](/configs/info-of-abilities/entity-state#set-attribute) |
| `refresh_attribute` | [Entity State Abilities](/configs/info-of-abilities/entity-state#refresh-attribute) |
| `set_health` | [Entity State Abilities](/configs/info-of-abilities/entity-state#set-health) |
| `set_absorption` | [Entity State Abilities](/configs/info-of-abilities/entity-state#set-absorption) |
| `set_air` | [Entity State Abilities](/configs/info-of-abilities/entity-state#set-air) |
| `set_food` | [Entity State Abilities](/configs/info-of-abilities/entity-state#set-food) |
| `set_item_cooldown` | [Entity State Abilities](/configs/info-of-abilities/entity-state#set-item-cooldown) |
| `set_velocity` | [Entity State Abilities](/configs/info-of-abilities/entity-state#set-velocity) |
| `set_invulnerable` | [Entity State Abilities](/configs/info-of-abilities/entity-state#set-invulnerable) |
| `potion_effect` | [Entity State Abilities](/configs/info-of-abilities/entity-state#potion-effect) |
| `remove_potion_effect` | [Entity State Abilities](/configs/info-of-abilities/entity-state#remove-potion-effect) |
| `extend_potion_effects` | [Entity State Abilities](/configs/info-of-abilities/entity-state#extend-potion-effects) |
| `potion_cloud` | [Entity State Abilities](/configs/info-of-abilities/entity-state#potion-cloud) |
| `freeze` | [Entity State Abilities](/configs/info-of-abilities/entity-state#freeze) |
| `fire` | [Entity State Abilities](/configs/info-of-abilities/entity-state#fire) |
| `experience` | [Entity State Abilities](/configs/info-of-abilities/entity-state#experience) |
| `explosion` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#explosion) |
| `lightning` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#lightning) |
| `damage_entity` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#damage-entity) |
| `damage_item` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#damage-item) |
| `pull_target` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#pull-target) |
| `teleport_near_target` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#teleport-near-target) |
| `guardian_beam` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#guardian-beam) |
| `sonic_boom` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#sonic-boom) |
| `evoker_fangs` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#evoker-fangs) |
| `arrow_rain` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#arrow-rain) |
| `creeper_stats` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#creeper-stats) |
| `swap_health` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#swap-health) |
| `swap_potion_effects` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#swap-potion-effects) |
| `swap_locations` | [Combat and Movement Abilities](/configs/info-of-abilities/combat#swap-locations) |
| `launch_projectile` | [Projectile Abilities](/configs/info-of-abilities/projectiles#launch-projectile) |
| `reflect_projectile` | [Projectile Abilities](/configs/info-of-abilities/projectiles#reflect-projectile) |
| `ricochet_projectile` | [Projectile Abilities](/configs/info-of-abilities/projectiles#ricochet-projectile) |
| `shulker_bullet` | [Projectile Abilities](/configs/info-of-abilities/projectiles#shulker-bullet) |
| `homing_projectile` | [Projectile Abilities](/configs/info-of-abilities/projectiles#homing-projectile) |
| `consume_food` | [Inventory and Equipment Abilities](/configs/info-of-abilities/inventory-equipment#consume-food) |
| `enhance_equipment` | [Inventory and Equipment Abilities](/configs/info-of-abilities/inventory-equipment#enhance-equipment) |
| `enhance_helditem` | [Inventory and Equipment Abilities](/configs/info-of-abilities/inventory-equipment#enhance-helditem) |
| `replace_item` | [Inventory and Equipment Abilities](/configs/info-of-abilities/inventory-equipment#replace-item) |
| `disarm` | [Inventory and Equipment Abilities](/configs/info-of-abilities/inventory-equipment#disarm) |
| `shuffle_inventory` | [Inventory and Equipment Abilities](/configs/info-of-abilities/inventory-equipment#shuffle-inventory) |
| `delay` | [Control-flow Abilities](/configs/info-of-abilities/orchestration#delay) |
| `conditional` | [Control-flow Abilities](/configs/info-of-abilities/orchestration#conditional) |
| `any_of` | [Control-flow Abilities](/configs/info-of-abilities/orchestration#any-of) |
| `limit` | [Control-flow Abilities](/configs/info-of-abilities/orchestration#limit) |
| `repeat` | [Control-flow Abilities](/configs/info-of-abilities/orchestration#repeat) |
| `state` | [Control-flow Abilities](/configs/info-of-abilities/orchestration#state) |
| `nearby_entities` | [Integration and Targeting Abilities](/configs/info-of-abilities/integration#nearby-entities) |
| `summon` | [Integration and Targeting Abilities](/configs/info-of-abilities/integration#summon) |
| `mythic_skill` | [Integration and Targeting Abilities](/configs/info-of-abilities/integration#mythic-skill) |
| `send_message` | [Integration and Targeting Abilities](/configs/info-of-abilities/integration#send-message) |
| `execute_command` | [Integration and Targeting Abilities](/configs/info-of-abilities/integration#execute-command) |
# Fundamental and Visual 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](/configs/info-of-abilities) page.
## Registry keys on this page
* `mark`
* `cancel_event`
* `remove`
* `place_block`
* `particle`
* `sound`
* `vanilla_animation`
***
## `mark`
**Purpose:** Marks the selected entity as belonging to the current power chain.
**Context:** Default `target`: `SKILL`; requires the selected entity to exist.
### Fields
*No type-specific fields.*
### Example
```yaml
type: mark
target: SKILL
```
### Behavior and limits
* The marker is internal; it does not add a visible scoreboard tag.
* Normally used for projectiles or helper entities that must retain power context.
***
## `cancel_event`
**Purpose:** Requests cancellation of the current trigger event.
**Context:** No entity target is required; the trigger must provide a cancellable event.
### Fields
*No type-specific fields.*
### Example
```yaml
type: cancel_event
```
### Behavior and limits
* The cancellation signal is propagated through parent control-flow abilities.
* Cancelling a late notification event may not undo server work that already happened.
***
## `remove`
**Purpose:** Removes the selected entity from the world.
**Context:** Default `target`: `SKILL`; requires an entity.
### Fields
*No type-specific fields.*
### Example
```yaml
type: remove
target: SKILL
```
### Behavior and limits
* Players are never intended targets for this cleanup ability.
* Useful for projectiles, temporary helpers, or replaced skill entities.
***
## `place_block`
**Purpose:** Places a temporary block at the resolved ability location.
**Context:** Uses the trigger location plus common location offsets; no entity target is required.
### Fields
| Field | Default | Description |
| ---------- | -------- | --------------------------------------------------------- |
| `block` | `COBWEB` | Bukkit material to place; must be a valid block material. |
| `duration` | `40` | Lifetime in ticks, clamped to at least 1. |
### Example
```yaml
type: place_block
block: COBWEB
duration: 100
location:
offset-y: 1
```
### Behavior and limits
* The destination block must currently be air.
* The original block is restored by `TempBlockManager` when the duration expires.
***
## `particle`
**Purpose:** Spawns a Bukkit particle at the resolved location.
**Context:** Default target is ability-specific; positioning uses the trigger/resolved location and common offsets.
### Fields
| Field | Default | Description |
| -------------------------------- | ----------------- | ---------------------------------------------------------------------------- |
| `particle` | `FLAME` | Bukkit `Particle` enum name. |
| `count` | `1` | Particle count. |
| `offset-x / offset-y / offset-z` | `0` | Particle spread. |
| `extra` | `0` | Particle-specific speed/extra value. |
| `block` | `STONE` | Block material for block-data particles. |
| `item` | `STONE` | Item material for `ITEM`. |
| `color` | particle-specific | RGB value such as `255,0,0`. |
| `size` | `1` | Dust size or particle-specific size/duration. |
| `from / to` | particle-specific | Transition colors, vibration destination, or other structured particle data. |
| `value` | `1.0` | Float data for particles such as `DRAGON_BREATH` or `SCULK_CHARGE`. |
| `delay` | `20` | Delay data for `SHRIEK`. |
| `duration` | `20` | Travel duration for `VIBRATION`. |
### Example
```yaml
type: particle
particle: DUST
count: 20
offset-x: 0.4
offset-y: 0.8
offset-z: 0.4
color: 255,80,20
size: 1.5
```
### Behavior and limits
* Invalid particle names or incompatible required data cause the ability to do nothing.
* Keep counts small on high-frequency triggers.
***
## `sound`
**Purpose:** Plays a Bukkit sound at the resolved location.
**Context:** Uses the trigger/resolved location and common offsets.
### Fields
| Field | Default | Description |
| -------- | ----------------------- | ------------------------------- |
| `sound` | `ENTITY_PLAYER_LEVELUP` | Bukkit `Sound` enum name. |
| `volume` | `1` | Sound volume and audible range. |
| `pitch` | `1` | Sound pitch. |
### Example
```yaml
type: sound
sound: ENTITY_WARDEN_SONIC_BOOM
volume: 2
pitch: 1
```
### Behavior and limits
* Invalid sound names are ignored.
* Very large volume values increase audible range.
***
## `vanilla_animation`
**Purpose:** Plays a Bukkit `EntityEffect` animation on a selected entity.
**Context:** Default `target`: `SOURCE`; requires an entity compatible with the selected effect.
### Fields
| Field | Default | Description |
| --------------- | ------- | -------------------------------------- |
| `animation` | `HURT` | Bukkit `EntityEffect` enum name. |
| `entity-effect` | `HURT` | Alias used when `animation` is absent. |
### Example
```yaml
type: vanilla_animation
target: SOURCE
animation: TOTEM_RESURRECT
```
### Behavior and limits
* Invalid animation/effect names are ignored.
* The animation is client-visible and does not itself apply damage or another mechanic.
***
# 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](/configs/info-of-abilities) 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`.
***
# Combat and Movement 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](/configs/info-of-abilities) page.
## Registry keys on this page
* `explosion`
* `lightning`
* `damage_entity`
* `damage_item`
* `pull_target`
* `teleport_near_target`
* `guardian_beam`
* `sonic_boom`
* `evoker_fangs`
* `arrow_rain`
* `creeper_stats`
* `swap_health`
* `swap_potion_effects`
* `swap_locations`
***
## `explosion`
**Purpose:** Creates an explosion and an explosion-emitter particle at the resolved location.
**Context:** Default `target`: `TARGET`; selected target is supplied as the explosion source where supported.
### Fields
| Field | Default | Description |
| -------------- | ------- | ----------------------------------------- |
| `yield` | `2.0` | Explosion strength. |
| `set-fire` | `false` | Whether the explosion may ignite blocks. |
| `break-blocks` | `false` | Whether the explosion may destroy blocks. |
### Example
```yaml
type: explosion
target: TARGET
yield: 3
set-fire: false
break-blocks: false
```
### Behavior and limits
* Damage is wrapped as direct ability damage to avoid recursively firing the same power chain.
***
## `lightning`
**Purpose:** Creates visual lightning strikes around a target and directly damages nearby living entities.
**Context:** Default `target`: `TARGET`; `source` defaults to `SOURCE` for damage attribution.
### Fields
| Field | Default | Description |
| -------- | ------- | -------------------------------------------------- |
| `count` | `2` | Number of strike attempts, minimum 1. |
| `radius` | `3.0` | Horizontal random offset and nearby-damage radius. |
| `damage` | `4.0` | Damage applied near each strike. |
### Example
```yaml
type: lightning
target: TARGET
source: SOURCE
count: 3
radius: 4
damage: 6
```
### Behavior and limits
* The lightning is visual; configured damage is applied separately.
* Overlapping strike areas may damage the same entity more than once.
***
## `damage_entity`
**Purpose:** Deals a separate direct-damage instance to a living entity.
**Context:** Default `target`: `TARGET`; `source` chooses damage attribution and defaults to `SOURCE`.
### Fields
| Field | Default | Description |
| -------- | ------- | --------------------------------------------------------------------- |
| `amount` | `1` | Damage amount; supports current/original trigger damage placeholders. |
### Example
```yaml
type: damage_entity
target: TARGET
source: SOURCE
amount: '{original} * 0.5'
```
### Behavior and limits
* Amount is clamped to at least zero.
* Direct ability damage is guarded against recursive power triggering.
***
## `damage_item`
**Purpose:** Damages equipped items in selected slots.
**Context:** Default `target`: `TARGET`; requires a living entity with equipment.
### Fields
| Field | Default | Description |
| -------- | -------- | ----------------------------------------------------------------------------- |
| `amount` | `1` | Durability damage; may use trigger damage placeholders. |
| `slots` | empty | `MAIN_HAND`, `OFF_HAND`, armor slots, or `ARMOR`. |
| `mode` | `DIRECT` | `DIRECT` edits item damage metadata; `PAPER` uses Paper item-damage behavior. |
### Example
```yaml
type: damage_item
target: TARGET
amount: 2
mode: PAPER
slots:
- ARMOR
- MAIN_HAND
```
### Behavior and limits
* Air, unbreakable, and non-damageable items are skipped.
* Paper mode allows normal platform durability behavior such as Unbreaking and break events.
***
## `pull_target`
**Purpose:** Pulls a target toward the source, pushes it away, or randomly chooses direction.
**Context:** Default `target`: `TARGET`; `source` defaults to `SOURCE` and acts as direction origin.
### Fields
| Field | Default | Description |
| -------------------- | ----------------- | ----------------------------------------------------------------------------------- |
| `direction` | `TOWARD` | `TOWARD`, `AWAY`/`AWAY_FROM_SOURCE`, or `RANDOM`. |
| `speed` | `strength` or `1` | Velocity magnitude. |
| `strength` | `1` | Legacy alias when `speed` is absent. |
| `vertical` | automatic | Exact Y velocity; when absent the implementation supplies a small upward component. |
| `remove-powder-snow` | `false` | Replace powder snow at target feet before moving. |
### Example
```yaml
type: pull_target
source: SOURCE
target: TARGET
direction: TOWARD
speed: 1.1
vertical: 0.25
```
### Behavior and limits
* When source and target overlap, source look direction is used as fallback.
***
## `teleport_near_target`
**Purpose:** Teleports a living entity to a random safe location near its current position.
**Context:** Default `target`: `TARGET`.
### Fields
| Field | Default | Description |
| ------------ | ------- | --------------------------------------------------- |
| `min-radius` | `3.0` | Minimum horizontal distance, at least 1. |
| `max-radius` | `8.0` | Maximum horizontal distance, at least `min-radius`. |
| `max-tries` | `12` | Random candidate attempts, minimum 1. |
### Example
```yaml
type: teleport_near_target
target: SOURCE
min-radius: 4
max-radius: 10
max-tries: 16
```
### Behavior and limits
* Each candidate searches around its Y position for passable feet/head blocks over a solid block.
* Yaw and pitch are preserved and teleporting uses scheduler-safe handling.
***
## `guardian_beam`
**Purpose:** Displays a virtual guardian beam, waits for charge, then damages the target.
**Context:** Requires living `SOURCE` and living `TARGET`.
### Fields
| Field | Default | Description |
| -------------- | ------- | ----------------------------------------- |
| `range` | `18.0` | Maximum distance at start and completion. |
| `charge-ticks` | `30` | Charge time, minimum 1. |
| `damage` | `6.0` | Final damage, minimum 0. |
### Example
```yaml
type: guardian_beam
target: TARGET
range: 20
charge-ticks: 35
damage: 8
```
### Behavior and limits
* Requires PacketEvents.
* Damage is skipped if entities become invalid/dead, change world, or move out of range before completion.
***
## `sonic_boom`
**Purpose:** Charges and fires a Warden-style sonic boom with particles, sound, damage, and knockback.
**Context:** Requires living `SOURCE` and living `TARGET`.
### Fields
| Field | Default | Description |
| ------------------------------ | ------- | -------------------------------- |
| `range-xz` | `15` | Horizontal range. |
| `range-y` | `20` | Maximum vertical difference. |
| `charge-ticks` | `34` | Delay before firing. |
| `charge-volume / charge-pitch` | `3 / 1` | Charge sound. |
| `boom-volume / boom-pitch` | `3 / 1` | Boom sound. |
| `particle-extra-steps` | `7` | Extra particle positions. |
| `damage` | `10` | Direct damage. |
| `knockback-horizontal` | `2.5` | Horizontal knockback multiplier. |
| `knockback-vertical` | `0.5` | Vertical-direction multiplier. |
### Example
```yaml
type: sonic_boom
target: TARGET
charge-ticks: 30
damage: 12
knockback-horizontal: 2
knockback-vertical: 0.4
```
### Behavior and limits
* Range and entity validity are checked again after charging.
***
## `evoker_fangs`
**Purpose:** Creates vanilla evoker-fang attack patterns between source and target.
**Context:** Requires living `SOURCE` and living `TARGET`.
### Fields
| Field | Default | Description |
| ------------- | ------- | ------------------------------------------------------------------------------ |
| `damage` | `6.0` | Damage stored on each fang for direct-damage handling. |
| `close-range` | `3.0` | Below this distance, ring patterns are used; otherwise a line pattern is used. |
### Example
```yaml
type: evoker_fangs
target: TARGET
damage: 8
close-range: 4
```
### Behavior and limits
* Fangs search downward for solid ground.
* The selected living source becomes fang owner.
***
## `arrow_rain`
**Purpose:** Spawns downward-moving arrows in a random square above a target location.
**Context:** Default `target`: `TARGET`; `source` controls shooter attribution.
### Fields
| Field | Default | Description |
| -------------- | ------- | ------------------------------------------------- |
| `count` | `10` | Arrow count, minimum 1. |
| `radius` | `4.0` | Horizontal spread, minimum 0.1. |
| `height` | `12.0` | Spawn height, minimum 2. |
| `spread` | `0.18` | Random X/Z velocity spread. |
| `damage` | `-1` | Arrow base damage; negative keeps Bukkit default. |
| `pierce-level` | `0` | Pierce level, minimum 0. |
| `critical` | `false` | Critical flag. |
### Example
```yaml
type: arrow_rain
target: TARGET
source: SOURCE
count: 16
radius: 5
height: 14
damage: 4
```
### Behavior and limits
* Arrow pickup is disabled.
***
## `creeper_stats`
**Purpose:** Changes selected creeper properties.
**Context:** Default `target`: `SOURCE`; selected entity must be a creeper.
### Fields
| Field | Default | Description |
| ------------------ | --------- | ---------------------------------- |
| `explosion-radius` | unchanged | New radius, minimum 0. |
| `fuse-ticks` | unchanged | New maximum fuse ticks, minimum 1. |
| `powered` | unchanged | Charged state. |
### Example
```yaml
type: creeper_stats
target: SOURCE
explosion-radius: 6
fuse-ticks: 30
powered: true
```
### Behavior and limits
* Only fields present in configuration are changed.
***
## `swap_health`
**Purpose:** Swaps current health percentages between source and target.
**Context:** Requires living `SOURCE` and living `TARGET`; configurable selectors are not used by the shared implementation.
### Fields
*No type-specific fields.*
### Example
```yaml
type: swap_health
```
### Behavior and limits
* Absolute health is recalculated from each entity's own maximum.
* Results are clamped above zero, so this ability does not directly kill either entity.
***
## `swap_potion_effects`
**Purpose:** Transfers or swaps selected active potion effects between source and target.
**Context:** Uses common `source` and `target`; both must be different living entities.
### Fields
| Field | Default | Description |
| ------------- | ------------------ | ---------------------------------------------------------- |
| `direction` | `SOURCE_TO_TARGET` | `SOURCE_TO_TARGET`, `TARGET_TO_SOURCE`, or `SWAP` aliases. |
| `potion` | unset | Single effect selector. |
| `potions` | `ALL` | Effect selectors, including categories. |
| `max-effects` | `-1` | Maximum selected types; negative means unlimited. |
### Example
```yaml
type: swap_potion_effects
source: SOURCE
target: TARGET
direction: SWAP
potions:
- HARMFUL
max-effects: 3
```
### Behavior and limits
* Transfer modes remove effects from origin and add them to destination.
* Swap exchanges each selected effect type; one-sided effects move to the other entity.
***
## `swap_locations`
**Purpose:** Swaps the locations of two entities.
**Context:** Uses common `source` and `target` selectors.
### Fields
*No type-specific fields.*
### Example
```yaml
type: swap_locations
source: SOURCE
target: TARGET
```
### Behavior and limits
* Entities must be distinct and in the same world.
* Teleports use scheduler-safe handling.
***
# Projectile 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](/configs/info-of-abilities) page.
## Registry keys on this page
* `launch_projectile`
* `shulker_bullet`
* `reflect_projectile`
* `ricochet_projectile`
* `homing_projectile`
***
## `launch_projectile`
**Purpose:** Spawns and configures one or more projectile entities from a living shooter.
**Context:** When `source` is present it selects the shooter; otherwise `target` selects the shooter. `TARGET` remains the aim target.
### Fields
| Field | Default | Description |
| --------------------- | ------- | -------------------------------------------------------------------- |
| `entity-type` | `ARROW` | Spawnable Bukkit entity type implementing `Projectile`. |
| `speed` | `1.5` | Launch speed. |
| `extra-y` | `0` | Additional Y component. |
| `count` | `1` | Projectile count, minimum 1. |
| `spread-degrees` | `0` | Maximum fan angle; projectiles are evenly distributed. |
| `spawn-offset` | `0` | Forward offset from shooter eye. |
| `damage` | unset | Ability-damage override stored on projectile. |
| `inherit-powers` | `false` | Track projectile for projectile-tick/hit continuation. |
| `fireball-yield` | `1.0` | Yield for explosive projectiles. |
| `fireball-incendiary` | `true` | Incendiary flag for fireballs. |
| `potion-type` | unset | Base potion type for thrown potions. |
| `potion` | unset | Single custom effect when `potion-effects` is absent. |
| `duration` | `100` | Single custom-effect duration. |
| `amplifier` | `0` | Single custom-effect amplifier. |
| `potion-effects` | unset | Map of custom effects with optional potion, duration, and amplifier. |
### Example
```yaml
type: launch_projectile
source: SOURCE
entity-type: SPLASH_POTION
speed: 1.3
count: 3
spread-degrees: 12
inherit-powers: true
potion-effects:
poison:
potion: POISON
duration: 100
amplifier: 0
```
### Behavior and limits
* A living same-world target is aimed at; otherwise shooter look direction is used.
* Non-projectile spawn results are removed and shulker bullets receive the current target.
* `inherit-powers` captures owner, bow, consumable, hand, force, and exact inherited power IDs for continuation.
***
## `shulker_bullet`
**Purpose:** Compatibility alias of `launch_projectile`.
**Context:** Uses the same shooter selection, aim target, and fields as `launch_projectile`.
### Fields
| Field | Default | Description |
| --------------------- | ------- | -------------------------------------------------------------------- |
| `entity-type` | `ARROW` | Normally set to `SHULKER_BULLET`. |
| `speed` | `1.5` | Launch speed. |
| `extra-y` | `0` | Additional Y component. |
| `count` | `1` | Projectile count, minimum 1. |
| `spread-degrees` | `0` | Maximum fan angle; projectiles are evenly distributed. |
| `spawn-offset` | `0` | Forward offset from shooter eye. |
| `damage` | unset | Ability-damage override stored on projectile. |
| `inherit-powers` | `false` | Track projectile for projectile-tick/hit continuation. |
| `fireball-yield` | `1.0` | Yield for explosive projectiles. |
| `fireball-incendiary` | `true` | Incendiary flag for fireballs. |
| `potion-type` | unset | Base potion type for thrown potions. |
| `potion` | unset | Single custom effect when `potion-effects` is absent. |
| `duration` | `100` | Single custom-effect duration. |
| `amplifier` | `0` | Single custom-effect amplifier. |
| `potion-effects` | unset | Map of custom effects with optional potion, duration, and amplifier. |
### Example
```yaml
type: shulker_bullet
entity-type: SHULKER_BULLET
target: SOURCE
speed: 1.2
```
### Behavior and limits
* The spawned shulker bullet automatically targets the current context target when available.
* All other behavior matches this repository's `launch_projectile` implementation.
***
## `reflect_projectile`
**Purpose:** Redirects the projectile from the current context back toward its attacker.
**Context:** `target` defaults to `SKILL` and must resolve to a projectile. `shooter` defaults to the power-owning mob (`OWNER`).
### Fields
| Field | Default | Description |
| -------------------------- | ------- | ------------------------------------------------------------------------- |
| `target` | `SKILL` | Entity selector for the projectile to reflect. |
| `shooter` | `OWNER` | New projectile shooter; also accepts `SOURCE`, `SKILL`, or `TARGET`. |
| `velocity-multiplier` | `1.0` | Multiplier applied after reversing the incoming velocity. |
| `damage-multiplier` | `1.0` | Multiplier applied when the reflected projectile later deals damage. |
| `reflection-cooldown` | `0` | Per-owner reflection cooldown in seconds. |
| `minimum-velocity-squared` | `0.08` | Velocities below this squared length use the fallback direction. |
| `fallback-speed` | `0.95` | Speed used toward the original attacker for a near-stationary projectile. |
| `origin-distance` | `0.55` | Distance in front of the owner's eyes where the projectile is placed. |
| `abilities` | unset | Nested abilities executed only after a successful reflection. |
### Example
```yaml
type: reflect_projectile
target: SKILL
shooter: OWNER
random: 0.3
reflection-cooldown: 1.5
velocity-multiplier: 0.8
damage-multiplier: 0.65
abilities:
effect:
type: sound
sound: ITEM_SHIELD_BLOCK
```
### Behavior and limits
* The current hit event is cancelled after reflection succeeds.
* Arrows are replaced with fresh reflected copies so their completed-impact state cannot make them fall; other projectile types are redirected in place.
* Entity type and payload data are preserved while ownership, position, velocity, and damage are updated.
* Existing projectile tracking is stopped so abilities belonging to the original shooter do not continue.
* A reflected projectile is marked and cannot be reflected by this ability again.
* Use nested standard `particle` and `sound` abilities for successful-reflection effects.
***
## `ricochet_projectile`
**Purpose:** Replaces an arrow that hits a block with a reflected copy moving away from the impacted face.
**Context:** Requires a block `ProjectileHitEvent` and an `AbstractArrow` in `SKILL`.
### Fields
| Field | Default | Description |
| ------------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `maximum-ricochets` | `1` | Maximum bounces for one arrow, clamped to `0..12`. |
| `speed-bonus-per-ricochet` | `0.1` | Fractional speed increase applied on every bounce. |
| `damage-bonus-per-ricochet` | `0` | Flat damage accumulated on every bounce. |
| `minimum-velocity-squared` | `0.09` | Minimum incoming squared speed required to bounce. |
| `minimum-live-velocity-squared` | `0.0004` | Below this value, the arrow's facing direction is used. |
| `minimum-post-ricochet-speed` | `0.45` | Minimum speed before applying the speed bonus. |
| `maximum-post-ricochet-speed` | `1.5` | Maximum final speed after applying the speed bonus. |
| `maximum-ricochet-distance` | `24` | Maximum cumulative flight distance after each bounce; non-positive disables the limit. |
| `surface-offset` | `0.22` | Distance away from the impacted block face. |
| `direction-offset` | `0.14` | Additional distance along the reflected direction. |
| `abilities` | unset | Nested abilities executed after a successful bounce. |
### Example
```yaml
type: ricochet_projectile
maximum-ricochets: 2
speed-bonus-per-ricochet: 0.1
damage-bonus-per-ricochet: 1.0
abilities:
spark:
type: particle
particle: ELECTRIC_SPARK
count: 8
```
### Behavior and limits
* Arrow, spectral-arrow, potion, persistent-data, and scoreboard-tag state is copied to the replacement.
* Existing projectile tracking and its exact power IDs continue after the bounce.
* Nested standard `particle` and `sound` abilities provide bounce effects.
* Entity hits do not ricochet.
***
## `homing_projectile`
**Purpose:** Steers the current projectile toward a locked or newly selected living target.
**Context:** Requires `SKILL` to be a valid projectile; normally used on a projectile-tick trigger.
### Fields
| Field | Default | Description |
| ----------------------- | ------- | ------------------------------------------------- |
| `radius` | `16` | Maximum target search/lock radius. |
| `strength` | `0.2` | Steering blend, clamped `0.01..1`. |
| `require-line-of-sight` | `false` | Require line of sight. |
| `max-angle` | `360` | Maximum cone half-angle around current heading. |
| `lead` | `0` | Target-motion prediction factor. |
| `max-ticks` | `100` | Maximum executions; non-positive disables expiry. |
| `remove-on-expire` | `true` | Remove projectile when expired. |
| `disable-gravity` | `false` | Disable gravity while homing. |
### Example
```yaml
type: homing_projectile
radius: 24
strength: 0.18
max-angle: 90
lead: 0.5
max-ticks: 120
```
### Behavior and limits
* The projectile retains its previous valid target and rescans only when needed.
* Creative and spectator players are ignored.
* Target priority is existing lock, source mob target, then best nearby candidate.
* Expiry returns a cancellation request so projectile tracking can stop.
***
# Inventory and Equipment 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](/configs/info-of-abilities) page.
## Registry keys on this page
* `consume_food`
* `enhance_equipment`
* `enhance_helditem`
* `replace_item`
* `disarm`
* `shuffle_inventory`
***
## `consume_food`
**Purpose:** Consumes player saturation and/or food, including fractional food accumulation.
**Context:** Default `target`: `TARGET`; selected entity must be a player.
### Fields
| Field | Default | Description |
| ------------------- | ------- | ------------------------------------------------------ |
| `amount` | `0.25` | Combined amount; supports `{food}` and `{saturation}`. |
| `saturation-first` | `true` | Consume saturation before food in combined mode. |
| `saturation-amount` | unset | Explicit saturation consumption. |
| `food-amount` | unset | Explicit food consumption. |
### Example
```yaml
type: consume_food
target: TARGET
amount: 1.5
saturation-first: true
```
### Behavior and limits
* Fractional food consumption is stored per player until it reaches a whole point.
* When either explicit amount exists, explicit mode controls actual reductions.
***
## `enhance_equipment`
**Purpose:** Replaces selected armor pieces with newly created armor and random compatible enchantments.
**Context:** Default `target`: `SOURCE`; requires a living entity with equipment.
### Fields
| Field | Default | Description |
| ---------------------- | -------------- | -------------------------------------------------------- |
| `armor-material` | `NETHERITE` | Material prefix combined with armor piece names. |
| `pieces` | all armor | List of `HELMET`, `CHESTPLATE`, `LEGGINGS`, and `BOOTS`. |
| `enchant.min-amount` | `1` | Minimum distinct enchantments. |
| `enchant.max-amount` | `3` | Maximum distinct enchantments. |
| `enchant.min-level` | `1` | Minimum level. |
| `enchant.max-level` | `4` | Maximum level, capped by enchantment max. |
| `enchant.enchantments` | all compatible | Optional allow-list of Bukkit enchantments. |
### Example
```yaml
type: enhance_equipment
target: SOURCE
armor-material: DIAMOND
pieces:
- HELMET
- CHESTPLATE
enchant:
min-amount: 1
max-amount: 2
min-level: 1
max-level: 3
enchantments:
- PROTECTION
- UNBREAKING
```
### Behavior and limits
* Existing selected equipment is replaced.
* Non-player equipment drop chances for replaced pieces are set to zero.
***
## `enhance_helditem`
**Purpose:** Adds random compatible enchantments to a held item.
**Context:** Default `target`: `SOURCE`; requires a living entity with equipment and a non-air hand item.
### Fields
| Field | Default | Description |
| -------------------- | ----------- | --------------------------------------------- |
| `hand` | `MAIN_HAND` | `MAIN_HAND` or `OFF_HAND`. |
| `enchant.min-amount` | `1` | Minimum distinct enchantments. |
| `enchant.max-amount` | `3` | Maximum distinct enchantments. |
| `enchant.min-level` | `1` | Minimum level. |
| `enchant.max-level` | `4` | Maximum level, capped by enchantment maximum. |
### Example
```yaml
type: enhance_helditem
target: SOURCE
hand: MAIN_HAND
enchant:
min-amount: 1
max-amount: 3
min-level: 1
max-level: 4
```
### Behavior and limits
* Compatible enchantments are selected without duplicates.
* For non-player equipment, both hand drop chances are set to zero.
***
## `replace_item`
**Purpose:** Builds an item from nested ItemFormat and places it in an equipment slot.
**Context:** Default `target`: `SOURCE`; requires a living entity with equipment.
### Fields
| Field | Default | Description |
| ------ | ----------- | ------------------------------------------------------------------------ |
| `slot` | `MAIN_HAND` | `MAIN_HAND`, `OFF_HAND`, `HELMET`, `CHESTPLATE`, `LEGGINGS`, or `BOOTS`. |
| `item` | required | Nested ItemFormat used to build the replacement. |
### Example
```yaml
type: replace_item
target: SOURCE
slot: MAIN_HAND
item:
material: DIAMOND_SWORD
name: 'Elite Blade'
```
### Behavior and limits
* Non-player drop chance for the replaced slot is set to zero.
* Unsupported slot values do not change equipment.
***
## `disarm`
**Purpose:** Removes a matched main-hand or off-hand item and optionally drops it.
**Context:** Default `target`: `TARGET`; requires a living entity.
### Fields
| Field | Default | Description |
| -------------- | ----------- | ------------------------------------------ |
| `slot` | `MAIN_HAND` | `MAIN_HAND` or `OFF_HAND`. |
| `match-item` | match all | Optional Match Item rules. |
| `drop` | `true` | For player targets, drop the removed item. |
| `pickup-delay` | `20` | Pickup delay for the dropped item. |
### Example
```yaml
type: disarm
target: TARGET
slot: MAIN_HAND
drop: true
pickup-delay: 40
match-item:
material:
- SHIELD
- BOW
```
### Behavior and limits
* For non-player targets the item is removed but not dropped.
* Dropped player items are marked for the plugin's optional automatic-return behavior.
***
## `shuffle_inventory`
**Purpose:** Randomly permutes occupied player inventory slots inside a configured range.
**Context:** Default `target`: `TARGET`; selected entity must be a player.
### Fields
| Field | Default | Description |
| ------------ | ------- | ---------------------------------------- |
| `start-slot` | `0` | First player-inventory index, minimum 0. |
| `end-slot` | `35` | Last index, capped by inventory size. |
### Example
```yaml
type: shuffle_inventory
target: TARGET
start-slot: 0
end-slot: 35
```
### Behavior and limits
* Only occupied slots participate, so empty slots stay empty.
* Fewer than two occupied slots produces no change.
***
# 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](/configs/info-of-abilities) 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..conditions` | empty | AND condition group. |
| `cases..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..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.
***
# Integration and Targeting 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](/configs/info-of-abilities) page.
## Registry keys on this page
* `nearby_entities`
* `summon`
* `mythic_skill`
* `send_message`
* `execute_command`
***
## `nearby_entities`
**Purpose:** Finds nearby entities and runs children with each accepted entity as the new `TARGET`.
**Context:** Default base `target`: `SOURCE`; falls back to resolved location when the entity is unavailable.
### Fields
| Field | Default | Description |
| -------------------------------- | --------- | --------------------------------------------------------------------------------------- |
| `radius` | `5` | Default radius for all axes. |
| `radius-x / radius-y / radius-z` | `radius` | Per-axis radii. |
| `max-targets` | `0` | Maximum accepted entities; zero means unlimited. |
| `include-source` | `false` | Allow original source. |
| `exclude-target` | `false` | Exclude the original context target from the candidates. |
| `include-items` | `false` | Allow dropped items. |
| `include-non-living` | `false` | Allow other non-living entities. |
| `include-living` | `true` | Allow living entities. |
| `include-armor-stands` | `false` | Allow armor stands when living entities are enabled. |
| `direction-source` | `SOURCE` | Entity whose facing direction is used by `max-angle`. |
| `max-angle` | unset | Maximum cone half-angle in degrees; unset disables cone filtering. |
| `match-entity` | match all | Match Entity rules for living candidates. |
| `abilities` | required | Nested abilities. |
| `after-abilities` | unset | Abilities run once after at least one candidate is accepted. Receives `{target_count}`. |
### Example
```yaml
type: nearby_entities
target: SOURCE
radius: 8
max-targets: 3
include-source: false
exclude-target: true
max-angle: 45
match-entity:
entity-types:
- PLAYER
abilities:
damage:
type: damage_entity
amount: 4
after-abilities:
feedback:
type: send_message
message: 'Hit {target_count} nearby targets.'
```
### Behavior and limits
* Candidates are ordered nearest-first.
* Child context location is updated to each selected target.
* `max-angle` is a half-angle: `45` accepts a 90-degree frontal cone.
* `after-abilities` runs only when at least one candidate was accepted and keeps the original target context.
***
## `summon`
**Purpose:** Spawns one living Bukkit entity and optionally assigns EnchantedMobs powers.
**Context:** Spawn location uses the resolved ability location.
### Fields
| Field | Default | Description |
| ----------------------------------------------- | ------------- | ------------------------------------------------------------------------- |
| `entity` | empty | Single Bukkit entity type. |
| `entity-type` | empty | Alias for `entity`. |
| `entities` | empty | Equal-probability entity list; takes priority. |
| `max-health` | `-1` | Set maximum health when positive. |
| `health` | `-1` | Set current health when positive. |
| `attack-damage` | `-1` | Set attack-damage base when non-negative. |
| `set-target` | unset | Context entity selector assigned as target to spawned mobs. |
| `set-none-drops` | `false` | Clear loot table, disable pickup, and set equipment drop chances to zero. |
| `creeper.explosion-radius` | `-1` | Creeper radius. |
| `creeper.fuse-ticks` | `-1` | Creeper max fuse. |
| `creeper.powered` | unset | Creeper charged state. |
| `powers / power.list` | empty | Explicit power-ID list. |
| `power` | empty | One additional power ID. |
| `power-level / power.level` | current level | Power level, minimum 1. |
| `random-power-by-level / power.random-by-level` | `false` | Generate random powers when no valid explicit power remains. |
### Example
```yaml
type: summon
entities:
- ZOMBIE
- SKELETON
set-target: TARGET
set-none-drops: true
max-health: 30
attack-damage: 6
power-level: '{level}'
powers:
- Hasty
```
### Behavior and limits
* The selected type must be spawnable and produce a living entity.
* Valid explicit power IDs take priority over random generation.
***
## `mythic_skill`
**Purpose:** Casts one or more MythicMobs skills.
**Context:** Caster is `SOURCE`; default `target`: `TARGET` and must exist.
### Fields
| Field | Default | Description |
| -------- | ------- | ----------------------------------------- |
| `skill` | empty | Single skill used when `skills` is empty. |
| `skills` | empty | Ordered skill-name list. |
| `power` | `1.0` | MythicMobs skill power multiplier. |
### Example
```yaml
type: mythic_skill
target: TARGET
skills:
- Fireball
- GroundSlash
power: 1.5
```
### Behavior and limits
* Requires MythicMobs.
* Target entity and resolved location are supplied to the integration.
***
## `send_message`
**Purpose:** Sends one or more formatted messages to the source mob's current player target or nearby players.
**Context:** Target-player mode resolves the current player target of mob `SOURCE`; nearby mode searches around `SOURCE`.
### Fields
| Field | Default | Description |
| -------------- | --------------- | --------------------------------------------------------------------------------------------------------- |
| `mode` | `target-player` | `target-player` or `nearby`. |
| `radius` | `16` | Nearby-player radius. |
| `message` | empty | Single message when `messages` is empty. |
| `messages` | empty | Message list. |
| `placeholders` | empty | Custom message-placeholder map. Values resolve context variables and are evaluated as math when possible. |
### Example
```yaml
type: send_message
mode: nearby
radius: 12
messages:
- 'The elite mob is enraged!'
- 'Target: {target}'
placeholders:
scaled_amount: '{original_damage} * 0.5'
```
### Behavior and limits
* Recipient-aware parsing supports `{player}`, `{target}`, power variables, runtime placeholders, language parsing, and PlaceholderAPI.
* Placeholder keys can be used as `{key}` in `message` or `messages`. Numeric expressions are evaluated automatically and insignificant trailing zeroes are removed.
* Offline or dead players are skipped.
***
## `execute_command`
**Purpose:** Runs commands for the source mob's current player target or nearby players.
**Context:** Target-player mode resolves the current player target of mob `SOURCE`; nearby mode searches around `SOURCE`.
### Fields
| Field | Default | Description |
| ------------ | --------------- | --------------------------------------------------------------- |
| `mode` | `target-player` | `target-player` or `nearby`. |
| `radius` | `16` | Nearby-player search radius. |
| `as-console` | `true` | Run as console; false makes each recipient execute the command. |
| `command` | empty | Single command used when `commands` is empty. |
| `commands` | empty | Command list. |
### Example
```yaml
type: execute_command
mode: target-player
as-console: true
commands:
- 'effect give {player} minecraft:slowness 5 1'
```
### Behavior and limits
* A leading slash is removed.
* Commands execute once per selected online, living player and support player/target/context placeholders.
***
# Block and World 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](/configs/info-of-abilities) page.
## Registry keys on this page
This repository does not register an ability in this category.
# Advanced Language Management
## Default Language
You can set default language at `config.yml` file.
```yaml
config-files:
language: en_US
# Premium version only.
per-player-language: true
```
The input here is the name of the language file (without the suffix). All language files are stored in the "`languages`" folder. You can also create a new language file by simply copying the "`en_US.yml`" file and renaming it to the corresponding language code. For example, `zh_CN.yml`.
## Per Player Language
You can enable `per-player-language` at `config.yml` file. After being enabled, the plugin will determine which language file to display to the player based on their client language. The server must have the relevant language files preloaded; otherwise, it will display content using the default language file.
Let us watch this video to understand it!
## Lang Placeholder
You can use `{lang:}` placeholder in plugin message to enable players from all over the world to display language settings that match their client.
You can add your desired custom language text under the "`override-lang`" section of each language file, in the format of "`ID: text content`". For example:
```yaml
// ... The content originally present in the language file
# Added content
override-lang:
# This means shop-title it's language key.
shop-title: 'Item Shop'
```
```yaml
// ... The content originally present in the language file
# Added content
override-lang:
# This means shop-title it's language key.
shop-title: '物品商店'
```
Then use `{lang:shop-title}` in the place you want to use.
In `config.yml`, you can directly use `{lang}` to represent the custom language from the language file to be used. The language ID should be synchronized with the configuration file structure in the `config.yml` file, for example:
In `config.yml` file:
```yaml
placeholder:
# Premium version only
compare:
up: '{lang}'
down: '{lang}'
same: '{lang}'
```
In each language file:
```yaml
// ... The content originally present in the language file
override-lang:
placeholder:
compare:
up: '↑'
down: '↓'
same: '-'
```
Similarly, if we cannot find this custom language in the corresponding language file, we will search for it in the default language file. If it is still not found, then the plugin will not parse this placeholder.
## Advanced Message Format
The default language text is directly filled into the text content that needs to be output, along with [color codes](https://ultimateshop.superiormc.cn/features/color-code). However, you can also utilize this feature to enable the plugin to display not only regular chat box messages, but also actionbars, titles, bossbars, sounds, and more!
You can still use color codes (including MiniMessage) while using our advanced message format.
#### Common Usage
```yaml
welcome: 'Welcome to the server!'
```
#### Chat Message
```yaml
welcome: '[message]&aWelcome![/message]'
```
#### Title
welcome: '[title=20,60,20]&6Welcome;;&eThis is sub title[/title]'
# Format: [title=fadeIn,Stay,fadeOut]title;;subTitle[/title]
#### Both Chat Message and Title will be sent
You can mix and match these different message types, just like this.
```yaml
welcome: '[message]&aGood day![/message][title=20,60,20]&6Welcome;;&eThis is sub title[/title]'
```
#### Action Bar
```yaml
welcome: '[actionbar]&7Please wait...[/actionbar]'
```
#### Boss Bar - Early Alpha
```yaml
welcome: '[bossbar=GREEN,SOLID,1.0]&aHappy Today[/bossbar]'
```
#### Sound
```yaml
welcome: '[sound=ENTITY_EXPERIENCE_ORB_PICKUP,1,1][/sound][sound=ENTITY_PLAYER_LEVELUP,1,1][/sound]'
```
# Color Code
## Hex Color
To use hex color, you should use special color code, it should like this:
**\&#Hex color code**
For example, \&#ff0000.
## Gradient Color
To use gradient color, you should use special gradient color code, it should like this:
**&<#Start Color Code> Message &<#End Color Code>**
For example, &<#666666>UltimateShop &<#ffffff>
# Saved Item (Item Manager)
## Create your item
You can create your own item at `items` folder of plugin, just create a **yml** file and then follow [ItemFormat](https://ultimateshop.superiormc.cn/format/itemformat-tm) in this file. The file name is the item ID.
## Save your item
You can use command `/em saveitem ` command to save your hold item. There are 2 methods to save item.
* Bukkit
* If you are using Spigot version of UltimateShop: Use BukkitAPI's method to save item. The method only support saving vanilla data and persistent data stored through BukkitAPI, and other custom NBT data from other plugins will not be saved.
* If you are using Paper version of UltimateShop: Use PaperAPI's method to save item, this new method can 100% save item data, no data will lose. **(Paper and 1.15+ server only)**
* ItemFormat: will parse item into [Item Format](https://ultimateshop.superiormc.cn/format/itemformat-tm).
An example for item config file that use Bukkit save item method with Paper version of MythicChanger:
```yaml
item: !!binary |-
H4sIAAAAAAAA/21RzW4TMRCeJd0oWVB/1IIQXILEG/TGpSDxCKhXa2LPbkxsz8qepUlPPAonXoBn6nsw27TaViBZljzz/XmmAZjBy68oeE25eE4Ap3cLeOEdnEWfyGZs5ZPzGDm5GdSWhyQAMG+gsRx7TpSkNHA8gVtmRS7TINnLvSLUNTQFZcg4Fj7/Aqjg2GIyGG5wXwyhVJrj7SQScWeKoN2a4m9pNFw+9QicqdFqtRgj6QuOuoz7BRwJ7QQuvm18WenJhCHsV8lb+qCeHycFSnaDSaLGN13wevMPytk7qhp4819cmT2diVacT90YAhp4PTXsUISjSRhpSrcOAz2me/Vl1emMVuWGs1Pu+3+4kR0F43QrS5i3gVFKPRpd/dR7Ae8mwvdhS2vemT7gHteB4HzqsWzGnTp6th5hDjM4dRixI9NTNuvAdnvY0oWjFocgRvH6OVN6Inf1u22XUOchUHkY+vyeU+Bk0tXgiSo4s5wzWTEtZ+My96WqoT7o/Lm8VDr8BZMVpHJ0AgAA
```
An example for item config file that use ItemFormat save item method with Paper version of MythicChanger:
```yaml
material: DIAMOND
amount: 6
name: A good sword
lore:
- This is really nice!
custom-model-data: 1
max-stack: 6
food:
nutrition: 5
saturation: 5.0
tool:
damage-per-block: 5
mining-speed: 1.3
rules:
- STONE, 1.4, true
song: minecraft:otherside
glow: true
enchants:
mending: 1
```
## Match Save Item
Use `item-format` match rule and set `material` option in ItemFormat to the save item ID.
You can use saved item in [ItemFormat](https://ultimateshop.superiormc.cn/format/itemformat-tm). In ItemFormat, there is a option called `material`, by default, you need type vanilla item ID there, but, you can also use saved item id to let plugin directly get the saved item instead of generate a whole new item with that type.
```yaml
display-item:
material: superior_sword # If saved item id is 'superior_sword'
```
Saved items will be cached in memory continuously after loading to avoid repeatedly reading the saved item file, which may consume too much server performance. However, the cost is that if you have too many saved items, it may correspondingly consume more memory.
# Developer API
EnchantedMobs 2.0.0 exposes registries for custom abilities, conditions, modifiers, and triggers. Register extensions after EnchantedMobs has enabled.
## Maven dependency
```xml
repo-lanink-cn
https://repo.lanink.cn/repository/maven-public/
cn.superiormc.enchantedmobs
plugin
2.0.0
provided
```
Add a hard dependency when your plugin requires the API:
```yaml
depend:
- EnchantedMobs
```
## Registry keys
Ability, condition, and modifier keys are normalized by:
* converting to lowercase;
* replacing `-` with `_`.
`My-Ability` and `my_ability` therefore refer to the same key. Registering a duplicate normalized key throws `IllegalArgumentException`; built-ins are not silently replaced.
## Custom ability
Register a factory during `onEnable`:
```java
@Override
public void onEnable() {
AbilityManager.abilityManager.register("launch_ring", LaunchRingAbility::new);
}
```
```java
public final class LaunchRingAbility extends AbstractAbility {
public LaunchRingAbility(ConfigurationSection section) {
super("launch_ring", section);
}
@Override
public boolean execute(PowerContext context) {
Entity target = getTargetEntity(context);
if (target == null) {
return false;
}
double strength = getDouble("strength", 1.0, context);
Vector velocity = target.getVelocity();
velocity.setY(strength);
target.setVelocity(velocity);
return false;
}
@Override
public TargetEntityType getDefaultTargetEntityType() {
return TargetEntityType.TARGET;
}
}
```
Returning `true` requests cancellation of a cancellable trigger event. Most effect abilities return `false`.
The base class applies common typed `conditions`, `random`, `cooldown`, `times`, dynamic values, entity selectors, and location offsets.
```yaml
abilities:
launch:
type: launch_ring
target: TARGET
strength: 1.4
```
## Custom condition
```java
PowerConditionsManager.powerConditions.register(new PowerConditionIsNamed());
```
```java
public final class PowerConditionIsNamed extends AbstractPowerCondition {
public PowerConditionIsNamed() {
super("is_named");
}
@Override
protected boolean onMatch(ObjectSingleCondition condition) {
PowerContext context = condition.getContext();
if (context == null) {
return false;
}
LivingEntity target = context.livingEntity(
condition.getString("target", "TARGET"),
EntitySelector.TARGET
);
return target != null && target.getCustomName() != null;
}
}
```
The base implementation applies the common `not: true` inversion after `onMatch` returns.
```yaml
conditions:
named-target:
type: is_named
target: TARGET
```
## Custom modifier
```java
PowerModifiersManager.powerModifiers.register(
"minimum_damage",
MinimumDamageModifier::new
);
```
```java
public final class MinimumDamageModifier extends AbstractPowerModifier {
public MinimumDamageModifier(ConfigurationSection section) {
super("minimum_damage", section);
}
@Override
protected void onApply(PowerContext context) {
double current = context.result().damage(context.triggerData());
double minimum = getDouble(
"value",
1.0,
context,
"original",
String.valueOf(current)
);
context.result().damage(Math.max(current, minimum));
}
}
```
The modifier base class evaluates typed `conditions`, `random`, and per-path `cooldown` before `onApply`.
## Manual trigger
A manual trigger lets another plugin expose a custom power section without adapting a Bukkit event.
```java
public final class MyPlugin extends JavaPlugin {
private ManualTrigger ragePulse;
@Override
public void onEnable() {
TriggerManager manager = EnchantedMobs.instance.getTriggerManager();
ragePulse = manager.register(this, "rage_pulse");
}
public TriggerResult fireRagePulse(
LivingEntity owner,
LivingEntity target
) {
TriggerData data = TriggerData.builder(owner)
.source(owner)
.skill(owner)
.target(target)
.location(target.getLocation())
.build();
return EnchantedMobs.instance
.getTriggerManager()
.fire(ragePulse, data);
}
@Override
public void onDisable() {
EnchantedMobs.instance
.getTriggerManager()
.unregisterAll(this);
}
}
```
The power section key is the trigger's namespaced key. For a plugin named `MyPlugin`:
```yaml
'myplugin:rage_pulse':
conditions:
close-enough:
type: distance
max: 12
abilities:
effect:
type: particle
particle: ANGRY_VILLAGER
```
`TriggerData.builder(owner)` requires an owner. Source, skill, target, block, location, Bukkit event, tick number, and typed extra context values are optional.
`TriggerManager.fire` evaluates the owner's assigned powers, applies their final result, and returns a `TriggerResult` containing execution and cancellation state.
## Custom event-backed trigger
Advanced integrations may extend `AbstractTrigger`, provide a unique `NamespacedKey` and configuration key, declare supported `TriggerEventType` values, and register it with:
```java
EnchantedMobs.instance
.getTriggerManager()
.register(this, customTrigger);
```
The trigger manager dispatches registered triggers for their event types. Call `unregisterAll(plugin)` during disable to remove every trigger owned by that plugin.
## Lifecycle cleanup
Custom ability, modifier, and condition implementations may override:
```java
public void onUnload()
public void onEntityUnload(UUID entityId)
```
These hooks are intended for type-wide runtime cleanup during EnchantedMobs reload/unload and tracked entity removal. Do not make cleanup depend on one particular YAML section instance.
## Compatibility guidance
* Use scheduler-safe entity operations when supporting Folia.
* Store UUIDs instead of retaining unloaded entity objects.
* Validate that required context entities and result values exist for the trigger.
* Keep published type IDs stable because user YAML depends on them.
* Re-test integrations when the EnchantedMobs API version changes across a major release.
# 🎉Welcome
Welcome to **EnchantedMobs**, a plugin that pseudo-randomly adds terrifying new powers to naturally spawned mobs in your world.
You may have seen similar mechanics in other plugins or mods, but **EnchantedMobs** aims to provide a lightweight experience, including:
* Minimizing visual effects for powers whenever possible. We believe premium combat effects should come from a small number of high-impact bosses, because too many effects on too many mobs can seriously hurt server performance.
* Focusing only on monster powers. How players fight enhanced mobs is entirely up to you—add stronger enchantments, introduce RPG weapons, or even use custom guns, magic skills, and summoned companions.
* Relying on vanilla mechanics whenever possible to avoid compatibility conflicts with other plugins.
## Links
### Get the plugin
**SpigotMC:** [PREMIUM](https://www.spigotmc.org/resources/enchantedmobs-dynamic-mob-abilities-and-player-scaling-difficulty-1-21-3-26-1-1.133242/) (will post each update)
**Polymart:** [PREMIUM](https://voxel.shop/product/9464/enchantedmobs) (will post each update)
**BuiltByBit:** [PREMIUM](https://builtbybit.com/resources/enchantedmobs.97592/) (will post each update)
### Get support
* All users have an obligation to comply with our rules after joining the Discord server, which can be viewed in the rules channel. If you do not agree with our rules, you will not be able to receive our service support. Users who violate the rules will be punished according to the situation, including permanent ban.
* Every user is obligated to comply with our plugin terms of use. You can find these in the **LICENSE** file within the JAR file. We do not provide any assistance to users who fail to comply with the terms of use.
* Compared to users who have purchased the paid version, our service support priority for free users will be lower, with more requirements and restrictions. I have invested a lot of time and effort in developing plugins, but despite this, I have provided a free version and the complete plugin source code. I have not closed the source or restricted the number of user IP addresses used. Therefore, better service support is not free, and you should not ask me to provide good service for free. If you want your issue to be taken seriously, please consider purchasing a paid version to support plugin development.
* Support is only available at our [Discord](https://discord.gg/rzajeybhbw) server.
* 因 Discord 在中国大陆区域不可用，如果您在中国大陆购买了此插件，可以凭购买的账号平台、名称，在此QQ群享受售后服务：815351827。
# ✅Requirements
## Java Version
* Basic Requirement: **Java21+**
## Server Software
| Server | Can work in your server | Can get offical support |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Spigot | ✅
Some features does not provide in Spigot servers
| ✅ |
| Paper/Purpur | ✅
Can provide subtle performance improvements.
| ✅ |
| Folia | ❓
Any problems only occurs in Folia servers may not be solved. Plugin is not designed for multi thread support.
| ❓
Folia's support is in the early testing stage and may be released in official versions or removed in the future. This support is not a guarantee.
|
| Other softwares | ❌ | ❌ |
## Server Version
| Version | Can work in your server | Can get offical support |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **Below 1.21.3** | ❌ | ❌ |
| **1.21.3 and above** | ✅
Using versions 1.21.5 and above is the most recommended, as you can enjoy the best features.
| ✅ |
* If you encounter errors while using a certain version, please join our Discord feedback.
{% hint style="info" %}
This documentation is written for game version **1.21.11**. Some content may differ on lower versions.
{% endhint %}
# ⚙️Install
## Install
* Download the plugin from the official release site. The file name should be **EnchantedMobs-X.X.X.jar**, where X is the version number.
* Put the `.jar` file into your server's `plugins` folder.
* Stop your server and then restart it. Cannot load plugins in any other way while the server is starting.
* When updating plugins, please be sure to remove old versions.
* Previously, you used the free version, but now to upgrade to the paid version, you only need to install the paid version on the server and remove the free version. The configuration file of the plugin does not require any changes.
* When downgrading from **a new game version** to **an old version** on the server where the plugin is located, it is important to remove the `items` folder from the configuration file.
* Default configs are just helping you understand the config framework, you need modify them that meet your needs.
## Update
* When updating plugins, please be sure to remove old versions.
* You should always keep the plugin updated to the latest version.
* To prevent your custom config files from being overwritten or broken, the plugin does not auto-update existing configs. You can manually merge changes from new default configs, or regenerate fresh config files.
* Before every update, read the changelog carefully. If you skip multiple versions, review all changelogs in between. Major breaking changes will be noted there.
# 🔗Compatibility
This plugin mainly adds **direct compatibility** for some item plugins.
## **Direct compatibility**
### Directly supported item plugins list
You can use items from these plugins in [ItemFormat](https://ultimateshop.superiormc.cn/format/itemformat-tm).
* ItemsAdder
* Oraxen
* EcoItems
* EcoArmor
* MMOItems
* MythicMobs
* eco
* NeigeItems
* ExecutableItems
* Nexo
* CraftEngine
## NBTAPI: Extra Item Format option
For info about ItemFormat, please view UltimateShop wiki [here](https://ultimateshop.superiormc.cn/format/itemformat-tm).
The format of this option is:
```yaml
nbt:
:
:
```
Supported NBT Type:
* byte
* short
* int
* long
* float
* double
* string
For example:
```yaml
nbt:
string:
customNBT: 'Hello!'
int:
anotherNBTComponent.theNBTKey: 5
```
## PlaceholderAPI: Extra placeholders
w\.i.p.
# 🛠️Configuration files
The plugin generates the following configuration files, some of which will only be generated after you first use this feature.
* `items` folder: stores saved item files.
* `languages` folder: stores language message files.
These two folders are less critical. Focus on the following:
* `powers` folder: stores all created power files.
* `config.yml`: stores general plugin configuration.
* `player-power.yml`: stores how player strength is calculated.
## Config.yml file content
It is recommend that you view this file at GitHub, becuase Wiki's `config.yml` maybe not **latest**. Click [here](https://github.com/ManyouTeam/EnchantedMobs/blob/master/plugin/src/main/resources/config.yml) to view this file on **Github.**
```yaml
# EnchantedMobs by @PQguanfang
#
# Read the Wiki here: https://enchantedmobs.superiormc.cn
debug: false
debug-categories:
spawn: true
projectile: true
ability: true
# Require player has enchantedmobs.nodify permission to display.
display-spawn-message: false
optimize:
enabled-projectile-tick: true
enabled-entity-scanner-cache: true
config-files:
language: 'en_US'
# Premium version only.
per-player-language: true
force-parse-mini-message: true
debuild-item-method: 'LEGACY'
math:
enabled: true
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: []
# Ghost, Slime and Ender Dragon are disabled by default and can not being changed.
# All peaceful mobs are disabled by default and can not being changed.
disabled-entity:
entity-types:
- WARDEN
- WITHER
mob-display:
name:
format: '&6[{powers}] &f{mob}'
separator: ', '
max-show: 4
more: '...(+{count})'
bossbar:
min-powers: 2
keep-ticks: 20
radius: 16
color: 'RED'
style: 'SOLID'
title: '&c{entity} &7[{health}/{max-health}] &f{powers_full}'
mob-combat:
# If true, damage between monsters will be cancelled.
disable-powered-mob-friendly-fire: false
# If true, dropped item by disarm ability will auto return back to player inventory if they are going to removed.
disarm-auto-return-item: true
```
# ⌨️Commands & Permissions
Main command: `/enchantedmobs`\
Aliases: `/emobs`, `/em`
> All commands below are subcommands in this format: `/enchantedmobs ...`
### `reload`
* Reload plugin configs, language files, items, and power managers.
### `saveitem [bukkit|itemformat]` (player only)
* Save the item in your main hand under the specified ID.
* `bukkit` or default: save as Bukkit item data.
* `itemformat`: save as formatted item data.
### `givesaveitem [player] [amount]`
* Give a saved item to yourself or a specified player. Console usage must include player.
### `generateitemformat` (player only)
* Export the item in your main hand to `generated-item-format.yml`.
### `spawnmob [world x y z]`
* Spawn the specified entity with a custom power list and optional world/coordinates.
* Console usage requires coordinates.
### `spawnrandommob [world x y z]`
* Spawn the specified entity type and auto-roll random powers based on level.
* Players may omit coordinates to use current location; console must provide full coordinates.
### `power [player]`
* Check your own strength or the strength of a specified online player.
### `chunkpower` (player only)
* Check nearby average player strength (used as a spawn strength reference).
# ❓FAQ
### Reward/Drops/Block Totem Spawn
To ensure that the plugin is lightweight enough, it does not have built-in new rewards and drop mechanisms. However, you can achieve this through our [MythicRewards](https://www.spigotmc.org/resources/mythicrewards-boss-kill-reward-drop-plugin-with-custom-rule-support-1-20-5-1-21-11.129453/) plugin.\
In addition, if you are interested in using the block structure to summon EnchantedMobs and the Bonus Totem feature, you may want to check out our [MythicTotem](https://www.spigotmc.org/resources/mythictotem-custom-boss-spawn-totem-and-bonus-totem-all-in-1-1-20-5-1-21-11.102466/).
# 📝ItemFormat™
The **Item Format** provided by **EnchantedMobs** are almost identical to those in UltimateShop. Therefore, they will not be elaborated on in this wiki. Please refer to UltimateShop's wiki for a detailed introduction about them. Click [here](https://ultimateshop.superiormc.cn/format) to view.
# ➗Math Calculate Format
The **Math Calculate Format** provided by **EnchantedMobs** are almost identical to those in UltimateShop. Therefore, they will not be elaborated on in this wiki. Please refer to UltimateShop's wiki for a detailed introduction about them. Click [here](https://ultimateshop.superiormc.cn/format) to view.
# 🎮Mechanic
## Player Strength
Mob strength depends on player strength. The higher the player strength, the stronger generated mobs become. Player strength calculation is configured in `plugins/EnchantedMobs/player-power.yml`.
```yaml
formula: "({equipment_sum} / 4) + ({backpack_max} + {backpack_avg}) / 2"
incremental-slot-update: true
rules:
diamond-sword:
match-item:
material:
- DIAMOND_SWORD
add-weight: 10
netherite-armor:
match-item:
material-tag:
- minecraft:netherite_armor
add-weight: 12
```
Options:
* `formula`: Defines the strength formula. Supported variables:
* `{equipment_sum}`: Total strength value of equipment slots (helmet, chestplate, leggings, boots).
* `{backpack_max}`: Highest strength value among backpack items (excluding equipment slots).
* `{backpack_avg}`: Average strength value of backpack items (excluding equipment slots).
* `{backpack_sum}`: Total strength value of backpack items (excluding equipment slots).
* All PlaceholderAPI placeholders.
* `incremental-slot-update`: Defines how player strength updates. Modes:
* `true`: When a player joins, all item strength values are calculated once. After that, inventory changes update only affected slots by subtracting old item strength and adding new item strength.
* `false`: Recalculates full inventory strength each time on join and inventory changes.
* `true` has lower performance overhead in most cases. However, if your server has edge cases where slot updates are not detected, strength may become inaccurate and stay incorrect until the player rejoins.
* On Spigot, this feature may miss some inventory updates. Paper does not have this issue.
* `rules`: Defines item strength calculation rules. You can add more rules based on the example. Top-level keys such as `diamond_sword` and `netherite_armor` are rule IDs and must be unique. Each rule includes:
* `match-item`: Item matching rule using Match Item Format.
* `add-weight`: How much strength value is added when the rule matches.
* If one item matches multiple rules, values are accumulated.
* `placeholderapi-cache-ticks`: Final player power value cache for PlaceholderAPI results, in ticks. 0 = disable cache. Frequent requests for the value of PlaceholderAPI may cause severe performance issues, making it imperative to set up a cache in a timely manner.
Use `/es playerpower` to check your own strength, or `/es playerpower ` to check another player's strength.
If your server has **PlaceholderAPI**, you can display player strength with `%enchantedmobs_player_power%`.
## Mob Spawn
You can spawn **EnchantedMobs** in two ways:
* Command spawn: rarely used in most servers.
* Automatic spawn the plugin replaces newly spawning vanilla mobs with **EnchantedMobs**.
For automatic spawn:
* Players with `enchantedmobs.nodify` permission receive notifications when replacement occurs.
* Related config options are in `config.yml`:
```yaml
mob-power-generator:
enabled: true
ignore-custom-spawn: true
player-scan-range: 48
default-level: '25~100'
max-level: 400
spawn-chance: '35~70'
disabled-worlds: []
disabled-entity:
none: true
```
Options:
* `enabled`: Enable/disable this feature.
* `ignore-custom-spawn`: Ignore mobs spawned by other plugins. Some plugin-spawned mobs are indistinguishable from vanilla mobs, so this is not guaranteed to work for every plugin.
* `disabled-worlds`: Worlds where this feature is disabled. Format: `["world1", "world2"]`.
* `disabled-entity`: Match Entity Format. Matched entities will not be enhanced.
* `max-level`: Maximum generated mob level. Must be a fixed number.
When a mob attempts to spawn, the plugin checks whether enhancement is disabled by the above settings. If disabled, no enhancement is applied; otherwise enhancement starts.
Each enhanced mob has a level. Higher level mobs can receive more powers. The generated level depends on nearby players: if players are found in scan range, the average value is used; otherwise the `default-level` value is used. You can configure range with `player-scan-range`.
Not all mobs are enhanced. Use `spawn-chance` to control enhancement probability.
Both `default-level` and `spawn-chance` support random range format like the example (`A~B`), but do not support formulas or variables.
## Power Rolling
Each power config has an `apply-rules` section that defines how that power is selected. Example:
```yaml
apply-rules:
group: death
group-unique: true
weight: 5
conflicts:
- Flying
match-entity:
equip:
main-hand:
material:
- bow
- crossbow
- trident
level-weight: 15~25
```
Options:
* `group`: The group this power belongs to (`apply-rules.group`). Powers with the same group are in one pool. The plugin shuffles groups each cycle, then rolls one power per group from first to last. If rolling is not finished after one full pass, it starts another pass, and continues until all valid powers are exhausted or rolling ends.
* `group-unique`: If enabled, powers in this group can only be selected once and will not participate in later passes.
* `conflicts:` Other powers that conflict with this power will not be selected. (Added in 1.1.1)
* `weight`: Selection weight. Higher values are more likely to be selected.
* `match-entity`: Match Entity Format describing which entities can roll this power.
* `level-weight`: Each enhanced mob starts with a level budget. When a power is selected, this value is consumed from the budget. Selection ends when budget is fully consumed. Supports range format like `15~25`, variable `{level}`, and math expressions.
## Entity List Optimization
The plugin needs to detect which mobs are enhanced in real time, so it must frequently read entities existing on the server. This process is expensive, so the plugin provides an optimization mechanism: after first startup, it scans all server entities once until it finds the first enhanced mob. Then it caches the scan result and only updates the cache when new entities spawn or existing entities die.
However, on Spigot, entity spawn detection may be limited, and some enhanced mobs spawned by special methods might not be detected. This issue does not occur on Paper.
You can disable this feature in `config.yml`.
```yaml
optimize:
enabled-entity-scanner-cache: true
```
# 💥Mob Powers
All mob power configuration files are stored in `plugins/EnchantedMobs/powers`.
* The filename (without extension) is the power ID. Every ID must be unique.
* To create a new power, create a new file and paste a valid power config into it.
* Most changes require a plugin reload/restart. Some features require a full server restart.
* All power configs use YAML format.
### Dynamic Numeric Values
In power configs, almost all numeric fields support math expressions and the `{level}` variable (mob level).
You can also use range-based conditions like this:
```yaml
random:
">=15;;<23": 0.3
">=23": 0.6
```
This means:
* if level is `>= 15` and `< 23`, value is `0.3`
* if level is `>= 23`, value is `0.6`
### Example Power Config
```yaml
# Web Trap
# The projectile launched by a monster with this ability will generate a temporary spider web upon landing.
enabled: true
placeholder: '{lang:power.web_arrow}'
apply-rules:
group: ranged_projectile
group-unique: true
conflicts:
- Flying
weight: 5
match-entity:
equip:
main-hand:
material:
- bow
- crossbow
- trident
level-weight: 15~25
limit:
random:
">=15;;<23": 0.3
">=23": 0.6
cooldown:
">=15;;<22": 10
">=22": 5
no-attack-ticks: 100
on-projectile-hit:
abilities:
1:
type: delay
delay:
">=15;;<20": 20
">=20": -1
abilities:
1:
type: place_block
block: cobweb
duration: '{level} * 4'
2:
type: sound
sound: BLOCK_WOOL_PLACE
3:
type: particle
particle: BLOCK
count: 20
block: cobweb
4:
type: remove
on-shoot-bow:
abilities:
1:
type: mark
on-projectile-tick:
abilities:
1:
type: particle
particle: WHITE_ASH
count: 6
offset-x: 0.05
offset-y: 0.05
offset-z: 0.05
```
Key fields:
* `enabled`: Enable/disable this power.
* `placeholder`: Display name placeholder.
* `apply-rules`: Power selection rules (see [Mechanics](/docs/configs/ji-zhi)).
* `limit`: Execution limits for the power:
* `random`: chance to execute (`1.0` = 100%)
* `cooldown`: cooldown in seconds
* `times`: maximum execution count
* `no-attack-ticks`: has target but didn't attack target for a certain period of time (Added in 1.1.0)
* event sections starting with `on-...`: actions that run when the event triggers.
### Power Trigger Events
A power can run actions when specific events are triggered.
Most events expose these contexts:
* **Source entity**: who triggers the event
* **Skill entity**: intermediate entity used by the event (for example, projectile)
* **Target entity**: final target entity
* **Location**: where the event happens
Power effects themselves do not recursively trigger new power events.
| Event | Source | Skill | Target | Location |
| -------------------- | ------------------------------------------------------------- | ---------- | ------------------- | ----------------------- |
| `on-projectile-hit` | Shooter | Projectile | Hit entity (if any) | Hit location |
| `on-shoot-bow` | Shooter | Projectile | Projectile | Projectile location |
| `on-projectile-tick` | Shooter | Projectile | Projectile | Projectile location |
| `on-tick` | Self | Self | Self | Current entity location |
| `on-spawn` | Self | Self | Self | Current entity location |
| `on-combust` | Self | Self | Self | Current entity location |
| `on-damage` | Damager (if any) | Self | Self | Current entity location |
| `on-regain` | Self | Self | Self | Current entity location |
| `on-melee-attack` | Self | Self | Victim | Victim location |
| `on-death` | Self | Self | Self | Current entity location |
| `on-target` | Self | Self | Hate target | Target location |
| `on-target-tick` | Self | Self | Hate target | Target location |
| `on-untarget` | Self | Self | Self | Current entity location |
| `on-explode` | Self / Shooter (if explode entity is shooted by other entity) | Self | Self | Current entity location |
### Event Section Structure
Each event section can contain:
* `abilities`: actions to execute
* `modifier`: modify the event values
* `conditions`: conditions that must pass
### Event Modifiers
Not every event supports modifiers. Supported examples:
#### `on-shoot-bow`
```yaml
on-shoot-bow:
modifier:
projectile: TNT
fuse: 40
```
* `projectile`: new projectile type
* `fuse`: TNT fuse ticks
* `fireball-yield`: explosion yield for fireballs
* `fireball-incendiary`: whether fireball creates fire
Splash potion example:
```yaml
on-shoot-bow:
modifier:
projectile: SPLASH_POTION
potion-type: HARMING
potion-effects:
SLOW:
duration: "60 + {level} * 20"
amplifier: 1
POISON:
duration: 100
amplifier: 0
```
#### `on-combust`
```yaml
on-combust:
modifier:
duration: '60'
```
#### `on-damage`
```yaml
on-damage:
modifier:
damage: '{original} * (0.8 - {level} / 500)'
```
#### `on-regain`
```yaml
on-regain:
modifier:
amount: 15
```
#### `on-melee-attack`
```yaml
on-melee-attack:
modifier:
damage: '{original} * (1.2 + {level} / 50)'
```
#### `on-death` (Paper only)
```yaml
on-death:
modifier:
revive-health: '{original} / 2'
```
#### `on-explode`
```yaml
on-explode:
modifier:
yield: 5
```
### Conditions
Unless explicitly configured, conditions are considered unused.
#### Health conditions (most events except `on-death`)
```yaml
on-melee-attack:
conditions:
now-health:
compare: '>='
value: '{max-health} / 2'
max-health:
compare: '>='
value: 200
```
`compare` supports: `>`, `>=`, `<`, `<=`, `!=`, `=`.
#### `on-combust`
```yaml
on-combust:
conditions:
by-block: false
by-entity: false
min-duration: 5
max-duration: 10
```
#### `on-damage`
```yaml
on-damage:
conditions:
by-block: false
by-entity: false
min-damage: 5
max-damage: 10
match-damager: # Use Match Entity Format here.
entity-types:
- 'PLAYER'
damage-cause:
- 'BLOCK_EXPLOSION'
ignore-damage-cause:
- 'BLOCK_EXPLOSION'
```
Damage causes are listed on the [Damage Source](/docs/configs/bian-ji-guai-wu-neng-li/shang-hai-lai-yuan) page.
#### `on-regain`
```yaml
on-regain:
conditions:
min-amount: 0
max-amount: 5
```
#### `on-melee-attack`
```yaml
on-melee-attack:
conditions:
accept-source: false
min-amount: 0
max-amount: 20
```
#### `on-explode`
```yaml
on-explode:
conditions:
min-yield: 0
max-yield: 5
from-creeper: false
```
#### `on-tag/on-untag`
```yaml
on-tag: # OR on-untag
conditions:
reason:
- 'TARGET_DIED'
ignored-reason:
- 'NEARBY_PLAYER'
```
Possible reason:
```yaml
TARGET_DIED,
CLOSEST_PLAYER,
TARGET_ATTACKED_ENTITY,
@Deprecated
PIG_ZOMBIE_TARGET,
FORGOT_TARGET,
TARGET_ATTACKED_OWNER,
OWNER_ATTACKED_TARGET,
RANDOM_TARGET,
DEFEND_VILLAGE,
TARGET_ATTACKED_NEARBY_ENTITY,
REINFORCEMENT_TARGET,
COLLISION,
CUSTOM,
CLOSEST_ENTITY,
FOLLOW_LEADER,
TEMPT,
TARGET_OTHER_LEVEL,
TARGET_INVALID,
UNKNOWN
```
# Damage Source
#### Projectile Damage
**PROJECTILE**\
Damage caused by being hit by a projectile, such as:
* Arrows
* Fireballs
* Tridents
* Snowballs
***
#### Entity Attack Damage
**ENTITY\_ATTACK**\
Damage caused by a normal melee attack from an entity, such as:
* Player attacks
* Zombie attacks
* Skeleton melee attacks
**ENTITY\_SWEEP\_ATTACK**\
Damage caused by a sweep attack performed with a sword (player sweep attack).
**THORNS**\
Damage caused by the **Thorns enchantment** reflecting damage back to the attacker.
***
#### Magic and Status Damage
**MAGIC**\
Magic-based damage, such as:
* Instant Damage potions
* Certain magical attacks
**POISON**\
Damage over time caused by the **Poison** effect.
**WITHER**\
Damage over time caused by the **Wither** effect.
**DRAGON\_BREATH**\
Damage caused by the **Ender Dragon's breath attack**.
**SONIC\_BOOM**\
Damage caused by the **Warden's sonic boom attack**.
***
#### Survival Damage
**DROWNING**\
Damage caused by running out of air while underwater.
**STARVATION**\
Damage caused when the hunger bar reaches zero.
**FREEZE**\
Damage caused by freezing in **Powder Snow**.
**DRYOUT**\
Damage caused when aquatic creatures that require water dry out (e.g., fish).
**MELTING**\
Damage caused when **Snow Golems melt in hot environments**.
***
#### Special Damage
**LIGHTNING**\
Damage caused by being struck by lightning.
**VOID**\
Damage caused by falling into the **Void**.
**WORLD\_BORDER**\
Damage caused by being pushed by the **World Border**.
**KILL**\
Damage caused by the `/kill` command.
**SUICIDE**\
Damage caused when an entity kills itself.
**CUSTOM**\
Custom damage triggered by plugins or NMS.
# 📂Info of abilities
### Common Options
No matter which ability you use, the following options are supported:
* `type`: Required. Defines which action to run.
* `target`: Who the action applies to. Supported values:
* `SOURCE` (source entity)
* `SKILL` (skill carrier entity)
* `TARGET` (target entity)
* `random`: Execution chance. `1.0` means 100%.
* `cooldown`: Cooldown time in seconds.
* Powers also have `random` and `cooldown`. If power-level limits pass, actions begin to execute. Action-level `random`/`cooldown` are independent from power-level limits.
* Actions do not provide a `times` limit directly (unless wrapped in `Limit`).
* `location`: Offset from event location.
* `offset-x`
* `offset-y`
* `offset-z`
Example:
```yaml
on-target-tick:
abilities:
1:
type: arrow_rain
location:
offset-y: 5
target: TARGET
random: 0.5
cooldown: 5
```
# Mark
## Mark
Marks an entity as "already used this power" for internal logic (for example, anti-duplicate chains).
```yaml
type: mark
```
Default `target: SKILL`.
# Delay
## Delay
Delays execution, then runs child `abilities`.
```yaml
type: delay
ticks: 20
abilities:
1:
type: Sound
sound: ENTITY_ENDERMAN_SCREAM
```
#### Field Details
**ticks**
Delay in ticks (`20 ticks = 1 second`).
```yaml
ticks: 40
```
**delay**
Legacy alias of `ticks`; used only when `ticks` is not set.
```yaml
delay: 40
```
**abilities**
Child actions to execute after delay.
```yaml
abilities:
1:
type: particle
particle: FLAME
```
***
# Conditional (1.2.0+)
## Conditional
Executes the first matching ability branch.
Branches can check distance between `SOURCE` and `TARGET`, the target's potion effects, and a random chance. This is useful for configurable AI-like behavior such as choosing a potion by player distance.
```yaml
type: conditional
cases:
1:
min-distance: 8
target-has-potion: SLOWNESS
abilities:
1:
type: launch_projectile
entity-type: SPLASH_POTION
potion: POISON
2:
max-distance: 3
target-missing-potion: WEAKNESS
random: 0.25
match-entity:
entity-types:
- PLAYER
abilities:
1:
type: launch_projectile
entity-type: SPLASH_POTION
potion: WEAKNESS
default:
abilities:
1:
type: launch_projectile
entity-type: SPLASH_POTION
potion: INSTANT_DAMAGE
```
### **Field Details**
**cases**: Ordered branches. The first branch whose conditions match will execute.
**min-distance** and **max-distance**: Distance range between the source and target.
**distance**: Compare-style distance condition.
```yaml
distance:
compare: >=
value: 8
```
**match-entity**: Entity matcher for the condition target. Uses the same format as power `apply-rules.match-entity`.
**now-health** and **max-health**: Compare-style health conditions for the condition target.
**target-has-potion**: Requires the checked target to already have this potion effect. Can be a string or list.
**target-missing-potion**: Requires the checked target to not have this potion effect. Can be a string or list.
**condition-target**: Entity used for potion checks. Supports `SOURCE`, `TARGET`, and `SKILL`. Defaults to `TARGET`.
**random**: Optional branch chance from `0` to `1`.
**default**: Optional fallback branch when no case matches.
# Nearby Entities (1.2.0+)
## Nearby Entities
Executes nested abilities for entities near the selected base entity or location.
Each matched nearby entity becomes `TARGET` while the nested `abilities` are executed. This makes it possible to reuse existing abilities such as `potion_effect`, `set_health`, `sound`, and `particle` as area effects.
```yaml
type: nearby_entities
target: SOURCE
radius: 7
match-entity:
not:
entity-tag:
- monster
abilities:
1:
type: potion_effect
target: TARGET
potion: SLOWNESS
duration: 80
amplifier: 1
```
### **Field Details**
**target**: Base entity used as the center of the search.
Supported values are `SOURCE`, `TARGET`, and `SKILL`. Defaults to `SOURCE`.
```yaml
target: SOURCE
```
**radius**: Search radius on all axes.
```yaml
radius: 7
```
**radius-x**, **radius-y**, **radius-z**: Optional axis-specific search radius values.
```yaml
radius-x: 7
radius-y: 4
radius-z: 7
```
**match-entity**: Optional entity matcher used to filter nearby living entities.
It uses the same matcher format as power `apply-rules.match-entity`. The source entity is skipped automatically.
```yaml
match-entity:
entity-tag:
- monster
```
To affect non-monsters only:
```yaml
match-entity:
not:
entity-tag:
- monster
```
**abilities**: Nested abilities to execute on every matched nearby entity.
```yaml
abilities:
1:
type: potion_effect
target: TARGET
potion: SPEED
duration: 100
amplifier: 0
```
For repeated area effects, wrap `nearby_entities` inside `repeat`.
```yaml
type: repeat
duration: 100
interval: 20
abilities:
1:
type: nearby_entities
radius: 7
abilities:
1:
type: potion_effect
target: TARGET
potion: SLOWNESS
duration: 80
amplifier: 1
```
# Repeat (1.2.0+)
## Repeat
Executes nested abilities immediately, then repeats them for a configured duration.
Use this ability when an effect should keep running over time. For example, a death aura can use `repeat` outside `nearby_entities`.
```yaml
type: repeat
duration: 100
interval: 20
abilities:
1:
type: nearby_entities
radius: 7
abilities:
1:
type: potion_effect
target: TARGET
potion: SLOWNESS
duration: 80
amplifier: 1
```
### **Field Details**
**duration**: How long the nested abilities keep repeating, in ticks.
When omitted or set to `0`, the nested abilities run once immediately.
```yaml
duration: 100
```
**interval**: Repeat interval in ticks when `duration` is greater than `0`.
```yaml
interval: 20
```
**abilities**: Nested abilities to execute.
```yaml
abilities:
1:
type: sound
sound: ENTITY_WITHER_AMBIENT
```
# Place Block
## Place Block
Places a temporary block at action location, then restores the original block after time expires.
Temporary blocks do not drop items. On Spigot, some non-standard block-break methods may not be detected. Paper does not have this issue.
Avoid placing high-value blocks. If the server crashes and temporary-block state is not saved, those blocks may be treated as real blocks after restart and can be dropped.
```yaml
type: place_block
block: COBWEB
duration: 60
```
#### Field Details
**block**
Block material to place.
```yaml
block: POWDER_SNOW
```
**duration**
Duration in ticks.
```yaml
duration: 80
```
# Explosion
## Explosion
Creates an explosion at location, with optional fire and block damage control.
```yaml
type: explosion
yield: 2.0
set-fire: false
break-blocks: false
```
Default `target: TARGET`.
#### Field Details
**yield**
Explosion power (larger value = larger radius).
```yaml
yield: 4.0
```
**set-fire**
Whether the explosion ignites nearby blocks.
```yaml
set-fire: true
```
**break-blocks**
Whether the explosion breaks blocks.
```yaml
break-blocks: true
```
# Cancel Event
## Cance lEvent
Cancels the current trigger event.
`on-death` cannot be cancelled directly. If needed, use `on-death.modifier.revive-health` for similar behavior.
```yaml
type: cancel_event
```
Often used to "negate" one damage/behavior instance.
# Lighting
## Lightning
Strikes lightning at random positions near target, with optional extra damage.
```yaml
type: lightning
count: 2
radius: 3
damage: 4
```
Default `target: TARGET`.
#### Field Details
**count**
Number of lightning strikes.
```yaml
count: 5
```
**radius**
Random radius around target.
```yaml
radius: 6
```
**damage**
Additional damage dealt to hit entities.
```yaml
damage: 8
```
# Particle
## Particle
Plays particle effects at location.
```yaml
type: particle
particle: FLAME
count: 8
offset-x: 0.3
offset-y: 0.2
offset-z: 0.3
extra: 0
```
Default `target: TARGET`.
#### Basic Fields
**particle**: particle type.
```yaml
particle: SMOKE
```
**count**: amount per play.
```yaml
count: 30
```
**offset-x / offset-y / offset-z**: spread range.
```yaml
offset-x: 0.5
offset-y: 1.0
offset-z: 0.5
```
**extra**: extra particle parameter (often speed).
```yaml
extra: 0.01
```
#### Special Fields (particle-specific)
**block**: block data for block particles.
```yaml
particle: BLOCK
block: STONE
```
**item**: item data for item particles.
```yaml
particle: ITEM
item: DIAMOND
```
**color / size**: color-based particles (for example `DUST`).
```yaml
particle: DUST
color: "255,0,0"
size: 1
```
**from / to**: gradient color particles (for example `DUST_COLOR_TRANSITION`).
```yaml
from: "255,0,0"
to: "0,0,255"
```
**value / delay / duration**: vibration-related parameters.
```yaml
value: 1.0
delay: 20
duration: 40
```
# Sound
## Sound
Plays sound at location.
```yaml
type: sound
sound: ENTITY_PLAYER_LEVELUP
volume: 1
pitch: 1
```
#### Field Details
**sound**: Bukkit sound enum name.
```yaml
sound: ENTITY_ENDERMAN_TELEPORT
```
**volume**: sound volume.
```yaml
volume: 2
```
**pitch**: pitch multiplier.
```yaml
pitch: 0.8
```
# Set Attribute
## Set Attribute
Sets base value of an entity attribute.
```yaml
type: set_attribute
attribute: MAX_HEALTH
value: 40
```
Default `target: SOURCE`.
#### Field Details
**attribute**: attribute name to modify.
```yaml
attribute: MOVEMENT_SPEED
```
**value**: new value. Supports `{max}` (attribute max) and `{now}` (current attribute value).
```yaml
value: 0.4
```
# Set Health
## Set Health
Sets (or heals) target health, capped at max health.
Supports `{max-health}` and `{health}` variables.
```yaml
type: set_health
amount: 10
```
Default `target: SOURCE`.
#### Field Details
**amount**: resulting health value (supports formulas).
```yaml
amount: 20
```
# Pull Target (1.2.0+)
## Pull Target
Changes the target entity's velocity relative to the source entity.
This ability can pull a target toward the source, push it away, or randomly choose either direction.
```yaml
type: pull_target
target: TARGET
direction: RANDOM
speed: 0.75
vertical: 1.2
remove-powder-snow: true
```
### **Field Details**
**target**: Entity to move. Supports `SOURCE`, `TARGET`, and `SKILL`. Defaults to `TARGET`.
**direction**: Movement direction relative to the source. Supports `TOWARD`, `AWAY`, and `RANDOM`.
**speed**: Horizontal velocity strength. `strength` is still supported as a fallback.
**vertical**: Optional vertical velocity. When omitted, the legacy pull behavior is used.
**remove-powder-snow**: If true, removes powder snow at the target's current block before moving it. This does not remove cobwebs.
# Potion Cloud
## Potion Cloud
Creates an area effect cloud.
```yaml
type: potion_cloud
radius: 3
duration: 120
potion: POISON
potion-duration: 100
potion-amplifier: 1
accumulate: true
```
Default `target: TARGET`.
#### Field Details
**radius**: cloud radius.
```yaml
radius: 5
```
**duration**: cloud lifetime in ticks.
```yaml
duration: 200
```
**potion**: potion effect type.
```yaml
potion: SLOWNESS
```
**potion-duration**: applied effect duration in ticks.
```yaml
potion-duration: 60
```
**potion-amplifier**: effect amplifier (`0 = level I`, `1 = level II`).
```yaml
potion-amplifier: 2
```
**accumulate**: If true and the entity already has the same effect, the new duration is added to the existing remaining duration. The higher amplifier is kept. (Added in 1.2.0)
```yaml
accumulate: true
```
# Potion Effect
## Potion Effect
Applies potion effects directly to entity.
```yaml
type: potion_effect
potion: SLOWNESS
duration: 100
amplifier: 0
ambient: false
particles: true
icon: true
accumulate: true
```
Default `target: TARGET`.
#### Field Details
**potion**: potion type.
```yaml
potion: WEAKNESS
```
**duration**: ticks.
```yaml
duration: 200
```
**amplifier**: level amplifier (`0 = I`).
```yaml
amplifier: 1
```
**ambient**: ambient-style effect visuals.
```yaml
ambient: true
```
**particles**: show potion particles.
```yaml
particles: false
```
**icon**: show HUD icon.
```yaml
icon: false
```
**accumulate**: If true and the entity already has the same effect, the new duration is added to the existing remaining duration. The higher amplifier is kept. (Added in 1.2.0)
```yaml
accumulate: true
```
### RemovePotionEffect
Remove potion effects from entity.
```yaml
type: remove_potion_effect
potion: INVISIBILITY
```
Default `target: TARGET`.
#### Field Details
**potion**: potion type. Set to `ALL` means remove all potion from entity.
```yaml
potion: WEAKNESS
```
**potions:** If you has multi potion effect type to remove, you can use this format.
```yaml
potions:
- 'WEAKNESS'
- 'INVISIBILI'
```
# Freeze
## Freeze
Sets freeze ticks (powder-snow freezing behavior).
```yaml
type: freeze
freeze-ticks: 60
accumulate: true
```
Default `target: TARGET`.
#### Field Details
**freeze-ticks**: freeze duration in ticks.
```yaml
freeze-ticks: 120
```
**accumulate:** accumulate the freeze ticks. (Added in 1.2.0)
```yaml
accumulate: true
```
# Fire
## Fire
Sets target on fire.
```yaml
type: fire
fire-ticks: 60
accumulate: true
```
Default `target: TARGET`.
#### Field Details
**fire-ticks**: burn duration in ticks.
```yaml
fire-ticks: 100
```
**accumulate:** accumulate the freeze ticks. (Added in 1.2.0)
```yaml
accumulate: true
```
# Homing Projectile
## Homing Projectile
Makes skill entity (usually projectile) home toward nearby target.
```yaml
type: homing_projectile
radius: 16
strength: 0.2
max-ticks: 100
remove-on-expire: true
```
Default `target: SKILL`.
#### Field Details
**radius**: target search radius.
```yaml
radius: 24
```
**strength**: turning strength (higher = sharper turning).
```yaml
strength: 0.35
```
# Teleport Near Target
## Teleport Near Target
Teleports entity to a safe position near target.
```yaml
type: teleport_near_target
min-radius: 3
max-radius: 8
max-tries: 12
```
Default `target: TARGET`.
#### Field Details
**min-radius**: minimum distance from target.
```yaml
min-radius: 4
```
**max-radius**: maximum distance from target.
```yaml
max-radius: 10
```
**max-tries**: max attempts to find a safe location.
```yaml
max-tries: 20
```
# Guardian Beam
## Guardian Beam - Require packetevents
Simulates guardian beam lock-on, then deals damage after charge-up.
```yaml
type: guardian_beam
range: 18
charge-ticks: 30
damage: 6
```
Default `target: TARGET`.
#### Field Details
**range**: max lock distance.
```yaml
range: 24
```
**charge-ticks**: charge-up ticks.
```yaml
charge-ticks: 40
```
**damage**: damage after charging.
```yaml
damage: 10
```
# Vanilla Animation
## Vanilla Animation
Plays vanilla entity animation (`EntityEffect`).
```yaml
type: vanilla_animation
animation: HURT
```
Default `target: SOURCE`.
#### Field Details
**animation**: preferred animation field.
```yaml
animation: HURT
```
# Arrow Rain
## Arrow Rain
Spawns arrow rain above target area.
```yaml
type: arrow_rain
count: 10
radius: 4
height: 12
spread: 0.18
damage: -1
pierce-level: 0
critical: false
```
Default `target: TARGET`.
#### Field Details
**count**: number of arrows.
```yaml
count: 20
```
**radius**: rain area radius.
```yaml
radius: 6
```
**height**: spawn height.
```yaml
height: 16
```
**spread**: initial random velocity spread.
```yaml
spread: 0.3
```
**damage**: arrow damage; `< 0` keeps default damage.
```yaml
damage: 5
```
**pierce-level**: piercing level.
```yaml
pierce-level: 2
```
**critical**: whether arrows are critical.
```yaml
critical: true
```
# Enchance Equipmment
## Enhance Equipment
Enhances mob armor (material replacement / random enchants).
```yaml
type: enhance_equipment
armor-material: NETHERITE
pieces:
- HELMET
- CHESTPLATE
enchant:
min-amount: 1
max-amount: 3
min-level: 1
max-level: 4
enchantments:
- PROTECTION
```
Default `target: SOURCE`.
#### Field Details
**armor-material**: armor material prefix (`NETHERITE`, `DIAMOND`, etc.).
```yaml
armor-material: DIAMOND
```
**pieces**: armor pieces to modify.
```yaml
pieces:
- HELMET
- LEGGINGS
```
**enchant.min-amount**: minimum enchants per item.
```yaml
enchant:
min-amount: 1
```
**enchant.max-amount**: maximum enchants per item.
```yaml
enchant:
max-amount: 4
```
**enchant.min-level**: minimum enchant level.
```yaml
enchant:
min-level: 2
```
**enchant.max-level**: maximum enchant level.
```yaml
enchant:
max-level: 5
```
**enchant.enchantments**: enchant pool for random selection.
```yaml
enchant:
enchantments:
- PROTECTION
- THORNS
```
# Enchance Held Item
## Enhance Held Item
Enhances enchantments on main-hand/off-hand item.
```yaml
type: enhance_held_item
hand: MAIN_HAND
enchant:
min-amount: 1
max-amount: 3
min-level: 1
max-level: 4
```
Default `target: SOURCE`.
#### Field Details
**hand**: which hand to process.
```yaml
hand: OFF_HAND
```
**enchant.min-amount**: minimum enchant count.
```yaml
enchant:
min-amount: 1
```
**enchant.max-amount**: maximum enchant count.
```yaml
enchant:
max-amount: 3
```
**enchant.min-level**: minimum enchant level.
```yaml
enchant:
min-level: 1
```
**enchant.max-level**: maximum enchant level.
```yaml
enchant:
max-level: 4
```
# Replace Item
## Replace Item
Replaces item in a specific slot.
```yaml
type: replace_item
slot: MAIN_HAND
item:
material: DIAMOND_SWORD
```
Default `target: SOURCE`.
#### Field Details
**slot**: equipment slot to replace.
```yaml
slot: HELMET
```
**item**: item builder config (supports existing BuildItem format).
```yaml
item:
material: SHIELD
```
# Disarm
## Disarm
Disarms target hand slot, optionally dropping the item.
```yaml
type: disarm
slot: MAIN_HAND
drop: true
pickup-delay: 20
match-item:
material:
- diamond_sword
```
Default `target: TARGET`.
#### Field Details
**slot**: disarm slot (`MAIN_HAND` / `OFF_HAND`).
```yaml
slot: OFF_HAND
```
**drop**: whether removed item is dropped on ground.
```yaml
drop: false
```
**pickup-delay**: pickup delay in ticks.
```yaml
pickup-delay: 60
```
**match-item**: which item will active this ability. Use Match Item Format here.
```yaml
match-item:
material:
- diamond_sword
```
# Remove
## Remove
Removes target entity (players are not removed).
```yaml
type: remove
```
Default `target: SKILL`.
# Shuffle Inventory
## Shuffle Inventory
Randomly shuffles items in player inventory slot range.
```yaml
type: shuffle_inventory
start-slot: 0
end-slot: 35
```
Default `target: TARGET`.
#### Field Details
**start-slot**: start slot (inclusive).
```yaml
start-slot: 9
```
**end-slot**: end slot (inclusive).
```yaml
end-slot: 35
```
# Launch Projectile
## Launch Projectile
Makes source entity launch a projectile.
```yaml
type: launch_projectile
entity-type: ARROW
speed: 1.5
spawn-offset: 0.8
damage: 10
extra-y: 0
fireball-yield: 1.0
fireball-incendiary: true
```
Default `target: SOURCE`.
#### Field Details
**entity-type**: projectile entity type (for example `ARROW`, `FIREBALL`).
```yaml
entity-type: FIREBALL
```
**damage:** the damage when hit to target.
```yaml
damage: 10
```
**speed**: projectile velocity multiplier.
```yaml
speed: 2.2
```
**spawn-offset:**
```yaml
spawn-offset: 0.8
```
**extra-y**: upward addition to launch direction.
```yaml
extra-y: 0.2
```
**fireball-yield**: fireball explosion power (fireball types only).
```yaml
fireball-yield: 2.5
```
**fireball-incendiary**: whether fireball ignition is enabled.
```yaml
fireball-incendiary: false
```
# Send Message
## Send Message
Sends text messages to players (single message, multi-message, or nearby mode).
```yaml
type: send_message
mode: target-player
messages:
- "&cYou are cursed, {player}!"
```
Default `target: SOURCE`.
#### Field Details
**messages**: list of messages sent in order.
```yaml
messages:
- "&eFirst"
- "&cSecond"
```
**message**: single message; used when `messages` is empty.
```yaml
message: "&aHello {player}"
```
**mode**: target selection mode.
* `target-player`: current hate target player
* `nearby`: all nearby players
```yaml
mode: nearby
```
**radius**: search radius for `mode: nearby`.
```yaml
radius: 12
```
#### Variables
* `{player}`: current receiver
* `{target}`: mob hate target
* `{level}`: mob level
# Execute Command
## Execute Command
Executes commands (single or multiple), as console or player.
```yaml
type: execute_command
commands:
- give {player} diamond 1
```
Default `target: SOURCE`.
#### Field Details
**commands**: command list executed in order.
```yaml
commands:
- effect give {player} slowness 5 1
- say affected {player}
```
**command**: single command; used when `commands` is empty.
```yaml
command: give {player} golden_apple 1
```
**as-console**:
* `true`: run as console (default)
* `false`: run as player
```yaml
as-console: false
```
**mode**: target player selection.
* `target-player`: current hate target
* `nearby`: all nearby players
```yaml
mode: nearby
```
**radius**: search radius for `mode: nearby`.
```yaml
radius: 16
```
#### Variables
* `{player}`: current command target player
* `{target}`: mob hate target
* `{level}`: mob level
# Limit
## Limit
Wrapper executor: apply limits first, then execute nested `abilities`.
```yaml
type: limit
cooldown: 5
random: 0.5
abilities:
1:
type: PotionEffect
effect: WEAKNESS
duration: 60
```
Default `target: TARGET`.
#### Field Details
**abilities**: child actions that run after limits pass.
```yaml
abilities:
1:
type: Sound
sound: ENTITY_WITHER_AMBIENT
```
**times / random / cooldown**: standard limit fields reused for this action group.
```yaml
times: 2
random: 0.4
cooldown: 8
```
---
[Next Page](/llms-full.txt/1)