跨模块集成

其他模块引用 EmakiItem 物品的写法: 在配方, 宝石, 强化, 技能等地方按来源前缀引用它的物品 ID

Item 模块作为装备, 材料, 消耗品和展示物品的统一来源, 可以被 Attribute, Forge, Strengthen, Gem, Skills, Cooking 等模块引用. 跨模块引用时, 按 CoreLib 的物品来源短横线格式书写, 例如 emakiitem-shadow_ingot

集成方式

场景	推荐方式
作为配方材料	在其他模块的 item_sources 中引用 EmakiItem ID
作为装备基础	在物品定义中写入属性, 组件, 套装, 触发器和 PDC
作为技能消耗品	在 Skills 条件或动作中检查物品来源
作为宝石或强化材料	使用稳定 ID, 并避免只依赖名称或 Lore

Forge 中引用

materials:
  - item_sources:
      - "emakiitem-shadow_ingot"
    amount: 3
    capacity_cost: 5

Forge 配方材料统一用 item_sources 列表描述来源, 照上面的格式填即可

Gem 中引用

宝石定义里, base_item_source 负责构造宝石物品, 同级的 item_sources 负责识别哪种物品是宝石, 两处都要填:

id: "ruby_t1"
display_name: "<red>红宝石 I</red>"
gem_type: "attack"
base_item_source: "emakiitem-ruby_t1"   # 构造底材
item_sources:                           # 识别判定
  - "emakiitem-ruby_t1"
socket_compatibility:
  - "attack"
  - "universal"

插槽物品配置用顶层的 slot_groups, item_sources 与 matcher 判断哪些装备可以拥有插槽, 三者取 AND:

slot_groups:
  - "weapon"

item_sources:
  - "emakiitem-shadow_blade"

旧版的 match 块已不再被读取, 按 模板与插槽 写法迁移

Strengthen 中引用

stars:
  1:
    materials:
      - item_sources:
          - "emakiitem-strengthen_stone"
        amount: 1

物品层预览提供器

物品层 Preview SPI 由 EmakiItemApi 持有, 第三方通过 EmakiItemApi.extensions().registerLayerPreview(owner, provider) 注册, 注册句柄实现 AutoCloseable. 接口与注册表的含义详见 API

内置层 ID 为 strengthen 和 gem, 分别由 EmakiStrengthen 和 EmakiGem 在各自的条件加载 integration 包中注册: 它们监听 PluginEnableEvent / PluginDisableEvent, 仅在 EmakiItem 已启用时反射注册 provider, EmakiItem 缺失时进入 no-op, 不产生硬依赖. 对应模块未加载时, 预览结果中该层以 unavailable 占位出现, 其余层继续计算; 排查时先看目标模块是否已加载

技能 PDC 与协议模块

写入约定: Item 写入装备技能 ID 与装备强制触发器时不检查 EmakiSkills 的启用状态. 相关 PDC 键由 EmakiSkillsApi 的 emaki.jiuwu.craft.skills.api.pdc.EquipmentSkillPdcCodec 统一持有, 并在构建时嵌入 Item 自身 Jar, 因此即使 EmakiSkills 未安装, 技能数据仍会正常写入与清理, 装备后由 EmakiSkills 读取生效

PDC 与 Lore

配置约定: 跨模块集成优先用 PDC 保存真实数据, Lore 只作为展示层, 避免语言切换, 颜色变化或其他插件改 Lore 导致数据失效

排查建议

• 物品无法被识别: 先确认 EmakiItem 物品有没有写入稳定 ID
• 配方材料无法提交: 检查 item_sources 是不是用了正确的来源前缀
• 外部插件生成的同名物品不会自动等同于 EmakiItem 物品, 除非它拥有对应的 PDC 标记