API Documentation - Ubivis/UbiDungeon GitHub Wiki

API Documentation

This documentation describes how to integrate your plugin with AI Dungeon Generator through its API. The API allows you to access dungeon information and provide dungeon compasses to players through your own plugin functionality.

Setup

Before using the API, you need to add AI Dungeon Generator as a dependency in your plugin.yml:

depend: [AIDungeonGenerator]
# OR
softdepend: [AIDungeonGenerator]

Then, in your plugin code, get the API instance:

private AIDungeonAPI dungeonAPI;

/**
 * Set up the AIDungeonGenerator API
 * @return true if API was successfully obtained, false otherwise
 */
private boolean setupAIDungeonGenerator() {
    Plugin plugin = getServer().getPluginManager().getPlugin("AIDungeonGenerator");
    if (plugin == null) {
        return false;
    }
    
    // Get the API
    AIDungeonGenerator dungeonPlugin = (AIDungeonGenerator) plugin;
    dungeonAPI = dungeonPlugin.getAPI();
    return dungeonAPI != null;
}

@Override
public void onEnable() {
    // Initialize the API
    if (!setupAIDungeonGenerator()) {
        getLogger().warning("AIDungeonGenerator not found! Some features will be disabled.");
    }
}

Dungeon Compass Methods

The API provides several methods for obtaining dungeon compasses:

Get a compass for a specific dungeon

/**
 * Get a dungeon compass for a specific dungeon
 * @param dungeonId The ID of the dungeon (worldName:x:z)
 * @return The compass ItemStack, or null if dungeon not found
 */
ItemStack compass = dungeonAPI.getDungeonCompass("world:100:200");

Get a compass to the nearest dungeon to a player

/**
 * Get a compass to the nearest dungeon to a player
 * @param player The player
 * @return The compass ItemStack, or null if no dungeons found
 */
ItemStack compass = dungeonAPI.getNearestDungeonCompass(player);

Get a compass to a random dungeon

/**
 * Get a compass to a random dungeon
 * @return The compass ItemStack, or null if no dungeons found
 */
ItemStack compass = dungeonAPI.getRandomDungeonCompass();

Get a compass to a dungeon in a specific biome

/**
 * Get a compass to a random dungeon of a specific biome type
 * @param biome The biome type
 * @return The compass ItemStack, or null if no dungeons of that biome found
 */
ItemStack compass = dungeonAPI.getBiomeDungeonCompass(Biome.DESERT);

Dungeon Information Methods

The API provides methods to get information about dungeons:

Get the nearest dungeon to a player

/**
 * Get the nearest dungeon to a player
 * @param player The player
 * @return The nearest dungeon BiomeArea, or null if none found
 */
BiomeArea nearestDungeon = dungeonAPI.getNearestDungeon(player);

Get all dungeons

/**
 * Get all dungeons
 * @return A list of all dungeon BiomeAreas
 */
List<BiomeArea> allDungeons = dungeonAPI.getAllDungeons();

Working with BiomeArea Objects

The BiomeArea class is a key component when working with dungeons. Here's how you can use it:

// Properties available in BiomeArea
String worldName = biomeArea.getWorldName();    // Get the world name
int centerX = biomeArea.getCenterX();          // Get center X coordinate
int centerZ = biomeArea.getCenterZ();          // Get center Z coordinate
int radius = biomeArea.getRadius();            // Get radius of the area
Biome primaryBiome = biomeArea.getPrimaryBiome(); // Get primary biome type
String uniqueId = biomeArea.getUniqueId();     // Get unique ID (worldName:x:z)

// Creating a location from a BiomeArea
Location location = biomeArea.getCenterLocation();

// Checking if a location is within this area
boolean isInside = biomeArea.contains(playerLocation);

Examples

Shop Plugin Integration

This example shows how to integrate with a shop plugin to sell dungeon compasses:

/**
 * A method for a shop plugin that sells different types of dungeon compasses
 */
