模板与插槽

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

配置字段

字段	类型	必填	说明
id	string	是	配置唯一 ID。
item_sources	list	否	允许的装备物品来源列表。留空或缺失表示不限来源。与 slot_groups、matcher 是且关系。
matcher	object	否	通用物品匹配器，只写组件、PDC、Lore 等非物品源条件。见下方说明。
slot_groups	list	否	按物品材质名匹配的分组列表，写入时统一转小写、空串被丢弃。与 item_sources、matcher 是且关系。留空或缺失表示不限制。见下方分组名。
match	object	—	已废弃，不再被读取。见下方从 match 迁移。
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	否	首次识别并写入宝石层时的外观与动作，见下方说明。

匹配规则（slot_groups + item_sources + matcher）

装备匹配由文件顶层的三个字段决定，三者是且关系（全部成立才命中）：

字段	说明
slot_groups	按物品材质名匹配的分组列表，命中任意一个即算通过。留空表示不限制。
item_sources	允许的物品来源列表，命中任意一个即算通过。留空表示不限来源。
matcher	通用物品匹配器，只按组件、PDC、Lore、变量等非物品源条件判定。语法见 物品匹配器。

WARNING

matcher 内部不能写物品源条件。type: item_source / item_sources / source / sources 会被解析器拒绝并告警，该 matcher 恒不匹配。物品源一律写到同级的 item_sources。

分组名

slot_groups 判定的是物品的材质名（如 diamond_sword），不是玩家身上的装备栏位。识别的分组名如下：

分组名	命中条件
weapon、sword	材质名以 _sword 或 _axe 结尾。
armor、helmet、chestplate、leggings、boots	材质名以 _helmet、_chestplate、_leggings、_boots 之一结尾。
offhand、shield	材质名以 shield 结尾，或包含 totem。
tool	材质名以 _pickaxe、_axe、_shovel、_hoe 之一结尾。
其他任意值	回退为子串包含判定：材质名包含该值即命中。

WARNING

helmet、chestplate、leggings、boots 这四个名字与 armor 完全等价，都命中全部四种防具，并不会把范围收窄到对应部位。要精确限制到某个部位，请改用顶层 item_sources 列出具体物品源，或利用子串回退（例如只写 _helmet）。

同理，_axe 同时属于 weapon 与 tool，斧类会被两个分组同时命中。

id: enchanted_weapon_slots
slot_groups:
  - weapon
item_sources:
  - minecraft-diamond_sword
matcher:
  type: component
  component: enchantments
  operator: exists
slots:
  - index: 0
    type: attack

DANGER

三个字段全部留空（整个文件既没有 slot_groups、也没有 item_sources 和 matcher）时，这套插槽配置会匹配所有物品。从 match 迁移时如果漏了转换，就会落到这个状态。

从 match 迁移

旧版的 match 块（含 item_sources、slot_groups、lore_contains）已不再被读取。字段的去向：

旧字段	现在的写法
match.item_sources	提升为顶层 item_sources
match.slot_groups	提升为顶层 slot_groups
match.lore_contains	matcher 里的 type: component + component: lore + operator: contains，每条文本一个子条件

/gem convert-legacy 可以自动完成转换：

命令	行为
/gem convert-legacy	预演，只打印将要产生的差异，不改文件。
/gem convert-legacy confirm	实际改写 items/*.yml，并为每个文件留一份 .bak 备份。

--apply 与 confirm 等价。命令需要 emakigem.admin 权限。

WARNING

如果文件里同时存在 match 和已经写好的 matcher（或顶层 slot_groups），转换会报冲突并跳过该文件，需要手工合并后再执行。

转换命令建议先用预演模式看一遍再落盘。物品源会被直接提升为顶层 item_sources，不会写进 matcher，转换结果无需手工修正。

插槽定义（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"

slot_groups:
  - "weapon"

item_sources:
  - "minecraft-diamond_sword"

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:
    - 'send_message text="<gray>已识别可镶嵌装备：<yellow>%item_definition_id%</yellow></gray>"'

GUI 配置块与占位符

gui/gem/*.yml 与 gui/open/*.yml 里，slots 下的每个配置块用 type 声明它由哪个渲染器接管。带 type 的块由渲染器动态填充内容，块里写的 custom_name 与 lore 只是模板：渲染时按占位符替换。不带 type 的块（例如各种边框）是纯静态装饰，不参与占位符替换。

type 常量

type	适用界面	作用
target_item	镶嵌 / 开孔	目标装备展示位。
socket_info	镶嵌 / 开孔	插槽概况信息。
socket_slot	镶嵌 / 开孔	单个插槽格；声明多个槽位时按顺序对应插槽索引。
preview_display	镶嵌 / 开孔	待执行操作的预览。
confirm	镶嵌 / 开孔	确认执行按钮。
socket_summary	镶嵌	插槽统计汇总。
opener_item	开孔	开孔器投放位。
mode_inlay	镶嵌	切换到镶嵌模式。
mode_extract	镶嵌	切换到取出模式。
mode_upgrade	镶嵌	切换到升级模式。
mode_reroll_full	镶嵌	切换到全量洗炼模式。
mode_reroll_value	镶嵌	切换到数值洗炼模式。

未列出的 type 值不会被任何渲染器接管，该块会退化成静态物品。

占位符组

每类 type 提供一对占位符：标题用于 custom_name，行集合用于 lore。

type	标题占位符	行占位符
target_item	%target_title%	%target_lines%
socket_info	%info_title%	%info_lines%
socket_summary	%summary_title%	%summary_lines%
socket_slot	%slot_title%	%slot_lines%
preview_display	%preview_title%	%preview_lines%
confirm	%confirm_title%	%confirm_lines%
opener_item	%opener_title%	%opener_lines%
所有 mode_*	%mode_title%	%mode_lines%

所有 mode_* 块共用同一对占位符，具体文案由渲染器按该块的 type 决定，因此五个模式块的模板可以写得完全一样。

行占位符的展开规则

行占位符（%*_lines%）在 lore 中的行为与普通占位符不同：

写法	结果
整行只有 %x_lines%	按集合元素数量展开成多行，一个元素一行。
集合为空	展开成零行，该行消失。
行内混写（如 统计: %x_lines%）	不展开，仍是一行，前缀保留。
未提供的占位符	原样保留，会把 %key% 直接显示给玩家。

custom_name 只做标量替换，不做整行展开。

除标题与行占位符外，部分块还会额外提供标量占位符（例如插槽相关的 %slot%，开孔信息的 %item%、%opened%、%total%、%locked%），可在行文本里直接引用。

WARNING

升级插件后，plugins/EmakiGem/gui/ 下已存在的 GUI 文件不会被改动：默认 GUI 资源属于静态文件，只在目标路径不存在时才释放，既不会覆盖也不会与内置版本合并（只有 config.yml 与 lang/*.yml 走版本化合并）。因此老配置不会自动获得新增的 type 与占位符。需要用上新内容时，请手工补写对应配置块，或备份后删除该 GUI 文件让插件重新释放默认版本。

设计建议

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