Enchantment and ItemFormat Rules

Every rule on this page is a key inside a MatchItemFormat 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

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

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.<enchantment>	unset	A scalar minimum threshold or a list of exact allowed levels.

Examples

Require Sharpness above level 3:

match-item:
  contains-enchants:
    minecraft:sharpness: 3

Accept exactly level 1, 3, or 5:

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:

match-item:
  contains-enchants-amount: 3

Accept exactly one, three, or five enchantments:

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

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

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.