事件系统

Malkuth 提供 34 个 Bukkit 事件，覆盖商城操作的完整生命周期。标记 ✅ 的事件可取消（isCancelled）。

事件一览

事件	可取消	说明
`PlayerOpenShopEvent`	✅	玩家打开商店前触发
`PlayerCloseShopEvent`	❌	玩家关闭商店后触发
`PlayerPurchaseEvent`	✅	玩家购买商品前触发
`PlayerPurchasePostEvent`	❌	玩家购买商品后触发
`PlayerRecycleEvent`	✅	玩家回收物品前触发
`PlayerRecyclePostEvent`	❌	玩家回收物品后触发
`PlayerSellEvent`	✅	玩家出售物品前触发
`PlayerSellPostEvent`	❌	玩家出售物品后触发
`PlayerBuyFromPlayerEvent`	✅	玩家从其他玩家购买前触发
`PlayerBuyFromPlayerPostEvent`	❌	玩家从其他玩家购买后触发
`PlayerGiftEvent`	✅	玩家赠送物品前触发
`PlayerGiftPostEvent`	❌	玩家赠送物品后触发
`PlayerCartCheckoutEvent`	✅	玩家购物车结算前触发
`PlayerCartCheckoutPostEvent`	❌	玩家购物车结算后触发
`PlayerAuctionBidEvent`	✅	玩家拍卖出价前触发
`PlayerAuctionBidPostEvent`	❌	玩家拍卖出价后触发
`AuctionBuyoutPreEvent`	✅	拍卖一口价结算前触发
`AuctionBuyoutPostEvent`	❌	拍卖一口价结算后触发
`GlobalMarketAnnouncementEvent`	✅	全球市场公告发送前触发
`GlobalMarketRenewPreEvent`	✅	全球市场挂单续期前触发
`GlobalMarketRenewPostEvent`	❌	全球市场挂单续期后触发
`GlobalRequestCreatePreEvent`	✅	全球求购创建前触发
`GlobalRequestCreatePostEvent`	❌	全球求购创建后触发
`GlobalRequestSubmitPreEvent`	✅	全球求购供货提交前触发
`GlobalRequestSubmitPostEvent`	❌	全球求购供货提交后触发
`GlobalRequestApprovePreEvent`	✅	全球求购同意供货前触发
`GlobalRequestApprovePostEvent`	❌	全球求购同意供货后触发
`GlobalRequestRejectPreEvent`	✅	全球求购拒绝供货前触发
`GlobalRequestRejectPostEvent`	❌	全球求购拒绝供货后触发
`GlobalRequestCancelPreEvent`	✅	全球求购取消前触发
`GlobalRequestCancelPostEvent`	❌	全球求购取消后触发
`GlobalRequestExpirePostEvent`	❌	全球求购过期处理后触发
`ShopRandomRefreshEvent`	✅	商店随机商品刷新时触发
`MalkuthReloadEvent`	❌	Malkuth 重载完成后触发

事件详情

PlayerOpenShopEvent

玩家打开商店前触发，取消后商店不会打开。

属性	类型	说明
`player`	`Player`	触发玩家
`shopId`	`String`	商店 ID

@EventHandler
fun onOpenShop(event: PlayerOpenShopEvent) {
    if (event.shopId == "vip_shop" && !event.player.hasPermission("shop.vip")) {
        event.isCancelled = true
        event.player.sendMessage("你没有权限打开 VIP 商店")
    }
}

PlayerCloseShopEvent

玩家关闭商店后触发，不可取消。

属性	类型	说明
`player`	`Player`	触发玩家
`shopId`	`String`	商店 ID

PlayerPurchaseEvent

玩家购买商品前触发，取消后购买不会执行。

属性	类型	说明
`player`	`Player`	购买玩家
`shopId`	`String`	商店 ID
`goodsId`	`String`	商品 ID
`amount`	`Int`	购买数量
`price`	`Double`	当前生效单价
`currency`	`String`	当前货币类型
`buyMode`	`String`	购买模式：`currency` / `items` / `hybrid`
`buyItemRequirements`	`List<BuyItemRequirement>`	物品支付需求列表；仅物物交换 / 混合支付时有值
`currencyCosts`	`List<CurrencyCost>`	实际货币费用明细；多货币时按配置顺序包含全部费用

