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

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.

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:

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:

match-item:
  material-tag:
    - minecraft:swords
  not:
    contains-name:
      - Broken

See Logical and NBT Rules 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
items	Basic and Metadata Rules
material	Basic and Metadata Rules
material-tag	Basic and Metadata Rules
rarity	Basic and Metadata Rules
has-name	Basic and Metadata Rules
contains-name	Basic and Metadata Rules
has-lore	Basic and Metadata Rules
contains-lore	Basic and Metadata Rules
has-enchants	Enchantment and ItemFormat Rules
has-stored-enchants	Enchantment and ItemFormat Rules
contains-enchants	Enchantment and ItemFormat Rules
contains-enchants-amount	Enchantment and ItemFormat Rules
enchantable	Enchantment and ItemFormat Rules
item-format	Enchantment and ItemFormat Rules
any	Logical and NBT Rules
not	Logical and NBT Rules
contains-nbt	Logical and NBT Rules
nbt-string	Logical and NBT Rules
nbt-byte	Logical and NBT Rules
nbt-int	Logical and NBT Rules
nbt-double	Logical and NBT Rules

Complete example

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: entity matching and nested equipment matching.

• ItemFormat™: the serialized structure used by the item-format rule.

• Abilities: abilities such as disarm that may use item matching.