Module Integration

PhantomDungeons is built around a first-class module system. Every built-in feature, such as economy, enchants, wands, withdraw, crystals, has its own PhantomModule, with no special internal privileges over modules you write yourself.

The same API is open to external plugins. You can write a module that lives inside your own .jar but runs inside the PhantomDungeons plugin lifecycle:

This mirrors patterns used by frameworks like PaperMC's lifecycle API and is conceptually similar to how Guice modules or Spring @Configuration scope and do their dependencies, if you've used those, it will feel familiar.

---

How the System Works

DungeonManager (constructor)
  └─ ModuleRegistry.register(module)     <- your module registered here

DungeonManager.initialize()
  └─ ModuleRegistry (topological sort by dependencies + priority)
       └─ for each module in order:
            module.onEnable(ModuleContext)
              └─ checkConfigEnabled()    <- reads modules.yml
              └─ enable()               <- YOUR code runs here
            register module's Listeners

/dungeonsadmin reload
  └─ ModuleRegistry.reloadAll()
       └─ module.onReload(ModuleContext) → reload()

plugin disable
  └─ ModuleRegistry.shutdownAll() (reverse order)
       └─ module.onDisable(ModuleContext) → disable()

The ModuleContext passed into every lifecycle method gives you access to:

Field	Type	What it is
plugin	JavaPlugin	The PhantomDungeons plugin instance
configManager	ConfigurationManager	Loads/caches YAML files from the data folder
moduleRegistry	ModuleRegistry	Retrieve sibling modules by class or ID
playerRepository	PlayerRepository	Async database access for player data, this is the "cache" layer and NOT the database layer.
playerManager	PlayerManager	In-memory online player state

---

Quick Start

Step 1 - Extend AbstractPhantomModule

Always extend AbstractPhantomModule rather than implementing PhantomModule directly. It handles the boilerplate (context assignment, logger setup, enabled flag, isEnabled()) and exposes clean enable() / reload() / disable() hooks.

import me.fergs.phantomdungeons.modules.api.AbstractPhantomModule;
import me.fergs.phantomdungeons.modules.api.module.ModuleInitException;

public final class MyModule extends AbstractPhantomModule {

    public static final String ID = "my-module";

    public MyModule() {
        super(ID, "My Module"); // your module id
    }

    @Override
    protected void enable() throws ModuleInitException {
        info("My module is starting up!");
        // initialise managers, listeners, commands…
    }

    @Override
    protected void reload() {
        info("Reloading configuration...");
    }

    @Override
    protected void disable() {
        info("Shutting down...");
    }
}

Step 2 - Register it with the ModuleRegistry

Get the registry from DungeonManager and call register() before DungeonManager.initialize() runs. The right place is your plugin's onEnable(), immediately after PhantomDungeons is confirmed to be loaded.

import me.fergs.phantomdungeons.PhantomDungeons;
import me.fergs.phantomdungeons.managers.DungeonManager;

