Official Guide

Requirements & rewards

Explore the complete requirements and rewards documentation below for RankForge.

📋 Rank Requirements

Requirements are defined directly on each rank in ranks.yml. A player must satisfy all requirements simultaneously to rank up. If a specific player has a special circumstance, admins can waive a single requirement for them with /rank bypassreq <player> <requirement> (see Managing Ranks) rather than editing ranks.yml or force-setting their rank.

💰 Money

Requires a Vault economy balance. The balance is checked at rankup time; money is not automatically deducted — use a commands entry to call your economy plugin's withdrawal command if needed.

required-money: 10000

To deduct money on rankup, add a command reward: "eco take %player% 10000" (EssentialsX) or "vault take %player% 10000".

⭐ XP Level

Requires the player to hold at least this many vanilla Minecraft XP levels.

required-xp-level: 30

XP levels are checked but not consumed by RankForge. To consume levels, add a command like "xp set %player% 0l".

🔐 Permission

Requires the player to hold a specific Bukkit permission node.

required-permission: "server.vip"

Only one permission can be specified per rank using this built-in field. For multiple permission checks, use required-quests (each quest maps to one permission) or the Custom Requirements API.

⏱️ Playtime

RankForge's PlaytimeTracker records the exact time a player joins and calculates their playtime using real-world elapsed time through System.currentTimeMillis(). It does not depend on Minecraft ticks, TPS, or in-game time.

The calculated playtime is converted into the human-readable format used by the Playtime Requirement system in ranks.yml.

Playtime Format

RankForge supports the following time units:

s = Seconds
m = Minutes
hr = Hours
d = Days

⚔️ Mob Kills

Requires a minimum total mob kill count, read from the vanilla MOB_KILLS statistic.

required-mob-kills: 500

🪨 Block Breaks

Requires a minimum number of block breaks. This is tracked by RankForge's own BlockBreakTracker — an exact atomic counter incremented on every BlockBreakEvent. It is not based on the approximated MINE_BLOCK vanilla statistic.

required-block-breaks: 10000

Block break counts are flushed to storage at the interval set by tracker.block-break-flush-ticks in config.yml. Data is always safe on server shutdown (a final flush is performed).

📊 Bukkit Statistic

Requires any untyped Bukkit.Statistic enum value to meet a minimum.

required-statistic-id: "FISH_CAUGHT"
required-statistic-value: 100

A full list of valid statistic names is available in the Bukkit Statistic Javadoc. Only untyped statistics (those that don't require a material or entity type parameter) are supported by this built-in field. For typed statistics, use the Custom Requirements API.

🧩 Quests

Requires completion of one or more quest IDs. Each quest ID is translated to a permission node: rankforge.quest.completed.<questId>. If the player has that permission, the quest is considered complete.

required-quests:
  - "tutorial_complete"
  - "first_dungeon"

Grant the permission when a player finishes a quest in your quest plugin:

/lp user Steve permission set rankforge.quest.completed.tutorial_complete true

🗺️ World Lock

Requires the player to currently be in one of the listed worlds when they attempt to rank up.

required-worlds:
  - "world"
  - "world_nether"

Leave the list empty (or omit the field) to allow ranking up from any world.

🎒 Items

Requires specific items and quantities to be present in the player's inventory. Items are not consumed by RankForge — add a command reward to consume them if desired.

required-items:
  DIAMOND: 10
  IRON_INGOT: 64
  NETHERITE_INGOT: 1

The key is a Bukkit.Material name (uppercase). Only material and amount are checked — item names, lore, and NBT are ignored.

🔧 Custom Requirements (API)

Third-party plugins can register custom requirement types using the CustomRequirementRegistry. See Developer API for implementation details.

# In ranks.yml — after registering via the API
# (Custom requirements are evaluated programmatically;
#  see CustomRequirementRegistry.addRankRequirement())

🎁 Rank Rewards

Rewards are applied the moment a player successfully ranks up. Multiple reward types are applied simultaneously.

💻 Command Rewards

A list of console commands executed at rankup. Use %player% as the placeholder for the player's name.

commands:
  - "lp user %player% group set veteran"
  - "give %player% GOLDEN_APPLE 5"
  - "eco give %player% 500"
  - "broadcast %player% just ranked up!"

Commands are run synchronously on the main thread. For commands from plugins that support async dispatch, this is always safe.

🔐 Permission Rewards

Permissions listed in the permissions field are applied to the player when they hold that rank, and removed when they move to the next rank. With LuckPerms installed, they are applied as transient (session) nodes via the LuckPerms API. Without LuckPerms, they are granted via a Bukkit PermissionAttachment.

permissions:
  - "essentials.sethome.multiple.3"
  - "server.veteran"

These permissions represent what the player has while at this rank, not one-time grants. For permanent grants (e.g., LuckPerms group membership), use a commands entry instead: "lp user %player% group add veteran".

📣 Announcement Rewards

Configured globally in config.yml under announcements.rankup:

Chat broadcast — sent to all online players
Full-screen title — shown to the ranking-up player
Action bar — shown to the ranking-up player

All three are configurable and can be individually disabled.

🌟 Boss Bar

A boss bar is automatically shown to the player on rankup (configurable in cosmetic.bossbar). A progress variant is also available via the API.

✨ Particle Trail

A timed particle trail spawns around the player immediately after a rankup. It auto-expires after a short duration. The particle type and behavior are controlled by cosmetic.particles in config.yml.

Under server load (LOW performance mode), particles are suppressed automatically by the TPS monitor.

🪧 Tablist Update

The player's tab-list display name is updated to include their new rank's chat-prefix as soon as they rank up.