> 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/enchantedmobs-zhong-wen-wen-dang/features/pi-pei-wu-pin-ge-shi-match-item-format.md).

# 匹配物品格式（Match Item Format）

`Match Item Format` 会读取同一个配置节点下的所有规则，默认是 **AND** 关系（都满足才匹配）。

```yaml
match-item:
  material:
    - diamond_sword
  has-enchants:
    - sharpness
```

***

### 字段总览

#### material

作用：按材质匹配（命名空间 key，忽略大小写）。

```yaml
material:
  - diamond_sword
  - netherite_sword
```

***

#### material-tag

作用：按原版 Tag 匹配（支持 item tag 和 block tag）。

```yaml
material-tag:
  - minecraft:swords
  - minecraft:planks
```

***

#### items

作用：按外部物品插件 ID 匹配。

```yaml
items:
  - SWORD;;FLAME_BLADE
  - legend_blade
```

**use-tier-identify**

作用：是否解析成物品稀有度 ID 而非物品ID。

```yaml
use-tier-identify: true
```

***

#### has-name

作用：是否必须有显示名。

```yaml
has-name: true
```

***

#### contains-name

作用：物品名“包含”指定文本（忽略颜色与格式）。

```yaml
contains-name:
  - 史诗
  - 烈焰
```

***

#### has-lore

作用：是否必须有 lore。

```yaml
has-lore: true
```

***

#### contains-lore

作用：任意一行 lore 包含指定文本即可匹配。

```yaml
contains-lore:
  - 吸血
  - 诅咒
```

***

#### has-enchants

作用：检测物品附魔是否包含列表中的任意一个。

* 支持 `*` 表示“只要有任意附魔即可”

```yaml
has-enchants:
  - sharpness
  - unbreaking
```

```yaml
has-enchants:
  - "*"
```

***

#### has-stored-enchants

作用：检测附魔书（Stored Enchants）中是否包含指定附魔。

* 仅对附魔书元数据生效。
* 支持 `*` 表示“有任意储存附魔即可”。

```yaml
has-stored-enchants:
  - mending
```

***

#### contains-enchants

作用：检测指定附魔等级是否满足条件。

配置格式：

* `contains-enchants.<enchant>: <数字>` 表示等级 > 该数字
* `contains-enchants.<enchant>: [list]` 表示等级在 list 中

```yaml
contains-enchants:
  sharpness: 3
```

```yaml
contains-enchants:
  protection: [1, 2, 4]
```

***

#### contains-enchants-amount

作用：检测附魔总条数。

* 数字：表示 `>=`
* 列表：表示必须命中列表值

```yaml
contains-enchants-amount: 3
```

```yaml
contains-enchants-amount: [1, 2, 5]
```

***

#### enchantable

作用：判断该物品“是否可被这些附魔附魔”。

```yaml
enchantable:
  - sharpness
  - looting
```

***

#### rarity（1.20.5+）

作用：匹配物品稀有度（若无 rarity 则视为 `NONE`）。

```yaml
rarity: RARE
```

***

#### item-format

作用：按 DebuildItem 结构化结果精确比对物品属性（高级匹配）。

```yaml
item-format:
  material: DIAMOND_SWORD
  name: "&c烈焰剑"
  enchantment:
    sharpness: 5
```

**item-format-settings.require-same-key**

作用：是否要求“当前物品也必须包含模板中以外的同级 key 一致性检查”。

```yaml
item-format-settings:
  require-same-key: true
```

**item-format-settings.ignore-key**

作用：忽略比对的 key（支持前缀忽略，如 `nbt` 会忽略 `nbt.*`）。

```yaml
item-format-settings:
  ignore-key:
    - amount
    - damage
```

***

#### contains-nbt（需 NBTAPI）

作用：检测是否存在某个 NBT 路径。

路径格式：`父;;子;;最终键`

```yaml
contains-nbt:
  - CustomModelData
  - PublicBukkitValues;;myplugin:key
```

***

#### nbt-string（需 NBTAPI）

作用：匹配字符串 NBT 值。

格式：

* 顶层：`key;;value`
* 嵌套：`a;;b;;key;;value`

```yaml
nbt-string:
  - owner;;Steve
  - PublicBukkitValues;;myplugin:data;;state;;active
```

***

#### nbt-byte / nbt-int / nbt-double（需 NBTAPI）

作用：匹配数值型 NBT，支持比较符。

比较符：`>=` `>` `<=` `<` `==`

格式：

* 顶层：`key;;操作符;;值`
* 嵌套：`a;;b;;key;;操作符;;值`

```yaml
nbt-int:
  - CustomModelData;;>=;;1000
```

```yaml
nbt-byte:
  - PublicBukkitValues;;myplugin:data;;flag;;==;;1
```

```yaml
nbt-double:
  - PublicBukkitValues;;myplugin:data;;crit;;>;;0.25
```

***

#### any

作用：OR 逻辑组合（满足其中任意一组/任意一条规则即可）。

**方式 1：分组 OR（推荐）**

```yaml
any:
  1:
    material:
      - diamond_sword
  2:
    has-enchants:
      - sharpness
```

**方式 2：同层 OR**

```yaml
any:
  material:
    - bow
  has-name: true
```

***

#### not

作用：取反（`not` 内任意规则命中则整体失败）。

```yaml
not:
  material:
    - wooden_sword
```

***

#### none

作用：始终不匹配（可用于临时禁用某个分支）。

```yaml
none: true
```