物品来源

CoreLib Item Source 用于统一识别不同生态中的物品。Minecraft 服务器常常同时使用原版物品、自定义物品插件、MMO 物品插件和本套插件自己的物品系统；如果配置只依赖显示名或 Lore，很容易因为翻译、颜色、刷新或其他插件修改而失效。

物品来源系统的目标是：使用稳定的来源类型和 ID 来描述物品。

支持的来源类型

类型	别名	说明
`VANILLA`	`vanilla`、`minecraft`、`v`	原版 Minecraft 物品。
`CRAFTENGINE`	`craftengine`、`ce`	CraftEngine 自定义物品或方块生态。
`ITEMSADDER`	`itemsadder`、`ia`	ItemsAdder 自定义物品。
`NEIGEITEMS`	`neigeitems`、`ni`	NeigeItems 物品。
`MMOITEMS`	`mmoitems`、`mi`	MMOItems 物品。
`EMAKIITEM`	`emakiitem`、`ei`	EmakiItem 自定义物品。
`NEXO`	`nexo`、`no`	Nexo 物品。
`ORAXEN`	`oraxen`、`ox`	Oraxen 物品。
`ECOITEMS`	`ecoitems`、`eco`、`eci`	EcoItems 物品。

类型名与短横线简写前缀并不完全一致：type: 字段接受上表全部别名，而短横线简写的可用前缀是 minecraft-、mc-、v-、craftengine-、ce-、itemsadder-、ia-、neigeitems-、ni-、mmoitems-、mi-、emakiitem-、ei-、nexo-、no-、oraxen-、ox-、ecoitems-、eci-（简写不支持 eco-）。

类型名称解析不区分大小写。实际可用来源取决于服务器是否安装对应插件。未安装的来源无法创建或识别对应物品。

为什么不要依赖显示名

不推荐用显示名判断物品，原因包括：

显示名可能被铁砧、插件或语言系统修改。
Lore 可能被 Attribute、Forge、Strengthen、Gem 等模块重建。
颜色代码、MiniMessage、传统颜色符可能导致文本不一致。
玩家可能通过其他方式获得相似名称物品。
物品更新后显示名可能变化，但 ID 保持稳定。

推荐使用稳定 ID，例如原版 DIAMOND_SWORD、EmakiItem 的物品 ID、MMOItems 的类型和 ID。

配置格式

统一物品定义中的来源

CoreLib GUI 与 EmakiItem 的基础物品统一使用 ConfiguredItemDefinition。在 YAML 中，来源位于嵌套 item.source：

yaml

item:
  source: itemsadder-custom_items:ruby_sword
  amount: 1
  components:
    custom_name: '<red>红宝石剑</red>'

item.source 可使用 CoreLib 当前注册的全部 ItemSource 简写。加载 EmakiItem definition 时会实际验证 resolver 是否可用并能创建基础物品；验证失败的 definition 不进入有效缓存。对第三方来源应用组件时，会保留来源身份、PDC 与未知组件，只传递当前 Paper 能安全处理的组件 patch。

对象格式（用于来源匹配等业务配置）

对象格式使用 type 与 identifier 两个字段，二者都必须非空：

yaml

item:
  type: vanilla
  identifier: diamond

yaml

item:
  type: emakiitem
  identifier: flame_blade

解析对象节点时的取值顺序是：先看 item_sources 列表，再看字符串字段 item（按短横线简写解析），再看嵌套的 source，最后才回落到 type + identifier 组合。

MMOItems 标识符格式

MMOItems 的 identifier 必须写成 <类型>:<物品ID>：

yaml

item:
  type: mmoitems
  identifier: SWORD:FLAME_SWORD

对应的短横线简写为 mmoitems-SWORD:FLAME_SWORD。类型 ID 匹配不区分大小写。

短横线格式

部分模块（特别是 Cooking）使用短横线格式简写：

yaml

input:
  item_sources:
    - minecraft-diamond
    - emakiitem-flame_blade
    - craftengine-custom_block

格式为 来源类型-物品ID，中间用短横线分隔。

旧式冒号格式（不推荐）

yaml

# 不推荐，容易与命名空间解析规则冲突
item: minecraft:diamond

新配置建议使用对象格式或短横线格式。

各来源的 ID 查找方法

Vanilla

使用 Bukkit Material 枚举名，下划线分隔。标识符会被统一规范化为小写，因此大小写写法都可接受：

text

diamond_sword, iron_chestplate, golden_apple, netherite_axe

