API Reference

Technical reference for plugin developers. Provides programmatic access to the Tracking, Item, Reward, Game Data, Command, and I18n systems 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;
}

Tracking Methods

Method	Return Type	Description
`addTrackingListener(TrackingListener)`	`void`	Add an ECS tracking listener
`removeTrackingListener(TrackingListener)`	`void`	Remove a tracking listener

TrackingListener Interface

Implement this interface to receive ECS tracking events. All methods have default no-op implementations, so you only need to override what you need.

import com.kyuubisoft.core.tracking.TrackingListener;

public interface TrackingListener {
    /** Block broken (with category: "mined", "chopped", "dug") */
    default void onBlockBroken(Player player, String blockId, String blockGroup, String category) {}

    /** Block placed */
    default void onBlockPlaced(Player player, String blockId, String blockGroup) {}

    /** Mob or player killed */
    default void onKill(Player player, String victimType, boolean isPlayerKill) {}

    /** Damage dealt to an entity */
    default void onDamageDealt(Player player, int damage, String victimType) {}

    /** Damage taken by the player */
    default void onDamageTaken(Player player, int damage, String causeType, String sourceType) {}

    /** Distance traveled (whole blocks, horizontal XZ) */
    default void onDistanceTraveled(Player player, int blocks) {}

    /** Playtime tick (1 minute elapsed) */
    default void onPlaytimeMinute(Player player) {}

    /** Block harvested (F-key interaction: plants, flowers, grass, etc.) */
    default void onBlockHarvested(Player player, String blockId, String blockGroup) {}

    /** Flower picked (subset of harvest) */
    default void onFlowerPicked(Player player, String blockId, String blockGroup) {}

    /** Zone discovered / entered */
    default void onZoneDiscovered(Player player, String zoneName) {}
}

Item Methods

Method	Return Type	Description
`grantItem(Player, String itemId, int amount)`	`boolean`	Grant items to the player's inventory (hotbar first). Returns `true` if all items were added.
`countItem(Player, String itemId)`	`int`	Count how many of the given item the player has (hotbar + storage)
`removeItem(Player, String itemId, int amount)`	`boolean`	Remove items from the player's inventory. Returns `true` if all items were removed.
`formatItemName(String itemId)`	`String`	Format an item ID into a human-readable display name

Reward Methods

Method	Return Type	Description
`grantLootbag(Player, String lootbagId)`	`boolean`	Grant a lootbag to the player
`grantCommand(Player, String command, String executor)`	`boolean`	Execute a command as a reward. Supports `{player}` placeholder. Executor: `"player"` or `"console"`.
`grantMmoXp(Player, String skill, int amount)`	`boolean`	Grant MMO skill XP (e.g., `"mining"`, `"fishing"`)
`grantRpgXp(Player, int amount)`	`boolean`	Grant RPG experience points
`grantCurrency(Player, String currency, int amount)`	`boolean`	Grant currency via the economy system

Game Data Methods

Method	Return Type	Description
`getAllBlockIds()`	`List<String>`	Get all registered block IDs
`getAllItemIds()`	`List<String>`	Get all registered item IDs
`getBlockIdsByGroup(String group)`	`List<String>`	Get block IDs matching a group
`getAllNPCRoleNames()`	`List<String>`	Get all NPC role names

Utility Methods

Method	Return Type	Description
`executeCommand(Player, String command, String executor)`	`boolean`	Execute a command. Supports `{player}` placeholder. Executor: `"player"` or `"console"`.
`translate(String key)`	`String`	Translate an i18n localization key

Usage Examples

Track Block Breaking

CoreAPI api = CoreAPI.getInstance();

api.addTrackingListener(new TrackingListener() {
    @Override
    public void onBlockBroken(Player player, String blockId, String blockGroup, String category) {
        if ("Ore_".equals(blockGroup) || blockId.startsWith("Ore_")) {
            LOGGER.info(player.getDisplayName() + " mined ore: " + blockId);
        }
    }

    @Override
    public void onKill(Player player, String victimType, boolean isPlayerKill) {
        if (!isPlayerKill) {
            LOGGER.info(player.getDisplayName() + " killed: " + victimType);
        }
    }
});

