宝石孔（Legendinlay / MagicGem）

所属：服主指南　·　相关：物品定义 · 集成

QI 支持在装备上开宝石孔，对接两套后端：Legendinlay 和 MagicGem。QI 负责声明孔、渲染孔的 Lore，实际镶嵌逻辑由后端插件完成。

---

1. 三层概念

孔类型（GemSocketType）        ——你定义的孔种类（绿色孔 / 武器孔 / 护甲孔…）
   ├─ 映射到 Legendinlay 后端 socket
   └─ 映射到 MagicGem 后端 socket

物品的 gem-sockets             ——这件物品开了哪些孔（按类型 ID 列出）

providers.legendinlay/magicgem ——给后端的载荷（自动同步生成）

---

2. 定义孔类型

配置文件：integrations/gem_socket_types.yml。

types:
  绿色:
    display: "绿色"
    legendinlay: normal          # 映射到 Legendinlay 的 socket id
    magicgem: weapon_slot        # 映射到 MagicGem 的 socket id

  qi_weapon:
    display: "武器孔"
    legendinlay: qi_weapon

  armor:
    display: "护甲孔"
    magicgem: armor_slot
    lore: "<gray>◇ </gray><dark_gray>镶嵌孔</dark_gray>"   # 后端不可用时的兜底 Lore

键	含义
display	显示名（必填）
legendinlay	Legendinlay 后端 socket ID（可选）
magicgem	MagicGem 后端 socket ID（可选）
lore	后端目录都不可用时的兜底 Lore 行（可选）

---

3. 给物品开孔

在物品定义里用 gem-sockets（列表，每项是孔类型 ID）：

demo_thunder_edge:
  type: weapon                  # 类型须支持 GEM_SOCKET，见 物品类型
  gem-sockets:
    - 绿色
    - qi_weapon

也可用 GUI 编辑（见 其他编辑器 → 宝石孔）。

自动同步 provider

QI 会根据 gem-sockets 自动生成 providers.legendinlay / providers.magicgem 载荷（GemSocketService.syncProviders），无需手写。生成的载荷形如：

providers:
  legendinlay:
    value: '{"set":null,"slot":"weapon","sockets":["normal","qi_weapon"]}'

配置项 gem.inject-on-rebuild（默认 false）控制是否在 rebuild() 时也重新同步。

---

4. 孔 Lore 渲染优先级

每个孔的 Lore 按以下顺序解析（GemSocketService.resolveLore）：

1. Legendinlay 目录（若启用）：integrations/legendinlay_sockets.yml
2. MagicGem 目录（若启用）：integrations/magicgem_sockets.yml
3. 孔类型自带的 lore
4. 兜底目录搜索
5. 生成默认：[ + ] 空xxx槽

后端孔目录格式

legendinlay_sockets.yml：

sockets:
  normal:
    label: "十年魂环"
    lore: "十年魂环孔位"       # 必须与 Legendinlay 的 socket lore 精确一致（LI 靠 Lore 识别孔）
  qi_weapon:
    label: "武器孔"
    lore: "武器专属孔位"

magicgem_sockets.yml：

sockets:
  weapon_slot:
    lore: "§7✦ §8空宝石槽"
  armor_slot:
    lore: "§7◇ §8镶嵌孔"

⚠️ Legendinlay 用 Lore 行文本识别孔，所以 lore 必须和 LI 那边逐字一致，否则镶嵌识别不到。

---

5. 制作宝石物品

宝石本身就是一个 type: gem 的普通 QI 物品：

demo_emerald_gem:
  type: gem
  material: emerald
  display_name: "<green>翠绿宝石</green>"
  lore:
    - "<gray>可镶嵌入武器孔</gray>"
  options:
    max_stack_size: 64

镶嵌效果（属性加成等）由后端插件按其规则处理；QI 侧只管把宝石做成物品。

---

6. 开关与配置

config.yml：

gem:
  inject-sockets: true          # 是否渲染孔 Lore
  inject-on-rebuild: false      # rebuild 时是否重新同步 provider

legendinlay:
  enabled: true
  socket-catalog: integrations/legendinlay_sockets.yml
  auto-deploy-lc-script: true   # 自动部署 LegendCore 兜底 groovy 脚本

magicgem:
  enabled: true
  socket-catalog: integrations/magicgem_sockets.yml

---

7. PlaceholderAPI 占位符

GemPlaceholderProvider（标识 qinhitems），对玩家主手物品求值：

占位符	返回
%qinhitems_legendinlay_set% / %qinhitems_li_set%	Legendinlay 套装名
%qinhitems_magicgem_set% / %qinhitems_mg_set%	MagicGem 套装名
%qinhitems_socket_count% / %qinhitems_sockets%	已镶嵌孔数
%qinhitems_socket_total% / %qinhitems_socket_max%	总孔数

完整占位符见 占位符。

---

8. 开发者 API

GemSocketTypeRegistry.all(): List<GemSocketType>
GemSocketTypeRegistry.get(typeKey): GemSocketType?
GemSocketTypeRegistry.legendinlayId(typeKey): String?
GemSocketTypeRegistry.magicgemId(typeKey): String?

GemSocketService.readGemSocketsFromYaml(yaml): List<String>
GemSocketService.loreLines(definition): List<String>
GemSocketService.resolveLore(typeKey): String?
GemSocketService.syncProviders(definition): QinhItemDefinition

桥接细节见 集成。

🖼️ [图片占位] 带 2 个宝石孔的武器 hover（一个空孔、一个已镶嵌）　·　建议 assets/gem-sockets.png

---

下一步

• 灵魂绑定：绑定物品保护
• 集成：Legendinlay / MagicGem 桥接内部