原版标识符只允许小写字母、数字和下划线；带 minecraft: 命名空间前缀的写法会被判为无效。短横线简写支持 minecraft-、mc-、v- 三种前缀。

完整列表参考 Spigot Material 文档。

EmakiItem

使用 plugins/EmakiItem/items/*.yml 中定义的 id 字段：

yaml

# items/flame_blade.yml
id: flame_blade

引用时使用短横线简写 emakiitem-flame_blade，或对象格式 type: emakiitem + identifier: flame_blade。

CraftEngine

使用 CraftEngine 注册的物品 ID。通常可以通过 CraftEngine 的命令查看。

ItemsAdder

使用 ItemsAdder 的命名空间 ID，格式通常为 namespace:item_id：

yaml

item:
  type: itemsadder
  identifier: custom_items:ruby_sword

Nexo

使用 Nexo 注册的物品 ID。

MMOItems

需要在 identifier 中同时指定物品类型和 ID，用冒号分隔：

yaml

item:
  type: mmoitems
  identifier: SWORD:FLAME_SWORD

NeigeItems

使用 NeigeItems 配置中的物品 ID。

常见使用场景

配方材料

锻造、强化、烹饪、宝石升级都需要判断材料。材料必须能稳定识别，否则玩家可能用错误物品绕过或无法提交正确物品。

yaml

materials:
  - item:
      type: vanilla
      identifier: blaze_rod
    amount: 3
  - item:
      type: emakiitem
      identifier: strengthen_stone
    amount: 1

奖励发放

动作系统或配方结果可能创建物品。此时应明确来源和 ID，避免发放成普通原版物品。

yaml

actions:
  - 'createitem id=reward source=emakiitem-flame_blade amount=1'
  - 'senditem id=reward'

条件检查

条件系统可以检查玩家手持、背包、装备或 GUI 输入槽中的物品来源，用于限制配方、技能、套装或任务。

世界工位识别

Cooking 可通过 CraftEngine、ItemsAdder、Nexo 等生态识别方块或相关物品，实现自定义工位。同样的 CE / ItemsAdder / Nexo 物品来源也可以交给 placeblock 动作尝试作为自定义方块放置。

yaml

stations:
  chopping_board:
    block_item_sources:
      - craftengine-cutting_board

工具识别

部分工位要求特定工具才能操作：

yaml

tool_item_sources:
  - minecraft-iron_axe
  - minecraft-diamond_axe
  - minecraft-netherite_axe

物品来源优先级

当一个物品同时被多个插件识别时，CoreLib 按 resolver 的 priority 从大到小依次尝试；数值相同的按 resolver ID 排序。内置 resolver 的实际优先级为：

Resolver	priority
NeigeItems	`102`
CraftEngine	`101`
MMOItems	`100`
EmakiItem（由 EmakiItem 注册）	`100`
ItemsAdder	`98`
Nexo	`97`
Oraxen	`96`
EcoItems	`95`
Vanilla（兜底）	`0`

如果物品被错误识别，检查是否有多个插件同时标记了该物品。

ID 中含短横线时的写法

短横线格式按第一个短横线拆分来源与 ID，因此物品 ID 本身含短横线时容易产生歧义。这种情况请改用对象格式：

yaml

# 歧义写法（不推荐）
item_sources:
  - emakiitem-my-custom-item

# 明确写法（推荐）
input:
  type: emakiitem
  identifier: my-custom-item

物品来源 ​

支持的来源类型 ​

为什么不要依赖显示名 ​

配置格式 ​

统一物品定义中的来源 ​

对象格式（用于来源匹配等业务配置） ​

MMOItems 标识符格式 ​

短横线格式 ​

旧式冒号格式（不推荐） ​

各来源的 ID 查找方法 ​

Vanilla ​

EmakiItem ​

CraftEngine ​

ItemsAdder ​

Nexo ​

MMOItems ​

NeigeItems ​

常见使用场景 ​

配方材料 ​

奖励发放 ​

条件检查 ​

世界工位识别 ​

工具识别 ​

物品来源优先级 ​

ID 中含短横线时的写法 ​

物品来源

支持的来源类型

为什么不要依赖显示名

配置格式

统一物品定义中的来源

对象格式（用于来源匹配等业务配置）

MMOItems 标识符格式

短横线格式

旧式冒号格式（不推荐）

各来源的 ID 查找方法

Vanilla

EmakiItem

CraftEngine

ItemsAdder

Nexo

MMOItems

NeigeItems

常见使用场景

配方材料

奖励发放

条件检查

世界工位识别

工具识别

物品来源优先级

ID 中含短横线时的写法