API Getting Started
🔌 ShopMaster API
ShopMaster provides a flexible API for developers to interact with player rewards, sell services, and shop items.
📖 Introduction
The API allows you to access and modify player rewards, interact with shop services, and integrate with custom systems.
⚙️ Setup
To use the API, include the following in your Maven project.
📦 Maven Configuration
Replace VERSION with the plugin version or tag you want to use.
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.xShyo</groupId>
<artifactId>ShopMaster-API</artifactId>
<version>VERSION</version>
</dependency>
</dependencies>📋 plugin.yml
In your plugin.yml, you must add:
depend: [ShopMaster]This ensures your plugin loads after ShopMaster is initialized.
🧰 API Package
Main package:
package xshyo.us.shopMaster.api;📚 Imports
package xshyo.us.shopMaster.api;
import lombok.Getter;
import lombok.Setter;
import org.bukkit.Material;
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import xshyo.us.shopMaster.ShopMaster;
import xshyo.us.shopMaster.services.SellService;
import xshyo.us.shopMaster.services.records.SellAllResult;
import xshyo.us.shopMaster.services.records.SellResult;
import xshyo.us.shopMaster.shop.data.ShopItem;
/**
* API for ShopMaster plugin that provides access to shop functionality.
* This API allows developers to interact with the shop system to check if items are sellable
* and retrieve shop item information.
*/
@Getter
@Setter
public class ShopMasterAPI {
/**
* Calculates the sell price for a stack of items.
*
* @param itemStack The stack of items to calculate the sell price for.
* @return The total sell price for the item stack, or -1.0 if there is a problem.
*/
public static double getItemStackPriceSell(ItemStack itemStack) {
// Check if itemStack is null
if (itemStack == null) {
return -1.0;
}
ShopItem shopItem = getShopItem(itemStack);
// Check if the item exists in the shop
if (shopItem == null) {
return -1.0;
}
try {
int amount = itemStack.getAmount();
double unitPrice = shopItem.getSellPrice();
double baseAmount = shopItem.getAmount(); // Minimum quantity in the shop
if (baseAmount > 1) {
unitPrice = unitPrice / baseAmount; // Adjust unit price
}
return unitPrice * amount;
} catch (Exception e) {
// Any other unexpected error
return -1.0;
}
}
/**
* Calculates the sell price for a stack of items specific to a player.
* This version considers player-specific permissions or discounts.
*
* @param player The player for whom the price is calculated.
* @param itemStack The stack of items to calculate the sell price for.
* @return The total sell price for the item stack, or -1.0 if there is a problem.
*/
public static double getItemStackPriceSell(Player player, ItemStack itemStack) {
// Check if player or itemStack are null
if (player == null || itemStack == null) {
return -1.0;
}
ShopItem shopItem = getShopItemPlayer(player, itemStack);
// Check if the item exists in the shop for this player
if (shopItem == null) {
return -1.0;
}
try {
int amount = itemStack.getAmount();
double unitPrice = shopItem.getSellPrice();
double baseAmount = shopItem.getAmount(); // Minimum quantity in the shop
if (baseAmount > 1) {
unitPrice = unitPrice / baseAmount; // Adjust unit price
}
return unitPrice * amount;
} catch (Exception e) {
// Any other unexpected error
return -1.0;
}
}
/**
* Calculates the buy price for a stack of items.
*
* @param itemStack The stack of items to calculate the buy price for.
* @return The total buy price for the item stack, or -1.0 if there is a problem.
*/
public static double getItemStackPriceBuy(ItemStack itemStack) {
// Check if itemStack is null
if (itemStack == null) {
return -1.0;
}
ShopItem shopItem = getShopItem(itemStack);
// Check if the item exists in the shop
if (shopItem == null) {
return -1.0;
}
try {
int amount = itemStack.getAmount();
double unitPrice = shopItem.getBuyPrice();
double baseAmount = shopItem.getAmount(); // Minimum quantity in the shop
if (baseAmount > 1) {
unitPrice = unitPrice / baseAmount; // Adjust unit price
}
return unitPrice * amount;
} catch (Exception e) {
// Any other unexpected error
return -1.0;
}
}
/**
* Calculates the buy price for a stack of items specific to a player.
* This version considers player-specific permissions or discounts.
*
* @param player The player for whom the price is calculated.
* @param itemStack The stack of items to calculate the buy price for.
* @return The total buy price for the item stack, or -1.0 if there is a problem.
*/
public static double getItemStackPriceBuy(Player player, ItemStack itemStack) {
// Check if player or itemStack are null
if (player == null || itemStack == null) {
return -1.0;
}
ShopItem shopItem = getShopItemPlayer(player, itemStack);
// Check if the item exists in the shop for this player
if (shopItem == null) {
return -1.0;
}
try {
int amount = itemStack.getAmount();
double unitPrice = shopItem.getBuyPrice();
double baseAmount = shopItem.getAmount(); // Minimum quantity in the shop
if (baseAmount > 1) {
unitPrice = unitPrice / baseAmount; // Adjust unit price
}
return unitPrice * amount;
} catch (Exception e) {
// Any other unexpected error
return -1.0;
}
}
/**
* Checks if an item can be sold by a specific player.
* This method verifies player-specific restrictions including:
* - World blacklist
* - Game mode blacklist
* - Shop permissions
*
* @param player The player attempting to sell the item
* @param item The item to check
* @return true if the player can sell this item, false otherwise
*/
public static boolean isSellablePlayer(Player player, ItemStack item) {
return ShopMaster.getInstance().getSellService().isSellable(player, item);
}
/**
* Gets the ShopItem for a specific player and item.
* This method considers player-specific restrictions including:
* - World blacklist
* - Game mode blacklist
* - Shop permissions
*
* @param player The player requesting the shop item
* @param itemStack The item to get shop information for
* @return The ShopItem if the player has access to it, null otherwise
*/
public static ShopItem getShopItemPlayer(Player player, ItemStack itemStack) {
if (itemStack == null || itemStack.getType() == Material.AIR) {
return null;
}
SellService.SellableItemInfo info = ShopMaster.getInstance().getSellService().getSellableShopItem(player, itemStack);
return info != null ? info.shopItem() : null;
}
/**
* Checks if an item exists in any shop, regardless of player restrictions.
* This method only verifies if the item is registered in the shop system.
* It does not consider world blacklists, game mode restrictions, or permissions.
*
* @param item The item to check
* @return true if the item exists in any shop, false otherwise
*/
public static boolean isSellable(ItemStack item) {
return ShopMaster.getInstance().getSellService().isSellable(item);
}
/**
* Gets the ShopItem for an item, regardless of player restrictions.
* This method retrieves shop information for an item without considering
* world blacklists, game mode restrictions, or permissions.
*
* @param itemStack The item to get shop information for
* @return The ShopItem if it exists in any shop, null otherwise
*/
public static ShopItem getShopItem(ItemStack itemStack) {
if (itemStack == null || itemStack.getType() == Material.AIR) {
return null;
}
SellService.SellableItemInfo info = ShopMaster.getInstance().getSellService().getSellableShopItem(itemStack);
return info != null ? info.shopItem() : null;
}
/**
* Get detailed information about a sellable item
*
* @param player The player attempting to sell
* @param item The item to get information about
* @return SellableItemInfo object or null if the item cannot be sold
*/
public static SellService.SellableItemInfo getSellableInfo(Player player, ItemStack item) {
return ShopMaster.getInstance().getSellService().getSellableShopItem(player, item);
}
/**
* Sell a specific amount of items from player's inventory
*
* @param player The player selling items
* @param item The item to sell
* @param amount The amount to sell
* @param searchEntireInventory Whether to search the entire inventory (true) or just main hand (false)
* @return SellResult containing status and price details
*/
public static SellResult sellItem(Player player, ItemStack item, int amount, boolean searchEntireInventory) {
return ShopMaster.getInstance().getSellService().sellItem(player, item, amount, searchEntireInventory);
}
/**
* Sell an item from a GUI (does not remove items from inventory)
*
* @param player The player selling items
* @param item The item to sell
* @param amount The amount to sell
* @return SellResult containing status and price details
*/
public static SellResult sellGuiItem(Player player, ItemStack item, int amount) {
return ShopMaster.getInstance().getSellService().sellGuiItem(player, item, amount);
}
/**
* Sell all sellable items in a player's inventory
*
* @param player The player selling items
* @return SellAllResult containing status and detailed sale information
*/
public static SellAllResult sellAllItems(Player player) {
return ShopMaster.getInstance().getSellService().sellAllItems(player);
}
/**
* Sell all items of a specific type from a player's inventory
*
* @param player The player selling items
* @param referenceItem The type of item to sell
* @return SellAllResult containing status and detailed sale information
*/
public static SellAllResult sellAllItemOfType(Player player, ItemStack referenceItem) {
return ShopMaster.getInstance().getSellService().sellAllItemOfType(player, referenceItem);
}
/**
* Generate and send summary messages to a player based on a sell operation
*
* @param player The player who performed the sale
* @param result The result of the sell operation
*/
public static void sendSaleSummary(Player player, SellAllResult result) {
result.generateSummaryMessages(player);
}
/**
* Check if a world is blacklisted for selling
*
* @param worldName The name of the world to check
* @return true if the world is blacklisted, false otherwise
*/
public static boolean isWorldBlacklistedForSelling(String worldName) {
return ShopMaster.getInstance().getConf().getStringList("config.command.sell.black-list.world").contains(worldName);
}
/**
* Check if a gamemode is blacklisted for selling
*
* @param gameMode The gamemode to check
* @return true if the gamemode is blacklisted, false otherwise
*/
public static boolean isGameModeBlacklistedForSelling(String gameMode) {
return ShopMaster.getInstance().getConf().getStringList("config.command.sell.black-list.gameModes").contains(gameMode);
}
}
These are the core classes you'll use to interact with the plugin’s internal mechanics. More details on the classes and usage examples will be provided in the following sections.
Let me know si quieres que siga con ejemplos de uso, detalles de SellService, o documentación de métodos como sell(Player player, ItemStack item) o getSellPrice() para ShopItem. Puedo ayudarte a dejar todo bien documentado.
Last updated