Skip to content

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
empty Optional for 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());
	}
}
EventFiredCancellableNotes
ArenaPreStartEventBefore 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().
ArenaLoadingEventAfter ArenaPreStartEvent passes; the arena begins loading.❌Exposes getDuelSettings(), getArenaType(), getArena().
ArenaStartEventThe arena finished loading and both players were teleported in.❌May fire asynchronously — schedule back onto the main thread before touching non-thread-safe API.
ArenaDeathEventA player dies during a duel.✅getPlayer() is the player who died and may be null if not attributable.
ArenaEndEventA 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

ValueMeaning
NORMALA player won by defeating their opponent.
PLAYER_LEFTA player left the arena (leave command or teleporting out).
DISCONNECTA player disconnected from the server.
TIMEOUTThe match timer ran out with no winner.

❤️‍🩹 Best practices

  1. 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. Only api, data and safe are stable.
  2. Treat the API as read-only. Don't cast IArena / IDuelManager back to their concrete
    classes to mutate them — that defeats the contract and breaks under obfuscation.
  3. Null-check. getApi() and the @Nullable lookups (getByName, getArenaByPlayer,
    getLatestRequest, getWinnerUUID, …) can return null; the isX queries return Optional.
  4. Listen, don't poll. Subscribe to the events instead of scanning getActiveArenas() on a
    scheduler.
  5. 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.