Introduction To A P I

Mythic Dungeons exposes a stable developer API. You can:

• Listen to dungeon-lifecycle and party events.
• Query the running state of dungeons, instances, parties, and players.
• Programmatically initiate dungeons for players.

This page shows you how to depend on the plugin and call into its API. For specifics, see Methods and Events.

Dependency Setup

The published artifact is net.playavalon:MythicDungeons. The current version is 2.0.1-SNAPSHOT.

https://mvn.lumine.io/repository/maven/ is the repository Mythic Dungeons itself resolves its own dependencies from, and is the one to try first. The build's own deploy targets are https://mvn.lumine.io/repository/maven-releases/ for releases and https://mvn.lumine.io/repository/maven-snapshots/ for snapshots, so if a -SNAPSHOT version fails to resolve from maven/, add the snapshot repository as a second entry.

Maven

Put the following in your pom.xml:

<repositories>
    <repository>
        <id>lumine</id>
        <url>https://mvn.lumine.io/repository/maven/</url>
    </repository>
    <!-- Only needed if the -SNAPSHOT version does not resolve from the repository above. -->
    <repository>
        <id>lumine-snapshots</id>
        <url>https://mvn.lumine.io/repository/maven-snapshots/</url>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>net.playavalon</groupId>
        <artifactId>MythicDungeons</artifactId>
        <version>2.0.1-SNAPSHOT</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle (Kotlin DSL)

In your build.gradle.kts:

repositories {
    maven("https://mvn.lumine.io/repository/maven/")
    // Only needed if the -SNAPSHOT version does not resolve from the repository above.
    maven("https://mvn.lumine.io/repository/maven-snapshots/")
}

dependencies {
    compileOnly("net.playavalon:MythicDungeons:2.0.1-SNAPSHOT")
}

Gradle (Groovy DSL)

In your build.gradle:

repositories {
    maven { url 'https://mvn.lumine.io/repository/maven/' }
    // Only needed if the -SNAPSHOT version does not resolve from the repository above.
    maven { url 'https://mvn.lumine.io/repository/maven-snapshots/' }
}

dependencies {
    compileOnly 'net.playavalon:MythicDungeons:2.0.1-SNAPSHOT'
}

Note: The scope must be provided (Maven) or compileOnly (Gradle). Mythic Dungeons is a server plugin and will already be on the runtime classpath. Don't shade it into your own jar.

What is in the published jar

The artifact on mvn.lumine.io is not the runnable plugin. It is a slim API jar built by the project's api Maven profile, and it contains only two package trees:

That has one consequence worth knowing up front: MythicDungeons lives in the root package net.playavalon.mythicdungeons, so MythicDungeons.inst() does not compile against the published jar. Use the MythicDungeonsService lookup shown below. The same applies to a handful of types the API signatures reference from outside those two trees, most notably LootTable (net.playavalon.mythicdungeons.dungeons.rewards.LootTable, used by createLootTable and registerLootTable) and MenuButton (net.playavalon.mythicdungeons.menu.MenuButton, returned by every dungeon element's buildMenuButton()). If you are writing custom elements, compile against the full plugin jar instead.

Mythic Dungeons targets Java 21 and declares api-version: 1.21, so build your plugin with a release target of 21 or lower.

Plugin Setup

In your plugin.yml, declare Mythic Dungeons as a (soft- or hard-) dependency so the load order is correct:

depend: [MythicDungeons]
# or:
softdepend: [MythicDungeons]

Accessing the API

The plugin exposes a MythicDungeonsService interface through Bukkit's services manager. Cache the lookup on plugin enable:

public class MyPlugin extends JavaPlugin {

    private MythicDungeonsService dungeons;

    @Override
    public void onEnable() {
        this.dungeons = Bukkit.getServer()
                .getServicesManager()
                .load(MythicDungeonsService.class);
        if (this.dungeons == null) {
            getLogger().warning("MythicDungeons not present, disabling integration.");
        }
    }

    public MythicDungeonsService dungeons() {
        return this.dungeons;
    }
}

Note: The service is registered at the very end of Mythic Dungeons' own onEnable(), after every dungeon, menu and manager is up. A plugin that only softdepends on Mythic Dungeons may be enabled first, in which case the lookup returns null. Either use depend, or repeat the lookup from a one-tick-delayed task or from ServiceRegisterEvent.

Example: react when a player enters a dungeon

if (MyPlugin.getPlugin(MyPlugin.class).dungeons().isPlayerInDungeon(player)) {
    AbstractInstance instance = MyPlugin.getPlugin(MyPlugin.class).dungeons().getDungeonInstance(player);
    getLogger().info(player.getName() + " is inside dungeon " + instance.getDungeon().getWorldName());
}

Example: initiate a dungeon programmatically

dungeons.initiateDungeonForPlayer(player, "DungeonName");

Warning: Do not branch on the return value of initiateDungeonForPlayer. It returns false on every path, including the successful one. Mythic Dungeons messages the player itself on the failure paths. See Methods for the detail, and use forceInitiateDungeonForPlayer if you need a result you can act on.

See Methods for the full method list.

Listening to Events

Mythic Dungeons fires Bukkit-style events for every important state change: dungeon start/end, player enter/leave/finish, trigger fire, party create/join, etc. Register a Listener like any other Bukkit listener:

public class DungeonListener implements Listener {

    @EventHandler
    public void onDungeonStart(DungeonStartEvent event) {
        getLogger().info("Dungeon started: " + event.getDungeon().getWorldName()
            + " with " + event.getPlayers().size() + " players.");
    }

    @EventHandler
    public void onPlayerLeave(PlayerLeaveDungeonEvent event) {
        if (event.isEditMode()) return;
        // Award currency, log, etc.
    }
}

See Events for the full event catalog.

Javadocs and sources

The api build publishes three artifacts alongside each other: the slim API jar, a -sources.jar, and a -javadoc.jar. Both attached jars cover the same two package trees as the main artifact (api.** and player.**).

The javadoc jar is generated from delomboked sources, so the accessors Lombok synthesises from @Getter and @Setter do appear in it. That matters here, because most of the getters documented on Methods are Lombok-generated and would otherwise be missing from the rendered docs.

Most IDEs download both automatically once the dependency resolves. If yours does not, ask for them explicitly, for example mvn dependency:sources dependency:resolve -Dclassifier=javadoc.

For anything the javadocs do not answer, this wiki plus the source on the git repository is the canonical reference.