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

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

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

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

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

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.

{
  "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
• CoreAPI Reward Methods — Grant rewards programmatically: see Tracking API Reference