物品来源

CoreLib 的物品来源系统用固定的来源类型加 ID 描述一件物品, 各种来源的 ID 附查找方法

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

它的目标很直接: 用稳定的来源类型和 ID 来描述物品

支持的来源类型

先看设计: ItemSourceKind 是 record 而不是枚举, 规范形态为 namespace:id, 留空 namespace 时补为 emaki. 这样第三方插件也能自己注册来源类型: 谁提供 ItemSourceProvider, 就在同一次注册里声明自己的 kind 与短横线前缀, 并使用自己的命名空间

CoreLib 自己实现了 8 个内置常量, 都在 emaki 命名空间下:

常量	kind key	别名	说明
`VANILLA`	`emaki:vanilla`	`vanilla`, `minecraft`, `mc`, `v`	原版 Minecraft 物品, 也是裸文本 (不写来源) 时的默认来源
`CRAFTENGINE`	`emaki:craftengine`	`craftengine`, `ce`	CraftEngine 自定义物品或方块生态
`ITEMSADDER`	`emaki:itemsadder`	`itemsadder`, `ia`	ItemsAdder 自定义物品
`NEIGEITEMS`	`emaki:neigeitems`	`neigeitems`, `ni`	NeigeItems 物品
`MMOITEMS`	`emaki:mmoitems`	`mmoitems`, `mi`	MMOItems 物品
`NEXO`	`emaki:nexo`	`nexo`, `no`	Nexo 物品
`ORAXEN`	`emaki:oraxen`	`oraxen`, `ox`	Oraxen 物品
`ECOITEMS`	`emaki:ecoitems`	`ecoitems`, `eci`	EcoItems 物品

注意这里故意没有 EMAKIITEM 常量: 它的解析器 (resolver) 位于 EmakiItem 模块, 因此 kind 与前缀也在那里声明, 值为 ItemSourceKind.of("emakiitem:emakiitem"), 配置中的别名是 emakiitem, ei

你还要留意: 类型名与短横线简写前缀并不完全一致. 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 时会实际验证对应的解析器能不能用, 以及能不能创建基础物品; 验证失败的 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 (以 ItemsAdder 里实际注册的为准):

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:
  - 'create_item id=reward source=emakiitem-flame_blade amount=1'
  - 'send_item id=reward'

条件检查

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

世界工位识别

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

yaml

stations:
  chopping_board:
    block_item_sources:
      - craftengine-cutting_board

工具识别

部分工位要求特定工具才能操作, 这样写:

yaml

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

物品来源优先级

一个物品同时被多个插件识别时, CoreLib 按解析器的 priority 从大到小依次尝试; 数值相同的按解析器 ID 排序. 内置解析器的实际优先级是:

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

# 可以正确解析: 前缀 emakiitem- 命中后, ID 为 my-custom-item
item_sources:
  - emakiitem-my-custom-item

# 等价的对象格式, 来源与 ID 分开写更直观
input:
  type: emakiitem
  identifier: my-custom-item

只有当 ID 本身以另一个已注册前缀开头时, 才会涉及前缀优先级问题; 遇到这种情况, 改用对象格式能完全避免歧义

物品来源 ​

支持的来源类型 ​

为什么不要依赖显示名 ​

配置格式 ​

统一物品定义中的来源 ​

对象格式 (用于来源匹配等业务配置) ​

MMOItems 标识符格式 ​

短横线格式 ​

旧式冒号格式 (不推荐) ​

各来源的 ID 查找方法 ​

Vanilla ​

EmakiItem ​

CraftEngine ​

ItemsAdder ​

Nexo ​

MMOItems ​

NeigeItems ​

常见使用场景 ​

配方材料 ​

奖励发放 ​

条件检查 ​

世界工位识别 ​

工具识别 ​

物品来源优先级 ​

ID 中含短横线时的写法 ​

物品来源

支持的来源类型

为什么不要依赖显示名

配置格式

统一物品定义中的来源

对象格式 (用于来源匹配等业务配置)

MMOItems 标识符格式

短横线格式

旧式冒号格式 (不推荐)

各来源的 ID 查找方法

Vanilla

EmakiItem

CraftEngine

ItemsAdder

Nexo

MMOItems

NeigeItems

常见使用场景

配方材料

奖励发放

条件检查

世界工位识别

工具识别

物品来源优先级

ID 中含短横线时的写法