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);
        }
    }
});