public void registerDungeonCompassShopItems() {
    if (dungeonAPI == null) return;
    
    // Register a shop item for a random dungeon compass
    shopManager.registerItem("random_dungeon_compass", 500, (player) -> {
        ItemStack compass = dungeonAPI.getRandomDungeonCompass();
        if (compass != null) {
            player.getInventory().addItem(compass);
            player.sendMessage("§6You purchased a §eRandom Dungeon Compass§6!");
            return true;
        } else {
            player.sendMessage("§cNo dungeons available at this time.");
            return false;
        }
    });
    
    // Register shop items for biome-specific dungeon compasses
    for (Biome biome : new Biome[]{Biome.DESERT, Biome.JUNGLE, Biome.ICE_SPIKES}) {
        shopManager.registerItem(biome.toString().toLowerCase() + "_dungeon_compass", 750, (player) -> {
            ItemStack compass = dungeonAPI.getBiomeDungeonCompass(biome);
            if (compass != null) {
                player.getInventory().addItem(compass);
                player.sendMessage("§6You purchased a §e" + biome.toString() + " Dungeon Compass§6!");
                return true;
            } else {
                player.sendMessage("§cNo " + biome.toString() + " dungeons available at this time.");
                return false;
            }
        });
    }
    
    // Register a premium shop item for the nearest dungeon compass
    shopManager.registerItem("nearest_dungeon_compass", 1000, (player) -> {
        ItemStack compass = dungeonAPI.getNearestDungeonCompass(player);
        if (compass != null) {
            player.getInventory().addItem(compass);
            player.sendMessage("§6You purchased a §eNearest Dungeon Compass§6!");
            return true;
        } else {
            player.sendMessage("§cNo dungeons available at this time.");
            return false;
        }
    });
}

Quest Plugin Integration

This example shows how to integrate with a quest plugin to reward players with dungeon compasses:

/**
 * A method that gives a dungeon compass as a quest reward
 */
public void registerQuestRewards() {
    if (dungeonAPI == null) return;
    
    // Register a quest reward for completing an exploration quest
    questManager.registerReward("dungeon_compass_reward", (player, questType) -> {
        // For exploration quests, give a biome-specific compass based on where they explored
        if (questType == QuestType.EXPLORATION) {
            Biome biome = player.getLocation().getBlock().getBiome();
            ItemStack compass = dungeonAPI.getBiomeDungeonCompass(biome);
            
            if (compass != null) {
                player.getInventory().addItem(compass);
                player.sendMessage("§6You received a §e" + biome.toString() + " Dungeon Compass§6 as a reward!");
            } else {
                // Fallback to random compass if no biome-specific dungeon exists
                compass = dungeonAPI.getRandomDungeonCompass();
                if (compass != null) {
                    player.getInventory().addItem(compass);
                    player.sendMessage("§6You received a §eRandom Dungeon Compass§6 as a reward!");
                } else {
                    // Give alternative reward if no compasses available
                    player.getInventory().addItem(new ItemStack(Material.DIAMOND, 3));
                    player.sendMessage("§6You received §e3 Diamonds§6 as a reward!");
                }
            }
        } else {
            // For other quest types, give a random compass
            ItemStack compass = dungeonAPI.getRandomDungeonCompass();
            if (compass != null) {
                player.getInventory().addItem(compass);
                player.sendMessage("§6You received a §eRandom Dungeon Compass§6 as a reward!");
            } else {
                // Give alternative reward if no compasses available
                player.getInventory().addItem(new ItemStack(Material.DIAMOND, 3));
                player.sendMessage("§6You received §e3 Diamonds§6 as a reward!");
            }
        }
    });
}

Custom Integration

This example shows how to integrate with a custom plugin feature:

/**
 * A command that gives a player a compass to the nearest dungeon
 */