CurrencyCost 的 currencyKey 是货币标识，unitPrice 是单件价格，totalPrice 是本次购买实际扣除金额。不要用 price 或 currency 字段替代多货币明细。

@EventHandler
fun onPurchase(event: PlayerPurchaseEvent) {
    // 限制单次购买数量
    if (event.amount > 64) {
        event.isCancelled = true
        event.player.sendMessage("单次购买不能超过 64 个")
    }

    if (event.buyMode == "items") {
        logger.info("本次购买使用物品支付，共 ${event.buyItemRequirements.size} 条需求")
    }
}

PlayerPurchasePostEvent

购买完成后触发，用于记录日志或发放额外奖励。

属性	类型	说明
`player`	`Player`	购买玩家
`shopId`	`String`	商店 ID
`goodsId`	`String`	商品 ID
`amount`	`Int`	购买数量
`price`	`Double`	当前成交单价
`currency`	`String`	兼容字段；单货币场景的当前货币类型
`currencyCosts`	`List<CurrencyCost>`	实际货币费用明细；多货币时按配置顺序包含全部费用

@EventHandler
fun onPurchasePost(event: PlayerPurchasePostEvent) {
    // 购买后按单价的 10% 发放积分
    PointsPlugin.addPoints(event.player, (event.price * 0.1).toInt())
}

PlayerRecycleEvent

玩家回收物品前触发，取消后回收不会执行。

属性	类型	说明
`player`	`Player`	回收玩家
`shopId`	`String`	商店 ID
`itemStack`	`ItemStack`	回收的物品
`price`	`Double`	回收价格

PlayerRecyclePostEvent

回收完成后触发。

属性	类型	说明
`player`	`Player`	回收玩家
`shopId`	`String`	商店 ID
`totalCount`	`Int`	本次回收的物品总数
`totalPrice`	`Double`	本次回收的总价格

PlayerSellEvent

玩家出售物品前触发（玩家交易模式）。

属性	类型	说明
`player`	`Player`	出售玩家
`shopId`	`String`	商店 ID
`goodsId`	`String`	商品 ID
`amount`	`Int`	出售数量
`price`	`Double`	出售价格

PlayerSellPostEvent

玩家出售物品完成后触发，不可取消。

属性	类型	说明
`player`	`Player`	出售玩家
`shopId`	`String`	商店 ID
`goodsId`	`String`	商品 ID
`amount`	`Int`	出售数量
`price`	`Double`	出售价格

PlayerBuyFromPlayerEvent

玩家从其他玩家购买物品前触发。

属性	类型	说明
`buyer`	`Player`	买家
`sellerUuid`	`UUID`	卖家 UUID
`shopId`	`String`	商店 ID
`itemDisplayName`	`String`	商品显示名称
`price`	`Double`	价格

PlayerBuyFromPlayerPostEvent

玩家间交易完成后触发。

属性	类型	说明
`buyer`	`Player`	买家
`sellerUuid`	`UUID`	卖家 UUID
`shopId`	`String`	商店 ID
`itemDisplayName`	`String`	商品显示名称
`price`	`Double`	价格

PlayerGiftEvent

玩家赠送物品前触发。

属性	类型	说明
`player`	`Player`	赠送者
`targetUuid`	`UUID`	接收者 UUID
`targetName`	`String`	接收者名称
`shopId`	`String`	商店 ID
`goodsId`	`String`	商品 ID
`amount`	`Int`	赠送数量
`price`	`Double`	赠送价格

PlayerGiftPostEvent

赠送完成后触发。

属性	类型	说明
`player`	`Player`	赠送者
`targetUuid`	`UUID`	接收者 UUID
`targetName`	`String`	接收者名称
`shopId`	`String`	商店 ID
`goodsId`	`String`	商品 ID
`amount`	`Int`	赠送数量
`price`	`Double`	赠送价格

PlayerCartCheckoutEvent

购物车结算前触发，取消后结算不会执行。

属性	类型	说明
`player`	`Player`	结算玩家
`itemCount`	`Int`	购物车中的商品种类数
`totalPrice`	`Double`	预估总价格

PlayerCartCheckoutPostEvent

购物车结算完成后触发，不可取消。

