Boosters API

Overview

The Booster API enables external plugins to manage and query active multipliers for players. It supports permanent and temporary boosts for economies, enchants, and damage, with built-in support for stacking and time persistence.

Getting Started

Follow these steps to integrate with the booster system.

1

Get the Instance

Access the singleton API instance from the static provider.

import me.fergs.phantomdungeons.modules.boosters.api.BoostersAPI;

// Get the singleton instance
BoostersAPI boostersAPI = BoostersAPI.get();

Note: Ensure PhantomDungeons is listed as a dependency in your plugin.yml to guarantee the API is initialized before your plugin loads.

2

Check Availability

The API might return null if the boosters module is disabled in modules.yml.

if (boostersAPI == null) {
    getLogger().warning("Boosters module is disabled!");
    return;
}

3

Handle Offline Players

Most methods support both Player objects and UUIDs for efficient background processing.

UUID playerId = offlinePlayer.getUniqueId();
boolean isActive = boostersAPI.hasBooster(playerId, "money");

---

Core Operations

Checking Multipliers

Multipliers are cached in memory for zero-latency lookups. If no booster is active, the API returns 1.0.

// Get the total multiplier for a player's money gains
double multiplier = boostersAPI.getMultiplier(player, "money");

// Check if a player has any active enchantment boost
boolean boosted = boostersAPI.hasBooster(player, "enchant-void-rift");

Activating Temporary Boosters

Use this to give timed rewards (e.g., from crates or kits). The duration is in seconds.

// Give 1.5x money boost for 1 hour (3600s)
boostersAPI.giveBooster(player, "money", 1.5, 3600)
    .thenAccept(success -> {
        if (success) {
            player.sendMessage("§aYour 1.5x Money Booster is now active!");
        }
    });

Granting Permanent Boosters

Permanent boosters stay with the player until manually revoked.

// Grant permanent 2.0x damage boost
boostersAPI.givePermanentBooster(player, "damage", 2.0);

Revoking Boosters

Remove specific boosters or clear all active boosts from a player.

// Remove a specific booster
boostersAPI.removeBooster(player, "money");

// Wipe all active reflectors/boosters
boostersAPI.removeAllBoosters(player).thenAccept(count -> {
    getLogger().info("Removed " + count + " boosters from " + player.getName());
});

---

Advanced Management

Time Tracking

Query the remaining life of a booster.

long remaining = boostersAPI.getRemainingTime(player, "money");

if (remaining == -1) {
    // Permanent booster
} else if (remaining > 0) {
    // Seconds until expiry
}

Stacking and Extensions

Depending on the plugin configuration, applying multiple boosters of the same type can either extend the time or increase the multiplier.

// Check if player can stack more boosters for this type
if (boostersAPI.canStack(player, "money")) {
    int currentStacks = boostersAPI.getStackCount(player, "money");
    
    // Manually extend an existing booster duration
    boostersAPI.extendBooster(player, "money", 1800); // Add 30 minutes
}

---

Events API

Use events to react to booster changes or customize how gains are calculated.

Booster Activated Event

Fired when a player successfully redeems or is given a booster.

@EventHandler
public void onBoosterActivate(BoosterActivatedEvent event) {
    Player player = event.getPlayer();
    String type = event.getType();
    
    player.sendMessage("§6System: Booster '" + type + "' activated!");
    
    // maybe you can use for quest progression? achievement progression?
}

Booster Expired Event

Fired when a timed booster reaches its end of life.

@EventHandler
public void onBoosterExpire(BoosterExpiredEvent event) {
    // Notify player or log expiration
    // you dont actually need to notify, as it handles that. Just an example.
}

---

FAQ

What happens on logout?

Timed boosters continue to tick down based on the expiration_timestamp in the database.

Are multipliers additive?

Multipliers follow the stacking mode defined in the boosterconfiguration (e.g., EXTEND, REPLACE, or STACKED and more.).

How do I target enchants?

Use the format enchant-{enchant_id} (e.g., enchant-void-rift) as the booster type.

Is data saved if the server crashes?

The system uses auto-save intervals and guarantees data write during onDisable to prevent data loss.