API Reference

KS Dungeons provides a public API for other mods to integrate with.

Access

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

KS Dungeons requires Core — if Core is present, the API is always available:

try {
    Class<?> apiClass = Class.forName("com.kyuubisoft.dungeons.api.DungeonsAPI");
    Method getInstance = apiClass.getMethod("getInstance");
    Object api = getInstance.invoke(null);
    // Use reflection to call methods
} catch (ClassNotFoundException e) {
    // KS Dungeons not installed
}

Dungeon Instances

Method	Returns	Description
`createInstance(biome, difficulty)`	`DungeonInstance`	Create a new dungeon instance
`getInstance(instanceId)`	`DungeonInstance`	Get instance by ID
`getActiveInstances()`	`List<DungeonInstance>`	All running instances
`stopInstance(instanceId)`	`boolean`	Force-stop an instance
`getPlayerInstance(playerUuid)`	`DungeonInstance`	Get the instance a player is currently in
`isInDungeon(playerUuid)`	`boolean`	Check if player is in a dungeon

Party Management

Method	Returns	Description
`createParty(leaderUuid)`	`DungeonParty`	Create a new party
`getParty(partyId)`	`DungeonParty`	Get party by ID
`getPlayerParty(playerUuid)`	`DungeonParty`	Get a player’s current party
`disbandParty(partyId)`	`boolean`	Disband a party
`inviteToParty(partyId, playerUuid)`	`boolean`	Send a party invite
`joinParty(partyId, playerUuid)`	`boolean`	Add player to party
`leaveParty(playerUuid)`	`boolean`	Remove player from party
`isInParty(playerUuid)`	`boolean`	Check if player is in a party

Scoring & Stats

Method	Returns	Description
`getPlayerStats(playerUuid)`	`DungeonStats`	Get player’s dungeon statistics
`getLeaderboard(biome, difficulty, limit)`	`List<LeaderboardEntry>`	Get top scores
`getPersonalBest(playerUuid, biome, difficulty)`	`int`	Get personal best score
`getTotalClears(playerUuid)`	`int`	Total dungeon completions
`getTotalClears(playerUuid, biome)`	`int`	Completions for a specific biome

Token Economy

Method	Returns	Description
`getTokens(playerUuid)`	`int`	Get player’s token balance
`addTokens(playerUuid, amount)`	`boolean`	Add tokens to player
`removeTokens(playerUuid, amount)`	`boolean`	Remove tokens from player
`hasTokens(playerUuid, amount)`	`boolean`	Check if player has enough tokens

Biome & Configuration

Method	Returns	Description
`getBiomes()`	`List<DungeonBiome>`	All registered biomes
`getBiome(biomeId)`	`DungeonBiome`	Get biome by ID
`getDifficulties()`	`List<Difficulty>`	All difficulty tiers
`getModifiers()`	`List<Modifier>`	All registered modifiers

Events

DungeonsAPI.getInstance().registerDungeonStartListener(event -> {
    String biome = event.biomeId();
    String difficulty = event.difficulty();
    List<UUID> players = event.players();
    // Dungeon run started
});

DungeonsAPI.getInstance().registerDungeonCompleteListener(event -> {
    int score = event.score();
    int tokensEarned = event.tokensEarned();
    // Dungeon run completed successfully
});

DungeonsAPI.getInstance().registerDungeonFailListener(event -> {
    // Dungeon run failed (out of lives or timeout)
});

DungeonsAPI.getInstance().registerBossKillListener(event -> {
    String bossId = event.bossId();
    String biome = event.biomeId();
    // Boss was defeated
});

Example: Season Pass Integration

// Award bonus tokens when a season pass challenge is completed
DungeonsAPI.getInstance().registerDungeonCompleteListener(event -> {
    for (UUID player : event.players()) {
        if (event.difficulty().equals("MYTHIC")) {
            // Bonus tokens for mythic clears
            DungeonsAPI.getInstance().addTokens(player, 100);
        }
    }
});

Example: VoiceHub Integration

// Automatically create a voice channel for dungeon parties
DungeonsAPI.getInstance().registerDungeonStartListener(event -> {
    if (VoiceHubAPI.isAvailable() && event.players().size() > 1) {
        UUID leader = event.partyLeader();
        VoiceChannel ch = VoiceHubAPI.getInstance()
            .createChannel("Dungeon: " + event.biomeId(), ChannelType.GROUP, leader);
        for (UUID member : event.players()) {
            VoiceHubAPI.getInstance().joinChannel(member, ch.getId(), null);
        }
    }
});