> For the complete documentation index, see [llms.txt](https://enchantedmobs.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://enchantedmobs.superiormc.cn/format/match-item-format.md).

# 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.md) 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.md#none)                                  |
| `items`                    | [Basic and Metadata Rules](/format/match-item-format/basic-metadata.md#items)                                 |
| `material`                 | [Basic and Metadata Rules](/format/match-item-format/basic-metadata.md#material)                              |
| `material-tag`             | [Basic and Metadata Rules](/format/match-item-format/basic-metadata.md#material-tag)                          |
| `rarity`                   | [Basic and Metadata Rules](/format/match-item-format/basic-metadata.md#rarity)                                |
| `has-name`                 | [Basic and Metadata Rules](/format/match-item-format/basic-metadata.md#has-name)                              |
| `contains-name`            | [Basic and Metadata Rules](/format/match-item-format/basic-metadata.md#contains-name)                         |
| `has-lore`                 | [Basic and Metadata Rules](/format/match-item-format/basic-metadata.md#has-lore)                              |
| `contains-lore`            | [Basic and Metadata Rules](/format/match-item-format/basic-metadata.md#contains-lore)                         |
| `has-enchants`             | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format.md#has-enchants)             |
| `has-stored-enchants`      | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format.md#has-stored-enchants)      |
| `contains-enchants`        | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format.md#contains-enchants)        |
| `contains-enchants-amount` | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format.md#contains-enchants-amount) |
| `enchantable`              | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format.md#enchantable)              |
| `item-format`              | [Enchantment and ItemFormat Rules](/format/match-item-format/enchantments-format.md#item-format)              |
| `any`                      | [Logical and NBT Rules](/format/match-item-format/logic-nbt.md#any)                                           |
| `not`                      | [Logical and NBT Rules](/format/match-item-format/logic-nbt.md#not)                                           |
| `contains-nbt`             | [Logical and NBT Rules](/format/match-item-format/logic-nbt.md#contains-nbt)                                  |
| `nbt-string`               | [Logical and NBT Rules](/format/match-item-format/logic-nbt.md#nbt-string)                                    |
| `nbt-byte`                 | [Logical and NBT Rules](/format/match-item-format/logic-nbt.md#nbt-byte)                                      |
| `nbt-int`                  | [Logical and NBT Rules](/format/match-item-format/logic-nbt.md#nbt-int)                                       |
| `nbt-double`               | [Logical and NBT Rules](/format/match-item-format/logic-nbt.md#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.md): entity matching and nested equipment matching.
* [ItemFormat™](/format/itemformat-tm.md): the serialized structure used by the `item-format` rule.
* [Abilities](/configs/info-of-abilities.md): abilities such as `disarm` that may use item matching.