# API Reference

# API Reference

Technical reference for plugin developers and advanced users. Includes the public API for external plugin integration.

## Achievement Definition Schema

```typescript
interface Achievement {
  // Required
  id: string;                    // Unique identifier (snake_case)
  category: Category;            // Category classification
  trigger: Trigger;              // Unlock condition

  // Optional
  iconItem?: string;             // Item ID for icon (default: "Ore_Gold")
  hidden?: boolean;              // Hide until unlocked (default: false)
  difficulty?: Difficulty;       // Difficulty tier (default: "normal")
  requires?: string | string[];  // Prerequisite achievement ID(s)
  showRequires?: boolean;        // Show requirements when locked (default: true)
  title?: Title;                 // Unlockable title reward
  rewards?: Reward[];            // Item/command rewards
  additionalInfo?: AdditionalInfo; // Custom info text
  custom?: boolean;              // Mark as custom achievement
}

type Category = "combat" | "progression" | "exploration" | "social" | "husbandry" | "secret";

type Difficulty = "easy" | "normal" | "hard" | "epic";
```

## Trigger Types

### BlocksMined / BlocksPlaced

```typescript
interface BlockTrigger {
  type: "blocks_mined" | "blocks_placed";
  target: string;  // Block ID, "any", or prefix (e.g., "Ore_")
  count: number;   // Required count
}
```

**Target Matching:**
- `"any"` - Matches all blocks
- `"Stone"` - Exact match
- `"Ore_"` - Prefix match (matches Ore_Iron, Ore_Gold, etc.)

### Kills

```typescript
interface KillsTrigger {
  type: "kills";
  target: string;  // Entity ID, "any", "any_mob", "any_player"
  count: number;
}
```

**Target Options:**
| Value | Matches |
|-------|---------|
| `"any"` | All entities |
| `"any_mob"` | All non-player entities |
| `"any_player"` | All players |
| `"Spider"` | Exact entity type |

### ItemsCrafted

```typescript
interface CraftTrigger {
  type: "items_crafted";
  target: string;  // Item ID or "any"
  count: number;
}
```

### ZonesDiscovered

```typescript
interface ZoneTrigger {
  type: "zones_discovered";
  target: string;  // Zone ID or "any"
  count: number;
}
```

### ChatMessages

```typescript
interface ChatTrigger {
  type: "chat_messages";
  count: number;
}
```

### PlaytimeMinutes

```typescript
interface PlaytimeTrigger {
  type: "playtime_minutes";
  count: number;  // Minutes
}
```

### DistanceWalked

```typescript
interface DistanceTrigger {
  type: "distance_walked";
  count: number;  // Blocks
}
```

### FullArmorSet

```typescript
interface ArmorTrigger {
  type: "full_armor_set";
  target: ArmorMaterial;
}

type ArmorMaterial =
  | "iron" | "copper" | "bronze" | "steel"
  | "cobalt" | "mithril" | "thorium"
  | "adamantite" | "onyxium" | "prisma";
```

### EquipItem

```typescript
interface EquipTrigger {
  type: "equip_item";
  target: string;  // Item ID
}
```

### Manual

```typescript
interface ManualTrigger {
  type: "manual";
}
```

### AutoOnPrerequisites

```typescript
interface AutoTrigger {
  type: "auto_on_prerequisites";
}
```

### WeekendLogin

```typescript
interface WeekendLoginTrigger {
  type: "weekend_login";
  count: number;  // Number of weekend logins required
}
```

Triggers when a player logs in on Saturday or Sunday. Useful for attendance-based achievements.

### SkillLevel (MMO SkillTree)

```typescript
interface SkillLevelTrigger {
  type: "skill_level";
  target: string;  // "MINING:50" (skill in upper case + milestone) or "total:1000"
  count: number;   // 1
}
```

Only the milestones 10 / 25 / 50 / 75 / 100 per skill and `total:` 100 / 500 / 1000 / 1500 / 2000 / 2300 are sent. The old `total_skill_level` type is not counted; use `skill_level` with a `total:` target.

### RpgLevel (RPG Leveling)

```typescript
interface RpgLevelTrigger {
  type: "rpg_level";
  target: string;  // Level number as string
  count: number;   // Usually 1
}
```

### RpgXp (RPG Leveling)

```typescript
interface RpgXpTrigger {
  type: "rpg_xp";
  target: "any";
  count: number;  // Total XP required
}
```

## Reward Types

### Item Reward

```typescript
interface ItemReward {
  type: "item";
  itemId: string;  // Hytale item ID
  amount: number;  // Quantity (1-64)
}
```

### Command Reward

```typescript
interface CommandReward {
  type: "command";
  command: string;     // Command to execute (use {player} placeholder)
  executor: Executor;  // Who runs the command
}

type Executor = "console" | "player";
```

