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: - Custom Lobby - Configurable 1-20 rounds per duel - Custom Lobby - Full inventory, armor, and offhand serialization - Custom Lobby - Automatic arena regeneration using WorldEdit/FAWE - Custom Lobby - Team battles with Party vs Party and Party Split modes - Custom Lobby - Kit-specific Free-For-All combat zones - Custom Lobby - Dedicated world with interactive hotbar items

---

🌟 Core Features

1. Duel Modes

| Mode | Description | Players | |------|-------------|---------| | FFA (Free For All) | Classic solo dueling | 2 players | | FFA (Free For All) | Team battles between parties | 2-10+ players | | FFA (Free For All) | Internal scrimmage (Red vs Blue) | 2-10+ players | | FFA (Free For All) | Unlimited players in kit-specific arenas | Unlimited |

2. Queue System

| Feature | Description | |---------|-------------| | Party Queue | Players queue by selecting a specific kit | | Party Queue | Shows "In Queue: X" and "Fighting: Y" per kit | | Party Queue | Automatically pairs queued players | | Party Queue | Leaders can queue entire parties |

3. Multi-Round System

| Setting | Options | |---------|---------| | Score Tracking | 1 to 20 configurable rounds | | Score Tracking | "Best Of" (first to majority) or "Play All" (all rounds) | | Score Tracking | 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) ``` Full Inventory Serialization: ├── Main Inventory (36 slots) ├── Armor Slots (4 slots) │ ├── Helmet │ ├── Chestplate │ ├── Leggings │ └── Boots └── Offhand Slot (1 slot) ← CRUCIAL └── Shields, Totems, Food, etc. ```

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 | |------|---------|--------------| | FFA Arenas | 1v1 and Party battles | After each match | | FFA Arenas | Free-For-All combat | On server restart |

Arena Components ``` Arena Structure: ├── Name & ID ├── Arena Type (DUEL / FFA) ├── Spawn Points │ ├── Position 1 (Player/Team 1) │ └── Position 2 (Player/Team 2) ├── Schematic File ├── Assigned Kit (FFA only) └── State (AVAILABLE / IN_USE / REGENERATING) ```

Schematic Integration - Performance Optimized - Async schematic operations - Performance Optimized - 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 ``` 1. Players teleported to arena spawn points 2. Kit applied (Inventory + Armor + Offhand) 3. Players frozen (movement disabled) 4. Countdown: 3... 2... 1... FIGHT! 5. Players unfrozen, PvP enabled ```

Phase 2: Round End (Death) ``` 1. Death detected 2. Death message broadcast 3. Score updated 4. Check win condition: ├── If match continues: │ ├── Instant reset (heal, clear, restore kit) │ ├── Teleport to spawn points │ ├── Countdown: 3... 2... 1... FIGHT! │ └── Next round begins └── If match ends: ├── VICTORY/DEFEAT titles ├── 3-second celebration ├── Stats updated ├── Teleport to lobby └── Arena queued for regeneration ```

Phase 3: Post-Match ``` 1. Winner gets VICTORY title 2. Loser gets DEFEAT title 3. Loser becomes spectator (3 seconds) 4. Both teleported to lobby 5. Arena schematic pasted (async) 6. Arena marked AVAILABLE ```

---

👥 Party System

Party Structure ``` Party: ├── Leader (1 player) │ └── Full control: invite, kick, disband, queue ├── Members (up to 9 players) │ └── Can leave, view members └── Pending Invites └── Expire after 60 seconds ```

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 - Respawn System - Each FFA arena tied to one kit - Respawn System - Every player for themselves - Respawn System - No countdown, immediate PvP - Respawn System - Death sends to lobby, re-enter via Totem

FFA Flow ``` 1. Player clicks Totem in lobby 2. FFA Menu opens (kit/arena selection) 3. Player selects kit (e.g., "Sumo FFA") 4. Teleported to FFA arena 5. Kit applied 6. Immediate PvP enabled 7. On death: Teleport to lobby 8. To rejoin: Use Totem again ```

---

📊 Scoreboard System

Lobby Scoreboard ``` ╔═══════════════════════════╗ ║ ⚔ ULTIMATE DUELS ⚔ ║ ╠═══════════════════════════╣ ║ Player: Steve ║ ║ ║ ║ Kills: 150 ║ ║ Deaths: 45 ║ ║ K/D: 3.33 ║ ║ Streak: 12 ║ ║ ║ ║ Online: 64 ║ ║ Fighting: 24 ║ ║ ║ ║ play.yourserver.com ║ ╚═══════════════════════════╝ ```

