Enes Baltop | Ultimate System v1.0

EnesBaltop — Advanced Balance Leaderboard GUI (Paper / Folia / Purpur)
What is EnesBaltop?
EnesBaltop is a Paper-compatible (API 1.21+), Folia-supported, and Purpur-friendly Minecraft plugin that provides a complete balance leaderboard system. Players view the richest players on the server through an interactive paginated GUI with live player heads, real-time economy syncing, search via sign or chat, and full Folia-safe scheduling.
Who should download EnesBaltop?
• Server owners who want a professional baltop GUI with actual player heads and gradients
• Staff who need real-time balance tracking with automatic syncing every second
• Anyone running Folia who needs a leaderboard that works without the main thread
• Anyone searching for: Minecraft baltop, balance leaderboard GUI, Paper 1.21 economy, Folia leaderboard plugin, richest players display, /baltop
Complete feature list
Commands
• /baltop — Opens the balance leaderboard GUI with player heads, pagination, and full navigation.
• /baltop reload — Reloads all configuration files without restarting the server (config.yml, lang.yml, gui/main-gui.yml).
• /baltop <player> — Opens the GUI filtered to show a specific player's rank and surrounding players.
• /baltop help — Displays command usage information.
Permissions
• baltop.use — Use /baltop command (default: all players).
• baltop.reload — Reload the plugin configuration (default: op).
• baltop.admin — All permissions combined.
GUI system (gui/main-gui.yml)
• 6-row (54-slot) GUI with paginated player heads showing balance and rank.
• Configurable players per page — set the slot range via menu.players (default 0-44 = 45 players). Supports any range: 0-17 (18 players), 0-8 (9 players), etc.
• Player heads — each entry shows the player's actual Minecraft skull with their name, formatted balance, and rank number. All colors use MiniMessage with hex support.
• Self button (slot 48) — instantly shows your own balance and rank using your head.
• Refresh button (slot 49) — manually refreshes the leaderboard with cached data.
• Search button (slot 50) — initiates a player search via sign GUI or chat fallback.
• Back / Next buttons — always displayed with gradient colored display names (no inactive gray state). Uses gradient hex colors from config.
• Hardcoded button slots: back=45, self=48, refresh=49, search=50, next=53. Not configurable from YAML — prevents slot conflicts.
• GUI title shows current page and total pages: ʙᴀʟᴛᴏᴘ (Page 1/3).
• All GUI items are locked — players cannot take, drag, or move items.
• Fully configurable display names, lore, and materials for every button in gui/main-gui.yml.
Search system
• Sign GUI input — opens an Oak Sign editor with configurable text lines from config.yml (sign-gui section).
• Chat fallback — if sign API is unavailable, prompts the player to type a name in chat automatically.
• Type cancel in chat to abort the search at any time.
• Search filters player names in real-time and displays matching results in the same paginated GUI format.
• Folia-safe: sign block operations use Bukkit.getRegionScheduler().run() with 2-tick delay; cleanup runs after 30 seconds.
Data & storage (data.db)
• SQLite database — stores all player balances with name and balance columns.
• Auto-sync every second — all online players' balances are synced from the economy provider using Folia-safe GlobalRegionScheduler.runAtFixedRate().
• Player join/quit — balances are immediately synced on join and saved on quit via event listeners.
• Data persists across restarts and reloads.
Economy system
• Dual provider mode: VAULT (Vault API) or CUSTOM (reflection-based custom economy class).
• Vault is optional — listed as softdepend in plugin.yml. Plugin loads without Vault when using CUSTOM provider.
• Custom provider: define your own economy class via economy.custom-class in config.yml. Required methods: getBalance(OfflinePlayer), has(OfflinePlayer, double), withdrawPlayer(OfflinePlayer, double), depositPlayer(OfflinePlayer, double).
• Currency abbreviations — configurable suffixes (K, M, B, T by default). Enable/disable in config.
• Decimal format — configurable number formatting (#,##0.##).
• formatMoney() abides by your selected format and abbreviation settings.
Color system
• Full MiniMessage support (<#RRGGBB> format) for all configurable text.
• Use &#RRGGBB in YAML — automatically converted to MiniMessage format at runtime.
• Legacy & color codes also supported (&a, &c, etc.) — mapped to MiniMessage equivalents.
• Gradient display names on BACK/NEXT buttons use hex color interpolation.
PlaceholderAPI
• Softdepend — PlaceholderAPI is not required but fully supported when present.
• Placeholders are resolved in all player head display names and lore lines.
• Works without PlaceholderAPI — simply displays raw text.
Scheduling & Folia compatibility
• GlobalRegionScheduler — automatic balance sync every second, plugin reload, and shutdown tasks.
• EntityScheduler — player-bound operations: messaging, head display updates.
• RegionScheduler — location-bound operations: sign GUI block placement and removal.
• AsyncScheduler — database reads and writes (never blocks the game thread).
• Declared folia-supported: true in plugin.yml — runs on Folia, Paper, and Purpur without modification.
Caching & performance
• TTL cache — prevents redundant database queries during rapid page navigation.
• Force refresh — manual refresh button bypasses cache for instant updates from the database.
• Optimized rendering — minimal object creation; player head items are built efficiently with a single-item constructor pattern.
• One-second sync interval — balances are never stale for more than one second.
Configuration files
• config.yml — Economy provider selection, custom class path, currency format, abbreviation settings, sign GUI text, sound configuration.
• lang.yml — All plugin messages: reload confirmation, search prompts, permission errors, cancel confirmation. Supports & codes and &#RRGGBB hex.
• gui/main-gui.yml — GUI title, player slot range, all button configurations (material, display name, lore). Button slots are hardcoded in code.
Sounds
• Configurable click sound on button press.
• Configurable reload success sound.
• Configurable search sound.
• All sounds use Minecraft sound enum names (legacy format, wrapped in try-catch for cross-version compatibility).
• Sounds are disabled if the enum name is invalid — plugin continues without errors.
Typical player journey (in-game)
1. Server owner installs the plugin and chooses an economy provider in config.yml — VAULT (with Vault + economy plugin) or CUSTOM (with a custom class path).
2. A player runs /baltop — the leaderboard GUI opens showing up to 45 player heads per page, sorted by balance descending with rank numbers and formatted currency.
3. The player clicks NEXT (slot 53) — the GUI smoothly paginates to the next page with animated gradient text.
4. The player clicks SEARCH (slot 50) — a sign editor opens with configurable guide text. They type a player name and see filtered results instantly.
5. The player clicks REFRESH (slot 49) — the leaderboard bypasses cache and loads fresh data from the database.
6. The player clicks SELF (slot 48) — their own head appears with their current balance and rank.
7. Staff runs /baltop reload — all configs reload with sound confirmation, no restart needed.
Installation
1. Download the correct EnesBaltop-{platform}.jar for your server type (Paper, Folia, or Purpur) and place it in the plugins folder.
2. (Optional) Install Vault and an economy plugin (e.g. EssentialsX, CMI) if using VAULT provider.
3. (Optional) For CUSTOM provider, set economy.custom-class to your fully qualified economy class name in config.yml.
4. Start the server once — default configs generate automatically under plugins/EnesBaltop/.
5. Edit config.yml, lang.yml, and gui/main-gui.yml to match your server's theme.
6. Run /baltop reload to apply all changes without a full server restart.
Configuration files
config.yml — Main plugin settings:
Economy provider modes:
• VAULT (default): Uses Vault API. Requires Vault + an economy plugin.
• CUSTOM: Uses reflection to call economy methods on your own class. Set economy.custom-class to the fully qualified class name.
Required method signatures in your custom class:
• getBalance(OfflinePlayer) → double
• has(OfflinePlayer, double) → boolean
• withdrawPlayer(OfflinePlayer, double) → boolean
• depositPlayer(OfflinePlayer, double) → boolean
lang.yml — All plugin messages:
All messages support & colour codes and &#RRGGBB hex colours.
gui/main-gui.yml — Full GUI layout and item configuration:
Placeholder reference for player heads and self button:
• %name% — Player's Minecraft username.
• %value% — Player's balance (formatted with currency settings).
• %rank% — Player's position on the leaderboard (1, 2, 3...).
Hardcoded slots (not configurable from YAML):
• back: slot 45
• self: slot 48
• refresh: slot 49
• search: slot 50
• next: slot 53
Plugin structure
• EnesBaltop-1.21-Paper.jar — For Paper servers (uses Paper API).
• EnesBaltop-1.21-Folia.jar — For Folia servers (includes Folia-specific optimizations).
• EnesBaltop-1.21-Purpur.jar — For Purpur servers (Purpur-compatible Paper API).
• All variants are compiled against Paper API 1.21.11 and are compatible with MC 1.21 through 1.21.11.
• Declared api-version: '1.21' in plugin.yml — covers later 1.21.x patches.