@Override
public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
    if (!(sender instanceof Player)) {
        sender.sendMessage("§cThis command can only be used by players.");
        return true;
    }
    
    if (dungeonAPI == null) {
        sender.sendMessage("§cAIDungeonGenerator is not available.");
        return true;
    }
    
    Player player = (Player) sender;
    
    if (label.equalsIgnoreCase("findnearestdungeon")) {
        ItemStack compass = dungeonAPI.getNearestDungeonCompass(player);
        
        if (compass != null) {
            player.getInventory().addItem(compass);
            player.sendMessage("§6You received a compass pointing to the nearest dungeon!");
        } else {
            player.sendMessage("§cNo dungeons have been discovered yet.");
        }
        
        return true;
    }
    
    return false;
}

Adding AIDungeonGenerator as a Plugin Dependency

To properly rely on AIDungeonGenerator, add it to your plugin.yml file:

name: DungeonCompassIntegration
version: 1.0
main: com.yourplugin.DungeonCompassIntegration
api-version: 1.19
depend: [AIDungeonGenerator]  # Hard dependency - plugin won't load without AIDungeonGenerator
# OR
softdepend: [AIDungeonGenerator]  # Soft dependency - plugin will load even if AIDungeonGenerator isn't present

commands:
  dungeoncompass:
    description: Get a compass to dungeons
    usage: /dungeoncompass [nearest|random|biome|list]
    permission: dungeoncompass.use

Full Code Example

Here's a full example of a plugin that integrates with AI Dungeon Generator:

import org.bukkit.Bukkit;
import org.bukkit.block.Biome;
import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.bukkit.entity.Player;
import org.bukkit.inventory.ItemStack;
import org.bukkit.plugin.Plugin;
import org.bukkit.plugin.java.JavaPlugin;

import com.ubivismedia.aidungeon.AIDungeonGenerator;
import com.ubivismedia.aidungeon.api.AIDungeonAPI;
import com.ubivismedia.aidungeon.dungeons.BiomeArea;

import java.util.List;

public class DungeonCompassIntegration extends JavaPlugin {

    private AIDungeonAPI dungeonAPI;

    @Override
    public void onEnable() {
        // Setup API
        if (!setupAIDungeonGenerator()) {
            getLogger().warning("AIDungeonGenerator not found! Plugin will be disabled.");
            Bukkit.getPluginManager().disablePlugin(this);
            return;
        }

        // Register commands
        getCommand("dungeoncompass").setExecutor(this);
        
        getLogger().info("DungeonCompassIntegration has been enabled!");
    }

    private boolean setupAIDungeonGenerator() {
        Plugin plugin = getServer().getPluginManager().getPlugin("AIDungeonGenerator");
        if (plugin == null) {
            return false;
        }
        
        // Get the API
        AIDungeonGenerator dungeonPlugin = (AIDungeonGenerator) plugin;
        dungeonAPI = dungeonPlugin.getAPI();
        return dungeonAPI != null;
    }

    @Override
    public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
        if (!(sender instanceof Player)) {
            sender.sendMessage("§cThis command can only be used by players.");
            return true;
        }
        
        Player player = (Player) sender;
        
        if (label.equalsIgnoreCase("dungeoncompass")) {
            if (args.length < 1) {
                sendHelp(player);
                return true;
            }
            
            String subCommand = args[0].toLowerCase();
            
            switch (subCommand) {
                case "nearest":
                    giveNearestDungeonCompass(player);
                    break;
                case "random":
                    giveRandomDungeonCompass(player);
                    break;
                case "biome":
                    if (args.length < 2) {
                        player.sendMessage("§cUsage: /dungeoncompass biome <biometype>");
                        return true;
                    }
                    
                    try {
                        Biome biome = Biome.valueOf(args[1].toUpperCase());
                        giveBiomeDungeonCompass(player, biome);
                    } catch (IllegalArgumentException e) {
                        player.sendMessage("§cInvalid biome type: " + args[1]);
                    }
                    break;
                case "list":
                    listDungeons(player);
                    break;
                default:
                    sendHelp(player);
                    break;
            }
            
            return true;
        }
        
