模板与插槽

插槽物品配置定义哪些装备可以拥有宝石插槽、插槽的类型和数量、默认开放状态以及外观修改。文件位于 items/*.yml，文件名即为配置的内部标识。

配置字段

字段	类型	必填	说明
id	string	是	配置唯一 ID。
match	object	是	物品匹配规则。
slots	list	是	插槽定义列表。
default_open_slots	list<integer>	否	默认开放的插槽索引列表。不在 slots 中的索引会被忽略。
allowed_gem_types	list	否	允许镶嵌的宝石类型白名单。留空或包含 any 表示不限制。
max_same_type	integer	否	同类型宝石最大数量。未配置时不限制。
max_same_id	integer	否	同 ID 宝石最大数量。默认 1，最小 1。
gui	object	否	GUI 模板配置，支持 gem_template 与 open_template。
obtain	object	否	首次识别并写入宝石层时的外观与动作，见下方说明。

匹配规则（match）

字段	说明
item_sources	按物品来源匹配（格式 "提供者-物品ID"）。
slot_groups	按装备槽位组匹配（weapon/armor/offhand）。
lore_contains	按 Lore 包含文本匹配（空列表表示不限制）。

插槽定义（slots）

字段	说明
index	插槽索引（从 0 开始，唯一）。
type	插槽类型（决定哪些宝石可以镶嵌）。
display_name	插槽在 GUI 中的显示名称。

默认开放插槽

default_open_slots 使用索引列表精确指定哪些插槽初始已开放：

# 只有索引 0 的插槽默认开放，其余需要通过开槽操作解锁
default_open_slots:
  - 0

未列出的插槽需要玩家通过开槽操作来解锁。

获得装备时的外观与动作（obtain）

obtain 在装备首次被识别并写入宝石层时生效：

字段	类型	说明
obtain.name_actions	list	对物品名称的修改。
obtain.lore_actions	list	对物品 Lore 的修改。
obtain.actions	list<string>	首次写入宝石层时执行的动作行。

obtain.lore_actions 中可使用 %opened_slots%、%total_slots%、%item_definition_id% 等模板变量。

完整示例

id: "example_socket_item"

match:
  item_sources:
    - "minecraft-diamond_sword"
  slot_groups:
    - "weapon"
  lore_contains: []

slots:
  - index: 0
    type: "attack"
    display_name: "<red>攻击插槽</red>"
  - index: 1
    type: "universal"
    display_name: "<white>通用插槽</white>"
  - index: 2
    type: "defense"
    display_name: "<blue>防御插槽</blue>"

default_open_slots:
  - 0

allowed_gem_types:
  - "attack"
  - "defense"
  - "utility"
  - "universal"

max_same_type: 0
max_same_id: 1

gui:
  gem_template: "gem/default"
  open_template: "open/default"

obtain:
  name_actions:
    - action: "prepend_prefix"
      value: "<gold>✦</gold> "
  lore_actions:
    - action: "append"
      content:
        - "<dark_gray>─────────────</dark_gray>"
        - "<gray>宝石槽: <dark_gray>(%opened_slots%/%total_slots%)</dark_gray></gray>"
  actions:
    - 'sendmessage text="<gray>已识别可镶嵌装备：<yellow>%item_definition_id%</yellow></gray>"'

设计建议

• 不同装备类型使用不同配置，避免防具镶嵌武器宝石。
• 高级装备可以给更多插槽，但搭配 default_open_slots 控制初始开放数量。
• max_same_id: 1 防止重复镶嵌同一颗宝石。
• 如果装备来自 EmakiItem，建议在 match.item_sources 中使用稳定物品 ID。
• obtain.name_actions 与 obtain.lore_actions 用于在装备首次写入宝石层时标识可镶嵌状态。