UltimateRanks

** 🎖️ UltimateRanks - Complete Documentation Overview Description **UltimateRanks** is a next-generation rank management plugin for Minecraft servers running Paper 1.21+. Unlike traditional rank plugins that limit players to a single rank, UltimateRanks introduces a revolutionary **hybrid system** where players can **own multiple ranks simultaneously** while selecting which one to **display actively** in chat and tab lists. Built with modern Java 21 features and the Paper API, UltimateRanks delivers exceptional performance through asynchronous database operations, intelligent caching, and a beautiful GUI-based rank management interface. Why Choose UltimateRanks? | Feature | Traditional Plugins | UltimateRanks | |---------|-------------------|---------------| | Multiple Ranks | ❌ One rank only | ✅ Unlimited ranks | | Permission Stacking | ❌ Single rank perms | ✅ All owned ranks contribute | | Visual Customization | ❌ Fixed display | ✅ Choose active display rank | | GUI Management | ⚠️ Basic or none | ✅ Beautiful paginated GUI | | RGB Colors | ⚠️ Limited support | ✅ Full MiniMessage support | | Performance | ⚠️ Sync operations | ✅ 100% async database | | LuckPerms Sync | ⚠️ Replace or conflict | ✅ Seamless integration | Target Audience - **Network Servers**: Manage complex rank hierarchies (VIP + Builder + Staff) - **RPG Servers**: Class ranks + achievement ranks + donor ranks - **Creative Servers**: Builder roles + theme ranks + VIP tiers - **Survival Servers**: Progression ranks + donor perks + special events - **Prison Servers**: Mine ranks + prestige + VIP packages --- Features 🎯 Core Features 1. **Multi-Rank Ownership System** - Players can own **unlimited ranks** simultaneously - Own VIP + Builder + Helper at the same time - All ranks contribute permissions (additive system) - Zero conflicts between rank permissions ``` Example: Player owns: Permissions = Member + VIP + Builder (combined) Active Display = VIP (shown in chat) ``` 2. **Active Display Rank Selection** - Choose which rank appears in chat prefix/suffix - Switch between owned ranks via interactive GUI - Real-time updates without reconnecting - Maintains all permissions from other ranks 3. **Beautiful Paginated GUI** - Clean, intuitive rank selection menu - Visual states: **Active** (glowing), **Owned** (available), **Locked** (unavailable) - 28 ranks per page with smooth navigation - Expiration timers shown directly in GUI - Custom icons with resource pack support 4. **Advanced Permission System** - **Dual Mode Operation**: - **Standalone Mode**: Built-in Bukkit permission system - **LuckPerms Mode**: Full integration with LuckPerms API - Auto-detection of available systems - Permission aggregation from all owned ranks - Wildcard support (e.g., `essentials.*`) - Negation support (e.g., `-essentials.fly`) 5. **Expiration & Time Management** - Temporary ranks with automatic expiration - Flexible duration formats: `30d`, `7d`, `1w`, `1mo`, `1y`, `permanent` - Automatic cleanup of expired ranks - Warning notifications before expiration - Visual countdown in GUI 6. **Full MiniMessage Support** - RGB colors: `<FF5555>text</color>` - Gradients: `<gradient:gold:yellow>VIP</gradient>` - Formatting: `<bold>`, `<italic>`, `<underline>` - Hover events and click actions - Legacy color code conversion 7. **High-Performance Database** - **SQLite**: Zero-config, perfect for small servers - **MySQL**: HikariCP pooling for large networks - 100% asynchronous operations (zero server lag) - Transaction support for data integrity - Automatic schema management 8. **Smart Caching System** - In-memory cache for online players - Sub-millisecond lookup times - Automatic cache invalidation - Thread-safe concurrent operations --- 🎨 Visual Features Chat Formatting ``` Before: <Player> Hello! After: Player ★: Hello! Format: {prefix} + {player} + {suffix} + : + {message} ``` GUI States | State | Visual | Description | |-------|--------|-------------| | **Active** | 🌟 Glowing item | Currently equipped rank | | **Owned** | ✅ Normal icon | Click to equip | | **Locked** | 🚫 Barrier | Not owned | Rank Display Example ``` ╔══════════════════════════════╗ ║ My Ranks ║ ╠══════════════════════════════╣ ║ ║ ║ (Active) ║ ║ Click to keep equipped ║ ║ Duration: Permanent ║ ║ ║ ║ ║ ║ Click to equip ║ ║ Expires in: 15 days ║ ║ ║ ║ (Locked) ║ ║ You don't own this rank ║ ║ ║ ╚══════════════════════════════╝ ``` --- 🔧 Technical Features Architecture - **SOLID Principles**: Single Responsibility, Interface Segregation - **Design Patterns**: Strategy, Builder, Repository, Singleton - **Dependency Injection**: Clean, testable code - **Layer Separatio