集成实操手册（逐插件）

所属：开发者　·　相关：集成（架构） · 属性与数值 · 宝石孔

集成 讲架构，本页讲从装到联调的完整步骤——给服主和开发者照着接每个外部插件。

---

一、AttributePlus（属性后端）

QI 的数值后端。没它则进入纯物品库模式（物品能造、动作能触发，但属性不上身）。

步骤

1. 安装 AttributePlus，放进 plugins/，启动一次让它生成 plugins/AttributePlus/attribute.yml。
2. 在 AP 里定义属性（attribute.yml），记下你给每个属性起的显示名（默认可能只有「物理伤害」）。
3. 在 QI 的 config.yml 配映射，把 QI 内部键映射到你 AP 的显示名：

   attribute-mapping:
     attack_damage: "物理伤害"     # 右边填你 AP 里的真实名
     health: "生命"
     defense: "防御"

4. 确认 combat 开启：

   combat:
     enabled: true
     attribute-backend: auto       # 自动检测 AP

5. /qi reload，看启动 / 重载日志：属性后端: attributeplus (已接入) = 成功。
6. 给物品配属性：

   my_sword:
     providers:
       ap:
         value: '{"attack_damage":18}'

7. 装备物品 → 看玩家 AP 面板是否加了对应属性。

排错

现象	原因 / 修法
日志显示 noop	没装 AP，或 combat.enabled: false
属性数字显示但不上身	纯物品库模式；或映射名与 AP 不符（控制台会警告）
控制台警告映射名不存在	attribute-mapping 右边的名字在 AP 里不存在，改成一致

完整说明见 属性与数值。

开发者：接自定义属性系统

不用 AP 而用别的属性插件？实现 AttributeBackend 并注册：

class MyBackend : AttributeBackend {
    override val id = "mybackend"
    override fun isAvailable() = true
    override fun apply(player, source, attributeLines): Boolean { /* 应用 */ return true }
    override fun remove(player, source): Boolean { /* 移除 */ return true }
}
QinhCombatAPI.registerAttributeBackend(MyBackend())

---

二、QinhSkills（技能引擎）

物品动作 / 套装技能里的 qinhskills:cast 把技能释放交给 QS。

步骤

1. 安装 QinhSkills（及其依赖）。QI 与 QS 谁先启动都行——QI 用 QinhSkillsEnableListener 支持晚加载链接。
2. 启动后看 QI 启动日志的 Action Handler 列表是否含 qinhskills:cast（已链接）。
3. 在物品里调用技能：

   actions:
     triggers:
       left_click:
         trigger: { atom: left_click }
         refs:
           - handler: qinhskills:cast
             payload: '{"skill":"fireball","level":1}'

4. 在套装里调用（注意 handler 用 map 形式）：

   abilities:
     - trigger: right_click
       cooldown: 5s
       actions:
         - {handler: "qinhskills:cast", payload: "套装爆发技能名"}

5. 左键 / 触发条件 → QS 收到技能释放请求。

排错

现象	原因
HANDLER_UNAVAILABLE	QinhSkills 未加载 / 未启用
技能名无效	payload 的 skill 在 QS 里不存在；QI 原样透传不校验
套装技能不触发	handler 用了字符串简写被首冒号拆错，改 map 形式

链接机制见 集成 → QinhSkills。

---

三、Legendinlay（宝石孔后端 A）

步骤

1. 安装 Legendinlay（及 LegendCore）。
2. 确认 QI 配置开启：

   legendinlay:
     enabled: true
     socket-catalog: integrations/legendinlay_sockets.yml
     auto-deploy-lc-script: true

3. 定义孔类型（integrations/gem_socket_types.yml），映射到 LI 的 socket：

   types:
     qi_weapon:
       display: "武器孔"
       legendinlay: qi_weapon       # 对应 LI 的 socket id

4. 配 LI 孔目录（integrations/legendinlay_sockets.yml），lore 必须与 LI 那边逐字一致：

   sockets:
     qi_weapon:
       label: "武器孔"
       lore: "武器专属孔位"

5. 给装备开孔（YAML 或 GUI）：

   my_sword:
     gem-sockets:
       - qi_weapon

6. /qi reload。启动日志看 宝石: LI(LC✔·N孔)。
7. 玩家用 LI 的镶嵌界面对该装备镶嵌宝石。

LegendCore 兜底

auto-deploy-lc-script: true 时 QI 自动把 QinhItemsModule.groovy 部署到 LegendCore/groovy/ 并 lce reload，作为 Kotlin 反射桥失败时的备份。检查日志的 检查 LegendCore/groovy/QinhItemsModule.groovy。

排错

现象	原因
镶嵌界面识别不到孔	LI 孔目录 lore 与 LI 那边不一致（必须逐字相同）
qi- 前缀取不到物品	LegendCore 桥未注册，检查 groovy 脚本部署

详见 宝石孔 与 集成 → Legendinlay。

---

四、MagicGem（宝石孔后端 B）

与 Legendinlay 并存或二选一。

步骤

1. 安装 MagicGem。
2. QI 配置：

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

3. 孔类型映射（gem_socket_types.yml）：

   types:
     armor:
       display: "护甲孔"
       magicgem: armor_slot

4. MG 孔目录（integrations/magicgem_sockets.yml）：

   sockets:
     armor_slot:
       lore: "§7◇ §8镶嵌孔"

5. 开孔、/qi reload，日志看 MG(N孔)。

共用 LegendinlayProviderParser 解析格式。详见 集成 → MagicGem。

---

五、PlaceholderAPI

1. 安装 PlaceholderAPI。
2. QI 自动注册 qinhitems 扩展。
3. 在计分板 / Tab / 全息等用占位符（对主手物品求值）：

   %qinhitems_socket_count%   %qinhitems_li_set%

完整占位符见 占位符。

---

六、CoreLib 物品源（让别的插件取 QI 物品）

QI 把自己注册成 CoreLib 物品源（id qinhitems，别名 qi）。其它插件：

// 通过 CoreLib 前缀解析（注意：前缀解析在 CoreLib）
ItemStack s = ItemManagerAPI.getHookItem("qi:demo_thunder_edge");

或直接用 QI API（反查物品归属只有 QI 有）：

String id = QinhItemsAPI.INSTANCE.getItemId(stack);
ItemStack s = QinhItemsAPI.INSTANCE.assembly().build("demo_thunder_edge", 1);

接入路线对比见 API 概览。

---

下一步

• 集成（架构）：桥 / 注册表内部
• API 配方集：市场 / 邮件 / 抽奖等完整代码
• Provider 与桥