Wands API

---

Overview

The Wands API enables external plugins to interact with PhantomDungeons wands system. Query data about wands, modify outputs and more.

---

Getting Started

Follow these steps to integrate with the enchant system.

1

Get the Instance

Access the singleton API instance from the static provider.

Example.java

import me.fergs.phantomdungeons.modules.wands.api.WandAPI;

// Get the singleton instance
WandAPI enchantAPI = WandAPI.get();

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

2

Cache for Performance

Store the API instance in your plugin for better performance.

MyPlugin.java

public class MyPlugin extends JavaPlugin {
    private WandAPI wandAPI;
    
    @Override
    public void onEnable() {
        try {
            this.wandAPI = WandAPI.get();
            getLogger().info("Hooked into wands!");
        } catch (IllegalStateException e) {
            getLogger().warning("PhantomDungeons not loaded!");
        }
    }
    
    public EnchantAPI getEnchantAPI() {
        return enchantAPI;
    }
}

3

Safe Null Checks

Always ensure the API is available before using it.

ExampleCheck.java

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

---

Core Operations

1

Checking Wands

Reading wand information is synchronous and instant, all configs are cached in memory by the module.

if (!wandAPI.isWand(item)) {
    return;
}

String wandId = wandAPI.getWandId(item);
WandConfig config = wandAPI.getWandConfig(item);

2

Creating & Giving Wands

Create a wand ItemStack for a player, or add it directly to their inventory.

// Create and give separately
ItemStack wand = wandAPI.createWand("basic-wand", player);
player.getInventory().addItem(wand);

// Or give in one call
wandAPI.giveWand(player, "advanced-wand");

3

Registry Metadata

Query available wands, check existence, and get totals.

Set<String> ids = wandAPI.getWandIds();
Collection<WandConfig> all = wandAPI.getAllWands();
boolean exists = wandAPI.exists("basic-wand");
int total = wandAPI.getWandCount();

---

Cooldown Access

1

Checking Cooldowns

Determine whether a player still has an active cooldown on a specific wand.

if (wandAPI.isOnCooldown(player, "basic-wand")) {
    long remainingMs = wandAPI.getRemainingCooldown(player, "basic-wand");
    player.sendMessage("&cWand on cooldown for " + remainingMs + "ms");
}

2

Clearing Cooldowns

Remove a cooldown manually - useful for perk systems or admin overrides.

// Clear one wand's cooldown
wandAPI.clearCooldown(player, "basic-wand");

// Clear all wand cooldowns for the player
wandAPI.clearAllCooldowns(player);

---

Config Reading

Use WandConfig values to drive custom UI, restrictions, or scaling logic.

1

Reading Combat Values

Pull damage expression, cooldown, and range directly from config.

WandConfig config = wandAPI.getWandConfig("advanced-wand");
if (config == null) return;

String damageExpr = config.getDamageExpression();
long cooldownMs = config.getCooldownMs();
double maxRange = config.getMaxRange();
double minRange = config.getMinRange();

2

Reading Hologram Config

Access per-wand hologram settings for custom display logic.

WandConfig.WandHologramConfig holo = config.getHologramConfig();
if (holo != null && holo.isEnabled()) {
    String style = holo.getStyle();
    String format = holo.getFormat();
}

---

Events API

Listen to wand lifecycle events to extend or restrict behaviour from your own plugin.

1

WandAttackEvent

Fired when a wand successfully raycasts a mob, before final damage is applied. Cancellable — you can also modify the damage amount.

@EventHandler
public void onWandAttack(WandAttackEvent event) {
    // Boost basic wand damage by 25 %
    if (event.getWandConfig().getId().equalsIgnoreCase("basic-wand")) {
        event.setDamage(event.getDamage() * 1.25);
    }

    // Cancel if player is missing a permission
    if (!event.getPlayer().hasPermission("myplugin.wand.use")) {
        event.setCancelled(true);
    }
}

Available data:

Method	Returns
getPlayer()	The attacking player
getTarget()	The PhantomEntity found on a successful raytrace
getWandConfig()	The wand's config
getDamage() / setDamage()	Final damage value
isCancelled() / setCancelled()	Cancel the hit

2

WandMergedEvent

Fired when two compatible wands merge into a result wand. Not cancellable — use it for analytics, messages, or rewards.

@EventHandler
public void onWandMerged(WandMergedEvent event) {
    Player player = event.getPlayer();
    player.sendMessage("§6You created: §e" + event.getResultConfig().getDisplayName());
}

Available data:

Method	Returns
getPlayer()	The player who merged
getSourceConfig()	The wand that was consumed
getResultConfig()	The wand that was produced
getResultItem()	The final ItemStack given to the player

---

FAQ

Can I check if an item is a wand without reading NBT myself?

Yes. Use wandAPI.isWand(item) — the check is handled internally.

Is reading wand data async?

No. getWandIds(), getAllWands(), exists(), and config reads are synchronous in-memory reads.

Can I create wands for offline players?

createWand requires an online Player instance for expression evaluation. It is not intended for offline use.

Can I modify wand damage from another plugin?

Yes. Listen to WandAttackEvent and call event.setDamage(newValue).

How do I verify a wand exists before giving it?

Use wandAPI.exists("wand-id") before calling giveWand.

Can I clear cooldowns for all players at once?

Not via the API directly. Iterate online players and call clearAllCooldowns(player) for each.

---