Zone API

Overview

The Zone API provides a clean interface for external plugins to interact with PhantomDungeons dungeon zone system. Access zone configurations, manage stages, query mob data, and integrate with the dungeon progression system.

Zones are the core progression system - players advance through zones and stages, fighting increasingly difficult mobs.

Getting Started

1

Get the API Instance

In your plugin's onEnable, grab the API instance.

Java

import me.fergs.phantomdungeons.modules.zone.api.ZoneAPI;

// Get the singleton instance
ZoneAPI zoneAPI = ZoneAPI.get();

Add depend: [PhantomDungeons] to your plugin.yml to ensure proper load order.

2

Cache for Performance

Store it in your main plugin class.

Java

public class MyPlugin extends JavaPlugin {
    private ZoneAPI zoneAPI;
    
    @Override
    public void onEnable() {
        try {
            this.zoneAPI = ZoneAPI.get();
        } catch (IllegalStateException e) {
            getLogger().warning("PhantomDungeons not loaded!");
        }
    }
}

3

Safe Null Checks

Always check availability before using.

Java

if (zoneAPI == null) {
    getLogger().warning("Zone API not available!");
    return;
}

Zone Operations

Getting Zone Data

Retrieve zone configurations and information.

Java

// Get zone by ID
ZoneConfigurationModel zone = zoneAPI.getZone("barn-zone");

if (zone != null) {
    player.sendMessage("§7Zone: §a" + zone.getZoneId());
    player.sendMessage("§7World: §e" + zone.getWorld());
    player.sendMessage("§7Max Mobs: §c" + zone.getMaxMobs());
    player.sendMessage("§7Respawn Time: §b" + zone.getMobRespawnTime() + "s");
}

// Check if zone exists
if (zoneAPI.zoneExists("barn-zone")) {
    player.sendMessage("§aZone found!");
}

Getting All Zones

Access all loaded zones.

Java

// Get all zones
Collection<ZoneConfigurationModel> allZones = zoneAPI.getAllZones();

player.sendMessage("§6Total Zones: §e" + allZones.size());
for (ZoneConfigurationModel zone : allZones) {
    player.sendMessage("§7- §a" + zone.getZoneId());
}

// Get zones in progression order
List<ZoneConfigurationModel> orderedZones = zoneAPI.getZonesInOrder();

player.sendMessage("§6Zone Progression:");
for (int i = 0; i < orderedZones.size(); i++) {
    player.sendMessage("§7" + (i + 1) + ". §a" + orderedZones.get(i).getZoneId());
}

getZonesInOrder() returns zones in their configured progression order, useful for building UI or checking prerequisites.

Zone Count

Get total number of zones.

Java

int totalZones = zoneAPI.getZoneCount();
player.sendMessage("§6Server has §e" + totalZones + " §6dungeon zones!");

Stage Operations

Stages represent difficulty tiers within zones. Each stage has different mobs, spawn rates, and rewards.

Getting Stage Data

Java

// Get specific stage
StageConfigurationModel stage = zoneAPI.getStage("barn-zone", 1);

if (stage != null) {
    player.sendMessage("§7Stage: §a" + stage.getStageNumber());
    player.sendMessage("§7Mobs: §e" + stage.getMobs().size());
}

// Check if stage exists
if (zoneAPI.stageExists("barn-zone", 5)) {
    player.sendMessage("§aStage 5 exists!");
}

Getting All Stages for Zone

Java

// Get all stages for a zone (as map)
Map<Integer, StageConfigurationModel> stages = zoneAPI.getStagesForZone("barn-zone");

player.sendMessage("§6Barn Zone Stages:");
for (Map.Entry<Integer, StageConfigurationModel> entry : stages.entrySet()) {
    player.sendMessage("§7Stage " + entry.getKey() + " - §e" 
        + entry.getValue().getMobs().size() + " mob types");
}

// Get stages in order (as list)
List<StageConfigurationModel> orderedStages = zoneAPI.getStagesInOrder("barn-zone");

