EconomyShopGUI API 文档

包名

me.gypopo.economyshopgui

核心API类

EconomyShopGUIHook – 主要API入口类

主要API方法

1. 获取物品价格（单次API调用）

Optional<BuyPrice> optional = EconomyShopGUIHook.getBuyPrice(owner, new ItemStack(Material.COBBLESTONE));

说明：自动检查所有条件，返回Optional或Optional

检查条件：

ShopItem是否在商店中找到
ShopItem是否有物品错误
ShopItem是否为显示物品
ShopItem是否可购买
物品数量是否小于最大购买限制
是否有足够的库存可用
玩家是否在线
玩家是否有权限访问商店部分
玩家是否有权限访问特定商店物品
玩家是否满足物品要求

2. 获取ShopItem对象

ShopItem shopItem = EconomyShopGUIHook.getShopItem(player, item);

说明：获取商店物品对象，自动验证权限和条件

检查条件：

ShopItem是否可出售
ShopItem是否有物品错误
ShopItem是否为显示物品
玩家是否有权限访问商店部分
玩家是否满足商店物品要求（Premium版）

3. 手动获取物品价格

EconomyShopGUIHook.getItemBuyPrice(shopItem, item, player, item.getAmount());

说明：获取物品的购买价格，自动计算折扣/出售倍数、定价倍数和动态定价

4. 检查最大交易限制

shopItem.isMaxBuy(amountToBuy);

说明：检查是否超过最大交易限制，返回false表示超过限制

5. 检查物品库存/限制

if (shopItem.getLimitedStockMode() != 0) {
    int stock = EconomyShopGUIHook.getItemStock(shopItem, player.getUniqueId());
    if (item.getAmount() > stock)
        return -1; // 库存限制达到，物品可能无法购买
}

说明：检查库存限制（Premium版功能）

6. 处理多个价格

Map<EcoType, Double> buyPrices;
if (EconomyShopGUIHook.hasMultipleBuyPrices(shopItem)) {
    Map<EcoType, Double> prices = !player.isOnline() ? 
        EconomyShopGUIHook.getMultipleBuyPrices(shopItem).getBuyPrices(null, item.getAmount()) :
        EconomyShopGUIHook.getMultipleBuyPrices(shopItem).getBuyPrices(null, (Player) player, item.getAmount());
    buyPrices.addAll(prices);
} else {
    double buyPrice = !player.isOnline() ? 
        EconomyShopGUIHook.getItemBuyPrice(shopItem, item.getAmount()) :
        EconomyShopGUIHook.getItemBuyPrice(shopItem, (Player) player, item.getAmount());
    buyPrices.put(shopItem.getEcoType(), buyPrice);
}

说明：处理多个价格（Premium版功能）

7. 更新物品库存

if (this.shopItem.getLimitedStockMode() != 0)
    EconomyShopGUIHook.buyItemStock(this.shopItem, this.player.getUniqueId(), this.amount);
if (this.shopItem.isDynamicPricing())
    EconomyShopGUIHook.buyItem(this.shopItem, this.amount);

说明：购买/出售后更新库存和动态定价

8. 使用不同的经济类型

EcoType type = shopItem.getEcoType();
EconomyProvider provider = EconomyShopGUIHook.getEcon(type);

支持的经济类型：

VAULT
PlayerPoints
CoinsEngine
UltraEconomy
GemsEconomy
VotingPlugin
zEssentials

9. 经济提供者操作

// 获取玩家余额
Double balance = provider.getBalance(player);

// 存款
provider.depositBalance(player, amount);

// 取款
provider.withdrawBalance(player, amount);

10. 获取Vault价格

double vaultPrice = buyPrices.getOrDefault(EconomyType.getFromString("VAULT"), -1d);

说明：从多个价格中获取Vault价格

11. 更新限制

price.updateLimits(); // 更新物品上设置的所有限制

说明：在返回物品价格之前更新任何库存限制

12. 获取价格映射

return price.getPrices();

说明：获取价格映射（支持多个价格）

13. 检查物品是否可购买

EconomyShopGUIHook.isBuyAble(shopItem);

说明：检查物品是否可购买

14. 检查物品是否可出售

EconomyShopGUIHook.isSellAble(shopItem);

说明：检查物品是否可出售

15. 获取物品库存

EconomyShopGUIHook.getItemStock(shopItem, UUID);

说明：获取特定玩家的物品库存

事件系统

1. PreTransactionEvent

触发时机：在任何商店交易之前调用
用途：允许取消事件（交易）或通过添加某些倍数来修改交易成本

2. PostTransactionEvent

触发时机：在任何商店交易之后调用
用途：允许任何插件监听并验证商店交易是否通过，并检查交易结果

3. ShopItemsLoadEvent

触发时机：当ShopItem可用并预加载时调用
用途：如果插件需要在服务器启动时与ShopItem对象交互，应监听此事件

重要注意事项

版本要求：API自EconomyShopGUI v3.9/1.12版本添加
兼容性：免费版和Premium版API相似，但Premium版有额外功能
插件依赖：应在plugin.yml中添加softdepend: [EconomyShopGUI, EconomyShopGUI-Premium]
权限检查：API自动检查玩家权限
库存限制：Premium版支持库存限制功能
多个价格：Premium版支持每个物品多个价格
动态定价：Premium版支持动态定价功能
经济类型：支持多种经济类型，需要正确处理

使用示例

基本使用模式：

// 获取ShopItem
ShopItem shopItem = EconomyShopGUIHook.getShopItem(player, item);
if(shopItem == null) {
    return -1; // ShopItem不存在/未找到，或玩家没有权限
}

// 检查最大交易限制
if(shopItem.isMaxBuy(amountToBuy)) {
    return -1; // 超过最大交易限制
}

// 检查库存限制
if (shopItem.getLimitedStockMode() != 0) {
    int stock = EconomyShopGUIHook.getItemStock(shopItem, player.getUniqueId());
    if (item.getAmount() > stock)
        return -1; // 库存限制达到
}

// 获取价格
double price = EconomyShopGUIHook.getItemBuyPrice(shopItem, item, player, item.getAmount());

// 更新限制
EconomyShopGUIHook.buyItemStock(shopItem, player.getUniqueId(), amount);

最佳实践

始终检查API方法的返回值是否为null或Optional是否为空
正确处理多个经济类型
在交易前后更新库存限制
监听相关事件以获得完整的交易信息
考虑Premium版功能的兼容性
使用API方法进行存款/取款操作，而不是直接操作经济系统

Overview