Summary API

Overview

The Summary API provides a clean interface for external plugins to interact with PhantomDungeons periodic summary system. Track player gains (currency, levels, etc.) and display them in timed intervals, keeping players informed of their progress.

Getting Started

1

Get the API Instance

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

Java

import me.fergs.phantomdungeons.modules.summary.api.SummaryAPI;

// Get the singleton instance
SummaryAPI summaryAPI = SummaryAPI.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 SummaryAPI summaryAPI;
    
    @Override
    public void onEnable() {
        try {
            this.summaryAPI = SummaryAPI.get();
        } catch (IllegalStateException e) {
            getLogger().warning("PhantomDungeons not loaded!");
        }
    }
}

3

Safe Null Checks

Always check availability before using.

Java

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

Core Operations

Tracking Currency Gains

Record currency gains for a player. These accumulate and display in periodic summaries.

Java

// Track currency gain for a player
summaryAPI.trackCurrencyGain(player, "money", BigDecimal.valueOf(1000));
summaryAPI.trackCurrencyGain(player, "souls", BigDecimal.valueOf(50));

// Track by UUID (safe for offline players)
summaryAPI.trackCurrencyGain(uuid, "money", BigDecimal.valueOf(1000));

Currency gains are thread-safe and can be called from any thread.

Tracking Level Gains

Record level progression for a player.

Java

// Track level gains
summaryAPI.trackLevelGain(player, "sword-level", 3);
summaryAPI.trackLevelGain(player, "prestige", 1);

Querying Player Data

Retrieve accumulated gains for a player.

Java

// Get specific currency gain
BigDecimal moneyGained = summaryAPI.getCurrencyGain(player, "money");

// Get specific level gain
int swordLevels = summaryAPI.getLevelGain(player, "sword-level");

// Get all currency gains
Map<String, BigDecimal> allCurrency = summaryAPI.getCurrencyGains(player);

Summary Management

Control when summaries are sent or cleared.

Java

// Send summary to player immediately
summaryAPI.sendSummaryToPlayer(player);

// Clear player tracked data
summaryAPI.clearPlayerData(player);

Frequently Asked Questions

How often are summaries sent?

Summaries are sent based on the interval setting in config.yml (default: 60 seconds). This can be changed and reloaded without restarting the server.

Are summaries persistent across restarts?

No. Summary data is session-based and resets after each display and when players log out. It's designed for real-time progress tracking, not long-term statistics.

Can I customize the summary format?

Yes. Edit the summary-message.message section in config.yml. You can use any PlaceholderAPI placeholders, including PhantomDungeons summary placeholders, and color codes.

What happens if a player has no gains?

Summaries are automatically suppressed if a player has nothing to display (no gains tracked). This prevents spam and empty messages.

Can I track custom currencies?

Yes! Use any currency ID you want. As long as you have the corresponding placeholder configured (e.g., %phantomdungeons_summary_mycurrency_formatted%), it will display correctly.

Is there a way to clear all players' summary data at once?

Not directly through the API, but you can iterate through online players and call clearPlayerData() for each, or simply reload the plugin.

---

Related APIs

Economy APIBoosters APIEnchants APILevelling APISword API