Drako Dungeons API

Drako Dungeons exposes one unified API v1. It provides immutable, implementation-independent profile, ability, leaderboard, extension and rebirth types together with custom-enchant, live currency-booster, crystal, loot and wallet APIs.

Add the API to your plugin

Compile against the DrakoDungeons JAR, but do not shade it into your plugin:

dependencies {
    compileOnly(files("libs/DrakoDungeons-1.0.0.jar"))
}

Use a hard dependency when your plugin cannot run without DrakoDungeons:

# plugin.yml
depend: [DrakoDungeons]

For an optional integration, use softdepend and check that the API is present.

DungeonApi api = Bukkit.getServicesManager().load(DungeonApi.class);
if (api == null || api.apiVersion() != DungeonApi.CURRENT_API_VERSION) {
    getLogger().warning("DrakoDungeons API v1 is unavailable or incompatible");
    return;
}

Dungeons.api() is also available after DrakoDungeons has enabled. Service lookup is usually easier to test and handles optional integrations cleanly.

Live gameplay callbacks and mutating API methods run on Paper's primary thread. Profile and leaderboard futures complete asynchronously. Extension callbacks must be fast and must not perform network or database I/O during combat; cache external state before the callback runs.

Use the unified v1 DTO API

New integrations should use the Dungeon* DTO methods. These records contain only API and JDK types, copy mutable collections on construction, and do not expose persistence implementation classes.

UUID playerId = player.getUniqueId();

api.loadedPlayerProfile(playerId).ifPresent(profile ->
        getLogger().info(profile.lastKnownName() + " is sword level "
                + profile.swordLevel()));

api.playerProfile(playerId).thenAccept(profile -> profile.ifPresent(snapshot ->
        getLogger().info("Persisted profile revision: " + snapshot.revision())));

DungeonAbilityActivation activation =
        api.activateDungeonAbility(player, "earthquake");
if (activation.status() == DungeonAbilityActivation.Status.COOLDOWN) {
    player.sendMessage("Ready in " + activation.cooldownMillis() + " ms");
}

api.currencyLeaderboard(DungeonCurrencies.SOULS, 10).thenAccept(entries ->
        entries.forEach(entry -> getLogger().info(
                entry.lastKnownName() + ": " + entry.balance())));

DungeonExtensionSummary extensions = api.extensionSummary();
boolean customEnchantLoaded = extensions.customEnchantIds().contains("coin_burst");

loadedPlayerProfile reads only an already loaded profile. playerProfile and currencyLeaderboard may perform storage work and therefore return CompletableFuture results; do not block Paper's primary server thread while waiting for them. Ability activation and wallet mutations must run on the primary thread.

RebirthUpgradeEvent#getUpgradeType() exposes the API-owned DungeonRebirthUpgrade enum. Deprecated profile, ability-result, leaderboard and rebirth aliases remain as unversioned compatibility shims. Runtime provider registration through extensions() is an official v1 API; use extensionSummary() for read-only discovery. New integrations should otherwise use the API-owned Dungeon* DTOs.

Register pet bonuses

A pet plugin should own selection and progression in its own storage, then register one dynamic provider with DrakoDungeons. Return BigDecimal.ONE when no active pet applies. Multiple providers stack multiplicatively, and a failing provider is isolated from combat.

private ExtensionRegistration dungeonPets;

public void hookDungeons(DungeonApi api) {
    dungeonPets = api.extensions().register(new PetBonusProvider() {
        @Override
        public String id() {
            return "my_pets";
        }

        @Override
        public BigDecimal damageMultiplier(DungeonMobContext context) {
            ActivePet pet = petCache.get(context.player().getUniqueId());
            return pet == null ? BigDecimal.ONE : pet.dungeonDamageFactor();
        }

        @Override
        public BigDecimal rewardMultiplier(
                DungeonMobContext context, String currencyId, DungeonRewardCause cause) {
            ActivePet pet = petCache.get(context.player().getUniqueId());
            return pet == null ? BigDecimal.ONE : pet.dungeonCurrencyFactor(currencyId);
        }
    });
}

