物品源系统

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

MalkuthItem 对象

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

方法一览

方法	返回值	说明
getLoadedSources()	List<ItemSource>	获取所有已加载的物品源实例
get(source: String)	ItemSource?	根据名称精确获取物品源实例
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
}

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 内置了 33 个固定物品源 + 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 物品
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 物品（模组服支持）

备注

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