Doc ID: SIRC-067

UltimateShop API 知识文档

UltimateShop API 知识相关文档

Overview

UltimateShop API Documentation

包名和主要类

主包名： cn.superiormc.ultimateshop

API 包 (cn.superiormc.ultimateshop.api)

  • ShopHelper.java – 商店辅助工具类
  • ItemPreTransactionEvent.java – 交易前事件
  • ItemFinishTransactionEvent.java – 交易完成事件

管理器包 (cn.superiormc.ultimateshop.managers)

  • ConfigManager – 配置管理器
  • CacheManager – 缓存管理器
  • HookManager – 钩子管理器
  • LanguageManager – 语言管理器

对象包 (cn.superiormc.ultimateshop.objects)

  • ObjectShop – 商店对象
  • ObjectItem – 商品对象
  • ObjectUseTimesCache – 使用次数缓存
  • ObjectThingRun – 事物运行对象

物品包 (cn.superiormc.ultimateshop.objects.items)

  • AbstractSingleThing – 抽象单个事物
  • GiveResult – 给予结果
  • TakeResult – 获取结果
  • ObjectPrices – 价格对象

方法包 (cn.superiormc.ultimateshop.methods)

  • BuyProductMethod – 购买商品方法
  • SellProductMethod – 出售商品方法
  • ProductTradeStatus – 商品交易状态

核心 API 用法

1. 获取商店和商品对象

// 获取商店对象
ObjectShop shop = ConfigManager.configManager.getShop("shopID");

// 获取商品对象
ObjectItem item = shop.getProduct("productID");

// 获取商店所有商品列表
List<ObjectItem> items = shop.getProductList();

2. 购买商品

// 开始购买商品
BuyProductMethod.startBuy(
    Inventory inventory,      // 玩家库存
    String shop,              // 商店ID
    String product,           // 商品ID
    Player player,            // 玩家对象
    boolean quick,            // 是否快速购买（是否发送消息）
    boolean test,             // 是否测试模式（不实际扣除）
    int multi                 // 购买数量
);

3. 出售商品

// 开始出售商品
SellProductMethod.startSell(
    Inventory inventory,      // 玩家库存
    String shop,              // 商店ID
    String product,           // 商品ID
    Player player,            // 玩家对象
    boolean quick,            // 是否快速出售
    boolean test,             // 是否测试模式
    boolean ableMaxSell,      // 是否允许最大出售（用于出售所有命令）
    int multi                 // 出售数量
);

4. 缓存管理

// 获取玩家缓存对象
ObjectCache playerCache = CacheManager.cacheManager.playerCacheMap.get(player);

// 获取服务器缓存对象
ServerCache serverCache = CacheManager.cacheManager.serverCache;

// 获取玩家使用次数缓存
ObjectUseTimesCache useTimesCache = ShopHelper.getPlayerUseTimesCache(item, player);

// 获取服务器使用次数缓存
ObjectUseTimesCache serverUseTimesCache = ShopHelper.getServerUseTimesCache(item);

5. 价格查询

// 获取购买价格
TakeResult buyPrices = ShopHelper.getBuyPrices(items, player, 1);

// 获取出售价格
GiveResult sellPrices = ShopHelper.getSellPrices(items, player, 1);

// 获取购买价格显示
String buyDisplay = ShopHelper.getBuyPricesDisplay(items, player, 1);

// 获取出售价格显示
String sellDisplay = ShopHelper.getSellPricesDisplay(items, player, 1);

6. 交易操作

// 给予物品/货币（不检查限制）
int sellUseTimes = ShopHelper.getSellUseTimes(item, player);
GiveResult giveResult = ShopHelper.getSellPrices(items, player, 1);
giveResult.give(sellUseTimes, 1, player, 1.01);

// 扣除物品/货币（不检查限制）
int buyUseTimes = ShopHelper.getBuyUseTimes(item, player);
TakeResult takeResult = ShopHelper.getBuyPrices(items, player, 1);
if (!takeResult.getResultBoolean()) return "余额不足";
takeResult.take(buyUseTimes, 1, player.getInventory(), player);

7. 事件系统