@Override
public void onDisable() {
    if (dungeonPets != null) dungeonPets.close();
}

DungeonMobContext identifies the zone, stage, area, mob, rarity, boss state, location, automatic/manual attack state and kill cause. Pet damage scales the direct strike and derived explosion, chain, zone and damage-over-time effects. Pet reward factors apply to per-swing and mob-kill currency.

Integrate backpacks and loot collectors

DungeonMobLootEvent fires synchronously after configured drops, enchants, armour, rebirths, global reward providers and pet factors, but before wallet or inventory delivery. It contains one mutable loot bundle for the defeated mob.

A backpack listener should store what it can first, then leave only overflow in the event bundle:

@EventHandler(priority = EventPriority.HIGH, ignoreCancelled = true)
public void onDungeonLoot(DungeonMobLootEvent event) {
    MutableDungeonLoot loot = event.loot();

    List<ItemStack> itemOverflow = backpacks.insertItems(
            event.getPlayer().getUniqueId(), loot.items());
    loot.replaceItems(itemOverflow);

    for (Map.Entry<String, BigDecimal> reward : loot.currencies().entrySet()) {
        BigDecimal accepted = backpacks.insertCurrency(
                event.getPlayer().getUniqueId(), reward.getKey(), reward.getValue());
        BigDecimal remaining = reward.getValue().subtract(accepted);
        loot.setCurrency(reward.getKey(), remaining.max(BigDecimal.ZERO));
    }

    if (loot.isEmpty()) event.setCancelled(true);
}

Only configured dungeon currency IDs enter the normal wallet. Remaining items enter the player's inventory, with overflow dropped at the private mob's location. Item stacks are defensive copies; use replaceItems or addItem to mutate the bundle. Never clear or cancel loot until the external storage operation has succeeded.

Plugins can also add loot before the event by registering a DungeonLootProvider. Providers run in stable ID order on private working copies, so a failing provider's partial changes are discarded.

ExtensionRegistration registration = api.extensions().register(new DungeonLootProvider() {
    @Override
    public String id() {
        return "my_custom_drops";
    }

    @Override
    public void contribute(DungeonMobContext context, MutableDungeonLoot loot) {
        if (context.boss()) loot.addItem(makeBossToken(context.mobId()));
    }
});

Use built-in abilities

The API exposes the configured ability catalogue and creates correctly tagged redemption items. This lets mob, crate, quest or backpack plugins award unlocks without copying private persistent data keys.

if (api.abilities().contains("booster")) {
    ItemStack token = api.abilityRedemptionItem("booster", 1); // primary thread
    rewards.add(token);
}

The player right-clicks the item to unlock it and selects it through /dungeons abilities. selectedAbility(playerId) reports the selection for a loaded profile. activateDungeonAbility(player, id) applies the same ownership, grinding and persistent cooldown checks as the Q input. Listen to DungeonAbilityUnlockEvent and DungeonAbilityActivateEvent to bridge activation into another system.

Create crystal loot

Prefer the API factories for correctly tagged Crystal Boxes and physical crystals instead of copying item metadata or persistent-data keys.

loot.addItem(api.crystalBox(1)); // amount
loot.addItem(api.crystalBox(4, 1)); // tier, amount

if (api.crystalEnchants().contains("archer")) {
    loot.addItem(api.crystalItem(
            "archer", new BigDecimal("72"), new BigDecimal("26"), false));
}

crystalEnchants() omits enchants whose base proc chance is already 100%. applyChance uses the displayed 0–100 percentage. Players can right-click either item to deposit or open it while all ownership, capacity, duplicate-type and application rules remain inside DrakoDungeons. The full CrystalService is separately available through Bukkit's service manager for advanced operations.

Create a custom enchant

A custom enchant has two parts:

1

Create the enchant YAML file

A normal enchant YAML file controls its name, GUI item, category, cost, levels, prestige and activation chance.