        return false;
    }
    
    private void sendHelp(Player player) {
        player.sendMessage("§6==== Dungeon Compass Commands ====");
        player.sendMessage("§e/dungeoncompass nearest§7 - Get a compass to the nearest dungeon");
        player.sendMessage("§e/dungeoncompass random§7 - Get a compass to a random dungeon");
        player.sendMessage("§e/dungeoncompass biome <biometype>§7 - Get a compass to a dungeon in a specific biome");
        player.sendMessage("§e/dungeoncompass list§7 - List all available dungeons");
    }
    
    private void giveNearestDungeonCompass(Player player) {
        ItemStack compass = dungeonAPI.getNearestDungeonCompass(player);
        
        if (compass != null) {
            if (player.getInventory().firstEmpty() != -1) {
                player.getInventory().addItem(compass);
                player.sendMessage("§6You received a compass pointing to the nearest dungeon!");
            } else {
                player.getWorld().dropItem(player.getLocation(), compass);
                player.sendMessage("§6Your inventory was full, so the compass was dropped at your feet.");
            }
        } else {
            player.sendMessage("§cNo dungeons have been discovered yet in this world.");
        }
    }
    
    private void giveRandomDungeonCompass(Player player) {
        ItemStack compass = dungeonAPI.getRandomDungeonCompass();
        
        if (compass != null) {
            if (player.getInventory().firstEmpty() != -1) {
                player.getInventory().addItem(compass);
                player.sendMessage("§6You received a compass pointing to a random dungeon!");
            } else {
                player.getWorld().dropItem(player.getLocation(), compass);
                player.sendMessage("§6Your inventory was full, so the compass was dropped at your feet.");
            }
        } else {
            player.sendMessage("§cNo dungeons have been discovered yet.");
        }
    }
    
    private void giveBiomeDungeonCompass(Player player, Biome biome) {
        ItemStack compass = dungeonAPI.getBiomeDungeonCompass(biome);
        
        if (compass != null) {
            if (player.getInventory().firstEmpty() != -1) {
                player.getInventory().addItem(compass);
                player.sendMessage("§6You received a compass pointing to a " + biome.toString().toLowerCase() + " dungeon!");
            } else {
                player.getWorld().dropItem(player.getLocation(), compass);
                player.sendMessage("§6Your inventory was full, so the compass was dropped at your feet.");
            }
        } else {
            player.sendMessage("§cNo dungeons have been discovered in " + biome.toString().toLowerCase() + " biomes yet.");
        }
    }
    
    private void listDungeons(Player player) {
        List<BiomeArea> dungeons = dungeonAPI.getAllDungeons();
        
        if (dungeons.isEmpty()) {
            player.sendMessage("§cNo dungeons have been discovered yet.");
            return;
        }
        
        player.sendMessage("§6==== Available Dungeons ====");
        int count = 0;
        
        for (BiomeArea dungeon : dungeons) {
            // Skip dungeons in other worlds
            if (!dungeon.getWorldName().equals(player.getWorld().getName())) {
                continue;
            }
            
            int distance = (int) Math.sqrt(
                Math.pow(dungeon.getCenterX() - player.getLocation().getX(), 2) +
                Math.pow(dungeon.getCenterZ() - player.getLocation().getZ(), 2)
            );
            
            player.sendMessage(String.format("§e%d. %s Dungeon at [%d, %d] - %d blocks away", 
                ++count, 
                dungeon.getPrimaryBiome().toString(), 
                dungeon.getCenterX(), 
                dungeon.getCenterZ(),
                distance
            ));
            
            // Limit to 10 dungeons per page
            if (count >= 10) {
                player.sendMessage("§7(Showing 10 closest dungeons)");
                break;
            }
        }
        
        if (count == 0) {
            player.sendMessage("§cNo dungeons have been discovered in this world yet.");
        }
    }
}
⚠️ **GitHub.com Fallback** ⚠️