### Lootbag Reward

```typescript
interface LootbagReward {
  type: "lootbag";
  lootbagId: string;  // ID from lootbags.json
}
```

## Title Definition

```typescript
interface Title {
  id: string;     // Title identifier (for localization)
  color?: string; // Hex color code (default: "#FFFFFF" white)
}
```

## Additional Info

```typescript
interface AdditionalInfo {
  text: string;   // Display text
  color?: string; // Hex color code (default: "#AAAAAA" gray)
}
```

## Configuration Schema

```typescript
interface Config {
  language: "en-US" | "de-DE";
  loadDefaultAchievements: boolean;

  display: {
    displayMode: "nametag" | "chat" | "both";
    titlePosition: "prefix" | "above" | "below";
    nametagFormat: string;
    chatFormat: string;
    titleColor: string;
    showRpgLevel: boolean;
    rpgLevelFormat: string;
    rpgLevelColor: string;
    rpgLevelPosition: "before_name" | "after_name" | "after_title";
  };

  notifications: {
    enabled: boolean;
    displayMode: "chat" | "banner" | "both";
    displayDurationMs: number;
    showRewardsInBanner: boolean;
    broadcastToChat: boolean;
    broadcastFormat: string;
  };

  tracking: {
    saveIntervalSeconds: number;
    enableExploration: boolean;
    enableCombat: boolean;
    enableProgression: boolean;
    enableSocial: boolean;
  };

  admin: {
    cascadeRevoke: boolean;
    cascadeRevokeWarning: boolean;
    bypassPrerequisites: boolean;
  };

  export: {
    enabled: boolean;
    intervalSeconds: number;
    exportGlobalStats: boolean;
    exportLeaderboards: boolean;
    exportRecentUnlocks: boolean;
    leaderboardSize: number;
    recentUnlocksSize: number;
    includePlayerTotals: boolean;
  };

  groupPrefixes: {
    [groupName: string]: {
      prefix: string;
      priority: number;
    };
  };
}
```

## Localization Keys

### Achievement Keys

```
achievements.name.<id>     - Achievement display name
achievements.desc.<id>     - Achievement description
achievements.title.<id>    - Title display name
```

### Book and Admin Keys

The achievement book uses `achievements.book.*` keys (for example category names `achievements.book.cat.<category>`), the HUD `achievements.hud.*`, the settings `achievements.settings.*` and the admin window `aadmin.*`. Hints for hidden achievements are `achievements.hint.<id>`. Put your own texts into `localization/custom_<lang>.json`; see [Localization](./localization).

### Command Keys

```
achievements.cmd.grant.success     - Grant success message
achievements.cmd.grant.already     - Already unlocked message
achievements.cmd.revoke.success    - Revoke success message
achievements.cmd.revoke.not_unlocked - Not unlocked message
achievements.cmd.list.header       - List header format
achievements.cmd.list.empty        - Empty list message
```

### Trigger Keys

```
achievements.trigger.blocks_mined      - "Mine {0} blocks"
achievements.trigger.blocks_placed     - "Place {0} blocks"
achievements.trigger.kills             - "Kill {0} {1}"
achievements.trigger.items_crafted     - "Craft {0} {1}"
achievements.trigger.playtime_minutes  - "Play for {0} minutes"
achievements.trigger.distance_walked   - "Walk {0} blocks"
achievements.trigger.chat_messages     - "Send {0} chat messages"
achievements.trigger.zones_discovered  - "Discover {0} zones"
```

## File Paths

```
mods/kyuubisoft_achievements/
├── config.json              - Main configuration
├── configs/                 - Standard configs (replaced on updates)
│   ├── achievements.json
│   ├── mmo_achievements.json
│   ├── rpg_leveling_achievements.json
│   └── lootbags.json
├── custom/                  - Custom configs (safe from updates)
│   ├── custom_achievements.json
│   └── custom_lootbags.json
├── localization/            - Language files (9 languages + custom_<lang>.json)
├── players/                 - Player achievement data (<uuid>.json, file storage)
├── stats/                   - Statistics export and server records
│   ├── global_stats.json
│   ├── leaderboards.json
│   ├── recent_unlocks.json
│   └── server_records.json
├── backups/                 - Backup sets of the admin window
└── admin/players/           - Players tool: action log and queued offline actions
```

## Events

### Achievement Events (Internal)

The plugin tracks these Hytale events:

| Event | Trigger Type |
|-------|--------------|
| `BlockBreakEvent` | blocks_mined |
| `BlockPlaceEvent` | blocks_placed |
| `EntityDeathEvent` | kills |
| `PlayerCraftEvent` | items_crafted |
| `PlayerMoveEvent` | distance_walked |
| `PlayerChatEvent` | chat_messages |
| `ZoneEnterEvent` | zones_discovered |
| `PlayerEquipEvent` | equip_item, full_armor_set |
| `PlayerJoinEvent` | weekend_login (checks day of week) |

