开孔器系统

开孔器用于解锁装备上预留但尚未开放的宝石插槽。它把“装备模板中允许存在的插槽”和“玩家实际可使用的插槽”分离开，适合制作长期养成、付费材料、活动材料或副本掉落材料。

工作流程

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

全局配置

开孔器位于 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:
        - 'sendmessage text="<green>成功为装备开启了攻击宝石插槽！</green>"'
        - "playsound sound=block.anvil.use volume=1.0 pitch=1.1"
      failure:
        - 'sendmessage text="<red>该装备没有可由攻击开孔器开启的预留插槽。</red>"'
        - "playsound sound=entity.villager.no volume=1.0 pitch=0.8"

字段说明

字段	类型	说明
enabled	boolean	是否启用该开孔器。关闭后对应物品不会作为开孔材料。
item_sources	list	可识别为开孔器的物品来源。支持原版物品和统一物品来源格式。
opens_gem_types	list	允许开启的插槽类型。填写 any 表示可开启任意类型。
consume_on_success	boolean	开孔成功后是否消耗开孔器。
actions.success	list	开孔成功时执行的动作。
actions.failure	list	开孔失败时执行的动作。

默认开孔器

开孔器	默认物品	可开启类型	适合用途
attack_drill	minecraft-blaze_rod	attack	武器或输出装备成长。
defense_drill	minecraft-prismarine_shard	defense	防具、防御向饰品成长。
universal_drill	minecraft-echo_shard	any	高价值通用开孔材料。

与插槽物品配置的关系

开孔器不会凭空创建任意插槽。装备必须先在插槽物品配置中声明可开放的插槽，例如：

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 是否与手持物来源一致。
• 提示无可开启插槽：检查插槽物品配置中的 slots 是否存在尚未写入 default_open_slots 的插槽，并确认类型匹配。
• 成功后未消耗材料：检查 consume_on_success 是否为 true，以及玩家是否被权限绕过配置影响。
• 开孔后显示未刷新：检查 CoreLib 装配层是否正常重建，必要时重新打开 GUI 或刷新装备。