✦ RankForge ⚡
Modular · Production-Ready · Rank Progression
Spigot / Paper · 1.20.1 – 1.21.x · Java 21+ · Free
[ ⭐ GitHub ] [ Documentation ] [ Issue Tracker ] [ bStats ]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Screenshots
▸ Player Rank Menu
▸ Player Rank Menu
▸ In-Game Admin Rank Editor
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overview
RankForge is a feature-complete rank progression plugin built around vanilla Minecraft XP. Players advance through fully customizable rank chains by meeting real in-game requirements — money , XP levels ⚡, playtime ⏳, mob kills ⚔️, block breaks ⛏️, world checks , and more.
Whether you run a tight-knit survival server or a high-traffic network, RankForge adapts to your needs. Every rank, every requirement, every message, and every GUI element is fully configurable and hot-reloadable — no restarts required.
No bloat · No fake currencies · No unnecessary systems
Just clean, native Minecraft progression ✨
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚡ Features
Gameplay & Progression
- ✔ Vanilla XP Integration — RankForge plugs directly into Minecraft's native experience system. No fake XP pools, no external syncing, no configuration overhead. Players earn and spend real XP levels just like vanilla — the plugin simply tracks and enforces the progression rules you define.
- ✔ 11+ Requirement Types — Build rank gates using any combination of: money, xp-level, playtime-minutes, mob-kills, block-breaks, worlds, items, Bukkit statistics, permissions, quest IDs, and fully custom API requirements. Every requirement type is optional — mix and match freely.
- ✔ Rank History System — Every rank change is recorded with a timestamp, the previous rank, and the acting player (player self-rankup or admin force). Players can review their own history with /rank history, and admins can audit any player.
- ✔ Cosmetics & Feedback — Make rank-ups feel rewarding. Trigger boss bars, particle effects, join/quit broadcast messages, and custom shell commands on promotion. Each rank can define its own unique set of effects.
GUI & Management
- ✔ Animated Rank Tree GUI — The /rank GUI gives players an interactive, real-time view of the entire rank ladder. Each rank slot shows live requirement status — a green ✔ or red ✘ — for money, XP, playtime, permissions, and every other configured gate. Players always know exactly what they need.
- ✔ In-Game Admin Editor — Administrators can create, edit, rename, reorder, and delete ranks entirely within the game GUI. Display names, materials, lore, permissions, commands, and requirements are all editable without ever opening a config file.
- ✔ Drag-and-Drop Slot Editor — Reorder ranks in the player-facing GUI by simply dragging them to new slots. Changes take effect immediately and save automatically.
- ✔ Paginated Player Manager — The /rank playerlist GUI displays all known players across 45-per-page navigation. Click any player to open a detailed data editor — adjust their rank, XP, money, and language preference without touching the console.
Storage & Performance
- ✔ Dual Storage System — RankForge supports both MySQL (via HikariCP connection pooling) and YAML flat-file storage. Configure MySQL for production networks or high-traffic servers, and let RankForge automatically fall back to YAML if the connection is unavailable — zero data loss, zero downtime.
- ✔ Hot Reload — Run /rank reload to instantly apply changes to ranks, config, messages, GUI layout, and language files — all without a server restart. Safe to run with players online.
Integrations
- ✔ PlaceholderAPI Support — Over 20 ready-to-use placeholders expose rank ID, display name, prefix, progress percentage, progress bar, XP, money, requirement status, and more. Use them in chat formats, tab lists, scoreboards, holograms, or any PAPI-compatible plugin.
- ✔ LuckPerms & Vault Integration — Automatically add and remove permission groups when a player ranks up or is demoted. Vault economy support enables money-based requirements and balance checks with no extra configuration.
- ✔ Crossplay Support — RankForge stores and checks all player data by UUID, not by name, making it fully compatible with Geyser and Floodgate. Bedrock player prefixes are detected and stripped automatically.
- ✔ Optional REST API — An embedded HTTP server provides authenticated external access to player rank data, progress, and history. Connect Discord bots, web dashboards, or third-party tools without modifying the plugin. Can be fully disabled if not needed.
- ✔ Developer API — Register fully custom requirement types, listen to RankupEvent and RankSetEvent, and interact with all internal managers via a clean, versioned API. Maven and Gradle artifacts available via JitPack.
- ✔ bStats Metrics — Anonymous, aggregated usage statistics are sent to bStats to help guide development priorities.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Why Choose RankForge?
Everything you need. Nothing you don't.
Everything you need. Nothing you don't.
⚙️ Built for Performance
RankForge is engineered to stay out of the way. All heavy operations — storage reads, sync cycles, data exports — run asynchronously so your main thread never waits. HikariCP connection pooling ensures MySQL access is fast and non-blocking even under heavy concurrent load. An in-memory TTL cache reduces database hits to a minimum, so player data is always available instantly. Whether you have 10 players or 1,000, the overhead is negligible.
Vanilla-Friendly Progression
RankForge doesn't fight vanilla Minecraft — it extends it. Progression is built on real in-game actions: earning XP, breaking blocks, killing mobs, accumulating playtime, and exploring worlds. There are no artificial currencies, no parallel economy systems, and no hidden mechanics. Players feel rewarded for doing what they already love doing. The experience is seamless, natural, and completely lore-friendly.
Fully Customizable
No two servers are alike, and RankForge doesn't assume yours is. Define as many ranks as you need, in any order, with any combination of requirements. Customize display names, chat prefixes, GUI materials, lore lines, permissions, and promotion commands per rank. Adjust every player-facing message in messages.yml, support multiple languages simultaneously, and restyle the entire GUI from gui.yml — all without touching a single line of code.
Developer-Friendly API
RankForge exposes a clean, well-documented Java API for server developers who want to go further. Register your own custom requirement types — integrate quest plugins, mini-game scoreboards, or any external data source. Listen to RankupEvent and RankSetEvent to trigger your own logic on promotion. Access player data, progress, and rank managers programmatically. The API is available via JitPack for both Maven and Gradle projects.
Cross-Platform Ready
RankForge supports Java and Bedrock players on the same server. All data is stored and looked up by UUID — never by player name — so Geyser/Floodgate users are treated identically to Java players. Bedrock name prefixes are stripped automatically. The plugin runs on both Spigot and Paper (1.20.1 through 1.21.x), and is compatible with proxy setups using MySQL as a shared storage backend.
Production-Ready
RankForge has been designed from the ground up for real-world servers. The dual YAML/MySQL storage system with automatic fallback means the plugin stays operational even if your database connection hiccups. A built-in anti-abuse system detects macro clicking (sub-20ms click intervals) and enforces command rate limits to prevent automated rank farming. A rankup queue prevents race conditions from concurrent promotion attempts. Every edge case that hurts servers in practice has been thought through and addressed.
Easy Setup, Zero Bloat
Drop the JAR into your plugins/ folder and start the server. RankForge generates all configuration files automatically on first run — config.yml, ranks.yml, messages.yml, gui.yml — each pre-populated with clear comments and working examples. There are no required dependencies. Vault, LuckPerms, PlaceholderAPI, and Floodgate are all optional enhancements. You can have a fully functional rank system running in under five minutes.
Actively Developed
RankForge is under continuous development. Bug reports are triaged on GitHub, feature requests are reviewed, and new versions ship regularly. The project is open source — contributions, translations, and feedback from the community directly shape the roadmap. When you install RankForge, you're getting a plugin that will still be maintained and improved long after your server is running.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Requirements
| Java | Server Software | Dependencies |
| ✔ Java 21 or higher | ✔ Spigot or Paper 1.20.1 – 1.21.x | ✔ None required |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Soft Dependencies
All entirely optional — RankForge works out of the box without any of them.
All entirely optional — RankForge works out of the box without any of them.
| Plugin | What It Unlocks |
| Vault | Enables economy support — use any Vault-compatible economy plugin to gate ranks behind a money requirement |
| LuckPerms | Automatically assigns and removes permission groups when players rank up or are demoted ️ |
| PlaceholderAPI | Exposes 20+ placeholders for use in chat formats, scoreboards, tab lists, and any PAPI-compatible plugin |
| Floodgate | Enables native Bedrock player detection — prefixes are stripped automatically for clean UUID-based lookups |
| MySQL | Replaces YAML flat-file storage with a scalable relational database — recommended for networks and large servers |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⌨️ Commands
Spoiler: ▸ Player Commands
Player Commands
All player commands require the rankforge.use permission (granted by default).
/rank — Open the animated rank progression GUI
/rank up — Attempt to rank up (checks all requirements)
/rank progress — View a detailed breakdown of your current rank progress
/rank next — Display requirements and info for the next rank
/rank current — Show your current rank name and details
/rank requirements — List all unmet requirements for your next rank
/rank xp — View your XP balance and progress toward the next level
/rank history — Browse your full rank change history with timestamps
/rank lang <set|list> — View or change your personal language preference
/rank version — Show the installed plugin version and build info
/rank help — Display the in-game help menu
All player commands require the rankforge.use permission (granted by default).
Code (Text):
/rank — Open the animated rank progression GUI
/rank up — Attempt to rank up (checks all requirements)
/rank progress — View a detailed breakdown of your current rank progress
/rank next — Display requirements and info for the next rank
/rank current — Show your current rank name and details
/rank requirements — List all unmet requirements for your next rank
/rank xp — View your XP balance and progress toward the next level
/rank history — Browse your full rank change history with timestamps
/rank lang <set|list> — View or change your personal language preference
/rank version — Show the installed plugin version and build info
/rank help — Display the in-game help menu
Spoiler: ▸ Admin Commands
Admin Commands
Admin commands require the rankforge.admin permission.
/rank editor — Open the in-game GUI rank editor
/rank editor drag — Open the drag-and-drop GUI slot editor
/rank editor save — Manually save the current rank configuration to disk
/rank create <id> — Create a new rank with the given ID
/rank delete <id> — Permanently delete a rank by ID
/rank playerlist — Open the paginated player manager GUI
/rank set <player> <rank> — Set a specific player's rank
/rank reset <player> — Reset a player back to the default starting rank
/rank force <player> <rank> — Force a rank change, bypassing all requirements
/rank xp set <player> <amt> — Set a player's RankForge XP to an exact value
/rank xp add <player> <amt> — Add a specific amount of XP to a player
/rank reload — Reload all configuration files without restarting
/rank stats — Display live system status, cache info, and storage health
/rank security — View the anti-abuse and anti-bypass system status
/rank debug — Output detailed debug information for troubleshooting
/rank bypassreq — Instantly complete one requirement for an online player; persists until they rank up
Admin commands require the rankforge.admin permission.
Code (Text):
/rank editor — Open the in-game GUI rank editor
/rank editor drag — Open the drag-and-drop GUI slot editor
/rank editor save — Manually save the current rank configuration to disk
/rank create <id> — Create a new rank with the given ID
/rank delete <id> — Permanently delete a rank by ID
/rank playerlist — Open the paginated player manager GUI
/rank set <player> <rank> — Set a specific player's rank
/rank reset <player> — Reset a player back to the default starting rank
/rank force <player> <rank> — Force a rank change, bypassing all requirements
/rank xp set <player> <amt> — Set a player's RankForge XP to an exact value
/rank xp add <player> <amt> — Add a specific amount of XP to a player
/rank reload — Reload all configuration files without restarting
/rank stats — Display live system status, cache info, and storage health
/rank security — View the anti-abuse and anti-bypass system status
/rank debug — Output detailed debug information for troubleshooting
/rank bypassreq — Instantly complete one requirement for an online player; persists until they rank up
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PlaceholderAPI Placeholders
Use these in any PlaceholderAPI-compatible plugin — chat, tab list, scoreboards, holograms, and more.
Use these in any PlaceholderAPI-compatible plugin — chat, tab list, scoreboards, holograms, and more.
Spoiler: ▸ All 20+ Placeholders
PlaceholderAPI — Full Reference
%rankforge_rank% — Internal rank ID
%rankforge_rank_name% — Formatted rank display name
%rankforge_rank_prefix% — Rank chat prefix (with color codes)
%rankforge_rank_position% — Rank position number in the chain
%rankforge_next_rank% — Display name of the next rank
%rankforge_next_cost% — Formatted cost summary of the next rank
%rankforge_is_max_rank% — true/false — whether the player is at max rank
%rankforge_progress% — Current progress value toward next rank
%rankforge_progress_percent% — Progress as a percentage (0–100)
%rankforge_progress_bar% — Visual ASCII progress bar
%rankforge_required_progress% — Total progress required for next rank
%rankforge_remaining_progress% — Remaining progress until next rank
%rankforge_xp_level% — Player's current Minecraft XP level
%rankforge_xp_progress% — Player's XP progress toward next XP level
%rankforge_money% — Player's current Vault economy balance
%rankforge_has_money% — true/false — whether the player meets the money requirement
%rankforge_missing_money% — Amount of money still needed for next rank
%rankforge_requirements_status% — Formatted summary of all requirement statuses
%rankforge_player% — Player's display name
%rankforge_uuid% — Player's UUID
%rankforge_lang% — Player's current language code
%rankforge_version% — Installed RankForge version string
Code (Text):
%rankforge_rank% — Internal rank ID
%rankforge_rank_name% — Formatted rank display name
%rankforge_rank_prefix% — Rank chat prefix (with color codes)
%rankforge_rank_position% — Rank position number in the chain
%rankforge_next_rank% — Display name of the next rank
%rankforge_next_cost% — Formatted cost summary of the next rank
%rankforge_is_max_rank% — true/false — whether the player is at max rank
%rankforge_progress% — Current progress value toward next rank
%rankforge_progress_percent% — Progress as a percentage (0–100)
%rankforge_progress_bar% — Visual ASCII progress bar
%rankforge_required_progress% — Total progress required for next rank
%rankforge_remaining_progress% — Remaining progress until next rank
%rankforge_xp_level% — Player's current Minecraft XP level
%rankforge_xp_progress% — Player's XP progress toward next XP level
%rankforge_money% — Player's current Vault economy balance
%rankforge_has_money% — true/false — whether the player meets the money requirement
%rankforge_missing_money% — Amount of money still needed for next rank
%rankforge_requirements_status% — Formatted summary of all requirement statuses
%rankforge_player% — Player's display name
%rankforge_uuid% — Player's UUID
%rankforge_lang% — Player's current language code
%rankforge_version% — Installed RankForge version string
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚙️ Rank Configuration
Define your entire rank ladder in ranks.yml — no restarts required.
Define your entire rank ladder in ranks.yml — no restarts required.
Spoiler: ▸ Example ranks.yml + Requirement Reference
Example — ranks.yml
Each rank is a named block. Link them into a chain using next-rank. Leave next-rank empty on the final rank.
ranks:
Member:
display-name : "&aMember"
next-rank : "Builder"
slot : 12
material : GREEN_WOOL
chat-prefix : "&a[Member] "
lore :
- "&7The first step of your journey."
permissions :
- "essentials.kits.member"
commands :
- "broadcast &6✦ &e%player% &aranked up to &aMember!"
requirements:
money : 5000
xp-level : 10
playtime-minutes : 60
mob-kills : 25
block-breaks : 200
Available Requirement Types
Each rank is a named block. Link them into a chain using next-rank. Leave next-rank empty on the final rank.
Code (YAML):
ranks:
Member:
display-name : "&aMember"
next-rank : "Builder"
slot : 12
material : GREEN_WOOL
chat-prefix : "&a[Member] "
lore :
- "&7The first step of your journey."
permissions :
- "essentials.kits.member"
commands :
- "broadcast &6✦ &e%player% &aranked up to &aMember!"
requirements:
money : 5000
xp-level : 10
playtime-minutes : 60
mob-kills : 25
block-breaks : 200
| Key | Description |
| money | Vault economy balance required (e.g. 5000) |
| xp-level | Vanilla Minecraft experience level (e.g. 10) |
| playtime | Real wall-clock playtime (e.g. 5d/5hr/5m/5s) — TPS-independent, never under-counts |
| mob-kills | Total mob kills tracked via the vanilla MOB_KILLS statistic |
| block-breaks | Blocks broken, tracked by RankForge's own event listener (more accurate than vanilla) |
| permission | A permission node the player must currently hold |
| statistic-id | Any untyped Bukkit Statistic enum value (e.g. JUMP, DEATHS) |
| quests | List of quest IDs the player must have completed (checked via permission node) |
| worlds | World names the player must have visited at least once |
| items | Items the player must have in their inventory at the time of rank-up |
| custom | Custom requirement types registered through the Developer API |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Ready to Transform Your Server?
Free forever. No paywalls. No premium tiers.
Free forever. No paywalls. No premium tiers.
RankForge gives your players a clear, rewarding sense of progression that keeps them engaged long-term. Instead of players logging off after achieving nothing, they log on with goals — a rank to chase, a requirement to meet, a reward waiting at the end.
Setup takes under five minutes. Drop the JAR in your plugins/ folder, start the server, open ranks.yml, and define your first rank chain. Everything else — GUI, messages, storage, integrations — is pre-configured and ready to go.
⬇ Download RankForge — it's completely free.
If RankForge improves your server, leaving a review or starring the GitHub repository helps other server owners discover it.
| 100% Free No hidden costs | Open Source Full code on GitHub | Actively Maintained Regular updates & fixes | No Dependencies Works out of the box |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Support & Links
[ ⭐ GitHub Repository ]
[ Full Documentation ]
[ Report an Issue ]
[ bStats Analytics ]
Please search existing issues before opening a new one.
For bug reports, always include your server version, Java version, and the full error from console.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Made with ☕ by JoshuaOP · ⭐ If RankForge helps your server, a review or star goes a long way!
Quick facts
- Edition: Minecraft Java
- File type: .jar
- Minecraft versions listed: 1.20, 1.20.6, 1.21
- How to install: Install the matching mod loader (Forge, Fabric or NeoForge) for your Minecraft version. → Download the .jar. → Put it in the .minecraft/mods folder and launch that loader profile.
- Where to get it: Opens on Spigot — not every file is mirrored on our own servers.
Install steps are the general flow for this file type — How to install Minecraft Java mods & modpacks walks through it step by step.
✦RankForge ⚡ | Advanced Custom GUI Rank System & Requirements is a free Minecraft Java mod. Compatible with Minecraft 1.20, 1.20.6, 1.21, 26.1 and newer. Downloaded 229 times (via Spigot). Download it and open it directly in the game.