物品来源系统 (Item Source)

Minecraft 服务器上经常同时跑着好几个物品插件——CraftEngine、ItemsAdder、NeigeItems 等等。物品来源系统就是为了解决"怎么用一种写法引用所有这些插件的物品"这个问题。

不管物品来自原版还是第三方插件，你都用同一套 类型-物品ID 的格式来引用。CoreLib 在运行时自动检测服务器上装了哪些插件，帮你把引用解析成实际的 ItemStack。

ItemSourceType 枚举

类型枚举	别名	对应插件	说明
VANILLA	vanilla, minecraft, mc	Minecraft 原版	原版物品，使用 Material 名称
CRAFTENGINE	craftengine, ce	CraftEngine	CraftEngine 自定义物品
ITEMSADDER	itemsadder, ia	ItemsAdder	ItemsAdder 自定义物品
NEIGEITEMS	neigeitems, ni	NeigeItems	NeigeItems 自定义物品
MMOITEMS	mmoitems, mi	MMOItems	MMOItems 自定义物品
NEXO	nexo	Nexo	Nexo 自定义物品

每种类型都有简短的别名，写配置时可以少打几个字。

简写格式

物品来源的格式是 类型-物品ID，用连字符 - 分隔：

<sourceType>-<itemId>

各类型示例

类型	简写示例	说明
VANILLA	vanilla-diamond_sword	原版钻石剑
VANILLA	minecraft-golden_apple	原版金苹果（用别名）
VANILLA	mc-netherite_ingot	原版下界合金锭（用别名）
CRAFTENGINE	craftengine-custom_pickaxe	CraftEngine 自定义镐
CRAFTENGINE	ce-magic_wand	CraftEngine 魔杖（用别名）
ITEMSADDER	itemsadder-emaki:fire_sword	ItemsAdder 物品（命名空间:ID）
ITEMSADDER	ia-emaki:ice_shield	ItemsAdder 物品（用别名）
NEIGEITEMS	neigeitems-legendary_bow	NeigeItems 物品
NEIGEITEMS	ni-epic_armor	NeigeItems 物品（用别名）
MMOITEMS	mmoitems-SWORD.fire_blade	MMOItems 物品（类型.ID）
MMOITEMS	mi-BOW.thunder_bow	MMOItems 物品（用别名）
NEXO	nexo-crystal_staff	Nexo 物品

重要

分隔符是连字符 -，不是冒号 :。这是最常见的写错的地方。

# ✅ 正确
source: "vanilla-diamond_sword"
source: "minecraft-diamond_sword"

# ❌ 错误
source: "minecraft:diamond_sword"
source: "vanilla:diamond_sword"

冒号 : 只会出现在第三方插件物品 ID 的内部（比如 ItemsAdder 的 namespace:id），而不是用来分隔来源类型和物品 ID。

使用场景

物品来源格式在 CoreLib 的多个子系统中都会用到：

GUI 物品字段

GUI 模板里的 item.source 字段：

slots:
  reward_display:
    slots: "13"
    type: DISPLAY
    item:
      source: "vanilla-diamond"
      name: "<aqua>钻石奖励"
      amount: 5

装配系统 baseSource

装配系统里指定基础物品：

assembly:
  baseSource: "craftengine-iron_longsword"
  namespace: "forge"

动作 createitem / senditem

动作系统里通过 source 参数引用物品：

actions:
  - "createitem source=vanilla-diamond amount=10"
  - "senditem source=itemsadder-emaki:rare_gem amount=1"
  - "clearitem source=vanilla-dirt"

集成机制

CoreLib 不会硬依赖任何第三方物品插件。启动时它会检测服务器上装了哪些插件，装了的就注册对应的提供者，没装的就跳过。CraftEngine 解析器直接调用 CraftEngine API 并监听其重载事件自动刷新物品表，其他插件的解析器在插件启用/禁用时动态注册或注销：

服务器启动
  ├─ 检测 CraftEngine  → 已安装 → 注册 CRAFTENGINE 提供者
  ├─ 检测 ItemsAdder   → 已安装 → 注册 ITEMSADDER 提供者
  ├─ 检测 NeigeItems   → 未安装 → 跳过
  ├─ 检测 MMOItems     → 未安装 → 跳过
  └─ 检测 Nexo         → 未安装 → 跳过

这样做的好处是，即使某个插件没装，CoreLib 也能正常启动，只是对应的物品来源类型不可用。当你尝试使用未安装插件的物品来源时，系统会返回 ITEM_SOURCE_NOT_FOUND 错误。

编程接口

ItemSourceService itemSourceService = EmakiServiceRegistry.get(ItemSourceService.class);

// 解析物品来源，拿到 ItemStack
Optional<ItemStack> item = itemSourceService.resolve("vanilla-diamond_sword", 1);

// 检查某个来源类型是否可用（对应插件是否已安装）
boolean available = itemSourceService.isAvailable(ItemSourceType.ITEMSADDER);

// 获取所有已注册的来源类型
Set<ItemSourceType> registered = itemSourceService.getRegisteredTypes();

注意

resolve 返回 Optional<ItemStack>。物品来源不可用或物品 ID 无效时会返回空值，调用方要记得处理这种情况。