> 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/enchantments-format.md).

# Enchantment and ItemFormat Rules

Every rule on this page is a key inside a [MatchItemFormat](/format/match-item-format.md) 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.<enchantment>` | 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.