Create plugins/DrakoDungeons/content/enchants/coin_burst.yml. The file name must exactly match the enchant ID and each file must contain one enchant.

schema-version: 1

enchants:
  coin_burst:
    display-name: '<gold><bold>Coin Burst'
    description: 'Occasionally deals extra damage and awards Money.'
    category: SOUL
    required-sword-level: 10
    max-level: 100

    gui:
      material: GOLD_INGOT
      primary-colour: '<gold>'
      accent-colour: '<yellow>'
      name: '{primary}<bold>Coin Burst'
      lore: ['{menu_template_lore}']

    activation-chance: { base: 0.10, per-level: 0.002, maximum: 0.35 }
    cost: { currency: souls, base: 250, multiplier: 1.08 }

    effects:
      burst:
        type: CUSTOM
        parameters: { money-per-level: 5.0, damage-multiplier: 1.25 }
        options: { reward-currency: money, menu-type: 'Damage and Money' }

    visual:
      particle: HAPPY_VILLAGER
      particle-count: 12
      sound: ENTITY_EXPERIENCE_ORB_PICKUP
      volume: 0.8
      pitch: 1.2
      animation: NONE

    prestige: { max-level: 5, cost-multiplier: 1.15, effect-bonus-per-level: 0.10 }

When gui.slot is omitted, DrakoDungeons places the enchant in the next free slot from menus/sword-enchanter.yml. A one-based gui.slot can be supplied when an exact position is needed. Slots cannot overlap another enchant in the same category.

2

Register code with the same ID

private ExtensionRegistration coinBurst;

private void registerCoinBurst(DungeonApi api) {
    coinBurst = api.extensions().register(new CustomEnchant() {
        @Override
        public String id() {
            return "coin_burst";
        }

        @Override
        public CustomEnchantResult activate(CustomEnchantContext context) {
            double configuredDamage = context.parameters().getOrDefault("damage-multiplier", 1.0);
            double damage = 1.0 + (configuredDamage - 1.0) * context.prestigeMultiplier();
            double perLevel = context.parameters().getOrDefault("money-per-level", 0.0);
            String currency = context.options().getOrDefault(
                    "reward-currency", DungeonCurrencies.MONEY);
            BigDecimal money = BigDecimal.valueOf(perLevel * context.level()
                    * context.prestigeMultiplier());

            return new CustomEnchantResult(
                    damage,
                    0.0, // optional flat bonus damage
                    Map.of(currency, money)
            );
        }
    });
}

@Override
public void onDisable() {
    if (coinBurst != null) coinBurst.close();
}

The callback runs only after the configured proc chance succeeds. CustomEnchantContext provides the player and mob context, an immutable profile snapshot, level and prestige, current calculated damage, mob health, and the custom parameters and options maps.

The returned damage is applied before pet, armour and DungeonMobDamageEvent modifiers. Returned currency enters the normal reward pipeline, including registered boosters, zone/pet modifiers, sword currency attributes, DungeonCurrencyGainEvent, wallet limits and persistence.

Useful catalogue checks:

boolean loaded = api.enchants().contains("coin_burst");
boolean custom = api.customEnchants().contains("coin_burst");

If the YAML exists but no matching callback is registered, the enchant can still appear and level up, but its CUSTOM effect is neutral. Callback exceptions and invalid results are contained and logged without stopping combat.

Currency API

The stable core IDs are available as constants:

DungeonCurrencies.MONEY;  // "money"
DungeonCurrencies.SHARDS; // "shards"
DungeonCurrencies.SOULS;  // "souls"

Discover the complete configured catalogue and its display metadata:

Set<String> ids = api.currencies();

api.currency(DungeonCurrencies.SHARDS).ifPresent(currency ->
        getLogger().info(currency.displayName() + " uses " + currency.symbol()));

Wallet operations use BigDecimal and require a loaded player profile. Run mutations on Paper's primary server thread.

UUID playerId = player.getUniqueId();

BigDecimal balance = api.balance(playerId, DungeonCurrencies.MONEY);

