ZelDuelAddons v1.0

ZelDuelAddons

A powerful QoL addon made for ZelDuels, designed to improve the duel experience with a cleaner GUI, smoother queue flow, random map selection, automatic mode syncing, auto-return after matches, and per-mode leaderboard support.

ZelDuelAddons does not replace ZelDuels. It works as an addon layer that improves usability, presentation, and player experience while keeping ZelDuels as the core duel system.


FEATURES


Custom /duelmenu GUI

Give your players a clean and modern duel menu instead of relying only on the default ZelDuels menu.

The menu supports:

• Auto-synced modes from ZelDuels
• Custom slots
• Live queue count
• Live in-match count
• Fill items
• Leave queue button
• Kit editor button
• Leaderboard button
• Fully configurable names, lore, materials, sounds, and layout

Automatic Mode Sync

ZelDuelAddons automatically syncs modes from your existing ZelDuels kits.

When you add a new mode in ZelDuels, it can be automatically added to the duel menu after reload/startup.

When you remove a mode from ZelDuels, it can also be removed from the addon menu.

No more manually creating every mode entry from scratch.


Random Map Selection

Players only choose the mode.

The addon can automatically select a random configured map for the match, creating a smoother and faster duel flow.

Example flow:

/duelmenu
→ Select Mode
→ Opponent Found
→ Random Map Selected
→ Duel Starts



Queue Switching

Players no longer need to manually leave their current queue before selecting another mode.

Example:

Player queues DiaSmp
Player clicks Mace
The addon automatically moves them from DiaSmp queue to Mace queue

This makes queueing much smoother and more player-friendly.



Match Found Titles

When an opponent is found, players can receive clean title/actionbar notifications.

Example:

MATCH FOUND!
vs PlayerName | Map: Obsidian | Mode: DiaSmp
Please wait... Preparing your arena.

All title text, subtitle text, actionbar text, timings, and sounds are configurable.



Direct Start Mode

ZelDuelAddons includes a direct start system for smoother match timing.

Instead of waiting on the default queue flow, the addon can control when the duel starts after a match is found.

Includes safety checks to help prevent players from getting stuck outside the arena.



Auto Return After Duel

After a duel ends, players can automatically return without needing to manually run /leave.

The addon can display a clean win/lose title and return countdown.

Example:

YOU WIN!
Returning back in 3...

or

YOU LOSE!
Returning back in 3...

This removes the need for players to manually type /leave after every duel.



Direct Kit Editor Button

The duel menu can include a Kit Editor button that opens the ZelDuels kit editor directly.

This helps avoid command conflicts with plugins like CMI and keeps everything inside one clean GUI.



Per-Mode Flatfile Stats

ZelDuelAddons tracks per-mode wins, losses, and matches using flatfile storage.

Data is stored in:

plugins/ZelDuelAddons/data/players/

Example:

stats:
diasmp:
wins: 30
losses: 5
matches: 35
mace:
wins: 10
losses: 2
matches: 12

This allows you to track stats separately for each duel mode.



PlaceholderAPI Support

ZelDuelAddons adds PlaceholderAPI placeholders for per-mode stats.

Examples:

%zeldueladdons_wins_diasmp%
%zeldueladdons_losses_diasmp%
%zeldueladdons_matches_diasmp%
%zeldueladdons_winrate_diasmp%

Top placeholders are also supported:

%zeldueladdons_top_wins_diasmp_1_name%
%zeldueladdons_top_wins_diasmp_1_value%

%zeldueladdons_top_wins_diasmp_2_name%
%zeldueladdons_top_wins_diasmp_2_value%

Useful for holograms, scoreboards, tablists, and leaderboard plugins.



Built-In Leaderboard GUI

ZelDuelAddons includes a paginated leaderboard GUI.

Open it using:

/duelleaderboard
/dueltop

Or through the Leaderboard button inside /duelmenu.

The GUI displays player heads ranked by total wins, with a dynamic per-mode breakdown in the lore.

Example:

#1 PlayerName

Total Wins: 50

Mode Wins:
DiaSmp: 30
Mace: 10
SpearMace: 10

The leaderboard supports pagination, so it can display all players, not just the top 10.


CONFIG FILES


Main configuration:

plugins/ZelDuelAddons/config.yml

Leaderboard GUI configuration:

plugins/ZelDuelAddons/duelleaderboard.yml

Player stats data:

plugins/ZelDuelAddons/data/players/


COMMANDS


/duelmenu
Opens the custom duel menu.

/duelmenu reload
Reloads the addon configuration.

/duelmenu debug
Shows debug information.

/duelleaderboard
Opens the leaderboard GUI.

/dueltop
Opens the leaderboard GUI.


PERMISSIONS


zeldueladdons.use
Allows players to use the custom duel menu.

zeldueladdons.admin
Allows admins to reload and debug the addon.


DEPENDENCIES


Required:

• ZelDuels
• Paper / Spigot compatible server

Optional:
- PlaceholderAPI

PlaceholderAPI is required only if you want to use the placeholder features.


EXAMPLE USE CASES


Use ZelDuelAddons if you want to:

• Make ZelDuels easier for players to use
• Replace a plain duel menu with a cleaner GUI
• Show live queue and in-match counts
• Let players queue by mode only
• Randomly select maps
• Automatically move players between queues
• Auto-return players after duels
• Add per-mode stats
• Add per-mode leaderboards
• Display stats using PlaceholderAPI
• Create a more polished duel experience for your server

IMPORTANT NOTES


ZelDuelAddons is an addon for ZelDuels.

It does not include ZelDuels and does not replace it.

You must already have ZelDuels installed on your server.

Mode data is synced from ZelDuels, while additional GUI settings, queue behavior, stats, and leaderboard features are handled by ZelDuelAddons.


SUMMARY


ZelDuelAddons is built for server owners who want a better, smoother, and more polished duel experience for ZelDuels.

With a custom duel menu, automatic mode syncing, random maps, queue switching, match titles, auto-return, PlaceholderAPI support, flatfile per-mode stats, and a built-in leaderboard GUI, it adds the QoL features many duel servers need.