API 概览

AIOShop 提供了完整的事件系统，方便开发者进行二次开发和插件集成。

事件系统

AIOShop 提供了 4 个核心事件，覆盖购买和出售的前后阶段：

事件	触发时机	可取消	线程
ShopPrePurchaseEvent	购买前	✅	主线程
ShopPostPurchaseEvent	购买后	❌	异步线程
ShopPreSellEvent	出售前	✅	主线程
ShopPostSellEvent	出售后	❌	异步线程

依赖配置

Maven

<dependency>
    <groupId>me.kzheart</groupId>
    <artifactId>aioshop</artifactId>
    <version>1.3.1</version>
    <scope>provided</scope>
</dependency>

Gradle

compileOnly("me.kzheart:aioshop:1.3.1")

快速示例

监听购买事件

import me.kzheart.aioshop.event.ShopPrePurchaseEvent
import me.kzheart.aioshop.event.ShopPostPurchaseEvent
import org.bukkit.event.EventHandler
import org.bukkit.event.Listener

class ShopListener : Listener {

    @EventHandler
    fun onPrePurchase(event: ShopPrePurchaseEvent) {
        val player = event.player
        val item = event.item
        val amount = event.amount
        val totalPrice = event.totalPrice

        // 检查是否在禁止交易的区域
        if (isInRestrictedArea(player)) {
            event.isCancelled = true
            event.cancelReason = "此区域禁止交易"
            return
        }

        player.sendMessage("你正在购买 $amount 个 ${item.displayName}")
    }

    @EventHandler
    fun onPostPurchase(event: ShopPostPurchaseEvent) {
        val transaction = event.transaction
        val player = event.player

        // 记录交易日志
        logger.info("${transaction.playerId} 购买了 ${transaction.amount} 个物品，花费 ${transaction.price}")

        // 发送 Discord 通知
        sendDiscordNotification(transaction)
    }
}

监听出售事件

import me.kzheart.aioshop.event.ShopPreSellEvent
import me.kzheart.aioshop.event.ShopPostSellEvent

class SellListener : Listener {

    @EventHandler
    fun onPreSell(event: ShopPreSellEvent) {
        val player = event.player
        val amount = event.amount

        // 自定义出售限制
        if (hasReachedDailyLimit(player)) {
            event.isCancelled = true
            event.cancelReason = "已达到今日出售上限"
        }
    }

    @EventHandler
    fun onPostSell(event: ShopPostSellEvent) {
        val transaction = event.transaction

        // 更新任务进度
        updateQuestProgress(transaction.playerId, "sell_items", transaction.amount)
    }
}

注册监听器

class MyPlugin : JavaPlugin() {
    override fun onEnable() {
        server.pluginManager.registerEvents(ShopListener(), this)
    }
}

使用场景

区域保护

在前置事件中检查玩家是否在允许交易的区域：

@EventHandler
fun onPrePurchase(event: ShopPrePurchaseEvent) {
    if (!canTrade(event.player.location)) {
        event.isCancelled = true
        event.cancelReason = "此区域禁止交易"
    }
}

交易日志

在后置事件中记录交易信息：

@EventHandler
fun onPostPurchase(event: ShopPostPurchaseEvent) {
    val t = event.transaction
    database.logTransaction(t.playerId, t.shopId, t.itemId, t.amount, t.price)
}

任务系统集成

统计玩家的购买/出售行为：

@EventHandler
fun onPostSell(event: ShopPostSellEvent) {
    questManager.updateProgress(
        event.transaction.playerId,
        "sell_diamonds",
        event.transaction.amount
    )
}

经济分析

收集交易数据用于经济分析：

@EventHandler
fun onPostPurchase(event: ShopPostPurchaseEvent) {
    analytics.recordPurchase(
        shopId = event.shop.id,
        itemId = event.item.id,
        price = event.transaction.price,
        amount = event.amount
    )
}