Doc ID: SIRC-065

Shopkeepers API 文档

Shopkeepers API 文档

Overview

Shopkeepers API 文档

包名

com.nisovin.shopkeepers.api

核心类

ShopkeepersAPI – 提供对Shopkeepers插件方法的静态访问器

API 启用状态检查

isEnabled()

检查API是否已启用

  • 返回: boolean – 如果启用返回true
  • 注意: 在插件启动早期调用时，即使返回true，API可能仍不安全使用

getPlugin()

获取ShopkeepersPlugin实例

  • 返回: ShopkeepersPlugin – 插件实例，不为null
  • 异常: IllegalStateException – 如果API当前未启用

权限相关方法

hasCreatePermission(Player player)

检查玩家是否有创建商店的权限

  • 参数: player – 玩家对象
  • 返回: boolean – 如果玩家可以创建商店返回true

商店类型相关

getShopTypeRegistry()

获取商店类型注册表

  • 返回: ShopTypesRegistry<?> – 商店类型注册表

getDefaultShopTypes()

获取默认商店类型

  • 返回: DefaultShopTypes – 默认商店类型

商店对象类型相关

getShopObjectTypeRegistry()

获取商店对象类型注册表

  • 返回: ShopObjectTypesRegistry<?> – 商店对象类型注册表

getDefaultShopObjectTypes()

获取默认商店对象类型

  • 返回: DefaultShopObjectTypes – 默认商店对象类型

UI相关

getUIRegistry()

获取UI注册表

  • 返回: UIRegistry<?> – UI注册表

getDefaultUITypes()

获取默认UI类型

  • 返回: DefaultUITypes – 默认UI类型

商店管理员注册表

getShopkeeperRegistry()

获取商店管理员注册表

  • 返回: ShopkeeperRegistry – 商店管理员注册表

存储相关

getShopkeeperStorage()

获取商店管理员存储

  • 返回: ShopkeeperStorage – 商店管理员存储

物品更新

updateItems()

为Shopkeepers插件存储的每个物品调用UpdateItemEvent

  • 功能:
    • 为每个已加载的商店管理员调用Shopkeeper.updateItems()
    • 为配置中的物品调用事件
    • 不调用交易历史中物品的事件
    • 可能中止当前打开的UI会话
    • 如果物品被更新，自动保存配置并触发存储保存
  • 返回: int – 更新的物品数量

商店创建

handleShopkeeperCreation(ShopCreationData shopCreationData)

以与玩家相同的方式创建和生成新的商店管理员

  • 参数: shopCreationData – 包含创建商店所需参数（生成位置、对象类型等）的商店创建数据
  • 返回: Shopkeeper – 新的商店管理员，如果创建不成功则返回null
  • 注意: 考虑可能影响创建者或所有者的限制，并在创建失败时向创建者发送消息

工厂方法（已弃用）

createPriceOffer(ItemStack item, int price)

创建新的PriceOffer

  • 参数:
    • item – 交易的物品，不能为null或空
    • price – 价格，必须为正数
  • 返回: PriceOffer – 新的报价
  • 弃用: 使用PriceOffer.create(ItemStack, int)

createPriceOffer(UnmodifiableItemStack item, int price)

创建新的PriceOffer（不可变版本）

  • 参数:
    • item – 交易的物品，不能为null或空
    • price – 价格，必须为正数
  • 返回: PriceOffer – 新的报价
  • 弃用: 使用PriceOffer.create(UnmodifiableItemStack, int)

createTradeOffer(ItemStack resultItem, ItemStack item1, ItemStack item2)

创建新的TradeOffer

  • 参数:
    • resultItem – 结果物品，不能为空
    • item1 – 第一个购买物品，不能为空
    • item2 – 第二个购买物品，可以为空
  • 返回: TradeOffer – 新的交易报价
  • 弃用: 使用TradeOffer.create(ItemStack, ItemStack, ItemStack)

createTradeOffer(UnmodifiableItemStack resultItem, UnmodifiableItemStack item1, UnmodifiableItemStack item2)

创建新的TradeOffer（不可变版本）

  • 参数:
    • resultItem – 结果物品，不能为空
    • item1 – 第一个购买物品，不能为空
    • item2 – 第二个购买物品，可以为空
  • 返回: TradeOffer – 新的交易报价
  • 弃用: 使用TradeOffer.create(UnmodifiableItemStack, UnmodifiableItemStack, UnmodifiableItemStack)

createBookOffer(String bookTitle, int price)

创建新的BookOffer

  • 参数:
    • bookTitle – 书籍标题，不能为null或空
    • price – 价格，必须为正数
  • 返回: BookOffer – 新的书籍报价
  • 弃用: 使用BookOffer.create(String, int)

导入的包和类

Bukkit相关

  • org.bukkit.entity.Player
  • org.bukkit.inventory.ItemStack
  • org.bukkit.plugin.Plugin

Shopkeepers API内部包

  • com.nisovin.shopkeepers.api.events.UpdateItemEvent
  • com.nisovin.shopkeepers.api.internal.InternalShopkeepersAPI
  • com.nisovin.shopkeepers.api.shopkeeper.DefaultShopTypes
  • com.nisovin.shopkeepers.api.shopkeeper.ShopCreationData
  • com.nisovin.shopkeepers.api.shopkeeper.ShopTypesRegistry
  • com.nisovin.shopkeepers.api.shopkeeper.Shopkeeper
  • com.nisovin.shopkeepers.api.shopkeeper.ShopkeeperRegistry
  • com.nisovin.shopkeepers.api.shopkeeper.offers.BookOffer
  • com.nisovin.shopkeepers.api.shopkeeper.offers.PriceOffer
  • com.nisovin.shopkeepers.api.shopkeeper.offers.TradeOffer
  • com.nisovin.shopkeepers.api.shopobjects.DefaultShopObjectTypes
  • com.nisovin.shopkeepers.api.shopobjects.ShopObjectTypesRegistry
  • com.nisovin.shopkeepers.api.storage.ShopkeeperStorage
  • com.nisovin.shopkeepers.api.ui.DefaultUITypes
  • com.nisovin.shopkeepers.api.ui.UIRegistry
  • com.nisovin.shopkeepers.api.util.UnmodifiableItemStack

使用示例

// 检查API是否启用
if (ShopkeepersAPI.isEnabled()) {
    // 获取插件实例
    ShopkeepersPlugin plugin = ShopkeepersAPI.getPlugin();
    
    // 检查玩家权限
    Player player = ...;
    boolean canCreate = ShopkeepersAPI.hasCreatePermission(player);
    
    // 获取商店管理员注册表
    ShopkeeperRegistry registry = ShopkeepersAPI.getShopkeeperRegistry();
    
    // 更新物品
    int updatedItems = ShopkeepersAPI.updateItems();
}

注意事项

  1. API访问器只能在API启用时使用
  2. 工厂方法已弃用，建议使用相应类的静态create方法
  3. 物品更新方法可能会中止当前打开的UI会话
  4. 商店创建方法会考虑所有限制并向创建者发送反馈消息