** 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

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

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

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

UltimateDuels

📖About UltimateDuels