商城核心 API

商城核心 API 提供商店管理、商品查询、购买记录、收藏夹、拍卖行、物品仓库等功能。所有方法通过 Malkuth.api 获取。

商店与商品

基础查询

方法	返回值	说明
getShop(shopId: String)	Shop?	根据 ID 获取商店实例，不存在返回 null
getGoods(goodsId: String)	Goods?	根据 ID 获取商品实例
getShopIds()	List<String>	获取所有已注册的商店 ID
getGoodsIds()	List<String>	获取所有已注册的商品 ID
isShopEnabled(player: Player, shopId: String)	Boolean	检查玩家是否有权访问指定商店

val api = Malkuth.api

// 获取商店
val shop = api.getShop("main_shop") ?: return

// 列出所有商店 ID
val allShops = api.getShopIds()
allShops.forEach { println(it) }

// 检查玩家是否可以访问
if (api.isShopEnabled(player, "vip_shop")) {
    // 玩家有权限
}

打开商店

方法	返回值	说明
openShop(player: Player, shopId: String)	Unit	为玩家打开指定商店 GUI

// 为玩家打开商店
api.openShop(player, "main_shop")

重载

方法	返回值	说明
reloadAll()	Unit	重载所有商店与商品配置

购买限制与计数

方法	返回值	说明
getPlayerPurchaseCount(uuid: UUID, shopId: String, goodsId: String)	Int	获取玩家对指定商品的已购买次数
getRemainingPurchaseLimit(player: Player, shopId: String, goodsId: String)	Int	获取玩家对指定商品的剩余可购买次数，-1 表示无限制

val uuid = player.uniqueId

// 查询已购买次数
val count = api.getPlayerPurchaseCount(uuid, "main_shop", "diamond_sword")

// 查询剩余可购买次数
val remaining = api.getRemainingPurchaseLimit(player, "main_shop", "diamond_sword")
if (remaining == 0) {
    player.sendMessage("你已达到该商品的购买上限")
}

动态定价

方法	返回值	说明
getEffectivePrice(shopId: String, goodsId: String)	Double	获取商品当前的实际价格（经过动态定价计算后的值）

// 获取动态定价后的实际价格
val price = api.getEffectivePrice("main_shop", "diamond_sword")
player.sendMessage("当前价格: $price")

提示

动态定价会根据全服购买量自动调整价格。getEffectivePrice 返回的是计算后的实时价格，而非配置文件中的基础价格。

交易记录

TransactionRecord

字段	类型	说明
uuid	UUID	玩家 UUID
shopId	String	商店 ID
goodsId	String	商品 ID
amount	Int	交易数量
price	Double	交易价格
type	String	交易类型（购买/回收/出售等）
timestamp	Long	交易时间戳

查询方法

方法	返回值	说明
getTransactions(uuid: UUID, limit: Int)	List<TransactionRecord>	获取玩家的交易记录，按时间倒序
getShopTransactions(shopId: String, limit: Int)	List<TransactionRecord>	获取指定商店的所有交易记录

// 获取玩家最近 10 条交易记录
val records = api.getTransactions(player.uniqueId, 10)
records.forEach { record ->
    println("${record.goodsId} x${record.amount} - ${record.price}")
}

// 获取商店最近 50 条交易记录
val shopRecords = api.getShopTransactions("main_shop", 50)

收藏夹

FavoriteRecord

字段	类型	说明
uuid	UUID	玩家 UUID
shopId	String	商店 ID
goodsId	String	商品 ID

方法

方法	返回值	说明
getFavorites(uuid: UUID)	List<FavoriteRecord>	获取玩家的所有收藏
hasFavorite(uuid: UUID, shopId: String, goodsId: String)	Boolean	检查是否已收藏
addFavorite(uuid: UUID, shopId: String, goodsId: String)	Unit	添加收藏
removeFavorite(uuid: UUID, shopId: String, goodsId: String)	Unit	移除收藏

val uuid = player.uniqueId

// 切换收藏状态
if (api.hasFavorite(uuid, "main_shop", "diamond_sword")) {
    api.removeFavorite(uuid, "main_shop", "diamond_sword")
} else {
    api.addFavorite(uuid, "main_shop", "diamond_sword")
}

// 获取所有收藏
val favorites = api.getFavorites(uuid)

物品邮件

方法	返回值	说明
sendMailItem(receiver: UUID, item: ItemStack, amount: Int, senderName: String, reason: String, message: String)	Unit	向玩家发送物品邮件
getUnclaimedMailCount(uuid: UUID)	Int	获取玩家未领取的邮件数量

// 发送物品邮件
api.sendMailItem(
    receiver = targetPlayer.uniqueId,
    item = itemStack,
    amount = 1,
    senderName = "系统",
    reason = "活动奖励",
    message = "恭喜你获得活动奖励！"
)

// 查询未领取邮件数
val count = api.getUnclaimedMailCount(player.uniqueId)
if (count > 0) {
    player.sendMessage("你有 $count 封未领取的邮件")
}

拍卖行

AuctionRecord

字段	类型	说明
seller	UUID	卖家 UUID
item	ItemStack	拍卖物品
price	Double	当前价格
startTime	Long	开始时间
endTime	Long	结束时间

方法

方法	返回值	说明
getActiveAuctions()	List<AuctionRecord>	获取所有进行中的拍卖
getPlayerAuctions(uuid: UUID)	List<AuctionRecord>	获取玩家发起的拍卖

// 获取所有进行中的拍卖
val auctions = api.getActiveAuctions()
auctions.forEach { auction ->
    println("卖家: ${auction.seller}, 价格: ${auction.price}")
}

// 获取玩家自己的拍卖
val myAuctions = api.getPlayerAuctions(player.uniqueId)

物品仓库

方法	返回值	说明
getRepositoryItem(category: String)	List<ItemStack>	获取指定分类下的仓库物品
getRepositoryCategories()	List<String>	获取所有仓库分类

// 列出所有仓库分类
val categories = api.getRepositoryCategories()

// 获取指定分类的物品
val items = api.getRepositoryItem("weapons")