Masks API

---

Overview

The Masks API enables external plugins to interact with PhantomDungeons masks system. Query registered masks, inspect equipped buffs, unlock masks for players, and open the built-in mask menu without touching internal managers.

---

Getting Started

Follow these steps to integrate with the masks system.

1

Get the Instance

Access the singleton API instance from the static provider.

Example.java

import me.fergs.phantomdungeons.modules.masks.api.MaskAPI;

// Get the singleton instance
MaskAPI maskAPI = MaskAPI.get();

Note: Ensure PhantomDungeons is listed as a dependency in your plugin.yml so the Masks module is initialized before your plugin loads.

2

Cache for Performance

Store the API instance in your plugin for easier repeated access.

MyPlugin.java

public class MyPlugin extends JavaPlugin {
    private MaskAPI maskAPI;
    
    @Override
    public void onEnable() {
        try {
            this.maskAPI = MaskAPI.get();
            getLogger().info("Hooked into masks!");
        } catch (IllegalStateException e) {
            getLogger().warning("Masks module not loaded!");
        }
    }
    
    public MaskAPI getMaskAPI() {
        return maskAPI;
    }
}

3

Safe Availability Checks

If your integration is optional, use the availability helper before calling into the API. Since masks is, you must.

ExampleCheck.java

if (!MaskAPI.isAvailable()) {
    getLogger().warning("Masks API not available!");
    return;
}

MaskAPI api = MaskAPI.get();

---

Core Operations

1

Checking Masks

Registry reads are synchronous and instant because mask configs are cached in memory.

final boolean exists = maskAPI.hasMask("shadow-mask");
final int total = maskAPI.getMaskCount();
final Set<String> ids = maskAPI.getMaskIds();
final Collection<MaskConfig> all = maskAPI.getAllMasks();

final MaskConfig config = maskAPI.getMask("shadow-mask");

2

Equipped Mask Access

You can query what a player is currently wearing without touching inventory internals.

UUID playerId = player.getUniqueId();

String equippedId = maskAPI.getEquippedMaskId(playerId);
MaskConfig equipped = maskAPI.getEquippedMask(playerId);

Notes:

• getEquippedMaskId(...) returns an empty string when nothing is equipped. Always guard against this.

• getEquippedMask(...) returns null when nothing is equipped.

3

Equip & Unequip Masks

Equip masks normally, or bypass checks for admin / reward flows.

// Respects permission needed
boolean equipped = maskAPI.equipMask(player, "shadow-mask");

// Bypasses permission + permission needed (if present)
boolean forced = maskAPI.equipMaskForced(player, "shadow-mask");

// Remove the current mask
maskAPI.unequipMask(player);

4

Unlock Management

Unlocks are persistent and tied to the player's UUID.

UUID playerId = player.getUniqueId();

boolean wasNewUnlock = maskAPI.unlockMask(playerId, "shadow-mask");
boolean unlocked = maskAPI.isUnlocked(playerId, "shadow-mask");
Collection<String> unlockedIds = maskAPI.getUnlockedMaskIds(playerId);

5

Creating Redeem Items

Generate the physical mask redeem items that players right-click to unlock a mask.

ItemStack redeemItem = maskAPI.createMaskRedeemItem("shadow-mask", 1);
if (redeemItem != null) {
    player.getInventory().addItem(redeemItem);
}

boolean isRedeem = maskAPI.isMaskRedeemItem(redeemItem);
String redeemMaskId = maskAPI.getRedeemMaskId(redeemItem);

6

Open the Built-In Menu

Open the PhantomDungeons mask selection GUI from your own plugin.

boolean opened = maskAPI.openMaskMenu(player);
if (!opened) {
    player.sendMessage("oops");
}

---

Buff Access

1

Built-In Buff Helpers

Buff lookups are synchronous and read from the currently equipped in-memory snapshot.

UUID id = player.getUniqueId();

double damageBuff = maskAPI.getDamageBuff(id);
double attackSpeedBuff = maskAPI.getAttackSpeedBuff(id);
double soulsBuff = maskAPI.getEconomyBuff(id, "souls");
double moneyBuff = maskAPI.getEconomyBuff(id, "money");
double infernoProcBuff = maskAPI.getEnchantProcBuff(id, "inferno");

Values are multiplier addends:

• 0.10 = +10%

• 0.35 = +35%

2

Generic Buff Lookups

If you know the exact buff key, use the generic accessor.

UUID id = player.getUniqueId();

double damage = maskAPI.getEquippedBuff(id, "damage");
double attackSpeed = maskAPI.getEquippedBuff(id, "attack-speed");
double souls = maskAPI.getEquippedBuff(id, "economy-souls");
double miningSpeed = maskAPI.getEquippedBuff(id, "mining-speed");

Returns 0.0 when the player has no equipped mask or the key is missing.

3

Custom Buffs

Third-party plugins can define their own mask buff keys and read them through the API.

Map<String, Double> buffs = maskAPI.getCustomBuffs(player.getUniqueId());

if (buffs.isEmpty()) {
    return;
}

double miningSpeed = buffs.getOrDefault("mining-speed", 0.0);
double xpRate = buffs.getOrDefault("xp-rate", 0.0);

Custom buffs exclude built-in system keys like:

• damage

• attack-speed

• economy-*

• enchant-*

4

Applying Buff Values

Mask buff values are additive multipliers. Apply them like this:

double baseReward = 100.0;
double buff = maskAPI.getEquippedBuff(player.getUniqueId(), "xp-rate");

double finalReward = buff > 0.0
    ? baseReward * (1.0 + buff)
    : baseReward;

---

Config Reading

Use MaskConfig to build custom UI, gating rules, or display previews.

1

Reading Basic Config Values

MaskConfig config = maskAPI.getMask("shadow-mask");
if (config == null) return;

String id = config.getId();
String displayName = config.getDisplayName();
String permission = config.getPermission();
Map<String, Double> buffs = config.getBuffs();

2

Reading Item Presentation Data

Each mask exposes item, virtual-item, and menu-item config objects.

MaskItemConfig item = config.getItem();
MaskItemConfig virtualItem = config.getVirtualItem();
MaskItemConfig menuItem = config.getMenuItem();

if (item != null) {
    Material material = item.getMaterial();
    String name = item.getDisplayName();
    List<String> lore = item.getLoreOrEmpty();
    boolean glow = item.isGlow();
    int modelData = item.getCustomModelData();
}

---

Events API

No dedicated public mask events yet

The masks module currently does not expose standalone API events for equip, unequip, or unlock actions. Integrations should call the API methods directly and query state using getEquippedMaskId(...), getEquippedMask(...), and the buff helpers.

---

FAQ

Are mask reads async?

No. Registry lookups, equipped mask reads, and buff reads are synchronous in-memory operations.

What happens if the player has no mask equipped?

getEquippedMaskId(...) returns an empty string, getEquippedMask(...) returns null, buff getters return 0.0, and getCustomBuffs(...) returns an empty map.

Can multiple masks stack?

No. The API exposes only one equipped mask per player at a time.

Can I unlock a mask without equipping it?

Yes. unlockMask(...) only grants persistent access. Equipping is a separate API call.

Can I create a redeem item for an invalid mask ID?

No. createMaskRedeemItem(...) returns null when the mask ID does not exist.

Can I use custom buff keys from another plugin?

Yes. As long as the server owner defines the custom key in the mask config, your plugin can read it with getEquippedBuff(...) or getCustomBuffs(...). This then can be used for another plugins listener.