BigDecimal credited = api.addCurrency(
        playerId,
        DungeonCurrencies.SHARDS,
        new BigDecimal("25"),
        "my-plugin:quest-reward"
);

BigDecimal removed = api.removeCurrency(
        playerId,
        DungeonCurrencies.SOULS,
        new BigDecimal("100")
); // zero when the full amount cannot be afforded

BigDecimal newBalance = api.setCurrency(
        playerId,
        DungeonCurrencies.MONEY,
        new BigDecimal("5000")
);

addCurrency requires the player to be online, applies the configured sword currency attribute, and fires DungeonCurrencyGainEvent. setCurrency is capped and rounded to the configured wallet rules. removeCurrency is all-or-nothing and rounds as a currency cost.

Create a currency booster

Register one provider for your plugin and return a factor for each reward calculation. Returning 1 leaves that currency unchanged. Providers stack multiplicatively.

private final Map<UUID, Long> doubleCurrencyUntil = new ConcurrentHashMap<>();
private ExtensionRegistration dungeonBooster;

private void registerBooster(DungeonApi api) {
    dungeonBooster = api.extensions().register(new CurrencyBoosterProvider() {
        @Override
        public String id() {
            return "my_plugin_boosters";
        }

        @Override
        public BigDecimal multiplier(CurrencyBoostContext context) {
            long expires = doubleCurrencyUntil.getOrDefault(context.playerId(), 0L);
            if (expires <= context.nowEpochMilli()) return BigDecimal.ONE;

            return switch (context.currencyId()) {
                case DungeonCurrencies.MONEY,
                     DungeonCurrencies.SHARDS,
                     DungeonCurrencies.SOULS -> new BigDecimal("2");
                default -> BigDecimal.ONE;
            };
        }
    });
}

public void activateDoubleCurrency(Player player, Duration duration) {
    doubleCurrencyUntil.put(player.getUniqueId(),
            System.currentTimeMillis() + duration.toMillis());
}

@Override
public void onDisable() {
    if (dungeonBooster != null) dungeonBooster.close();
}

Boosters affect generated dungeon rewards such as per-swing Souls, mob drops, enchant rewards and custom-enchant currency. They do not multiply direct administrative calls to addCurrency, setCurrency or removeCurrency.

Callbacks run synchronously during combat. Keep them fast, use cached state, and do not perform network or database I/O inside a custom enchant or booster callback.

Event timing

• DungeonMobDamageEvent: cancellable damage immediately before it is applied.

• DungeonMobLootEvent: cancellable and mutable loot before normal delivery or profile settlement.

• DungeonCurrencyGainEvent: final per-currency modification immediately before wallet planning.

• DungeonMobKillEvent: post-commit notification with credits, delivered item loot and kill cause.

• DungeonAbilityUnlockEvent: post-redeem notification after ownership is committed.

• DungeonAbilityActivateEvent: post-effect notification after the cooldown is committed.

• TierCompleteEvent: post-completion progression notification.

Pre-commit listeners may alter delivery. Post-commit listeners are notifications; cancelling or throwing from them cannot roll back an already committed reward.

External Money delivery guarantees

When economy.money-provider selects Vault, combat first writes a unique reward intent to the DrakoDungeons SQLite outbox. A later bounded primary-thread pass calls the active Vault provider. Failures use exponential backoff and survive restarts. Only provider-confirmed amounts are published to gameplay events and player feedback. /dga moneyoutbox status|replay provides asynchronous operational inspection without performing SQLite work on the server thread.

The outbox supports one DrakoDungeons server per SQLite database. Vault does not expose an idempotency key, so delivery is necessarily at-least-once: a JVM or power loss after the provider accepts a deposit but before the local acknowledgement commits can replay that intent. Ordinary database failures, acknowledgement retries and interrupted deletion are protected by terminal tombstones and the orderly-shutdown flush.

Reloading

After adding or editing an enchant file, run:

/dga reload

The reload validates the entire candidate config before publishing it. Existing extension registrations remain active, so a callback does not need to be registered again after a successful DrakoDungeons config reload.