属性	类型	说明
`player`	`Player`	结算玩家
`successCount`	`Int`	成功购买的商品种类数
`totalSpent`	`Double`	兼容汇总值；混合货币结算请以 `currencyTotals` 为准
`failures`	`List<String>`	购买失败的商品列表
`currencyTotals`	`Map<String, Double>`	按货币键汇总的实际花费

PlayerAuctionBidEvent

玩家在拍卖行出价前触发。

属性	类型	说明
`player`	`Player`	出价玩家
`auctionId`	`String`	拍卖 ID
`currentPrice`	`Double`	当前价格
`newPrice`	`Double`	新出价金额

PlayerAuctionBidPostEvent

玩家拍卖出价完成后触发，不可取消。

属性	类型	说明
`player`	`Player`	出价玩家
`auctionId`	`String`	拍卖 ID
`previousPrice`	`Double`	出价前的价格
`newPrice`	`Double`	新出价金额

AuctionBuyoutPreEvent

玩家触发一口价结算前调用，可取消。取消后不会买断该拍卖。

属性	类型	说明
`player`	`Player`	触发一口价的玩家
`auctionRecord`	`AuctionRecord`	当前拍卖记录
`auctionId`	`String`	拍卖 ID，来自 `auctionRecord.auctionId`
`currentPrice`	`Double`	当前竞拍价
`buyoutPrice`	`Double`	一口价

AuctionBuyoutPostEvent

一口价结算完成后触发，不可取消。

属性	类型	说明
`player`	`Player`	触发一口价的玩家
`auctionRecord`	`AuctionRecord`	当前拍卖记录
`auctionId`	`String`	拍卖 ID，来自 `auctionRecord.auctionId`
`price`	`Double`	实际一口价成交金额

GlobalMarketAnnouncementEvent

全球市场公告发送前触发，可取消。取消后本次公告不会发送。

属性	类型	说明
`player`	`Player?`	触发公告的玩家，上架时通常是卖家，成交时通常是买家
`shopId`	`String`	全球市场商店 ID
`type`	`GlobalMarketAnnouncementEvent.Type`	`UPLOAD` 或 `SOLD`
`price`	`Double`	用于公告阈值和事件判断的价格
`vars`	`Map<String, Any?>`	公告占位符变量
`seller`	`Player?`	在线卖家实例，离线时可能为空
`itemSnapshot`	`ItemStack?`	公告关联物品快照

GlobalMarketRenewPreEvent

全球市场挂单续期前触发，可取消。取消后不会扣费或刷新到期时间。

属性	类型	说明
`player`	`Player`	续期玩家
`shopId`	`String`	全球市场商店 ID
`listingId`	`String`	挂单 ID
`renewCost`	`Double`	本次续期费用

GlobalMarketRenewPostEvent

全球市场挂单续期完成后触发，不可取消。

属性	类型	说明
`player`	`Player`	续期玩家
`shopId`	`String`	全球市场商店 ID
`listingId`	`String`	挂单 ID
`newExpireTime`	`Long`	新到期时间戳（毫秒）

全球求购事件

全球求购模式提供 11 个事件，覆盖求购创建、供货提交、审核成交、拒绝、取消和过期处理。

GlobalRequestCreatePreEvent

全球求购创建前触发，可取消。

属性	类型	说明
`player`	`Player`	创建求购的玩家
`shopId`	`String`	全球求购商店 ID
`sampleItem`	`ItemStack`	样品物品快照
`unitPrice`	`Double`	求购单价
`amount`	`Int`	目标数量
`matchMode`	`GlobalRequestOptions.MatchMode`	匹配方式
`note`	`String`	备注

GlobalRequestCreatePostEvent

全球求购创建完成后触发。

属性	类型	说明
`player`	`Player`	创建求购的玩家
`request`	`GlobalRequestEntity`	已创建的求购单
`sampleItem`	`ItemStack`	样品物品快照

GlobalRequestSubmitPreEvent

供货提交前触发，可取消。

属性	类型	说明
`player`	`Player`	供货玩家
`request`	`GlobalRequestEntity`	目标求购单
`item`	`ItemStack`	本次提交物品快照
`amount`	`Int`	本次提交数量

GlobalRequestSubmitPostEvent

供货提交完成后触发。

属性	类型	说明
`player`	`Player`	供货玩家
`request`	`GlobalRequestEntity`	目标求购单
`offer`	`GlobalRequestOfferEntity`	已创建的供货申请
`item`	`ItemStack`	提交物品快照

