装备模板
装备模板定义了哪些装备可以参与宝石系统，以及它们有哪些孔位。没有匹配到模板的装备无法进行任何宝石操作。模板文件存放在 items/ 目录下。
完整 YAML 格式
yaml
# items/diamond_sword.yml
# 模板唯一标识
id: "diamond_sword"
# ============================================================
# 匹配规则 (Match)
# 决定哪些物品适用此模板
# ============================================================
match:
# 物品来源匹配（支持多个）
item_sources:
- "minecraft-diamond_sword"
# 槽位组匹配（可选，限制装备槽位）
slot_groups:
- "HAND"
# Lore 包含匹配（可选，物品 Lore 中必须包含指定文本）
lore_contains:
- "可镶嵌"
# ============================================================
# 孔位定义 (Slots)
# ============================================================
slots:
- index: 0
type: "attack"
display_name: "<red>攻击孔位 I"
- index: 1
type: "attack"
display_name: "<red>攻击孔位 II"
- index: 2
type: "defense"
display_name: "<blue>防御孔位"
- index: 3
type: "universal"
display_name: "<gold>万能孔位"
# 默认已开启的孔位索引
default_open_slots:
- 0
# 允许的宝石类型（全局限制）
allowed_gem_types:
- "attack"
- "defense"
- "utility"
- "universal"
# 同类型宝石最大数量（0 = 不限）
max_same_type: 2
# 同 ID 宝石最大数量（0 = 不限）
max_same_id: 1
# ============================================================
# GUI 模板引用
# ============================================================
gui:
gem: "gem/default"
open: "open/default"
upgrade: "upgrade/default"
# ============================================================
# 结构化展示 (Structured Presentation)
# ============================================================
structured_presentation:
# 宝石段落在装备 Lore 中的渲染配置
section_id: "gem_slots"
header: "<gray>═══ 宝石孔位 ═══"
footer: "<gray>════════════"
# 已开启但未镶嵌的孔位显示
empty_slot_format: "<dark_gray> ○ {slot_display_name} - 空"
# 未开启的孔位显示
locked_slot_format: "<dark_gray> ✖ {slot_display_name} - 未开启"
# 已镶嵌的孔位显示
filled_slot_format: "<gray> ● {slot_display_name} - {gem_display_name}"默认装备模板一览
| 模板 ID | 匹配物品 | 孔位数 | 默认开启 | 说明 |
|---|---|---|---|---|
diamond_sword | 钻石剑 | 4 | 1 | 2 攻击 + 1 防御 + 1 万能 |
iron_armor | 铁质盔甲 | 3 | 1 | 2 防御 + 1 万能 |
executioner_greatsword | 自定义大剑 | 5 | 2 | 3 攻击 + 1 防御 + 1 万能 |
匹配规则说明
当玩家把装备放入 GUI 时，系统会遍历所有装备模板，用 match 节点判断这件装备属于哪个模板。
| 规则 | 说明 |
|---|---|
item_sources | 物品来源匹配，支持原版和第三方物品插件（如 CraftEngine、MMOItems 等） |
slot_groups | 装备槽位组限制（如 HAND、ARMOR），只有在对应槽位的装备才匹配 |
lore_contains | 物品 Lore 中必须包含的文本，所有条目都必须匹配（AND 关系） |
提示
三个匹配规则之间是 AND 关系——必须全部满足才算匹配。item_sources 是必填项，slot_groups 和 lore_contains 是可选的额外过滤条件。比如你想让只有 Lore 里写了"可镶嵌"的钻石剑才能用宝石系统，就同时配置 item_sources 和 lore_contains。
关于 max_same_type 和 max_same_id：这两个字段用来限制同一件装备上宝石的重复度。max_same_type 限制同类型宝石的数量（比如最多镶 2 颗攻击型宝石），max_same_id 限制同 ID 宝石的数量（比如最多镶 1 颗红宝石）。设为 0 表示不限制。
GUI 布局
gem/default — 宝石镶嵌/提取 GUI（5 行）
行 1: [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框]
行 2: [边框] [孔位0] [孔位1] [边框] [装备槽] [边框] [孔位2] [孔位3] [边框]
行 3: [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框]
行 4: [边框] [边框] [边框] [边框] [宝石槽] [边框] [边框] [边框] [边框]
行 5: [边框] [边框] [边框] [边框] [确认] [边框] [边框] [边框] [边框]- 装备槽（slot 13）：放入待操作的装备
- 孔位展示（slot 10, 11, 15, 16）：显示各孔位状态，点击孔位可以选择要操作的目标
- 宝石槽（slot 31）：镶嵌时放入宝石，提取时显示要取出的宝石
- 确认按钮（slot 40）：执行镶嵌或提取操作
open/default — 开孔 GUI（4 行）
行 1: [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框]
行 2: [边框] [装备槽] [边框] [孔位预览...] [边框] [开孔器槽] [边框]
行 3: [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框]
行 4: [边框] [边框] [边框] [边框] [确认] [边框] [边框] [边框] [边框]- 装备槽（slot 10）：放入待开孔的装备
- 开孔器槽（slot 16）：放入开孔器
- 确认按钮（slot 31）：执行开孔
upgrade/default — 升级 GUI（4 行）
行 1: [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框]
行 2: [边框] [宝石槽] [边框] [预览] [→] [结果预览] [边框] [材料槽] [边框]
行 3: [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框] [边框]
行 4: [边框] [边框] [边框] [边框] [确认] [边框] [边框] [边框] [边框]- 宝石槽（slot 10）：放入要升级的宝石
- 材料槽（slot 16）：放入升级材料
- 确认按钮（slot 31）：执行升级