物品源系统

Malkuth 通过物品源（ItemSource）系统支持从 30+ 个第三方插件加载物品。你也可以注册自定义物品源。

MalkuthItem 对象

MalkuthItem 是物品源管理的核心对象，位于 kim.hhhhhy.malkuth.common.api.item 包下。

方法一览

方法	返回值	说明
getLoadedSources()	List<String>	获取所有已加载的物品源名称
get(source: String)	ItemSource?	根据名称获取物品源实例
getSource(source: String)	ItemSource?	同 get，别名方法
register(instance: ItemSource)	Unit	注册自定义物品源
parse2ItemStack(id: String, player: Player?)	ItemStack?	解析物品 ID 为 ItemStack

物品 ID 格式

Malkuth 使用 source:itemId 格式标识物品：

minecraft:diamond_sword     → 原版钻石剑
mythicmobs:SkeletonKingSword → MythicMobs 物品
itemsadder:custom_gem       → ItemsAdder 物品

解析物品

import kim.hhhhhy.malkuth.common.api.item.MalkuthItem

// 解析物品 ID 为 ItemStack
val item = MalkuthItem.parse2ItemStack("mythicmobs:SkeletonKingSword", player)
if (item != null) {
    player.inventory.addItem(item)
}

// 获取所有已加载的物品源
val sources = MalkuthItem.getLoadedSources()
sources.forEach { println("已加载物品源: $it") }

ItemSource 接口

自定义物品源需要实现 ItemSource 接口：

import kim.hhhhhy.malkuth.common.api.item.ItemSource

interface ItemSource {

    /** 物品源名称（唯一标识） */
    val name: String

    /** 物品源别名列表（可选的替代名称） */
    val alias: List<String>

    /** 所属插件名称 */
    val pluginName: String

    /** 该物品源对应的插件是否已加载 */
    val isLoaded: Boolean

    /**
     * 根据物品 ID 构建 ItemStack
     * @param id 物品 ID（不含 source: 前缀）
     * @param player 目标玩家（部分物品源需要玩家上下文）
     * @return 构建结果，失败返回 null
     */
    fun build(id: String, player: Player?): BuildSourceItem?
}

BuildSourceItem

字段	类型	说明
itemStack	ItemStack	构建出的物品
source	String	物品源名称
id	String	物品 ID

注册自定义物品源

import kim.hhhhhy.malkuth.common.api.item.ItemSource
import kim.hhhhhy.malkuth.common.api.item.BuildSourceItem
import kim.hhhhhy.malkuth.common.api.item.MalkuthItem

class MyItemSource : ItemSource {

    override val name = "myplugin"
    override val alias = listOf("mp", "my")
    override val pluginName = "MyPlugin"
    override val isLoaded: Boolean
        get() = Bukkit.getPluginManager().isPluginEnabled("MyPlugin")

    override fun build(id: String, player: Player?): BuildSourceItem? {
        val item = MyPlugin.getItem(id) ?: return null
        return BuildSourceItem(
            itemStack = item,
            source = name,
            id = id
        )
    }
}

// 注册物品源
MalkuthItem.register(MyItemSource())

注册后即可在商店配置中使用：

goods:
  - id: "my_item"
    source: "myplugin:custom_item"

内置物品源

Malkuth 内置了 30+ 个物品源，自动检测对应插件是否加载：

物品源名称	对应插件	说明
minecraft	—	原版物品
mythicmobs	MythicMobs	神话物品
itemsadder	ItemsAdder	IA 自定义物品
neigeitems	NeigeItems	NI 物品
mmoitems	MMOItems	MMO 物品
oraxen	Oraxen	Oraxen 自定义物品
zaphkiel	Zaphkiel	Zaphkiel 物品
craftengine	CraftEngine	CE 物品
sxitem	SX-Item	SX 物品
slimefun	Slimefun	粘液科技物品
headdatabase	HeadDatabase	头颅数据库
executableitems	ExecutableItems	EI 物品
azureflow	AzureFlow	AzureFlow 物品
magicgem	MagicGem	魔法宝石
pxrpg	PxRPG	PxRPG 物品
ratziel	Ratziel	Ratziel 物品
customfishing	CustomFishing	自定义钓鱼物品
nexo	Nexo	Nexo 物品
nova	Nova	Nova 物品
hmccosmetics	HMCCosmetics	HMC 装饰物品
sertraline	Sertraline	Sertraline 物品
dragonarmourers	DragonArmourers	龙铠甲物品
eco	Eco	Eco 核心物品
ecoitems	EcoItems	Eco 物品
ecoarmor	EcoArmor	Eco 护甲
ecoscrolls	EcoScrolls	Eco 卷轴
talismans	Talismans	Eco 护符
ecobosses	EcoBosses	Eco Boss 掉落
ecojobs	EcoJobs	Eco 职业物品
ecopets	EcoPets	Eco 宠物物品
ecoskills	EcoSkills	Eco 技能物品
reforges	Reforges	Eco 重铸物品
mod	—	Mod 物品（模组服支持）

备注

物品源的 isLoaded 属性会在运行时动态检测对应插件是否启用。未安装对应插件的物品源不会影响 Malkuth 正常运行。