Skip to main content

API Reference

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

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​

MethodReturn TypeDescription
getActiveTitle(Player)StringGet 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)booleanSet the active title (pass null to clear). Returns true on success. Automatically refreshes the display.
getTitleDisplayName(Player, String titleId)StringGet 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