public final class MyPlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        PhantomDungeons pd = (PhantomDungeons) getServer().getPluginManager().getPlugin("PhantomDungeons");
        if (pd == null) {
            getLogger().severe("PhantomDungeons not found — disabling.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        DungeonManager dm = pd.getDungeonManager();
        if (dm == null) {
            getLogger().severe("DungeonManager not ready — disabling.");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        dm.getModuleRegistry().register(new MyModule());
        // PhantomDungeons initialises after all plugins have enabled,
        // so your module will be picked up in the same initialisation pass.
    }
}

Declare the hard dependency in plugin.yml so Bukkit guarantees load order:

depend: [PhantomDungeons]

That's it, your module now runs inside the PhantomDungeons lifecycle.

---

Full Module Reference

AbstractPhantomModule fields available inside enable() / reload() / disable()

Field	Type	Description
plugin	JavaPlugin	The PhantomDungeons plugin instance.
context	ModuleContext	Full lifecycle context (see table above).
logger	Logger	Pre-prefixed logger: [MyModule] …
enabled	boolean	Set by checkConfigEnabled(). Read before doing real work.

Lifecycle methods

Method	When called	Notes
checkConfigEnabled()	Before enable(), always	Override to set enabled = false if modules.yml says off.
enable()	Once on startup if enabled	Throw ModuleInitException for critical failures.
reload()	On /pd reload	Flush caches, re-read config.
disable()	On plugin shutdown	Cancel tasks, release resources, clear API singletons.
getListeners()	After enable()	Return Bukkit listeners; they are auto-registered.

Logging helpers (use these instead of Bukkit.getLogger())

info("Player joined zone");      // [My Module] Player joined zone
warn("Config key missing");      // [My Module] Config key missing
severe("Database error");        // [My Module] Database error

---

Common Patterns

Toggle with modules.yml

Follow the same pattern all built-in sub-modules use, the read the flag in checkConfigEnabled() so the registry skips enable() automatically:

import me.fergs.phantomdungeons.configuration.YamlConfigFile;
import java.io.File;

@Override
protected void checkConfigEnabled() {
    YamlConfigFile cfg = YamlConfigFile.loadConfiguration(
            new File(plugin.getDataFolder(), "modules.yml")
    );
    enabled = cfg.getBoolean("sub-modules.my-module", true);
}

Add the corresponding key to your copy of modules.yml (or instruct server admins to add it):

sub-modules:
  my-module: true

Declare dependencies

If your module depends on, say, EconomyModule and ZoneModule, declare their IDs. The registry performs a topological sort ,your enable() is guaranteed to run after both dependencies are ready:

import me.fergs.phantomdungeons.modules.economy.EconomyModule;
import me.fergs.phantomdungeons.modules.zone.ZoneModule;

@Override
public Set<String> getDependencies() {
    return Set.of(EconomyModule.ID, ZoneModule.ID);
}

Control initialisation priority

Among modules with no unsatisfied dependencies, lower priority numbers initialise first (default is 100):

@Override
public int getPriority() {
    return 80; // run before priority-100 modules
}

Access a sibling module

import me.fergs.phantomdungeons.modules.economy.EconomyModule;
import me.fergs.phantomdungeons.modules.economy.managers.EconomyManager;

@Override
protected void enable() throws ModuleInitException {
    EconomyModule economy = context.getModule(EconomyModule.class);
    if (economy == null || !economy.isEnabled()) {
        throw new ModuleInitException(ID, "EconomyModule is required but not enabled.");
    }
    EconomyManager economyManager = economy.getEconomyManager();
    // use economyManager…
}

Or use the static helper from AbstractPhantomModule:

EconomyModule economy = AbstractPhantomModule.getModuleByClass(context, EconomyModule.class);

Expose a public API (recommended)

All built-in modules (Economy, Wands, Withdraw, Leveling) expose a typed API via a singleton provider. Reproduce the same three-file pattern:

MyModuleAPI.java

public interface MyModuleAPI {

    static MyModuleAPI get() {
        return MyModuleAPIProvider.getInstance();
    }

    int getScore(Player player);
    void addScore(Player player, int amount);
    boolean isAvailable();
}

MyModuleAPIProvider.java

MyModuleAPIImpl.java

Then hook it up inside the module:

private MyManager manager;

@Override
protected void enable() throws ModuleInitException {
    manager = new MyManager(plugin);
    MyModuleAPIProvider.setInstance(new MyModuleAPIImpl(manager));
}

@Override
protected void disable() {
    MyModuleAPIProvider.clearInstance();
    if (manager != null) manager.shutdown();
}

External callers then use:

if (MyModuleAPIProvider.isAvailable()) { <- or something similiar
    MyModuleAPI.get().addScore(player, 10);
}

---

Example

ScoreModule.java

import me.fergs.phantomdungeons.configuration.YamlConfigFile;
import me.fergs.phantomdungeons.modules.api.AbstractPhantomModule;
import me.fergs.phantomdungeons.modules.api.module.ModuleInitException;
import me.fergs.phantomdungeons.modules.economy.EconomyModule;
import org.bukkit.event.Listener;

import java.io.File;
import java.util.List;
import java.util.Set;

public final class ScoreModule extends AbstractPhantomModule {

    public static final String ID = "score-tracker";

    private ScoreManager scoreManager;
    private ScoreListener scoreListener;

    public ScoreModule() {
        super(ID, "Score Tracker");
    }

    @Override
    public int getPriority() {
        return 80; 
    }

    @Override
    public Set<String> getDependencies() {
        return Set.of(EconomyModule.ID);
    }

    @Override
    protected void checkConfigEnabled() {
        YamlConfigFile cfg = YamlConfigFile.loadConfiguration(
                new File(plugin.getDataFolder(), "modules.yml")
        );
        enabled = cfg.getBoolean("sub-modules.score-tracker", true);
    }

    @Override
    protected void enable() throws ModuleInitException {
        EconomyModule economy = context.getModule(EconomyModule.class);
        if (economy == null || !economy.isEnabled()) {
            throw new ModuleInitException(ID, "EconomyModule required but not available.");
        }

        scoreManager  = new ScoreManager(plugin, economy.getEconomyManager());
        scoreListener = new ScoreListener(scoreManager);

        ScoreAPIProvider.setInstance(new ScoreAPIImpl(scoreManager));
        info("Score Tracker ready.");
    }

    @Override
    protected void reload() {
        if (scoreManager != null) scoreManager.reload();
    }

    @Override
    protected void disable() {
        ScoreAPIProvider.clearInstance();
        if (scoreManager != null) scoreManager.shutdown();
    }
}

---

Throwing ModuleInitException

Use ModuleInitException to signal that your module cannot start. By default the exception is critical, meaning PhantomDungeons will log the error and continue without your module (it will not crash the whole server). Pass false as the third argument only if failure should abort startup entirely.

// Non-critical — module is skipped, server keeps going
throw new ModuleInitException(ID, "Optional dependency missing — module disabled.", false);

// Critical — prevents plugin startup (use sparingly)
throw new ModuleInitException(ID, "Required config file missing — cannot continue.");

// With cause
throw new ModuleInitException(ID, "Database connection failed.", cause);

---

Accessing PhantomDungeons APIs from Your Module

Once inside enable(), context exposes everything you need without touching PhantomDungeons.getInstance():

// Economy
EconomyModule eco = context.getModule(EconomyModule.class);
EconomyManager ecoMgr = eco != null ? eco.getEconomyManager() : null;

// Player data (async)
context.getPlayerRepository()
       .getBalance(player.getUniqueId(), "money")
       .thenAccept(balance -> { /* ... */ });

// Config files
YamlConfigFile cfg = context.getConfigManager().getConfig("my-config");

// Other module by ID
PhantomModule sibling = context.getModule("crystals");

---