CDuels

CDuels is a highly configurable 1v1 PvP duel plugin built for Paper 1.21-26.2. It features GUI-driven kit selection, simple arena management, detailed duel statistics, and clean admin tools that won't lag your server.

---

Features

• GUI Menus: Fully customize your menu layouts, titles, items, and lore inside menu.yml.
• In-Game Kit Editor: Create and edit kits directly in-game. Includes a dedicated layout guide menu to cleanly set up armor and offhand slots.
• Arena Settings: Set up multiple arenas and choose how they cycle: Random, Round-Robin, or First-Ready.
• Live Settings GUI: Toggle features and edit numerical values on the fly with a visual settings menu. Buttons change dynamically to show what's enabled.
• Stats & History: Tracks wins, losses, total matches, damage dealt, and damage taken. Save everything locally via YAML or connect to a MySQL database.
• Integrations: Native support for PlaceholderAPI, WorldGuard region checks for spectating, and a built-in Modrinth update checker.

---

How to Use

For Players

1. Send a Challenge: Use /duel <player> to challenge someone. You can only have one outgoing request at a time.
2. Pick a Kit: Choose your combat kit from the GUI menu that pops up.
3. Accept or Deny: The recipient can accept or deny the request. Requests expire automatically after a set timeout.
4. The Fight: When the duel ends, the winner sees a "You won" title, while the loser sees "<player> won". Subtitles show if they died, quit, or left.

For Admins

1. Set Up an Arena: Run /dueladmin create and follow the steps to set up the spawn points and bounds.
2. Create Kits: Put the items you want in your inventory and type /dueladmin kitcreate. Use the layout guide to fix slot placements.
3. Manage Live: Use /duelsadmin or /dueladmin settings to open the live configuration GUI or reload your files.

---

Commands

Command	Alias	Description
/duel <player>	/cd	Challenge a player to a 1v1 duel.
/duelaccept		Accept your pending duel request.
/dueldeny		Deny your pending duel request.
/duels <subcommand>		Main command hub for players.
/dueladmin <subcommand>		Main command hub for arena and kit management.
/duelsadmin		Open the administrative settings GUI.

/duels Subcommands:

• help — Show the help menu.
• list [page] — View active duels and arenas.
• top <wins\|winrate\|damage> [page] — Show leaderboard rankings.
• leaderboard <wins\|winrate\|damage> [page] — Show leaderboard rankings.
• stats [player] — View your own or another player's PvP stats.
• history <player> [page] — View a player's recent match history.
• cancel <player> — Cancel an outgoing challenge request.
• spectate <player> — Start spectating an ongoing duel.
• stopspectate — Stop spectating and return to your old position.
• leave — Forfeit and leave your current duel.
• viewkit — Inspect the kit items being used in the challenge.

/dueladmin Subcommands:

• create / edit / list / remove — Create, edit, list, or delete arenas.
• kitcreate / kitedit / kitremove — Create, edit, or delete kits.
• reload — Reload config.yml, menu.yml, messages.yml, and mysql.yml.
• settings — Open the live settings GUI.

---

Permissions

Node	Default	Description
cduels.command	true	Base permission for standard player commands.
cduels.command.duel	true	Allows using /duel, spectating, viewing kits, and leaving.
cduels.command.duels	true	Allows access to the /duels utility command hub.
cduels.command.duelaccept	true	Allows accepting requests.
cduels.command.dueldeny	true	Allows denying requests.
cduels.command.duels.history	op	Allows viewing player duel histories.
cduels.command.dueladmin	op	Allows access to the main administrative setup commands.
cduels.command.duelsadmin	op	Allows opening the main config GUI.
cduels.admin	op	Full admin access (includes reloads and management).

---

Placeholders

Use the %cd_<placeholder>% prefix on your scoreboards, tabs, or menus.

Arenas & Server State

• %cd_total_arenas% — Total configured arenas.
• %cd_arenas_available% / %cd_free_arenas% — Number of empty, available arenas.
• %cd_arenas_unavailable% / %cd_busy_arenas% — Number of arenas currently in use.
• %cd_total_duels% / %cd_current_duels% / %cd_active_fights% — Number of ongoing matches.
• %cd_players_dueling% / %cd_dueling_users% / %cd_users_dueling% — Total players currently fighting.
• %cd_total_kits% — Total number of created kits.
• %cd_spectators% — Total number of active spectators.

Player Stats

• %cd_wins% / %cd_player_wins% / %cd_stats_wins% — Total duel wins.
• %cd_losses% / %cd_player_losses% / %cd_stats_losses% — Total duel losses.
• %cd_battles% / %cd_battles_played% / %cd_matches_played% — Total duels played.
• %cd_damage_dealt% / %cd_total_damage_dealt% — Total damage dealt across all matches.
• %cd_damage_taken% / %cd_total_damage_taken% — Total damage taken across all matches.
• %cd_winrate% / %cd_win_rate% — Player winrate percentage.

Active Match Variables

• %cd_current_kit% / %cd_kit_used% / %cd_kit_use% — The kit being used in the current duel.
• %cd_opponent_name% / %cd_opponent% — Name of your opponent.
• %cd_opponent_health% — Current health of your opponent.
• %cd_your_health% / %cd_self_health% / %cd_health% — Your current health.
• %cd_in_duel% / %cd_is_dueling% — Check if a player is currently in a fight.