商城核心 API

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

商店与商品

基础查询

方法	返回值	说明
getShop(shopId: String)	ShopSerializer?	根据 ID 获取商店序列化对象，不存在返回 null
getGoods(goodsId: String)	GoodsSerializer?	根据 ID 获取商品序列化对象，不存在返回 null
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, itemPage: Int = 0)	Boolean	为玩家打开指定商店 GUI，返回商店是否存在
openPlayerShop(player: Player, shopId: String, targetUuid: UUID)	Boolean	为玩家打开指定玩家商店，返回商店是否存在

// 为玩家打开商店（默认第一页）
api.openShop(player, "main_shop")

// 为玩家打开商店的第 2 页
api.openShop(player, "main_shop", itemPage = 1)

// 打开指定玩家的商店
api.openPlayerShop(player, "main_shop", targetUuid)

重载

方法	返回值	说明
reloadAll()	Unit	重载主配置、货币、商品、商店、UI、回收规则与语言文件，并清理主要运行时缓存

购买限制与计数

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

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, player: Player? = null)	Double	获取商品当前的实际价格（会综合条件价、随机价、动态价与活动折扣），商品不存在时返回 -1.0

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

// 传入玩家以计算条件定价
val personalPrice = api.getEffectivePrice("main_shop", "diamond_sword", player)

提示

getEffectivePrice 返回的是当前实时生效价，而不是配置里的基础价。传入 player 时，它还会把条件价一起算进去；如果商店配置了 schedule.discount，最终结果也会再乘上活动折扣。

交易记录

TransactionRecord

字段	类型	说明
uuid	UUID	买家 UUID
seller	String	卖家标识（"server" 表示系统商店）
shopId	String	商店 ID
goodsId	String	商品 ID
amount	Int	交易数量
price	Double	交易总价
timestamp	Long	交易时间戳（毫秒）
type	String	交易类型；这是开放字符串字段，常见值有 "buy"、"buy_items"、"buy_hybrid"、"sell"、"recycle"

查询方法

方法	返回值	说明
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
timestamp	Long	收藏时间戳（毫秒）

方法

方法	返回值	说明
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

字段	类型	说明
auctionId	String	拍卖唯一 ID
seller	UUID	卖家 UUID
startPrice	Double	起拍价
currentPrice	Double	当前最高出价
highestBidder	String	最高出价者标识
endTime	Long	拍卖结束时间戳（毫秒）
shopId	String	所属商店 ID
status	String	拍卖状态（"active" / "settled" / "cancelled"）
amount	Int	拍卖物品数量，默认 1
buyoutPrice	Double	一口价，0.0 表示未设置

方法

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

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

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

物品仓库

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

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

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

购物车

方法	返回值	说明
getCartItemCount(uuid: UUID)	Int	获取玩家购物车中的商品种类数
clearCart(uuid: UUID)	Unit	清空玩家购物车

val uuid = player.uniqueId

// 查询购物车商品数
val cartCount = api.getCartItemCount(uuid)
player.sendMessage("购物车中有 $cartCount 种商品")

// 清空购物车
api.clearCart(uuid)

通知

方法	返回值	说明
sendNotification(uuid: UUID, message: String)	Unit	向玩家发送通知消息，离线时排队等待上线投递

// 向玩家发送通知
api.sendNotification(player.uniqueId, "你的商品已售出！")