Basic and Metadata Rules

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

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

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

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

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

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

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

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

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

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.