API Reference

Technical reference for plugin developers. Provides programmatic access to the Shop system through the unified CoreAPI facade.

Module

The CoreAPI is provided by kyuubisoft-core.jar. Ensure the Core mod is loaded before calling any API methods.

Getting the API Instance

import com.kyuubisoft.core.api.CoreAPI;

// Availability check (recommended)
if (CoreAPI.isAvailable()) {
    CoreAPI api = CoreAPI.getInstance();
    // ...
}

// Or direct (returns null if Core is not loaded)
CoreAPI api = CoreAPI.getInstance();
if (api == null) {
    // Core plugin not loaded
    return;
}

Shop Methods

Method	Return Type	Description
openShop(Player, PlayerRef, Ref, Store, String shopId)	void	Open a shop UI for the player
getShop(String id)	ShopConfig	Get the ShopConfig by ID, or null if not found
registerShop(ShopConfig)	void	Register a custom shop configuration at runtime
registerCurrency(CurrencyProvider)	void	Register a custom currency provider
getCurrency(String id)	CurrencyProvider	Get a currency provider by ID, or null if not found

Interfaces

CurrencyProvider

Implement this interface to define a custom currency for the shop system. Each currency must have a unique ID.

import com.kyuubisoft.core.shop.CurrencyProvider;

public interface CurrencyProvider {
    /** Unique currency ID (e.g., "quest_tokens", "achievement_points", "item:Ingredient_Bar_Gold") */
    String getCurrencyId();

    /** Display name (i18n key or plain text) */
    String getDisplayName();

    /** Icon item ID for display in the shop header */
    String getIconItemId();

    /** Get the player's current balance */
    int getBalance(Player player);

    /** Deduct currency. Returns true on success, false if insufficient balance. */
    boolean spend(Player player, int amount);

    /** Credit currency back (for refunds). */
    void refund(Player player, int amount);
}

Usage Examples

Open a Shop Programmatically

CoreAPI api = CoreAPI.getInstance();

// Open a shop for the player
// (typically called from within a command or event handler that has access to PlayerRef/Ref/Store)
api.openShop(player, playerRef, ref, store, "blacksmith_shop");

Register a Custom Currency

CoreAPI api = CoreAPI.getInstance();

api.registerCurrency(new CurrencyProvider() {
    @Override
    public String getCurrencyId() { return "quest_tokens"; }

    @Override
    public String getDisplayName() { return "Quest Tokens"; }

    @Override
    public String getIconItemId() { return "Ingredient_Gemstone_Ruby"; }

    @Override
    public int getBalance(Player player) {
        return questData.getTokens(player);
    }

    @Override
    public boolean spend(Player player, int amount) {
        if (questData.getTokens(player) < amount) return false;
        questData.removeTokens(player, amount);
        return true;
    }

    @Override
    public void refund(Player player, int amount) {
        questData.addTokens(player, amount);
    }
});

Check Shop Existence

CoreAPI api = CoreAPI.getInstance();

ShopConfig shop = api.getShop("blacksmith_shop");
if (shop != null) {
    LOGGER.info("Shop found: " + shop.getId());
} else {
    LOGGER.warning("Shop 'blacksmith_shop' does not exist");
}

Register a Custom Shop at Runtime

CoreAPI api = CoreAPI.getInstance();

ShopConfig customShop = new ShopConfig();
// ... configure shop items, currency, etc. ...
api.registerShop(customShop);

Check Currency Balance

CoreAPI api = CoreAPI.getInstance();

CurrencyProvider currency = api.getCurrency("quest_tokens");
if (currency != null) {
    int balance = currency.getBalance(player);
    player.sendMessage("You have " + balance + " " + currency.getDisplayName());
}

Thread Safety

• The API uses CopyOnWriteArrayList internally for currency provider lists (thread-safe registration)
• getShop and getCurrency are read-only lookups and can be called from any thread
• openShop involves UI operations and should be called from the main thread or within world.execute()
• registerShop and registerCurrency can be called during plugin initialization or at runtime

Java Package Structure

com.kyuubisoft.core.shop/
├── ShopService.java          - Shop lifecycle management
├── ShopConfig.java           - Shop configuration model
├── ShopPage.java             - Shop UI page
├── CurrencyProvider.java     - Currency interface
├── ItemCurrencyProvider.java - Built-in item-based currency
├── PurchaseResult.java       - Purchase result enum
└── ShopPlayerData.java       - Per-player shop data