ItemPreTransactionEvent (交易前事件)

  • 在开始扣除价格和给予玩家商品时触发
  • 可以修改 GiveResult 和 TakeResult
  • 交易可能因玩家库存满而失败
@EventHandler
public void onItemPreTransaction(ItemPreTransactionEvent event) {
    Player player = event.getPlayer();
    ObjectItem item = event.getItem();
    boolean isBuy = event.isBuyOrSell();
    int amount = event.getAmount();
    
    // 可以修改交易结果
    GiveResult giveResult = event.getGiveResult();
    TakeResult takeResult = event.getTakeResult();
}

ItemFinishTransactionEvent (交易完成事件)

  • 所有交易步骤完成后触发
  • 只读事件
@EventHandler
public void onItemFinishTransaction(ItemFinishTransactionEvent event) {
    Player player = event.getPlayer();
    ObjectShop shop = event.getShop();
    ObjectItem item = event.getItem();
    boolean isBuy = event.isBuyOrSell();
    int amount = event.getAmount();
}

8. 钩子系统

经济插件钩子

public class YourEconomyHook extends AbstractEconomyHook {
    public YourEconomyHook() {
        super("YourPluginName");
    }
    
    @Override
    public double getEconomy(Player player, String currencyID) {
        // 获取玩家余额
    }
    
    @Override
    public void takeEconomy(Player player, double value, String currencyID) {
        // 扣除玩家余额
    }
    
    @Override
    public void giveEconomy(Player player, double value, String currencyID) {
        // 给予玩家余额
    }
}

// 注册钩子
HookManager.hookManager.registerNewEconomyHook("YourPluginName", new YourEconomyHook());

物品插件钩子

  • 与经济插件钩子类似，继承 AbstractItemHook

9. 实用方法

// 根据ID获取商品
ObjectItem item = ShopHelper.getItemFromID("shopID", "productID");

// 获取目标商品（从物品堆中识别）
ObjectItem targetItem = ShopHelper.getTargetItem(itemStacks, player);

// 获取购买次数
int buyTimes = ShopHelper.getBuyUseTimes(item, player);

// 获取出售次数
int sellTimes = ShopHelper.getSellUseTimes(item, player);

// 出售所有物品
Map<AbstractSingleThing, BigDecimal> sellAllResult = ShopHelper.sellAll(player, inventory, multiplier);

10. 价格和商品格式

EconomyFormat (经济格式)

  • 用于定义经济价格
  • 支持多种经济插件

ItemFormat (物品格式)

  • 用于定义物品价格和商品
  • 支持多种物品插件
// 检查价格是否为Vault经济
Map<AbstractSingleThing, BigDecimal> resultMap = takeResult.getResultMap();
for (AbstractSingleThing singleThing : resultMap.keySet()) {
    if (singleThing.getSingleSection().getString("economy-plugin", "").equals("Vault")) {
        return "此价格包含Vault经济";
    }
}

变量系统

内置变量

  • 数学变量
  • 随机变量（仅付费版）
  • 条件变量（仅付费版）
  • 折扣变量

变量用法

  • 可以在数字类型选项中使用占位符和数学符号
  • 可以设置动态库存、商品数量、价格数量等
  • 支持基于玩家等级的价格设置

重要注意事项

  1. 动态显示：UltimateShop不是传统的商店插件，可以动态显示商品和价格
  2. 多对多关系：商品和价格之间是多对多关系
  3. 条件系统：可以通过条件系统自由控制
  4. 限制检查：使用 BuyProductMethod 和 SellProductMethod 会自动检查购买/出售限制
  5. 直接操作：使用 GiveResult.give() 和 TakeResult.take() 不会检查限制

兼容性

支持的经济插件

  • Vault
  • PlayerPoints
  • 及其他10+经济插件

支持的物品插件

  • MMOItems
  • ItemsAdder
  • Oraxen
  • MythicMobs
  • CraftEngine
  • 及其他15+物品插件

版本信息

  • 当前版本：4.2.2+（基于GitHub提交记录）
  • 支持Minecraft版本：1.14-1.21.4
  • 支持服务器类型：Folia, Paper, Purpur, Spigot

内容来自 SnowCutieOwO – Wiki