Ecosystem Integration (QinhSkills / Legendinlay / MagicGem)

Belongs to: Developer　·　Related: Provider and Bridge · Gem Sockets

QI manages integrations (action handlers, item sources, Provider bridges, external resolvers, layer contributors) uniformly through QinhIntegrationRegistry. This chapter covers the three built-in integrations.

---

1. Integration Registry

object QinhIntegrationRegistry {
    fun initDefaults()
    fun registerProviderBridge(bridge)
    fun registerExternalResolver(resolver)
    fun registerLayerContributor(contributor)
    fun registerBridgeHook(id, hook)
    fun registerActionHandler(handler)

    fun providerBridge(id): QinhProviderBridge?
    fun externalResolver(prefix): QinhExternalItemResolver?
    fun layerContributorsOrdered(): List<QinhItemLayerContributor>
    fun actionHandler(handlerId): QinhActionHandler?
    fun dispatchItemCompiled(event)
}

initDefaults() registers the default layer contributors: Base / Variables / Section / Affix.

---

2. QinhSkills Integration

The qinhskills:cast handler in item actions hands skill casting over to QinhSkills (QS).

Link Mechanism

QinhSkillsLinker, at load time:

1. If QinhSkills is present, loads com.qinhuai.skills.listener.QiListener through the QS class loader.
2. Adapts it via reflection into a QinhActionHandler and registers it under QISkillBridge.HANDLER_ID.
3. Calls QinhSkills.linkQinhItemsHandler(force) for a two-way link.

QinhSkillsLinker.requestHandlerRegistration(force = true)
QinhSkillsLinker.isRegistered(): Boolean

Late-Loading Support

QinhSkillsEnableListener listens for PluginEnableEvent; if QinhSkills is enabled after QI, it automatically triggers the link.

Dispatch Flow

item action triggered → refs contain qinhskills:cast → QI invokes the bridge handler → QS receives the skill cast request
payload: {"skill":"skillID","level":1}

---

3. Legendinlay Integration (Gem Socket Backend A)

Provider Bridge

object LegendinlayProviderBridge : QinhProviderBridge {
    override val providerId = "legendinlay"
    override fun isAvailable() = GemIntegrationBootstrap.isLegendinlayPresent()
    override fun parse(snapshot): BridgeParseResult?    // parses set/slot/piece/sockets/socket_lores
}

Payload Parsing

data class LegendinlayProviderMeta(
    val set: String?, val slot: String?, val piece: Int?,
    val socketIds: List<String>, val inlineSocketLores: Map<String,String>,
)
LegendinlayProviderParser.parse(blob): LegendinlayProviderMeta?

YAML payload example:

providers:
  legendinlay:
    value: '{"set":"sword_set","slot":"enhanced_1","sockets":["normal","bainian"],"socket_lores":{"normal":"Ten-Year Soul Ring socket"}}'

The lore in the socket catalog integrations/legendinlay_sockets.yml must match the LI side verbatim (LI identifies sockets by Lore); see Gem Sockets.

LegendCore Item Bridge

LegendCoreItemBridge registers QI into LegendCore's ItemManagerAPI via reflection, with aliases qi / qinhitems / QinhItems, and build(id) → QinhItemRegistry.create().

LegendCoreScriptDeployer deploys the groovy fallback script QinhItemsModule.groovy to LegendCore/groovy/, as a backup when the Kotlin reflection bridge fails (configured via legendinlay.auto-deploy-lc-script).

---

4. MagicGem Integration (Gem Socket Backend B)

object MagicGemProviderBridge : QinhProviderBridge {
    override val providerId = "magicgem"
    override fun isAvailable() = MagicGemBridge.isAvailable()
    override fun parse(snapshot): BridgeParseResult?
}

Shares the LegendinlayProviderParser parse format with Legendinlay. Socket catalog: integrations/magicgem_sockets.yml. Display hints include mg.set / mg.slot / mg.sockets / mg.socket_line_count.

---

5. Bridge Configuration

integrations/bridges.yml toggles each bridge independently:

azureflow:
  enabled: false

---

6. CoreLib Item Source Integration

QI registers itself as a CoreLib item source (QinhItemsItemSource, id qinhitems, alias qi). Other plugins can obtain QI items through CoreLib's ItemManagerAPI.getHookItem("qi:itemID").

Note: Prefix resolution (qi: / qinhitems:) lives in CoreLib, while item reverse-lookup (item → id) lives in QI. See API Overview → Integration Route for details.

---

Next Steps

• Provider and Bridge: bridge abstraction details
• Import / Export