Sword API

Overview

The Sword API provides a clean interface for external plugins to interact with PhantomDungeons dungeon sword system. Create custom swords, manage tiers, handle upgrades, and integrate with the combat system seamlessly.

Getting Started

Step 1: Get the API Instance

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

Java

import me.fergs.phantomdungeons.modules.sword.api.SwordAPI;

// Get the singleton instance
SwordAPI swordAPI = SwordAPI.get();

Add depend: [PhantomDungeons] to your plugin.yml to ensure proper load order.

Step 2: Cache for Performance

Store it in your main plugin class.

Java

public class MyPlugin extends JavaPlugin {
    private SwordAPI swordAPI;
    
    @Override
    public void onEnable() {
        try {
            this.swordAPI = SwordAPI.get();
        } catch (IllegalStateException e) {
            getLogger().warning("PhantomDungeons not loaded!");
        }
    }
}

Step 3: Safe Null Checks

Always check availability before using.

Java

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

Core Operations

Creating Swords

Generate new dungeon swords for players.

Java

// Create default starter sword
ItemStack defaultSword = swordAPI.createDefaultSword(player);
player.getInventory().addItem(defaultSword);

ItemStack customSword = swordAPI.createSword(player, "wooden-sword", 1);
player.getInventory().addItem(customSword);

// Create a higher tier sword
ItemStack powerfulSword = swordAPI.createSword(player, "diamond-sword", 5);
player.getInventory().addItem(powerfulSword);

Each sword has a unique UUID that maintains its identity even if dropped, stored, or traded.

Finding Player Swords

Locate a player's dungeon sword in their inventory.

Java

// Find player's current sword
ItemStack playerSword = swordAPI.findPlayerSword(player);

if (playerSword != null) {
    player.sendMessage("bingo");
} else {
    player.sendMessage("wha");
    
    // Give them one
    ItemStack newSword = swordAPI.createDefaultSword(player);
    player.getInventory().addItem(newSword);
}

Reading Sword Data

Extract information from sword ItemStacks.

Java

ItemStack sword = swordAPI.findPlayerSword(player);

if (sword != null) {
    // Get sword skin ID
    String skinId = swordAPI.getSwordSkinId(sword);
    player.sendMessage("Sword Type: §a" + skinId);
    
    // Get current tier
    int tier = swordAPI.getSwordTier(sword);
    player.sendMessage("Tier: §e" + tier);
    
    // Get damage value
    double damage = swordAPI.getSwordDamage(sword);
    player.sendMessage("Damage: §c" + damage);
}

Sword Upgrades

Validating Upgrades

Check if a sword can be upgraded before attempting.

Java

ItemStack sword = swordAPI.findPlayerSword(player);

if (sword != null) {
    SwordAPI.UpgradeValidationResult result = swordAPI.validateUpgrade(player, sword);
    
    if (result.isValid()) {
        switch (result.getUpgradeType()) {
            case TIER_UPGRADE -> {
                player.sendMessage("Next Tier: " + result.getTargetTier());
                player.sendMessage("Cost: " + result.getCost().getAmount());
            }
            case SWORD_UPGRADE -> {
                player.sendMessage("New Sword: " + result.getTargetSword());
            }
        }
    } else {
        player.sendMessage(result.getErrorMessage());
    }
}

Performing Upgrades

Upgrade swords asynchronously (handles economy deduction automatically).

Java

swordAPI.upgradeSword(player, sword).thenAccept(upgradedSword -> {
    if (upgradedSword != null) {
        player.getInventory().setItemInMainHand(upgradedSword);
        player.sendMessage("master");
    }
});

Always check if the returned sword is null - this indicates the upgrade failed (e.g., insufficient funds).

Enchantment Integration

Checking for Enchants

Query enchantment data from swords.

Java

ItemStack sword = swordAPI.findPlayerSword(player);

if (sword != null) {
    // Check if sword has specific enchant
    boolean hasSpeed = swordAPI.hasEnchant(sword, "speed");
    
    // Get enchant level
    int speedLevel = swordAPI.getEnchantLevel(sword, "speed");
    
    if (hasSpeed) {
        player.sendMessage("Speed Level: §e" + speedLevel);
    }
}

Managing Enchants

Add, update, or remove enchantments.

Java

ItemStack sword = swordAPI.findPlayerSword(player);

if (sword != null) {
    // Add/update enchant
    swordAPI.setEnchantLevel(sword, "speed", 5);
    
    // Remove enchant
    swordAPI.removeEnchant(sword, "speed");
    
    // Refresh sword display (updates lore)
    ItemStack refreshed = swordAPI.refreshSword(player, sword);
    player.getInventory().setItemInMainHand(refreshed);
}

Frequently Asked Questions

Can I create custom sword progression orders?

Yes. Define custom swords in the swords/ directory and set the progression order in sword.yml under settings.sword-order. The order determines which sword comes next when a player maxes out their current sword.

Are swords persistent across server restarts?

Yes. Swords use NBT data that persists across server restarts. Each sword has a unique UUID that maintains its identity even if the player dies, drops it, or stores it in a chest.

Can players have multiple dungeon swords?

Players should only have one dungeon sword at a time. The findPlayerSword() method locates their active sword in inventory. If you give a player a new sword, it's recommended to remove their old one first to avoid confusion.

What happens if sword configurations change?

Use refreshSword() to update existing swords with new display data after config changes. This updates the lore, name, and visual properties without changing the tier or progression state.

ItemStack sword = swordAPI.findPlayerSword(player);ItemStack updated = swordAPI.refreshSword(player, sword);player.getInventory().setItemInMainHand(updated);

Can I customize the damage formula per tier?

Yes! Each tier in a sword configuration can have its own damage value. You can use linear scaling, exponential growth, or custom values per tier:

tiers: 1: damage: 10.0 2: damage: 15.0 # +5 3: damage: 25.0 # +10 (exponential)

How do I integrate custom currencies?

Configure the currency field in the upgrade cost section:

upgrade-cost: currency: souls # Uses PhantomDungeons economy amount: 1000

As long as the currency is registered in the PhantomDungeons economy system (economies/ folder), it will work automatically!

---

Related APIs

Economy APIBoosters APIEnchants APILevelling APISword API