# 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

```java
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.

```java
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

```java
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

```java
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

```java
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

```java
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

```java
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