GlobalRequestApprovePreEvent

同意供货前触发，可取消。

属性	类型	说明
`player`	`Player`	审核玩家
`request`	`GlobalRequestEntity`	目标求购单
`offer`	`GlobalRequestOfferEntity`	供货申请
`totalPrice`	`Double`	本次成交总价

GlobalRequestApprovePostEvent

同意供货并完成结算后触发。

属性	类型	说明
`player`	`Player`	审核玩家
`request`	`GlobalRequestEntity`	更新后的求购单
`offer`	`GlobalRequestOfferEntity`	已同意的供货申请
`totalPrice`	`Double`	成交总价
`sellerIncome`	`Double`	供货者实收
`taxAmount`	`Double`	税费金额

GlobalRequestRejectPreEvent / GlobalRequestRejectPostEvent

拒绝供货前后触发；前置事件可取消。常用字段：player、request、offer。

GlobalRequestCancelPreEvent / GlobalRequestCancelPostEvent

取消求购前后触发；前置事件可取消。常用字段：player、request、admin，其中 admin 表示是否以管理员身份取消。

GlobalRequestExpirePostEvent

求购单过期处理完成后触发。

属性	类型	说明
`request`	`GlobalRequestEntity`	已过期处理的求购单
`returnedOffers`	`Int`	本次退回的供货申请数量
`refundedAmount`	`Double`	本次退回的托管金额

ShopRandomRefreshEvent

商店随机商品刷新时触发，可取消。取消后使用上一次的随机结果。

属性	类型	说明
`playerUuid`	`UUID`	玩家 UUID（始终有值）
`player`	`Player?`	在线玩家实例（离线刷新时为 `null`）
`shopId`	`String`	商店 ID
`randomResults`	`MutableMap<String, RandomSlotResult>`	随机结果（可修改）

注意

此事件在异步线程触发，监听器中不能直接操作 Bukkit API。

MalkuthReloadEvent

Malkuth 重载完成后触发，用于在重载后刷新缓存。

@EventHandler
fun onReload(event: MalkuthReloadEvent) {
    // 重载后刷新自定义缓存
    myCache.invalidateAll()
}

监听示例

import org.bukkit.event.EventHandler
import org.bukkit.event.Listener

class MalkuthListener : Listener {

    @EventHandler
    fun onPurchase(event: PlayerPurchaseEvent) {
        val player = event.player
        val goods = event.goodsId
        val price = event.price
        // 自定义逻辑
    }

    @EventHandler
    fun onPurchasePost(event: PlayerPurchasePostEvent) {
        // 购买完成后的处理
    }
}

备注

所有事件位于 kim.hhhhhy.malkuth.common.api.event 包下。可取消事件继承自 Cancellable，设置 isCancelled = true 即可阻止对应操作。

事件一览​

事件详情​

PlayerOpenShopEvent​

PlayerCloseShopEvent​

PlayerPurchaseEvent​

PlayerPurchasePostEvent​

PlayerRecycleEvent​

PlayerRecyclePostEvent​

PlayerSellEvent​

PlayerSellPostEvent​

PlayerBuyFromPlayerEvent​

PlayerBuyFromPlayerPostEvent​

PlayerGiftEvent​

PlayerGiftPostEvent​

PlayerCartCheckoutEvent​

PlayerCartCheckoutPostEvent​

PlayerAuctionBidEvent​

PlayerAuctionBidPostEvent​

AuctionBuyoutPreEvent​

AuctionBuyoutPostEvent​

GlobalMarketAnnouncementEvent​

GlobalMarketRenewPreEvent​

GlobalMarketRenewPostEvent​

全球求购事件​

GlobalRequestCreatePreEvent​

GlobalRequestCreatePostEvent​

GlobalRequestSubmitPreEvent​

GlobalRequestSubmitPostEvent​

GlobalRequestApprovePreEvent​

GlobalRequestApprovePostEvent​

GlobalRequestRejectPreEvent / GlobalRequestRejectPostEvent​

GlobalRequestCancelPreEvent / GlobalRequestCancelPostEvent​

GlobalRequestExpirePostEvent​

ShopRandomRefreshEvent​

MalkuthReloadEvent​

监听示例​