Skip to main content

QuickShop 自定义事件（开发者指南）

QuickShop-Hikari 提供了一个全面的自定义事件系统，让开发者能够将商店生命周期的几乎每个阶段绑定到交易和管理。

在 6.2.0.11 后，事件系统已经：

  • 全面重构
  • 分阶段（PRE/MAIN/POST）
  • 更加一致
  • 更可扩展
  • 更好地与 ShopType 和税收系统集成

此页面记录了开发者可用的支持的自定义事件。

此页最后更新版本为 6.2.0.11。

事件结构概述

所有 QuickShop 事件都会继承：AbstractQSEvent

所有事件都有阶段，且其生命周期可预测：

  • PRE（可取消）
  • MAIN（核心逻辑执行）
  • POST（执行后）

可取消的事件允许你安全阻止操作。

商店生命周期事件

这些事件涉及商店的创建、删除和状态更改。

ShopCreateEvent​

创建商店时触发。

  • 可取消
  • 在商店完全注册前触发
  • 可修改初始商店属性

常见用法：

  • 限制创建条件
  • 修改默认值
  • 强制执行区域规则

ShopDeleteEvent​

删除商店时触发。

  • 移除前触发
  • 可以用于日志记录或清理

常见用法：

  • 外部数据库同步
  • 自定义日志
  • 奖励退还

ShopDatabaseEvent​

商店保存、更新或持久化时触发。

常见用法：

  • 同步外部存储
  • 监视数据库更新
  • 统计数据

商店修改事件

商店属性被更改时触发。

ShopPriceEvent​

商店价格改变时触发。

  • 可取消（PRE 阶段）
  • 提供新旧价格

常见用法：

  • 强制执行价格上限
  • 应用动态定价规则
  • 联动经济平衡插件

ShopNameEvent​

商店名称改变时触发。

常见用法：

  • 屏蔽违规名称
  • 使用格式规则

ShopOwnerEvent​

商店转让时触发。

常见用法：

  • 限制转让
  • 同步权限
  • 审核日志

ShopUnlimitedEvent​

商店切换无限模式时触发。

常见用法：

  • 限制管理员不受限制
  • 强制自定义库存规则

商店类型事件

旧版的 ShopType 常量已经被更灵活的系统替代。

ShopTypeEnhancedEvent​

商店类型改变时触发。

支持：

  • SELLING
  • BUYING
  • FROZEN
  • 自定义商店类型（通过 IShopType 设置）

常见用法：

  • 限制特定的商店类型
  • 冻结/解冻相关操作
  • 更新外部地图或界面

交易事件

交易时触发。

ShopPreTransactionEvent​

处理交易前触发。

  • 可取消
  • 可验证

常见用法：

  • 阻止满足条件的交易
  • 应用自定义检查

ShopTransactionEvent​

交易进行时触发。

提供：

  • 买家
  • 卖家
  • 价格
  • 物品
  • 数量

常见用法：

  • 记录
  • 统计
  • 外部经济同步

ShopEnhancedTaxEvent​

计算税收时触发。

替换旧版税收事件。

提供：

  • 获取 TaxRates
  • 允许修改卖家税收
  • 允许修改买家税收
  • 交易构造器参考

常见用法：

  • VIP 减税
  • 动态税
  • 基于区域的税率倍率

限制事件

UserLimitCalculationEvent​

计算玩家拥有商店上限时触发。

允许：

  • 修改商店限制
  • 增加额外限度
  • 应用等级比例

常见用法：

  • 基于等级的奖励
  • 基于权限的商店限制
  • 基于活动的商店上限增加

交互事件

与玩家交互行为相关的事件。

InteractionPreEvent​

交互行为执行前触发。

  • 可取消
  • 提供 InteractionType
  • 提供 InteractionBehavior

常见用法：

  • 限制特定的点击类型
  • 重写交互逻辑

InteractionPostEvent​

交互执行后触发。

常见用法：

  • 统计
  • 记录
  • 刷新自定义界面

显示和视觉事件

ShopDisplayUpdateEvent​

展示物品更新时触发。

常见用法：

  • 替换显示逻辑
  • 同步外部地图标记
  • 自定义显示渲染

排版和格式事件

ShopLayoutResolveEvent​

解析告示牌排版时触发。

常见用法：

  • 注入自定义变量
  • 修改告示牌文本行
  • 分玩家显示格式

基于阶段的事件

许多事件继承了阶段事件的基础类。

例如：

  • PRE
  • MAIN
  • POST

监听事件时：

  • 若需取消或修改，请使用 PRE
  • 若需要记录或执行其他代码，请使用 POST

示例：

@EventHandler
public void onPriceChange(ShopPriceEvent event) {
    if (event.getNewPrice() < 0) {
        event.setCancelled(true);
    }
}

事件注册示例

@EventHandler
public void onTransaction(ShopTransactionEvent event) {

    Player buyer = event.getBuyer();
    double price = event.getPrice();

    buyer.sendMessage("你支付了 " + price);
}

确保你的类注册为 Bukkit 监听器。

已弃用事件（6.2.0.11）

如下旧版事件已被替换：

  • ShopTypeEvent → 替换为 ShopTypeEnhancedEvent
  • ShopTaxEvent → 替换为 ShopEnhancedTaxEvent
  • ShopUpdateEvent → 替换为 ShopDatabaseEvent

不要在新版本开发中使用这些已弃用事件。

最佳做法

  • 尽可能检查事件阶段。
  • 避免 PRE 阶段大量操作。
  • 不要用读写阻塞主线程。
  • 尊重取消状态。
  • 优先使用增强事件而非旧版事件。

总结

QuickShop-Hikari 对如下情况提供了事件：

  • 商店生命周期
  • 价格更新
  • 商店转让
  • 商店类型更改
  • 交易
  • 税收计算
  • 用户限制
  • 交互处理
  • 排版解析
  • 显示更新

6.2.0.11 事件系统的设计是为了：

  • 扩展性
  • 稳定性
  • 性能
  • 现代 API 结构

进阶集成建议使用 6.2.x 引入的增强事件变体。