开孔器系统

开孔器怎么配, 以及开孔时插件怎么判断装备上还有哪个插槽能被开出来

开孔器用来解锁装备上预留但尚未开放的宝石插槽. 它把「装备模板中允许存在的插槽」和「玩家实际可使用的插槽」分离开, 方便做长期养成, 付费材料, 活动材料或副本掉落材料

工作流程

1. 装备通过 items/*.yml 定义可用插槽和预留插槽
2. 玩家打开开孔 GUI
3. 放入目标装备和开孔器材料
4. 系统检查装备是否匹配插槽物品配置
5. 系统查找一个未开放且类型符合开孔器规则的插槽
6. 成功后消耗开孔器, 并把插槽写入装备 gem layer
7. EmakiGem 重建装备展示

全局配置

开孔器配置放在 config.yml 的 socket_openers 节点:

socket_openers:
  attack_drill:
    enabled: true
    item_sources: ["minecraft-blaze_rod"]
    opens_gem_types:
      - "attack"
    consume_on_success: true
    actions:
      success:
        - 'send_message text="<green>成功为装备开启了攻击宝石插槽！</green>"'
        - "play_sound sound=block.anvil.use volume=1.0 pitch=1.1"
      failure:
        - 'send_message text="<red>该装备没有可由攻击开孔器开启的预留插槽。</red>"'
        - "play_sound sound=entity.villager.no volume=1.0 pitch=0.8"

字段说明

字段	类型	必填	默认值	取值范围	说明
socket_openers.<id>	object	否	空 (无开孔器)	键名即开孔器 ID (转小写)	一个开孔器条目; 键名为空时该条目不加载
enabled	boolean	否	true	true / false	是否启用该开孔器. 关闭后对应物品不会作为开孔材料
custom_model_data	integer	否	未设置	任意整数	限定开孔器物品的 CustomModelData; 未写则不校验该项
display_name	string	否	开孔器 ID	MiniMessage 文本	开孔器显示名
lore	list	否	空列表	MiniMessage 文本	开孔器 Lore
opens_gem_types	list	否	空 (不限类型)	插槽类型; 含 any 也视为不限	允许开启的插槽类型
consume_on_success	boolean	否	true	true / false	开孔成功后是否消耗开孔器
item_sources	list	否	空 (不限来源)	物品源简写	允许的开孔器物品来源. 与同级的 matcher 一起判断, 两者都要成立
matcher	object	否	空	见 物品匹配器	只写组件, PDC, Lore 等非物品源条件. 与 item_sources 都省略时该开孔器永不命中
actions.success	list	否	空	CoreLib 动作行	开孔成功时执行的动作
actions.failure	list	否	空	CoreLib 动作行	开孔失败时执行的动作

用 matcher 收窄开孔器

matcher 让开孔器不只认物品种类, 还能认物品上的具体数据. 写法是: 物品种类交给同级的 item_sources, matcher 只写组件条件, 两者要同时成立. 例如只有被重命名过的烈焰棒才算攻击开孔器:

socket_openers:
  attack_drill:
    enabled: true
    item_sources:
      - minecraft-blaze_rod
    matcher:
      type: component
      component: custom_name
      operator: contains
      value: 攻击钻
    opens_gem_types:
      - "attack"

WARNING

matcher 内部不能写物品源条件 (type: item_source / item_sources / source / sources 会被拒绝并告警, 该 matcher 恒不匹配)

完整语法 (类型全集, operator, path) 见 物品匹配器

默认开孔器

开孔器	默认 enabled	默认物品	可开启类型	适合用途
attack_drill	true	minecraft-blaze_rod	attack	武器或输出装备成长
defense_drill	true	minecraft-prismarine_shard	defense	防具, 防御向饰品成长
universal_drill	true	minecraft-echo_shard	any	高价值通用开孔材料
legendary_drill	false	minecraft-blaze_rod + matcher (名称含"传说")	attack, defense	展示"物品源 + 组件条件并存"的写法; 默认关闭, 确认判定范围后再启用

与插槽物品配置的关系

开孔器不会凭空创建任意插槽. 你要先在插槽物品配置中声明装备可开放的插槽, 例如:

slots:
  - index: 0
    type: "attack"
    display_name: "<red>攻击插槽</red>"
  - index: 1
    type: "attack"
    display_name: "<red>攻击插槽 II</red>"
  - index: 2
    type: "universal"
    display_name: "<white>通用插槽</white>"
default_open_slots:
  - 0

看这个示例:

• attack_drill 可以开启索引 1 的攻击插槽
• universal_drill 可以开启索引 1 或 2
• 如果所有匹配类型插槽都已开放, 开孔会失败并执行 actions.failure

设计建议

• 武器, 防具, 饰品建议使用不同插槽类型, 避免一种低阶材料打开所有高价值插槽
• any 类型开孔器适合稀有活动, 赛季奖励或高阶副本掉落
• 如果服务器有装备品质系统, 可以让高品质装备拥有更多预留插槽, 但仍通过开孔器逐步解锁
• 开孔成功后建议播放清晰反馈, 例如音效, 消息或粒子, 减少玩家误判

排查建议

• 开孔器无效: 先确认 item_sources 和 matcher 至少写了一个, 并核对它们是否与手持物一致
• 提示无可开启插槽: 查插槽物品配置中的 slots 里有没有尚未写入 default_open_slots 的插槽, 并确认类型匹配
• 成功后未消耗材料: 查 consume_on_success 是否为 true, 再看玩家是否被权限绕过配置影响
• 开孔后显示未刷新: 查宝石层是否正常重建, 必要时重新打开 GUI 或刷新装备