# API Reference

# API Reference

:::caution[In development]
This page describes the current development build (4.4.3). The API is small and can still change before release.
:::

KS Dungeons provides a small public API for other mods.

## Access

```java
if (DungeonsAPI.isAvailable()) {
    DungeonsAPI api = DungeonsAPI.getInstance();
    // KS Dungeons is loaded and ready
}
```

Mods that should also run without KS Dungeons can check for the class first:

```java
try {
    Class.forName("com.kyuubisoft.dungeons.api.DungeonsAPI");
    // KS Dungeons is installed
} catch (ClassNotFoundException e) {
    // KS Dungeons not installed
}
```

## Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `isInDungeon(UUID playerUuid)` | `boolean` | Whether the player is in a dungeon run |
| `getPlayerDungeon(UUID playerUuid)` | `DungeonInstance` | The run the player is in, or `null` |
| `getActiveInstances()` | `Collection<DungeonInstance>` | All running dungeon runs |
| `getTokens(UUID playerUuid)` | `int` | The player's dungeon token balance |
| `addTokens(UUID playerUuid, int amount)` | `void` | Add tokens to a player |
| `isOnCooldown(UUID playerUuid, String biomeId)` | `boolean` | Whether the biome is on cooldown for the player |

## Achievement Triggers

KS Dungeons does not fire public events. With KyuubiSoft Achievements installed it sends these achievement triggers when a run is completed:

| Trigger | When |
|---------|------|
| `dungeon_complete_any` | Any completed run |
| `dungeon_complete_<biome>` | Completed run in that biome, e.g. `dungeon_complete_stone_caves` |
| `dungeon_rarity_<rarity>` | Completed run from a map of that rarity (`common` … `legendary`); runs without a map send `dungeon_rarity_command` |
| `dungeon_no_death` | Completed run without a team death |