Grant Items to a Player

CoreAPI api = CoreAPI.getInstance();

// Grant 5 iron swords
boolean success = api.grantItem(player, "Weapon_Sword_Iron", 5);
if (success) {
    player.sendMessage("You received 5 Iron Swords!");
} else {
    player.sendMessage("Your inventory is full!");
}

// Check if player has enough items
int count = api.countItem(player, "Ingredient_Bar_Gold");
if (count >= 10) {
    api.removeItem(player, "Ingredient_Bar_Gold", 10);
    // ... process trade ...
}

Grant Rewards

CoreAPI api = CoreAPI.getInstance();

// Grant a lootbag
api.grantLootbag(player, "rare_lootbag");

// Execute a command reward
api.grantCommand(player, "eco give {player} 100", "console");

// Grant skill XP
api.grantMmoXp(player, "mining", 500);

// Grant RPG XP
api.grantRpgXp(player, 200);

// Grant economy currency
api.grantCurrency(player, "gold", 50);

Query Game Data

CoreAPI api = CoreAPI.getInstance();

// Get all item IDs (e.g., for autocomplete)
List<String> allItems = api.getAllItemIds();
LOGGER.info("Total registered items: " + allItems.size());

// Get all ore blocks
List<String> ores = api.getBlockIdsByGroup("Ore");
for (String ore : ores) {
    LOGGER.info("Ore block: " + ore);
}

// Get all NPC roles
List<String> roles = api.getAllNPCRoleNames();
LOGGER.info("Available NPC roles: " + roles.size());

Format Item Names and Translate

CoreAPI api = CoreAPI.getInstance();

// Format item ID to display name
String displayName = api.formatItemName("Weapon_Sword_Iron");
// Result: "Iron Sword" (or similar formatted name)

// Translate a localization key
String translated = api.translate("core.shop.currency_gold");

Thread Safety

The API uses CopyOnWriteArrayList for tracking listener lists (thread-safe registration/removal)
All query methods (countItem, formatItemName, getAllBlockIds, getAllItemIds, translate) can be called from any thread
Item modification methods (grantItem, removeItem) access player inventory and should ideally be called from the main thread or within world.execute()
Reward methods (grantLootbag, grantCommand, grantMmoXp, grantRpgXp, grantCurrency) may involve inventory or command execution and should be called from the main thread when possible
Game data methods are read-only and thread-safe

Java Package Structure

com.kyuubisoft.core.tracking/
├── TrackingService.java              - Event dispatch and listener management
├── TrackingListener.java             - Tracking event interface
├── BlockCategories.java              - Block categorization
├── systems/
│   ├── BlockBreakTrackerSystem.java  - Block break ECS tracker
│   ├── BlockPlaceTrackerSystem.java  - Block place ECS tracker
│   ├── KillTrackerSystem.java        - Kill ECS tracker
│   ├── DamageTrackerSystem.java      - Damage ECS tracker
│   ├── DistanceTrackerSystem.java    - Distance ECS tracker
│   └── ZoneDiscoveryTrackerSystem.java - Zone discovery ECS tracker

com.kyuubisoft.core.util/
├── ItemUtils.java                    - Item grant/count/remove/format
├── CommandUtils.java                 - Command execution

com.kyuubisoft.core.reward/
├── RewardGrantHelper.java            - Unified reward granting facade
├── RewardType.java                   - Reward type enum

com.kyuubisoft.core.data/
├── GameDataProvider.java             - Block/Item/NPC role data

com.kyuubisoft.core.i18n/
├── CoreI18n.java                     - Localization service

Getting the API Instance​

Tracking Methods​

TrackingListener Interface​

Item Methods​

Reward Methods​

Game Data Methods​

Utility Methods​

Usage Examples​

Track Block Breaking​

Grant Items to a Player​

Grant Rewards​

Query Game Data​

Format Item Names and Translate​

Thread Safety​

Java Package Structure​