api/How to use the Dungeon Maze API

Using the DungeonMaze library

To use the Dungeon Maze API you've to do a few things. At first you've to import the DungeonMaze.jar to your project. This .jar file could be found in the newest downloadable Dungeon Maze package.

Hooking into Dungeon Maze

After you've included the DungeonMaze.jar library, you've to include the Dungeon Maze API class in your project by adding the following line to the top of your main file.

import com.timvisee.dungeonmaze.api.DungeonMazeApi;

Now make sure to create variable that holds the DungeonMazeApi instance somwhere in your main file, for example:

import com.timvisee.dungeonmaze.api.DungeonMazeApi;

public class MyPlugin extends JavaPlugin {
    public DungeonMazeApi api;

    public void onEnable() {

Now you can add the following code to the onEnable() method inside your main file:

public void onEnable() {
    // Hook into Dungeon Maze
    this.api = new DungeonMazeApi(this);

With the code above your plugin will automatically hook into Dungeon Maze!

Checking if your plugin is successfully hooked

It's very important to check if your plugin is successfully hooked into Dungeon Maze. Hooking into Dungeon Maze might fail, for example if a server owner doesn't have Dungeon Maze installed, your plugin will not be able to hook into Dungeon Maze. If the hook failed, the methods from the API will cause errors when being used. Another reason might be that the Dungeon Maze plugin is being disabled/unloaded, that will break the hook either. So this is why it's very important to check if your plugin is hooked correctly.

You can use the following method to check whether your plugin is currently hooked correctly;

if(this.api.isHooked()) {
    // Your plugin is hooked correctly!
} else {
    // Your plugin isn't hooked correctly!

You can try to re-hook into Dungeon Maze if the hook failed using the 'this.api.hook();' method, but make sure you won't create an infinite loop!

It's highly recommend to check if your plugin is hooked correctly for every method you are using, for example:

// Make sure my plugin is hooked correctly to prevent errors

Using the world manager

One of the features that's included with the API is a world manager. This world manager allows your plugin to easily list all the Dungeon Maze worlds, to check if a Dungeon Maze world is loaded, and so on. The world manager could be accesed as follows:


An example to list all Dungeon Maze worlds could be found bellow;

// Make sure my plugin is hooked into Dungeon Maze correctly
if(this.api.isHooked()) {
    // Print a list of dungeon maze worlds in the console retrieved through the Dungeon Maze API
    log.info("[DungeonMazeApiExample] Dungeon Maze worlds:");
    for(String w : this.api.getWorldManager().getDMWorlds()) {
        // Check whether the world is loaded or not
        boolean isLoaded = this.api.getWorldManager().isDMWorldLoaded(w);
            log.info("[DungeonMazeApiExample] - " + w + " (Loaded)");
            log.info("[DungeonMazeApiExample] - " + w + " (Not Loaded)");

There are way more methods available that you can use to manage or list Dungeon Maze worlds.

Using the permissions manager

Dungeon Maze contains an advanced permissions checking system that supports all the major permissions systems available for Bukkit.
The permissions manager could be accessed using:


For example, the permissions manager allows you to check if a player has permissions for something:

Player p;

// Make sure my plugin is hooked correctly
    DMAPermissionsManager permsMan = this.api.getPermissionsManager();

    if(permsMan.hasPermission(p, "permission.node", false)) {
        // The player has permission for this
    } else {
        // The player doesn't have permission for this

There are a lot more methods avaiable that you can use inside the permissions manager.

Example plugin

An example plugin that uses the Dungeon Maze API could be found on this page. This example plugin shows you how to hook into Dungeon Maze and how to list the Dungeon Maze worlds.

Writing an handler class

It´s highly recommended to create a new class (For example, called: DungeonMazeHandler) that manages the Dungeon Maze hook, so you don't have to add the whole hooking system into your main plugin class, this is just to keep your project clean.


Posts Quoted:
Clear All Quotes