# API Reference

# API Reference

Technical reference for plugin developers. Provides programmatic access to the Title management system.

:::info Module
Title management is handled through the **AchievementAPI** since titles are earned through achievements. The API is provided by `kyuubisoft-achievements.jar`. Ensure the Achievements mod is loaded before calling any API methods.
:::

## Getting the API Instance

```java
import com.hytale.achievements.api.AchievementAPI;

// Availability check (recommended)
if (AchievementAPI.isAvailable()) {
    AchievementAPI api = AchievementAPI.getInstance();
    // ...
}

// Or direct (returns null if Achievements is not loaded)
AchievementAPI api = AchievementAPI.getInstance();
if (api == null) {
    // Achievement plugin not loaded
    return;
}
```

## Title Methods

| Method | Return Type | Description |
|--------|-------------|-------------|
| `getActiveTitle(Player)` | `String` | Get the player's active title ID, or `null` if no title is active |
| `getUnlockedTitles(Player)` | `Set<String>` | Get all unlocked title IDs for the player |
| `setActiveTitle(Player, String titleId)` | `boolean` | Set the active title (pass `null` to clear). Returns `true` on success. Automatically refreshes the display. |
| `getTitleDisplayName(Player, String titleId)` | `String` | Get the localized display name of a title. Returns the raw `titleId` if no localization is found. |

## Usage Examples

### Get Active Title

```java
AchievementAPI api = AchievementAPI.getInstance();

String activeTitle = api.getActiveTitle(player);
if (activeTitle != null) {
    String displayName = api.getTitleDisplayName(player, activeTitle);
    player.sendMessage("Your active title: " + displayName);
} else {
    player.sendMessage("You have no active title.");
}
```

### List Unlocked Titles

```java
AchievementAPI api = AchievementAPI.getInstance();

Set<String> titles = api.getUnlockedTitles(player);
if (titles.isEmpty()) {
    player.sendMessage("You have not unlocked any titles yet.");
} else {
    player.sendMessage("Your titles (" + titles.size() + "):");
    for (String titleId : titles) {
        String name = api.getTitleDisplayName(player, titleId);
        String marker = titleId.equals(api.getActiveTitle(player)) ? " [ACTIVE]" : "";
        player.sendMessage("  - " + name + marker);
    }
}
```

### Set Active Title

```java
AchievementAPI api = AchievementAPI.getInstance();

// Set a specific title
boolean success = api.setActiveTitle(player, "monster_slayer");
if (success) {
    player.sendMessage("Title set to: Monster Slayer");
} else {
    player.sendMessage("Could not set title.");
}

// Clear the active title
api.setActiveTitle(player, null);
player.sendMessage("Title cleared.");
```

### Check Title Before Granting Access

```java
AchievementAPI api = AchievementAPI.getInstance();

// Example: Require a title to enter a special area
Set<String> titles = api.getUnlockedTitles(player);
if (titles.contains("champion_of_gaia")) {
    // Allow access
    player.sendMessage("Welcome, Champion!");
} else {
    player.sendMessage("Only Champions of Gaia may enter.");
}
```

## How Titles Are Earned

Titles are defined as part of achievement definitions. When a player unlocks an achievement that has a `title` field, the title is automatically added to the player's unlocked titles.

```json
{
  "id": "monster_hunter_master",
  "category": "combat",
  "trigger": { "type": "kills", "target": "any_mob", "count": 1000 },
  "title": {
    "id": "monster_slayer",
    "color": "#FF5555"
  }
}
```

The title's display name is resolved via localization:

```
achievements.title.monster_slayer = Monster Slayer
```

## Thread Safety

- All query methods (`getActiveTitle`, `getUnlockedTitles`, `getTitleDisplayName`) can be called from any thread
- `setActiveTitle` modifies player data and refreshes the display; it should ideally be called from the main thread
- The API uses `CopyOnWriteArrayList` internally for thread-safe listener management

## Related APIs

- **Achievement Query** -- Check which achievements a player has unlocked: see [Achievement System API Reference](https://wiki.kyuubisoft.com/hytale/achievement-system/api-reference)
- **CoreAPI Reward Methods** -- Grant rewards programmatically: see [Tracking API Reference](https://wiki.kyuubisoft.com/hytale/tracking/api-reference)