for (StageConfigurationModel stage : orderedStages) {
    player.sendMessage("§7Stage §e" + stage.getStageNumber());
}

Stage Counts and Limits

Java

// Get total stages in zone
int totalStages = zoneAPI.getStageCount("barn-zone");

// Get max stage number
int maxStage = zoneAPI.getMaxStageNumber("barn-zone");

// Check if zone has stages
if (zoneAPI.hasStages("barn-zone")) {
    player.sendMessage("§aZone has §e" + totalStages + " §astages");
    player.sendMessage("§aMax stage: §e" + maxStage);
}

// Get all zones with stages
Set<String> zonesWithStages = zoneAPI.getZonesWithStages();
player.sendMessage("§6Zones with stages: §e" + zonesWithStages.size());

Mob Operations

Getting Mob Data

Java

// Get mob configuration
MobConfigurationModel mob = zoneAPI.getMob("chicken-common");

if (mob != null) {
    player.sendMessage("§7Mob: §a" + mob.getMobId());
    player.sendMessage("§7Health: §c" + mob.getHealth());
    player.sendMessage("§7Damage: §e" + mob.getDamage());
    player.sendMessage("§7Type: §b" + mob.getEntityType());
}

// Check if mob exists
if (zoneAPI.mobExists("chicken-rare")) {
    player.sendMessage("§aRare chicken configured!");
}

Getting All Mobs

Java

// Get all mob IDs
Set<String> allMobIds = zoneAPI.getAllMobIds();

player.sendMessage("§6Total Mobs: §e" + allMobIds.size());
for (String mobId : allMobIds) {
    player.sendMessage("§7- §a" + mobId);
}

// Get all mob configurations
Collection<MobConfigurationModel> allMobs = zoneAPI.getAllMobs();

for (MobConfigurationModel mob : allMobs) {
    player.sendMessage("§a" + mob.getMobId() + " §7- HP: §c" + mob.getHealth());
}

AFK Mobs

AFK mobs are special mobs that spawn when players are idle.

Java

// Get all AFK mobs
List<MobConfigurationModel> afkMobs = zoneAPI.getAfkMobs();

player.sendMessage("§6AFK Mobs: §e" + afkMobs.size());
for (MobConfigurationModel mob : afkMobs) {
    player.sendMessage("§7- §c" + mob.getMobId());
}

Total Mob Count

Java

int totalMobs = zoneAPI.getMobCount();
player.sendMessage("§6Total mob configurations: §e" + totalMobs);

Frequently Asked Questions

What's the difference between zones and stages?

Zones are large dungeon areas with physical boundaries in the world. Stages are difficulty tiers within a zone - think of them as "levels" within a dungeon. Players progress through stages within a zone before moving to the next zone.

Example: Barn Zone might have 5 stages, each with progressively harder chickens and cows.

How are mob spawn locations determined?

Spawn locations are defined in the zone configuration file using the selection wand (/dungeonsadmin zone locationwand). Administrators mark spawn points, and mobs randomly spawn at these locations.

Can zones overlap?

No. Zones have defined boundaries (minPos/maxPos) and should not overlap. Each zone represents a distinct dungeon area.

Can I create zones programmatically?

The Zone API is read-only for external plugins. Zones must be configured via YAML files and admin commands. This ensures consistency and prevents conflicts.

How do I get player's current zone and stage?

Use the Player Manager API to access player dungeon data:

PlayerDungeonData data = playerManager.getPlayerData(player);String currentZone = data.getCurrentZone();int currentStage = data.getCurrentStage();

Are mob rewards dynamic?

Yes! Mob rewards support PlaceholderAPI and math expressions. Rewards can scale based on player levels, multipliers, boosters, and more. Each reward has requirements and chance percentages.

Can I listen for zone events?

While the Zone API doesn't provide events directly, you can use Bukkit's PlayerMoveEvent and check if players enter/exit zone boundaries using the zone's minPos and maxPos.

Related APIs

Economy APIBoosters APIEnchants APILevelling APISword API