UltimateDuels

** UltimateDuels Plugin - Complete Description --- Plugin Overview UltimateDuels is a professional-grade, competitive dueling plugin designed for Minecraft 1.21.1 through 1.21.x servers running on Paper. It provides a complete PvP ecosystem including ranked duels, Free-For-All arenas, party battles, and a sophisticated matchmaking system. Key Highlights: - Multi-Round Combat System - Configurable 1-20 rounds per duel - Complete Kit Management - Full inventory, armor, and offhand serialization - Schematic Arena Restoration - Automatic arena regeneration using WorldEdit/FAWE - Party System - Team battles with Party vs Party and Party Split modes - FFA Arenas - Kit-specific Free-For-All combat zones - Custom Lobby - Dedicated world with interactive hotbar items --- Core Features 1. Duel Modes | Mode | Description | Players | |------|-------------|---------| | 1v1 Duel | Classic solo dueling | 2 players | | Party vs Party | Team battles between parties | 2-10+ players | | Party Split | Internal scrimmage (Red vs Blue) | 2-10+ players | | FFA (Free For All) | Unlimited players in kit-specific arenas | Unlimited | 2. Queue System | Feature | Description | |---------|-------------| | Kit-Based Queue | Players queue by selecting a specific kit | | Real-Time Display | Shows "In Queue: X" and "Fighting: Y" per kit | | Smart Matchmaking | Automatically pairs queued players | | Party Queue | Leaders can queue entire parties | 3. Multi-Round System | Setting | Options | |---------|---------| | Rounds | 1 to 20 configurable rounds | | Win Conditions | "Best Of" (first to majority) or "Play All" (all rounds) | | Round Reset | Instant heal, kit restore, position reset | | Score Tracking | Real-time scoreboard updates | --- Detailed Feature Breakdown Kit System Admin Standard Kits - Created by administrators via commands - Server-wide availability - Examples: NoDebuff, Sumo, Diamond, Archer, UHC, Build UHC Player Custom Kits - Personal kit variants based on admin kits - Customizable through Kit Editor GUI - Saved per-player in YAML files Kit Serialization (Critical Feature) <br> Full Inventory Serialization: <br> ├── Main Inventory (36 slots) <br> ├── Armor Slots (4 slots) <br> │ ├── Helmet <br> │ ├── Chestplate <br> │ ├── Leggings <br> │ └── Boots <br> └── Offhand Slot (1 slot) ← CRUCIAL <br> └── Shields, Totems, Food, etc. <br> Kit Editor GUI - Visual inventory editor - Dedicated offhand slot representation - Drag-and-drop item placement - Real-time preview --- ️ Arena System Arena Types | Type | Purpose | Regeneration | |------|---------|--------------| | Duel Arenas | 1v1 and Party battles | After each match | | FFA Arenas | Free-For-All combat | On server restart | Arena Components <br> Arena Structure: <br> ├── Name & ID <br> ├── Arena Type (DUEL / FFA) <br> ├── Spawn Points <br> │ ├── Position 1 (Player/Team 1) <br> │ └── Position 2 (Player/Team 2) <br> ├── Schematic File <br> ├── Assigned Kit (FFA only) <br> └── State (AVAILABLE / IN_USE / REGENERATING) <br> Schematic Integration - WorldEdit/FAWE Support - Async schematic operations - Auto-Paste - Automatic arena restoration after matches - Performance Optimized - Non-blocking regeneration --- Lobby System Custom Lobby World - Separate world/spawn for duelists - Protected environment (no PvP, no block breaking) - Dedicated spawn point Hotbar Items (Locked/Saved) | Slot | Item | Action | |------|------|--------| | 1 | ⚔️ Diamond Sword | Open Queue/Duel Menu | | 2 | Spyglass | Open Party Menu | | 3 | Book | Open Kit Editor | | 4 | Totem of Undying | Open FFA Menu | | 5 | ⚙️ Comparator | Open Settings Menu | --- ⚔️ Combat Loop (Multi-Round) Phase 1: Duel Start <br> 1. Players teleported to arena spawn points <br> 2. Kit applied (Inventory + Armor + Offhand) <br> 3. Players frozen (movement disabled) <br> 4. Countdown: 3... 2... 1... FIGHT! <br> 5. Players unfrozen, PvP enabled <br> Phase 2: Round End (Death) <br> 1. Death detected <br> 2. Death message broadcast <br> 3. Score updated <br> 4. Check win condition: <br> ├── If match continues: <br> │ ├── Instant reset (heal, clear, restore kit) <br> │ ├── Teleport to spawn points <br> │ ├── Countdown: 3... 2... 1... FIGHT! <br> │ └── Next round begins <br> └── If match ends: <br> ├── VICTORY/DEFEAT titles <br> ├── 3-second celebration <br> ├── Stats updated <br> ├── Teleport to lobby <br> └── Arena queued for regeneration <br> Phase 3: Post-Match <br> 1. Winner gets VICTORY title <br> 2. Loser gets DEFEAT title <br> 3. Loser becomes spectator (3 seconds) <br> 4. Both teleported to lobby <br> 5. Arena schematic pasted (async) <br> 6. Arena marked AVAILABLE <br> --- Party System Party Structure <br> Party: <br> ├── Leader (1 player) <br> │ └── Full control: invite, kick, disband, queue <br> ├── Members (up to 9 players) <br> │ └── Can leave, view members <br> └── Pending Invites <br> └── Expire after 60 seconds <br> Party Modes Party vs Party: - Two party leaders queue - Full team vs team battle - All members participate Party Split: - Single party splits into teams - Red Team vs Blue Team - Internal scrimmage mode - Great for practice/training --- FFA (Free For All) System FFA Characteristics - Kit-Specific Arenas - Each FFA arena tied to one kit - No Teams - Every player for themselves - Instant Action - No countdown, immediate PvP - Respawn System - Death sends to lobby, re-enter via Totem FFA Flow <br> 1. Player clicks Totem in lobby <br> 2. FFA Menu opens (kit/arena selection) <br> 3. Player selects kit (e.g., "Sumo FFA") <br> 4. Teleported to FFA arena <br> 5. Kit applied <br> 6. Immediate PvP enabled <br> 7. On death: Teleport to lobby <br> 8. To rejoin: Use Totem again <br> --- Scoreboard System Lobby Scoreboard <br> ╔═══════════════════════════╗ <br> ║ ⚔ ULTIMATE DUELS ⚔ ║ <br> ╠═══════════════════════════╣ <br> ║ Player: Steve ║ <br> ║ ║ <br> ║ Kills: 150 ║ <br> ║ Deaths: 45 ║ <br> ║ K/D: 3.33 ║ <br> ║ Streak: 12 ║ <br> ║ ║ <br> ║ Online: 64 ║ <br> ║ Fighting: 24 ║ <br> ║ ║ <br> ║ play.yourserver.com ║ <br> ╚═══════════════════════════╝ <br> In-Duel Scoreboard <br> ╔═══════════════════════════╗ <br> ║ ⚔ ULTIMATE DUELS ⚔ ║ <br> ╠═══════════════════════════╣ <br> ║ Kit: NoDebuff ║ <br> ║ Round: 3/5 ║ <br> ║ ║ <br> ║ You: Steve ║ <br> ║ Ping: 24ms ║ <br> ║ ║ <br> ║ Enemy: Alex ║ <br> ║ Ping: 31ms ║ <br> ║ ║ <br> ║ Score: 2 - 1 ║ <br> ║ ║ <br> ║ play.yourserver.com ║ <br> ╚═══════════════════════════╝ <br> FFA Scoreboard <br> ╔═══════════════════════════╗ <br> ║ ⚔ FFA - SUMO ARENA ⚔ ║ <br> ╠═══════════════════════════╣ <br> ║ Player: Steve ║ <br> ║ Kills: 7 ║ <br> ║ Deaths: 2 ║ <br> ║ ║ <br> ║ Players: 12 ║ <br> ║ ║ <br> ║ play.yourserver.com ║ <br> ╚═══════════════════════════╝ <br> --- ️ Spectator System Spectator Features - Post-Match Spectating - Losers spectate for 3s before lobby - External Spectating - Players can spectate via GUI - Invisible Mode - Spectators invisible to duelists - Flight Enabled - Free movement around arena - No Interaction - Cannot affect duel Spectator GUI - Lists all active duels - Shows players, kit, arena, round - Click to spectate any duel --- ⚙️ Settings System Player Settings (Toggle) | Setting | Description | Default | |---------|-------------|---------| | Scoreboard | Show/hide scoreboard | ON | | Death Messages | Receive death notifications | ON | | Duel Requests | Accept incoming duel requests | ON | | Party Invites | Accept party invitations | ON | | Spectators | Allow others to spectate you | ON | | Private Mode | Hide from spectator list | OFF | --- Statistics System Tracked Statistics | Statistic | Description | |-----------|-------------| | Kills | Total kills across all modes | | Deaths | Total deaths across all modes | | K/D Ratio | Calculated kill/death ratio | | Wins | Total duel wins | | Losses | Total duel losses | | Win Rate | Percentage of duels won | | Current Streak | Active win streak | | Best Streak | Highest win streak achieved | | Games Played | Total duels participated | | FFA Kills | Kills in FFA arenas | Leaderboards - Top kills - Best K/D ratio - Highest win streak - Most wins --- Dependencies & Requirements Required Dependencies | Dependency | Purpose | Version | |------------|---------|---------| | Paper | Server software | 1.21.1 - 1.21.x | | WorldEdit or FAWE | Schematic operations | Latest | | PlaceholderAPI | Placeholder support | 2.11+ | Optional Dependencies | Dependency | Purpose | |------------|---------| | Vault | Economy integration (future) | | LuckPerms | Permission management | Storage Requirements | Storage | Purpose | |---------|---------| | MySQL | Player statistics (persistent) | | YAML | Configuration, arenas, kits | | File System | Schematics, player data | --- Use Cases Use Case 1: Server Owner Setup <br> 1. Install plugin and dependencies <br> 2. Configure config.yml (database, lobby world) <br> 3. Create arenas (/arena create <name>) <br> 4. Set spawn points (/arena setspawn pos1/pos2) <br> 5. Save schematics (/arena save) <br> 6. Create kits (/kit create <name>) <br> 7. Set lobby spawn (/duels setlobby) <br> 8. Reload plugin (/duels reload) <br> Use Case 2: Player Joining <br> 1. Player joins server <br> 2. Auto-teleported to lobby (if enabled) <br> 3. Receives locked hotbar items <br> 4. Lobby scoreboard appears <br> 5. Player can: <br> ├── Queue for duel (Sword) <br> ├── Manage party (Spyglass) <br> ├── Edit kits (Book) <br> ├── Join FFA (Totem) <br> └── Change settings (Comparator) <br> Use Case 3: 1v1 Duel <br> 1. Player A: /duel PlayerB <br> 2. Duel Request GUI opens <br> 3. Player A selects: Kit, Arena, Rounds (5), Win Condition (Best Of) <br> 4. Player B receives request <br> 5. Player B accepts <br> 6. Both teleported to arena <br> 7. Kits applied <br> 8. Countdown: 3... 2... 1... FIGHT! <br> 9. Combat begins <br> 10. Rounds continue until first to 3 wins <br> 11. VICTORY/DEFEAT titles <br> 12. Teleport to lobby <br> 13. Arena regenerates <br> Use Case 4: Party Battle <br> 1. Player A: /party create <br> 2. Player A: /party invite PlayerB PlayerC <br> 3. Players B & C accept <br> 4. Player A (leader) opens Queue Menu <br> 5. Selects "Party Queue" <br> 6. Another party queues <br> 7. Both parties matched <br> 8. Team 1 vs Team 2 <br> 9. Last team standing wins <br> Use Case 5: FFA Session <br> 1. Player clicks Totem in hotbar <br> 2. FFA Menu opens <br> 3. Player selects "Diamond FFA" <br> 4. Teleported to Diamond FFA arena <br> 5. Kit applied <br> 6. Immediate PvP (no countdown) <br> 7. Player fights others <br> 8. On death: Teleport to lobby <br> 9. To continue: Click Totem again <br> --- Commands Reference Player Commands | Command | Description | Permission | |---------|-------------|------------| | /duel <player> | Challenge player to duel | ultimateduels.duel | | /accept | Accept duel request | ultimateduels.duel | | /deny | Deny duel request | ultimateduels.duel | | /stats [player] | View statistics | ultimateduels.stats | | /leaderboard | View leaderboards | ultimateduels.leaderboard | Party Commands | Command | Description | Permission | |---------|-------------|------------| | /party create | Create new party | ultimateduels.party | | /party invite <player> | Invite player | ultimateduels.party | | /party accept | Accept invitation | ultimateduels.party | | /party leave | Leave party | ultimateduels.party | | /party disband | Disband party (leader) | ultimateduels.party | | /party kick <player> | Kick member (leader) | ultimateduels.party | | /party list | List members | ultimateduels.party | Admin Commands | Command | Description | Permission | |---------|-------------|------------| | /duels admin | Admin panel | ultimateduels.admin | | /duels setlobby | Set lobby spawn | ultimateduels.admin | | /duels reload | Reload configuration | ultimateduels.admin | | /duels forceend | Force end a duel | ultimateduels.admin | | /arena create <name> | Create arena | ultimateduels.admin | | /arena delete <name> | Delete arena | ultimateduels.admin | | /arena setspawn <pos> | Set spawn point | ultimateduels.admin | | /arena save | Save schematic | ultimateduels.admin | | /arena list | List arenas | ultimateduels.admin | | /kit create <name> | Create kit | ultimateduels.admin | | /kit delete <name> | Delete kit | ultimateduels.admin | | /kit edit <name> | Edit kit | ultimateduels.admin | | /kit give <player> <kit> | Give kit | ultimateduels.admin | --- Complete Summary UltimateDuels at a Glance | Category | Details | |----------|---------| | Plugin Name | UltimateDuels | | Version | 3.0.0 | | MC Versions | 1.21.1 - 1.21.x | | Server Software | Paper (required) | | Game Modes | 1v1, Party vs Party, Party Split, FFA | | Round System | 1-20 rounds, Best Of / Play All | | Kit System | Admin + Player Custom, Full Offhand Support | | Arena System | Auto-regeneration via WorldEdit/FAWE | | Queue System | Kit-based, Real-time statistics | | Party System | Up to 10 players, Split mode | | Statistics | MySQL storage, Full tracking | | Scoreboards | Lobby, Duel, FFA, Spectator | | GUIs | Full inventory-based interface | | Localization | Full messages.yml customization | Feature Completeness | Feature | Status | |---------|--------| | ✅ Multi-Round Duels | Complete | | ✅ Offhand Kit Support | Complete | | ✅ Schematic Regeneration | Complete | | ✅ Party System | Complete | | ✅ FFA Arenas | Complete | | ✅ Queue System | Complete | | ✅ Statistics & Leaderboards | Complete | | ✅ Custom Lobby | Complete | | ✅ Scoreboard System | Complete | | ✅ Settings System | Complete | | ✅ Spectator System | Complete | | ✅ PlaceholderAPI Integration | Complete | --- **