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
Section titled “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
Section titled “Tracking Methods”| Method | Return Type | Description |
|---|---|---|
addTrackingListener(TrackingListener) | void | Add an ECS tracking listener |
removeTrackingListener(TrackingListener) | void | Remove a tracking listener |
TrackingListener Interface
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “Usage Examples”Track Block Breaking
Section titled “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
Section titled “Grant Items to a Player”CoreAPI api = CoreAPI.getInstance();
// Grant 5 iron swordsboolean 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 itemsint count = api.countItem(player, "Ingredient_Bar_Gold");if (count >= 10) { api.removeItem(player, "Ingredient_Bar_Gold", 10); // ... process trade ...}Grant Rewards
Section titled “Grant Rewards”CoreAPI api = CoreAPI.getInstance();
// Grant a lootbagapi.grantLootbag(player, "rare_lootbag");
// Execute a command rewardapi.grantCommand(player, "eco give {player} 100", "console");
// Grant skill XPapi.grantMmoXp(player, "mining", 500);
// Grant RPG XPapi.grantRpgXp(player, 200);
// Grant economy currencyapi.grantCurrency(player, "gold", 50);Query Game Data
Section titled “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 blocksList<String> ores = api.getBlockIdsByGroup("Ore");for (String ore : ores) { LOGGER.info("Ore block: " + ore);}
// Get all NPC rolesList<String> roles = api.getAllNPCRoleNames();LOGGER.info("Available NPC roles: " + roles.size());Format Item Names and Translate
Section titled “Format Item Names and Translate”CoreAPI api = CoreAPI.getInstance();
// Format item ID to display nameString displayName = api.formatItemName("Weapon_Sword_Iron");// Result: "Iron Sword" (or similar formatted name)
// Translate a localization keyString translated = api.translate("core.shop.currency_gold");Thread Safety
Section titled “Thread Safety”- The API uses
CopyOnWriteArrayListfor 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 withinworld.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