ZelDuels
Developer API
The ZelDuels API lets other plugins read duel state and react to duels through Bukkit events. It
is a read-only / event-based API: you can query arenas, requests and player stats, and you can
veto a duel before it starts, but you cannot mutate internal state.
Everything public lives in the com.zeltuv.zelduels.api package (and its data / events
sub-packages), which is excluded from obfuscation — symbol names are stable across releases.
I) Adding ZelDuels as a dependency
Maven
<repository>
<id>repsy.io</id>
<url>https://repo.repsy.io/mvn/zeltuv/zelduels</url>
</repository>
<dependency>
<groupId>com.zeltuv</groupId>
<artifactId>zelduels-api</artifactId>
<version>3.3.4</version>
<scope>provided</scope>
</dependency>
Gradle
repositories {
mavenCentral()
maven { url '<https://repo.repsy.io/mvn/zeltuv/zelduels>' }
}
dependencies {
compileOnly 'com.zeltuv:zelduels-api:3.3.4'
}
Add ZelDuels to your plugin's softdepend in plugin.yml so it loads first.
II) Accessing the API
ZelDuels exposes a single interface, ZelDuelsAPI, registered with Bukkit's ServicesManager and
reachable through the static helper ZelDuels. Both live in the com.zeltuv.zelduels.api package.
import com.zeltuv.zelduels.api.ZelDuels;
import com.zeltuv.zelduels.api.ZelDuelsAPI;
ZelDuelsAPI api = ZelDuels.getApi();
if (api == null) {
// ZelDuels isn't enabled yet — bail out or retry later.
return;
}
ZelDuels.getApi() returns null until ZelDuels has finished enabling and registered itself, so
gate your initial calls on onEnable after the plugin loader has run (a softdepend guarantees
this ordering).
💠 The ZelDuelsAPI interface
The entry point to everything else.
import com.zeltuv.zelduels.api.manager.IDuelManager;
import com.zeltuv.zelduels.api.data.IDuelStats;
import java.util.Optional;
IDuelManager duels = api.getDuelManager();
// Persistent stats for a player currently loaded in memory (online / recently active).
Optional<IDuelStats> stats = api.getStats(player.getUniqueId());
stats.ifPresent(s -> {
int wins = s.getWins();
int losses = s.getLosses();
int streak = s.getWinstreak();
});
getStats(...)reflects in-memory data for online (or recently loaded) players. It returns an
emptyOptionalfor players who were never loaded this session.
🎯 The IDuelManager — querying duels
All methods are read-only. Lookups that can miss are annotated @Nullable; the isX checks return
an Optional<IArena>.
import com.zeltuv.zelduels.api.data.IArena;
import com.zeltuv.zelduels.api.data.IArenaType;
import com.zeltuv.zelduels.api.data.IDuelRequest;
// Active games
List<IArena> active = duels.getActiveArenas();
// Arena types configured on the server
LinkedList<IArenaType> types = duels.getArenaTypes();
IArenaType byName = duels.getByName("classic"); // @Nullable
// Is this player involved in a duel right now?
Optional<IArena> fighting = duels.isPlayerFighting(player);
Optional<IArena> spectating = duels.isSpectating(player);
Optional<IArena> waiting = duels.isWaiting(player);
// Arena / request lookups
IArena byPlayer = duels.getArenaByPlayer(player.getUniqueId()); // @Nullable
IArena byLocation = duels.getArenaByLocation(location); // @Nullable
Optional<IArena> here = duels.isInArena(location);
// Pending requests
boolean hasRequests = duels.hasAnyRequests(player);
IDuelRequest latest = duels.getLatestRequest(player); // @Nullable
IDuelRequest specific = duels.getRequestFrom(player, otherPlayer); // @Nullable
🏟️ Data types
IArena
A live duel. Highlights:
IArenaType type = arena.getArenaType();
ArenaState state = arena.getArenaState(); // LOADING, IN_GAME, ENDING, EDITING
IDuelSettings settings = arena.getDuelSettings();
Player p1 = arena.getPlayer1();
Player p2 = arena.getPlayer2();
List<UUID> alive = arena.getAlivePlayers();
List<UUID> spectators = arena.getSpectators();
UUID winner = arena.getWinnerUUID(); // @Nullable until the duel ends with a winner
UUID loser = arena.getLoserUUID(); // @Nullable
double bet = arena.getBet(); // 0 when betting is disabled
long elapsed = arena.getElapsedSeconds(); // seconds since the match started
boolean isFighting = arena.isFighting(player);
boolean isSpectating = arena.isSpectating(player);
boolean isWinner = arena.isWinner(player);
Player opponent = arena.getOpposite(player);
IArenaType
String id = type.id();
String name = type.name();
Material icon = type.icon();
IDuelSettings
long time = settings.getTime(); // match length, seconds
double bet = settings.getBet(); // 0 if betting disabled
boolean loseStuff = settings.isLoseStuff();
boolean fromQueue = settings.isQueue();
String kitName = settings.getKitName(); // @Nullable when no kit
IDuelRequest
Player from = request.getFrom();
Player to = request.getTo();
long expiresAt = request.getExpiration(); // epoch millis
IArenaType type = request.getArenaType();
IDuelSettings settings = request.getDuelSettings();
boolean expired = request.isExpired();
IDuelStats
UUID uuid = stats.getUuid();
String name = stats.getSavedUsername();
int games = stats.getGames();
int wins = stats.getWins();
int losses = stats.getLosses();
int winstreak = stats.getWinstreak();
double betProfits = stats.getBetProfits();
double betLosses = stats.getBetLosses();
int successScore = stats.getSuccessScore(); // clamped wins - losses, in [-20, 20]
🪝 Events
All events fire on the Bukkit event bus and respect the standard @EventHandler priorities. Only
ArenaPreStartEvent is Cancellable; cancel it to veto the duel.
import com.zeltuv.zelduels.api.events.ArenaPreStartEvent;
import com.zeltuv.zelduels.api.events.ArenaEndEvent;
import com.zeltuv.zelduels.api.events.EndReason;
@EventHandler
public void onPreStart(ArenaPreStartEvent event) {
if (event.getPlayer1().getWorld().getName().equals("hub")) {
event.setCancelled(true); // veto duels started from the hub (any bet is refunded)
}
}
@EventHandler
public void onEnd(ArenaEndEvent event) {
if (event.getReason() == EndReason.NORMAL && event.getWinner() != null) {
// reward a genuine win — ignore ragequits/timeouts
giveReward(event.getWinner(), event.getBet());
}
}
| Event | Fired | Cancellable | Notes |
|---|---|---|---|
ArenaPreStartEvent | Before a duel is created (request-accept and matchmaking-queue flows). | ✅ | Cancelling stops the duel and refunds any bet to both players. Exposes getPlayer1(), getPlayer2(), getArenaType(), getDuelSettings(). |
ArenaLoadingEvent | After ArenaPreStartEvent passes; the arena begins loading. | ❌ | Exposes getDuelSettings(), getArenaType(), getArena(). |
ArenaStartEvent | The arena finished loading and both players were teleported in. | ❌ | May fire asynchronously — schedule back onto the main thread before touching non-thread-safe API. |
ArenaDeathEvent | A player dies during a duel. | ✅ | getPlayer() is the player who died and may be null if not attributable. |
ArenaEndEvent | A duel ends, for any reason. | ❌ | getWinner() / getLoser() may be null (e.g. a timeout); getBet() is 0 when betting is off; getReason() returns an EndReason. |
EndReason
| Value | Meaning |
|---|---|
NORMAL | A player won by defeating their opponent. |
PLAYER_LEFT | A player left the arena (leave command or teleporting out). |
DISCONNECT | A player disconnected from the server. |
TIMEOUT | The match timer ran out with no winner. |
❤️🩹 Best practices
- Always go through
ZelDuels.getApi()— never reflect into the implementation packages
(com.zeltuv.zelduels.arena,.duel,.gui, …). Those are obfuscated and the symbol names
change across releases. Onlyapi,dataandsafeare stable. - Treat the API as read-only. Don't cast
IArena/IDuelManagerback to their concrete
classes to mutate them — that defeats the contract and breaks under obfuscation. - Null-check.
getApi()and the@Nullablelookups (getByName,getArenaByPlayer,
getLatestRequest,getWinnerUUID, …) can returnnull; theisXqueries returnOptional. - Listen, don't poll. Subscribe to the events instead of scanning
getActiveArenas()on a
scheduler. - Stats are in-memory.
getStats()only resolves currently-loaded (online/recent) players.
🛠️ Support
For additional support, feature requests, or bug reports, reach out on our Discord.