In-Duel Scoreboard ``` ╔═══════════════════════════╗ ║ ⚔ ULTIMATE DUELS ⚔ ║ ╠═══════════════════════════╣ ║ Kit: NoDebuff ║ ║ Round: 3/5 ║ ║ ║ ║ You: Steve ║ ║ Ping: 24ms ║ ║ ║ ║ Enemy: Alex ║ ║ Ping: 31ms ║ ║ ║ ║ Score: 2 - 1 ║ ║ ║ ║ play.yourserver.com ║ ╚═══════════════════════════╝ ```

FFA Scoreboard ``` ╔═══════════════════════════╗ ║ ⚔ FFA - SUMO ARENA ⚔ ║ ╠═══════════════════════════╣ ║ Player: Steve ║ ║ Kills: 7 ║ ║ Deaths: 2 ║ ║ ║ ║ Players: 12 ║ ║ ║ ║ play.yourserver.com ║ ╚═══════════════════════════╝ ```

---

👁️ Spectator System

Spectator Features - No Interaction - Losers spectate for 3s before lobby - No Interaction - Players can spectate via GUI - No Interaction - Spectators invisible to duelists - No Interaction - 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 | |-----------|-------------| | FFA Kills | Total kills across all modes | | FFA Kills | Total deaths across all modes | | FFA Kills | Calculated kill/death ratio | | FFA Kills | Total duel wins | | FFA Kills | Total duel losses | | FFA Kills | Percentage of duels won | | FFA Kills | Active win streak | | FFA Kills | Highest win streak achieved | | FFA Kills | 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 | |------------|---------|---------| | PlaceholderAPI | Server software | 1.21.1 - 1.21.x | | PlaceholderAPI or PlaceholderAPI | Schematic operations | Latest | | PlaceholderAPI | Placeholder support | 2.11+ |

Optional Dependencies

| Dependency | Purpose | |------------|---------| | LuckPerms | Economy integration (future) | | LuckPerms | Permission management |

Storage Requirements

| Storage | Purpose | |---------|---------| | File System | Player statistics (persistent) | | File System | Configuration, arenas, kits | | File System | Schematics, player data |

---

🎮 Use Cases

Use Case 1: Server Owner Setup ``` 1. Install plugin and dependencies 2. Configure config.yml (database, lobby world) 3. Create arenas (/arena create <name>) 4. Set spawn points (/arena setspawn pos1/pos2) 5. Save schematics (/arena save) 6. Create kits (/kit create <name>) 7. Set lobby spawn (/duels setlobby) 8. Reload plugin (/duels reload) ```

Use Case 2: Player Joining ``` 1. Player joins server 2. Auto-teleported to lobby (if enabled) 3. Receives locked hotbar items 4. Lobby scoreboard appears 5. Player can: ├── Queue for duel (Sword) ├── Manage party (Spyglass) ├── Edit kits (Book) ├── Join FFA (Totem) └── Change settings (Comparator) ```

Use Case 3: 1v1 Duel ``` 1. Player A: /duel PlayerB 2. Duel Request GUI opens 3. Player A selects: Kit, Arena, Rounds (5), Win Condition (Best Of) 4. Player B receives request 5. Player B accepts 6. Both teleported to arena 7. Kits applied 8. Countdown: 3... 2... 1... FIGHT! 9. Combat begins 10. Rounds continue until first to 3 wins 11. VICTORY/DEFEAT titles 12. Teleport to lobby 13. Arena regenerates ```

Use Case 4: Party Battle ``` 1. Player A: /party create 2. Player A: /party invite PlayerB PlayerC 3. Players B & C accept 4. Player A (leader) opens Queue Menu 5. Selects "Party Queue" 6. Another party queues 7. Both parties matched 8. Team 1 vs Team 2 9. Last team standing wins ```

Use Case 5: FFA Session ``` 1. Player clicks Totem in hotbar 2. FFA Menu opens 3. Player selects "Diamond FFA" 4. Teleported to Diamond FFA arena 5. Kit applied 6. Immediate PvP (no countdown) 7. Player fights others 8. On death: Teleport to lobby 9. To continue: Click Totem again ```

---

📝 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 | |----------|---------| | Localization | UltimateDuels | | Localization | 3.0.0 | | Localization | 1.21.1 - 1.21.x | | Localization | Paper (required) | | Localization | 1v1, Party vs Party, Party Split, FFA | | Localization | 1-20 rounds, Best Of / Play All | | Localization | Admin + Player Custom, Full Offhand Support | | Localization | Auto-regeneration via WorldEdit/FAWE | | Localization | Kit-based, Real-time statistics | | Localization | Up to 10 players, Split mode | | Localization | MySQL storage, Full tracking | | Localization | Lobby, Duel, FFA, Spectator | | Localization | 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 |

---

**