Doc ID: SIRC-077

ChestShop API 开发参考文档

ChestShop API 开发知识文档

Overview

ChestShop API 开发参考文档

基本信息

包结构

  • 主包名: com.acrobot.chestshop

事件API总览（该文档不全面 没有详细的接口信息）

ChestShop 采用事件驱动架构，以下是所有可用的事件分类：

1. 经济事件 (Economical Events) – 9个事件

  1. AccountCheckEvent – 检查账户是否存在
  2. AccountQueryEvent – 从商店招牌名称查询账户信息（用于自定义商店所有者如公会/派系）
  3. CurrencyAddEvent – 表示向实体添加货币
  4. CurrencyAmountEvent – 检查可用货币数量
  5. CurrencyCheckEvent – 检查指定货币数量是否存在
  6. CurrencyFormatEvent – 需要显示货币时的格式化事件
  7. CurrencyHoldEvent – 检查账户是否可以持有该金额的货币
  8. CurrencySubtractEvent – 表示从实体扣除货币
  9. CurrencyTransferEvent – 表示两个实体之间的商品交易

2. 交易事件 (Transaction Events) – 2个事件

  1. PreTransactionEvent – 预交易事件，可用于取消交易（例如玩家经验不足时）
  2. TransactionEvent – 交易后事件，交易完成后触发，可用于记录交易日志等

3. 商店事件 (Shop Events) – 3个事件

  1. PreShopCreationEvent – 商店创建时调用，可用于取消商店创建、修改招牌等
  2. ShopCreatedEvent – 商店创建后调用，可用于记录/奖励经验等
  3. ShopDestroyedEvent – 商店被销毁时调用

4. 保护事件 (Protection Events) – 3个事件

  1. BuildPermissionEvent – 检查是否可以在该位置创建商店，仅当所有使用此事件的插件都阻止使用时才会阻止商店创建
  2. ProtectBlockEvent – 通知保护插件保护方块，通常应在保护前检查方块是否已被保护
  3. ProtectionCheckEvent – 检查方块是否受保护以及事件中的玩家是否可以访问该方块

5. 杂项事件 (Miscellaneous Events) – 5个事件

  1. ShopInfoEvent – 可用于向 /shopinfo 命令或商店容器右键点击添加商店信息，是后操作事件
  2. ItemInfoEvent – 可用于向 /iteminfo 命令添加物品信息，或记录其使用情况，是后操作事件
  3. ItemStringQueryEvent – 查询代表招牌上物品的字符串，可用于提供自定义物品字符串
  4. ItemParseEvent – 从招牌字符串解析物品堆栈，可用于添加自定义物品功能或额外数据
  5. MaterialParseEvent – 从招牌字符串解析材料名称，可修改以支持自定义物品

实现自定义商店所有者

如果要实现自定义商店所有者（如派系/公会），需要监听以下事件：

必需事件

  1. PreShopCreationEvent – 在招牌上写入唯一名称/ID，而不是创建招牌的玩家名称
  2. AccountQueryEvent – 从招牌获取自定义账户
  3. AccountCheckEvent – 检查自定义账户是否仍然存在（例如解散后）
  4. Currency*Event – 所有货币事件都需要处理，以便将资金移动到自定义账户所有者（如果它们未原生集成Vault）

可选事件

  1. TransactionEvent – 可选，用于向所有者账户的成员发送消息
  2. PreTransactionEvent – 可选，在空商店时发送消息

开发指南

事件监听示例

@EventHandler
public void onShopCreation(PreShopCreationEvent event) {
    // 自定义商店创建逻辑
    if (shouldCancelCreation(event.getPlayer())) {
        event.setCancelled(true);
    }
}

@EventHandler
public void onAccountQuery(AccountQueryEvent event) {
    // 从招牌名称查询自定义账户
    String signName = event.getSignName();
    CustomAccount account = getCustomAccount(signName);
    if (account != null) {
        event.setAccount(account);
    }
}

注意事项

  1. 事件优先级: 根据需求设置适当的事件优先级
  2. 线程安全: 确保事件处理是线程安全的
  3. 性能考虑: 避免在事件处理中进行耗时操作
  4. 错误处理: 妥善处理异常，避免影响其他插件

版本兼容性

  • 当前文档基于 ChestShop 3.12.2 版本
  • 建议使用最新版本以获得完整功能支持
  • 注意不同版本间API可能的变化

常见用例

  1. 自定义经济系统集成 – 通过货币事件集成自定义经济插件
  2. 商店权限管理 – 通过保护事件实现复杂的权限控制
  3. 交易日志记录 – 使用交易事件记录所有商店交易
  4. 自定义物品支持 – 通过物品解析事件添加自定义物品类型
  5. 公会/派系商店 – 实现自定义商店所有者系统

资源链接

文档生成时间: ${new Date().toLocaleString()}
基于 SpigotMC Wiki 内容整理