---

## Public API

External plugins can interact with the Achievement System through a stable public API.

### Getting the API Instance

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

// Get API instance
AchievementAPI api = AchievementAPI.getInstance();
if (api == null) {
    // Achievement plugin not loaded
    return;
}

// Or with availability check
if (AchievementAPI.isAvailable()) {
    AchievementAPI api = AchievementAPI.getInstance();
    // ...
}
```

### Achievement Query Methods

| Method | Description |
|--------|-------------|
| `hasAchievement(Player, String)` | Check if player has achievement |
| `hasAchievement(UUID, String)` | Check by UUID |
| `getProgress(Player, String)` | Current progress |
| `getRequiredProgress(String)` | Required progress to unlock |
| `getUnlockedAchievements(Player)` | Set of all unlocked IDs |
| `getUnlockedCount(Player)` | Number of unlocked achievements |
| `getTotalAchievementCount()` | Total number of achievements |
| `getUnlockTimestamp(Player, String)` | Unix timestamp of unlock |
| `getAllAchievementIds()` | List of all achievement IDs |
| `getAchievementsByCategory(String)` | Achievements in a category |
| `achievementExists(String)` | Check if achievement exists |

### Title Query Methods

| Method | Description |
|--------|-------------|
| `getActiveTitle(Player)` | Id of the **achievement** whose title is active (or null) |
| `getActiveTitleId(Player)` | Id of the active **title** (or null), since 3.0.0 |
| `getUnlockedTitles(Player)` | Set of all unlocked titles |
| `getTitleDisplayName(Player, String)` | Translated name of a title in the player's language |
| `setActiveTitle(Player, String)` | Set the active title (title id or achievement id; null clears) |

### Modification Methods

| Method | Description |
|--------|-------------|
| `grantAchievement(Player, String)` | Grant achievement (with rewards) |
| `revokeAchievement(Player, String)` | Revoke achievement: points back, uncollected rewards dropped, title refreshed |
| `setProgress(Player, String, int)` | Set progress directly (does not unlock) |
| `incrementProgress(Player, String, int)` | Increment progress of **this** achievement and check the unlock. An id that is a trigger type (e.g. `dungeon_complete_any`) counts as that trigger |

### Points Methods

| Method | Description |
|--------|-------------|
| `getAchievementPoints(Player)` | Current balance |
| `addAchievementPoints(Player, int)` | Add points |
| `spendAchievementPoints(Player, int)` | Spend points; false when the balance is too low |

### Event Listeners

| Method | Description |
|--------|-------------|
| `onAchievementUnlock(BiConsumer<Player, String>)` | Listener for unlock events |
| `removeUnlockListener(BiConsumer)` | Remove unlock listener |
| `onProgressUpdate(BiConsumer<Player, String>)` | Listener for progress updates |
| `removeProgressListener(BiConsumer)` | Remove progress listener |

### Statistics Methods

| Method | Description |
|--------|-------------|
| `getTotalBlocksMined(Player)` | Total blocks mined |
| `getTotalBlocksPlaced(Player)` | Total blocks placed |
| `getTotalMobKills(Player)` | Total mob kills |
| `getPlaytimeMinutes(Player)` | Playtime in minutes |

### Usage Examples

#### Check Achievement Status

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

// Does the player have "monster_hunter_1"?
if (api.hasAchievement(player, "monster_hunter_1")) {
    player.sendMessage("You are a monster hunter!");
}

// Show progress
int progress = api.getProgress(player, "blocks_mined_1000");
int required = api.getRequiredProgress("blocks_mined_1000");
player.sendMessage("Progress: " + progress + "/" + required);
```

#### React to Achievement Unlocks

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

api.onAchievementUnlock((player, achievementId) -> {
    // Firework effect or similar
    spawnFirework(player.getLocation());

    // Logging
    LOGGER.info(player.getDisplayName() + " unlocked " + achievementId + "!");
});
```

#### Grant Achievement Programmatically

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

// Grant achievement on special event
if (specialEventTriggered) {
    boolean granted = api.grantAchievement(player, "special_event_2026");
    if (granted) {
        // Successfully granted
    } else {
        // Player already had it or achievement doesn't exist
    }
}
```

#### Statistics for Leaderboard

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

int blocksMinedTotal = api.getTotalBlocksMined(player);
int achievementCount = api.getUnlockedCount(player);
long playtimeMinutes = api.getPlaytimeMinutes(player);

// Use for leaderboard...
```

### Thread Safety

- The API is thread-safe using `CopyOnWriteArrayList` for listeners; since 3.0.0 unlock and progress listeners really fire
- All query methods can be called from any thread
- Modification methods should ideally be called from the main thread