物品来源

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 物品。

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

为什么不要依赖显示名

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

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

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

配置格式

对象格式（推荐）

item:
  type: vanilla
  id: DIAMOND
  amount: 3

item:
  source: emakiitem
  id: flame_blade
  amount: 1

type 和 source 是等价字段，取第一个非空值。

MMOItems 特殊格式

MMOItems 需要额外的 item_type 字段：

item:
  type: mmoitems
  item_type: SWORD
  id: FLAME_SWORD

短横线格式

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

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

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

旧式冒号格式（不推荐）

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

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

各来源的 ID 查找方法

Vanilla

使用 Bukkit Material 枚举名，全大写，下划线分隔：

DIAMOND_SWORD, IRON_CHESTPLATE, GOLDEN_APPLE, NETHERITE_AXE

完整列表参考 Spigot Material 文档。

EmakiItem

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

# items/flame_blade.yml
id: flame_blade

引用时：source: emakiitem, id: flame_blade

CraftEngine

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

ItemsAdder

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

item:
  type: itemsadder
  id: custom_items:ruby_sword

Nexo

使用 Nexo 注册的物品 ID。

MMOItems

需要同时指定物品类型和 ID：

item:
  type: mmoitems
  item_type: SWORD
  id: FLAME_SWORD

NeigeItems

使用 NeigeItems 配置中的物品 ID。

常见使用场景

配方材料

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

materials:
  - item:
      type: vanilla
      id: BLAZE_ROD
    amount: 3
  - item:
      type: emakiitem
      id: strengthen_stone
    amount: 1

奖励发放

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

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

条件检查

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

世界工位识别

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

stations:
  chopping_board:
    block_item_sources:
      - craftengine-cutting_board

工具识别

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

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

物品来源优先级

当一个物品同时被多个插件识别时，CoreLib 按注册顺序检查。通常优先级为：

1. EmakiItem（如果物品有 EmakiItem PDC 标记）
2. 外部插件（CraftEngine、ItemsAdder、Nexo、MMOItems、NeigeItems）
3. Vanilla（兜底）

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

歧义写法（不推荐）

item_sources:

• emakiitem-my-custom-item

明确写法（推荐）

input: source: emakiitem id: my-custom-item