# ULTIMATE SUPER PRACTICE — COMPLETE MASTER DEVELOPMENT PROMPT
## ROLE
Act as a senior Minecraft Paper plugin developer, Java architect, PvP systems engineer, GUI developer, database engineer, and QA tester.
Build a complete, professional, premium-quality Minecraft PvP Practice plugin named **Ultimate Super Practice**.
This must be a real, working plugin suitable for a production PvP server. Do not create a demo, incomplete skeleton, placeholder implementation, or a GUI-only plugin.
Do not claim zero bugs without testing. Write reliable code, test it, fix discovered errors, and document anything that remains incomplete.
# 1. PROJECT INFORMATION
- Plugin name: Ultimate Super Practice
- Plugin ID: UltimateSuperPractice
- Main package: `com.ryn.ultimatesuperpractice`
- Main class: `com.ryn.ultimatesuperpractice.UltimateSuperPractice`
- Maven artifact ID: `ultimate-super-practice`
- Java version: Java 21
- Server API: Paper 1.21.11
- Build system: Maven
- Plugin metadata: `plugin.yml`
- Default database: SQLite
- Optional database: MySQL/MariaDB
Use compatible, stable APIs and dependencies. Prefer Paper/Bukkit API. Do not depend on NMS or unsupported internal server classes.
The core plugin must work without requiring Vault, LuckPerms, ProtocolLib, PlaceholderAPI, or any other third-party plugin.
Optional integrations must be detected safely and must never prevent the plugin from starting when absent.
# 2. PROJECT STRUCTURE
Organize the project into clean, maintainable modules:
- Main plugin lifecycle
- Configuration and validation
- Commands and permissions
- GUI framework
- Game mode registry
- Kit management
- Arena management
- Matchmaking and queue management
- Match lifecycle and result processing
- Ranked and ELO systems
- Party and team systems
- FFA and training
- Spectator system
- Player profiles and statistics
- Database and migrations
- Leaderboards
- Placeholder integrations
- Admin and debugging tools
- Event listeners
- Unit and integration tests
Use dependency injection or clear constructor-based service wiring where practical. Avoid giant classes, duplicated listeners, global mutable state, and circular dependencies.
# 3. COMPLETE PRACTICE CORE
Implement:
- Practice lobby and configurable spawn
- `/practice` main menu
- Solo, duo, team, ranked, and unranked queues
- Automatic matchmaking
- Queue cancellation and status
- Queue timeout and graceful cancellation
- Configurable countdown
- Match start, active, ending, and finished states
- Best of 1, Best of 3, and Best of 5
- Match timers and overtime where appropriate
- Rematch requests with expiration
- Disconnect and reconnect handling
- Forfeit and timeout handling
- Death and victory detection
- Draw handling
- Match history and result messages
- Spectator mode
- Automatic player return to lobby
- Player state restoration
- Match recovery after abnormal shutdown
Each match must have a unique ID and a controlled lifecycle.
Never allow a player to enter multiple matches simultaneously. Never process the same match result twice.
# 4. GAME MODES — 25+ MODES
Implement real game mechanics for these modes:
1. Sword
2. Classic
3. NoDebuff
4. Debuff
5. Boxing
6. Sumo
7. BuildUHC
8. UHC
9. Gapple
10. Axe
11. Pot
12. OP
13. Combo
14. Pearl Fight
15. SkyWars Duel
16. BedWars Practice
17. Bridge
18. Stick Fight
19. Archer
20. Mace
21. Crystal PvP
22. FFA
23. Custom Kit
24. Party Fight
25. Team Fight
26. Parkour PvP
27. Fireball Fight
28. Knockback
29. Classic UHC
30. TNT Sumo
Every mode must have its own configurable kit, rules, inventory, win conditions, arena requirements, and matchmaking settings.
Do not simply create mode buttons without implementing their mechanics.
Modes requiring special maps or mechanics must document those requirements. Disable a mode safely if its required configuration is missing.
All item materials, enchantments, and attributes must be compatible with Minecraft 1.21.11.
# 5. KIT SYSTEM
Implement:
- Custom kit definitions
- Kit editor GUI
- Per-mode kits
- Save and load layouts
- Default kit restoration
- Enchantments and item metadata
- Supported item components
- Armor slots and offhand
- Item limits and validation
- Configurable allowed items
- Configurable health and potion effects
- Kit import/export where practical
- Safe kit persistence across restarts
Prevent kit editing during matches and prevent inventory duplication exploits.
# 6. ARENA SYSTEM
Implement:
- Arena creation, editing, deletion, and validation
- Player 1 and player 2 spawn points
- Spectator spawn points
- Arena boundaries
- Void detection and recovery
- Arena availability tracking
- Separate arenas for simultaneous matches
- Mode-specific arena selection
- Arena reset after matches
- Arena protection
- Safe handling of unloaded or missing worlds
- Recovery of abandoned arenas
- Admin arena inspection commands
Provide easy commands for setting locations.
For block-based arenas, implement a safe snapshot/reset system with configurable block limits. Prevent concurrent resets and do not reset an arena used by another match.
Document any world-reset limitation instead of pretending a feature works when it does not.
# 7. RANKED AND ELO SYSTEM
Implement:
- Configurable ELO calculation
- Initial rating
- Rating gains and losses
- Matchmaking by rating difference
- Expanding rating search range
- Rank tiers
- Win/loss/draw statistics
- Win streaks
- Seasonal leaderboards
- Configurable rating thresholds
- Season reset and rewards
- Persistent match history
- Anti-abuse protection against repeated rating farming
Ensure that ratings and statistics are updated exactly once per completed match.
Use safe database transactions for related rating and match-result updates.
# 8. PARTY AND TEAM SYSTEM
Implement:
- Party creation
- Invitations with expiration
- Accept and decline
- Party leader transfer
- Leave and disband
- Maximum party size
- Party chat
- Party versus party matchmaking
- Team assignment and balancing
- Friendly-fire settings
- Party restrictions during matches
- Safe offline-member handling
Validate all party actions and permissions.
# 9. FFA AND TRAINING SYSTEM
Implement:
- Multiple FFA arenas
- Custom FFA kits
- Kill and death statistics
- Kill streaks
- Respawn locations
- Spawn protection options
- Combat tags
- Combo counter
- CPS display
- Ping display
- Training targets or dummies where technically feasible
- Practice statistics
Do not advertise an intelligent PvP bot unless a functional bot is implemented.
# 10. PREMIUM GUI SYSTEM
Create professional, configurable GUIs for:
- Main practice menu
- Mode selection
- Ranked and unranked selection
- Queue status
- Kit selection
- Kit editor
- Party management
- Statistics
- Leaderboards
- Match results
- Rematch confirmation
- Player settings
- Arena administration
GUI requirements:
- Configurable titles, materials, slots, names, and lore
- Configurable sounds and visual effects
- Click validation
- No unintended item movement
- No duplicate actions from repeated clicks
- Safe handling of player disconnections
- Clear locked, unavailable, and queue states
- Configurable filler items
- Inventory restoration after GUI use
Do not hardcode server IP addresses, world names, or spawn coordinates.
# 11. SPECTATOR SYSTEM
Implement:
- Match spectating
- Permission checks
- Safe teleportation
- Spectator visibility settings
- No spectator damage or combat interference
- No item pickup or item dropping where inappropriate
- Cleanup when matches end
- Restoration of spectator state
- Protection against arena escape
- Recovery from invalid spectator locations
# 12. PLAYER STATISTICS
Track:
- Wins
- Losses
- Draws
- Kills and deaths
- Win streak
- Highest win streak
- ELO
- Per-mode statistics
- Playtime where appropriate
- Recent match history
Implement `/stats [player]` and `/leaderboard`.
Store data persistently and handle missing or corrupt records safely.
# 13. DATABASE
Use SQLite by default and support optional MySQL/MariaDB.
Implement:
- Database connection management
- Connection pooling where appropriate
- Schema versioning
- Database migrations
- Prepared statements
- Safe transactions
- Reconnection handling
- Player data caching
- Asynchronous database operations
- Safe shutdown and saving
- Backup instructions
Never execute blocking database queries on the Minecraft main thread.
Never access Bukkit world, entity, inventory, or player APIs asynchronously unless the specific API explicitly supports it.
# 14. COMMANDS AND PERMISSIONS
Player commands:
- `/practice`
- `/queue `
- `/leavequeue`
- `/duel `
- `/accept `
- `/deny `
- `/rematch`
- `/spectate `
- `/party`
- `/kit`
- `/stats [player]`
- `/leaderboard`
- `/ping`
- `/settings`
Admin commands:
- `/usp admin`
- `/usp arena create `
- `/usp arena setspawn <1|2>`
- `/usp arena setspectator `
- `/usp arena enable `
- `/usp arena disable `
- `/usp arena delete `
- `/usp arena list`
- `/usp match list`
- `/usp match end `
- `/usp player reset `
- `/usp reload`
- `/usp debug`
Implement command aliases, tab completion, permissions, validation, and helpful error messages.
Administrative commands must never be available to ordinary players.
# 15. CONFIGURATION — EASY SETUP
Generate these files:
- `config.yml`
- `messages.yml`
- `modes.yml`
- `kits.yml`
- `arenas.yml`
- `ranks.yml`
- `database.yml`
- `gui.yml`
- `plugin.yml`
- `pom.xml`
- `README.md`
Provide useful defaults and comments.
Configuration must support:
- Lobby spawn
- Mode enable/disable
- Kits and enchantments
- Match countdown
- Match timeout
- Arena settings
- Queue settings
- ELO settings
- Rank thresholds
- Database credentials
- GUI layout
- Messages, sounds, titles, and effects
- Permission nodes
- Debug logging
Validate configurations during startup and reload.
If a configuration value is invalid, log the file, setting, and reason. Never silently ignore invalid settings or overwrite valid user configuration unexpectedly.
Implement a controlled reload mechanism. Do not blindly recreate active matches or destroy player state during reload.
# 16. OPTIONAL INTEGRATIONS
Provide safe optional integrations for:
- PlaceholderAPI
- LuckPerms
- Vault
- Economy-based cosmetic purchases, if Vault is installed
- Permission-based rank cosmetics
- External statistics export, if implemented securely
The core plugin must still start and work when these plugins are absent.
Do not add fake integrations, hidden telemetry, or mandatory payment systems.
# 17. PERFORMANCE AND SECURITY
- Optimize for busy Paper servers.
- Avoid unnecessary work every tick.
- Avoid blocking database and disk operations.
- Use appropriate collections and cache cleanup.
- Prevent queue spam and duplicate requests.
- Validate every command and GUI interaction.
- Prevent arena and match exploits.
- Handle null, offline, and invalid player references safely.
- Clean up scheduled tasks and temporary entities.
- Protect database credentials.
- Avoid memory leaks.
- Provide useful diagnostic logging.
# 18. CRITICAL MATCH-END BUG FIXES
This section has the highest priority.
When a match ends:
1. Atomically mark it as ending.
2. Stop all match timers and scheduled tasks.
3. Determine the winner exactly once.
4. Save match results and rating changes exactly once.
5. Release match restrictions.
6. Teleport both players safely to the configured lobby spawn.
7. Restore inventory, armor, health, hunger, effects, visibility, flight, and game mode.
8. Remove temporary entities and spectators.
9. Reset the arena only after it is released safely.
10. Remove the match from active match registries.
11. Release arena reservations.
12. Notify players and administrators appropriately.
Fix the following issues:
- Players floating after a match
- Players stacking on top of each other
- Players staying invisible
- Players remaining in spectator mode
- Players getting stuck in arenas
- Players losing items
- Duplicate victory messages
- Duplicate ELO changes
- Arena reset conflicts
- Teleportation failures
- Abandoned matches
- Countdown tasks continuing after matches end
Use defensive state transitions, idempotent cleanup, and proper task cancellation.
# 19. TESTING AND QUALITY ASSURANCE
Create automated tests for critical business logic, including:
- Match state transitions
- Winner detection
- Duplicate result prevention
- ELO calculations
- Queue matching
- Arena reservations
- Configuration validation
- Player state cleanup logic
Before declaring the project complete:
1. Run Maven compilation.
2. Run all available tests.
3. Fix all discovered Java compiler errors.
4. Resolve dependency and plugin metadata problems.
5. Check for missing classes and methods.
6. Validate configuration files.
7. Test startup and shutdown behavior in a compatible server environment when available.
8. Test match-end cleanup and arena release.
9. Confirm that advertised features are implemented.
10. Clearly report tests that could not be performed.
Never fabricate successful test results.
# 20. BUILD AND DELIVERY
Deliver the complete project with:
- All Java source files
- All required resources
- All configuration files
- Maven build configuration
- Automated tests
- Installation instructions
- Arena setup tutorial
- Mode and kit configuration tutorial
- Commands and permissions documentation
- Troubleshooting guide
- Compiled JAR if the build environment supports it
The plugin must be straightforward for a beginner to install.
Explain exactly where to place the JAR, how to start the server, how to set the lobby spawn, how to create arenas, and how to enable game modes.
Do not stop after producing a plan. Do not return only a few Java classes. Continue implementing the complete project in organized stages while maintaining a consistent, buildable codebase.
If you reach an output or context limit, save the current project state, list the completed files, identify unfinished work, and continue from that exact state in the next stage.
## FINAL OBJECTIVE
Deliver **Ultimate Super Practice**, a complete, maintainable, configurable, premium-style Minecraft Practice plugin for Paper 1.21.11 and Java 21.
Prioritize correct functionality, safe match cleanup, reliable arena management, accurate statistics, clean architecture, beginner-friendly setup, and verified builds over simply claiming to have many features.
Do not call the plugin complete until its implementation status and actual test results have been reported honestly.