> 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/basic-metadata.md).

# Basic and Metadata Rules

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