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, hosted at https://mvn.lumine.io/repository/maven/. The current version is 2.1.0-SNAPSHOT.
Maven
Put the following in your pom.xml:
<repositories>
<repository>
<id>lumine</id>
<url>https://mvn.lumine.io/repository/maven/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>net.playavalon</groupId>
<artifactId>MythicDungeons</artifactId>
<version>2.1.0-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
</dependencies>
Gradle (Kotlin DSL)
In your build.gradle.kts:
repositories {
maven("https://mvn.lumine.io/repository/maven/")
}
dependencies {
compileOnly("net.playavalon:MythicDungeons:2.1.0-SNAPSHOT")
}
Gradle (Groovy DSL)
In your build.gradle:
repositories {
maven { url 'https://mvn.lumine.io/repository/maven/' }
}
dependencies {
compileOnly 'net.playavalon:MythicDungeons:2.1.0-SNAPSHOT'
}
Note: The scope must be
provided(Maven) orcompileOnly(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 an API jar that contains only two package trees:
| Included | Package |
|---|---|
| Yes | net.playavalon.mythicdungeons.api.** |
| Yes | net.playavalon.mythicdungeons.player.** |
| No | everything else, including the MythicDungeons plugin class itself |
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 is compiled for Java 21 and declares api-version: 1.21.
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 onlysoftdepends on Mythic Dungeons may be enabled first, in which case the lookup returnsnull. Either usedepend, or repeat the lookup from a one-tick-delayed task or fromServiceRegisterEvent.
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");
This returns true once the player (and their party) has been queued, and false if they could not be queued. Mythic Dungeons tells the player why itself, so you don't need to. Use forceInitiateDungeonForPlayer to skip the queue and ready check.
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
A -sources.jar and a -javadoc.jar are published next to the API jar and cover the same two packages. 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.