API Reference

API Reference

Technical reference for plugin developers. Provides programmatic access to the Lootbag 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;
}

Lootbag Methods

Method	Return Type	Description
getLootbagDefinition(String id)	LootbagDefinition	Get a lootbag definition by ID, or null if not found
lootbagExists(String id)	boolean	Check if a lootbag with the given ID exists
getAllLootbags()	Map<String, LootbagDefinition>	Get all registered lootbag definitions
grantLootbag(Player, String lootbagId)	boolean	Grant a lootbag to the player (resolves items and adds to inventory)

LootbagDefinition Model

The LootbagDefinition class provides information about a lootbag template. Three modes are supported:

1. Fixed Items — A static list of items
2. Random Pool — Random selection from a weighted pool
3. Hybrid — Guaranteed items plus random picks from a pool

import com.kyuubisoft.core.lootbag.LootbagDefinition;

// Key getters
definition.getId();              // String: Lootbag ID
definition.getName();            // String: Display name (default: "Lootbag")
definition.getDescription();     // String: Description text
definition.getIcon();            // String: Icon item ID (default: "Chest_Wood")
definition.getRarity();          // String: "common", "uncommon", "rare", "epic", "legendary"
definition.getRarityColor();     // String: Hex color for the rarity tier

// Type checks
definition.isFixedItems();       // Fixed item list only
definition.isRandomPool();       // Random pool only
definition.isHybrid();           // Guaranteed items + random pool

// Item data
definition.getItems();           // List<LootItem>: Fixed items
definition.getGuaranteedItems(); // List<LootItem>: Guaranteed items (hybrid mode)
definition.getPool();            // List<PoolItem>: Weighted random pool
definition.getPickCount();       // int: Number of random picks from pool
definition.isAllowDuplicates();  // boolean: Allow duplicate picks

Usage Examples

Check Lootbag Existence

CoreAPI api = CoreAPI.getInstance();

if (api.lootbagExists("rare_lootbag")) {
    LOGGER.info("Lootbag 'rare_lootbag' is registered");
} else {
    LOGGER.warning("Lootbag 'rare_lootbag' not found");
}

Get Lootbag Details

CoreAPI api = CoreAPI.getInstance();

LootbagDefinition def = api.getLootbagDefinition("starter_pack");
if (def != null) {
    LOGGER.info("Lootbag: " + def.getName());
    LOGGER.info("Rarity: " + def.getRarity());
    LOGGER.info("Icon: " + def.getIcon());

    if (def.isFixedItems()) {
        LOGGER.info("Contains " + def.getItems().size() + " fixed items");
    } else if (def.isRandomPool()) {
        LOGGER.info("Random pool with " + def.getPickCount() + " picks");
    } else if (def.isHybrid()) {
        LOGGER.info("Hybrid: " + def.getGuaranteedItems().size() + " guaranteed + "
                     + def.getPickCount() + " random picks");
    }
}

Grant a Lootbag to a Player

CoreAPI api = CoreAPI.getInstance();

boolean success = api.grantLootbag(player, "rare_lootbag");
if (success) {
    player.sendMessage("You received a Rare Lootbag!");
} else {
    player.sendMessage("Could not grant lootbag (inventory full or lootbag not found).");
}

List All Available Lootbags

CoreAPI api = CoreAPI.getInstance();

Map<String, LootbagDefinition> allBags = api.getAllLootbags();
for (Map.Entry<String, LootbagDefinition> entry : allBags.entrySet()) {
    String id = entry.getKey();
    LootbagDefinition def = entry.getValue();
    LOGGER.info(id + " - " + def.getName() + " (" + def.getRarity() + ")");
}

Use Lootbag as a Reward in Custom Logic

CoreAPI api = CoreAPI.getInstance();

// Example: Grant a lootbag when a player completes a custom challenge
public void onChallengeComplete(Player player, String challengeId) {
    String lootbagId = challengeRewards.get(challengeId);
    if (lootbagId != null && api.lootbagExists(lootbagId)) {
        api.grantLootbag(player, lootbagId);
    }
}

Thread Safety

• getLootbagDefinition, lootbagExists, and getAllLootbags are read-only lookups and can be called from any thread
• grantLootbag involves inventory operations and should ideally be called from the main thread or within world.execute()

Java Package Structure

com.kyuubisoft.core.lootbag/
├── LootbagService.java        - Lootbag loading, resolution, and granting
├── LootbagDefinition.java     - Lootbag template model (with LootItem, PoolItem)
├── LootbagConfig.java         - Lootbag configuration loading
└── LootbagAdminService.java   - Admin CRUD operations