物品源系统

Malkuth 通过物品源（ItemSource）系统支持 36 个固定物品源 + 1 个条件物品源（mod，仅 Mod 服务器生效），可从第三方插件或内置来源加载物品。你也可以注册自定义物品源。

MalkuthItem 对象

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

方法一览

方法	返回值	说明
getLoadedSources()	List<ItemSource>	获取所有已加载的物品源实例
get(source: String)	ItemSource?	根据名称精确获取物品源实例
findSource(source: String)	ItemSource?	忽略大小写按名称或别名查找物品源，未找到返回 null
normalizeSource(source: String)	String	返回已加载物品源的规范名称；未找到时返回去除首尾空白并转为小写的输入值
readSourceTrace(item: ItemStack)	ItemSourceTrace?	读取物品上的 Malkuth 来源追踪信息，未记录或读取失败时返回 null
getItemSourceId(item: ItemStack, sourceName: String? = null)	String	反向识别 source:itemId；指定来源时仅使用该来源，无法识别时返回空字符串
getSource(source: String)	ItemSource	根据名称或别名获取物品源，未找到时回退到 minecraft
register(instance: ItemSource)	Unit	注册自定义物品源
parse2ItemStack(id: String, player: Player?)	BuildSourceItem	解析物品 ID 为 BuildSourceItem

物品 ID 格式

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

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

解析物品

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

// 解析物品 ID 为 BuildSourceItem
val result = MalkuthItem.parse2ItemStack("mythicmobs:SkeletonKingSword", player)
player.inventory.addItem(result.itemStack)

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

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 构建出的 ItemStack
     */
    fun build(id: String, player: Player? = null): ItemStack

    /** 反向识别物品 ID，不匹配当前来源时返回空字符串 */
    fun getId(itemStack: ItemStack): String {
        val trace = MalkuthItem.readSourceTrace(itemStack) ?: return ""
        if (!trace.source.equals(name, ignoreCase = true)) {
            return ""
        }
        return formatId(trace.itemId)
    }

    /** 格式化为 name:itemId，空 ID 返回空字符串 */
    fun formatId(itemId: String): String {
        val normalized = itemId.trim()
        if (normalized.isEmpty()) {
            return ""
        }
        return "$name:$normalized"
    }

    /** 输出物品源错误消息并返回基岩占位物品 */
    fun warnItemNotFound(value: String): ItemStack {
        return buildItem(XMaterial.BEDROCK).also {
            console().sendLang("item-source-error", pluginName, value)
        }
    }
}

ItemSourceTrace

MalkuthItem.readSourceTrace 返回的来源追踪结构：

字段	类型	说明
source	String	物品源名称
itemId	String	物品源内部 ID

BuildSourceItem

字段	类型	说明
player	Player?	目标玩家
id	String	物品 ID
itemStack	ItemStack	构建出的物品
source	String	物品源插件名称

注册自定义物品源

import kim.hhhhhy.malkuth.common.api.item.ItemSource
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?): ItemStack {
        return MyPlugin.getItem(id) ?: warnItemNotFound(id)
    }
}

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

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

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

内置物品源

Malkuth 内置了 36 个固定物品源 + 1 个条件物品源，自动检测对应插件是否加载：

物品源名称	对应插件	说明
minecraft	—	原版物品
mythicmobs	MythicMobs	神话物品
itemsadder	ItemsAdder	IA 自定义物品
neigeitems	NeigeItems	NI 物品
mmoitems	MMOItems	MMO 物品
oraxen	Oraxen	Oraxen 自定义物品
zaphkiel	Zaphkiel	Zaphkiel 物品
craftengine	CraftEngine	CE 物品
baikiruto	Baikiruto	Baikiruto 物品
emakiitem	EmakiItem	EmakiItem 物品，别名 emaki / emaki-item / emaki_item
qinhitems	QinhItems	QinhItems 物品，别名 qinh / qi / qinh-items / qinh_items
overture	Overture	Overture 物品，别名 ovt / over
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	龙铠甲物品
repository	—	Malkuth 物品仓库
ecoarmor	EcoArmor	Eco 护甲
ecocrates	EcoCrates	Eco 宝箱
ecoitems	EcoItems	Eco 物品
ecomobs	EcoMobs	Eco 怪物掉落
ecopets	EcoPets	Eco 宠物物品
ecoscrolls	EcoScrolls	Eco 卷轴
reforges	Reforges	Eco 重铸物品
stattrackers	StatTrackers	Eco 统计追踪器
talismans	Talismans	Eco 护符
mod	—	Mod 物品（模组服支持），ID 使用 modid:item_id

备注

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

mod 是条件来源，只在 ModUtil.isModServer() 判定为 Mod 服务端时注册。Arclight、Mohist、Banner 等混合端上的模组注册表物品应使用 mod:modid:item_id，不要交给 minecraft 来源解析。