API Reference

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.

:::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;
}

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