API Reference

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

:::info 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