** 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)
```
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 |
|------|---------|--------------|
| **Duel 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
- **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
```
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
- **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
```
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
- **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
```
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 |
|----------|---------|
| **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 |

---