Zrank

What is this?
Zrank is a Paper rank ladder plugin. Players open a GUI, see the next rank, complete requirements, and buy the rank (or let auto rank do it when everything is ready). Costs can mix Vault money, experience levels, inventory items, and tracked quests (walk, mine, kill, craft, play time, and many more).
Ranks are defined in gui.yml (icons, lore, order, commands on buy, prefix/suffix). Player progress is stored in YAML or SQLite. Messages and GUI text support MiniMessage gradients and classic & color codes.
Where it runs

• Yes: Paper 26.1.x (api version 26.1, built on Paper API 26.1.2). Java 25 or newer.
• Usually fine: Purpur on the same game version as Paper 26.1.x.
• No: plain Spigot or CraftBukkit.
• No: Folia.
• Old Paper 1.21.11: not the build target. Update to Paper 26.1.x first.

Written in Kotlin. SQLite JDBC is listed as a Paper library in plugin.yml (downloaded by Paper when needed).
Optional soft depends

• Vault money costs (required if ranks cost money and economy.use vault is true)
• Zsystem preferred Vault economy provider name in config (optional; any Vault economy works)
• PlaceholderAPI %zrank_*% for TAB, chat, scoreboard

The plugin starts without them. Money purchases fail cleanly if Vault is missing or use vault is false.
How ranks work

• Ranks live in plugins/Zrank/gui.yml under ranks.*. Each has id, order, display name, lore, icon, prefix, suffix, purchasable flag, cost, and commands on buy.
• Players advance in order. You buy the next purchasable rank when costs and quests are met (you cannot skip the ladder via the GUI).
• Cost money Vault withdraw
• Cost XP experience levels
• Cost items materials taken from inventory
• Cost quests stats tracked while the player is online (only stats needed for the next rank are tracked, to keep load low)
• Auto rank periodic check; if requirements are ready, the rank is bought automatically. Toggle with /zrank auto. New players get auto rank on by default (configurable).
• Commands on buy run as console (with {player}), or special lines: sound:NAME,vol,pitch | message:text | broadcast text | bc text
• Admin /zrank get forces a rank and still runs that ranks buy commands.

Default gui.yml ships a long example ladder (novice → … → admin). Edit or replace it for your server.
Quest types (cost.quests)
Each quest: type, amount, optional material / entity type / custom key / display message.

• WALK_BLOCKS, SWIM_DISTANCE, FLY_DISTANCE, FALL_DISTANCE, JUMP_COUNT
• PLACE_BLOCK, BREAK_BLOCK (optional material)
• MINE_ORE, PLANT_CROP, HARVEST_CROP (optional material)
• KILL_ENTITY (optional entity type), KILL_PLAYER, DEATH_COUNT
• DAMAGE_DEALT, DAMAGE_TAKEN
• USE_ITEM, CRAFT_ITEM, SMELT_ITEM, ENCHANT_ITEM, BREW_POTION
• TRADE_WITH_VILLAGER, CATCH_FISH, EAT_FOOD
• BREED_ANIMAL, TAME_ANIMAL, OPEN_CHEST
• PLAY_TIME (amount in hours; stored as minutes internally)
• CUSTOM (custom key string)

Anti abuse notes built in: player placed blocks do not count as mined for break/ore quests; crop plant/harvest has compatibility keys; play time ticks once per minute online.
GUI
/zrank opens the rank menu (default permission true for everyone).
gui.yml controls title, size, PATH layout, decoration, animation, sounds, info item, and every rank entry.
Lore can use quest placeholders such as %quest%, %quest_current%, %quest_required%, %quest_progress%, and indexed %quest1_% … for multiple quests on one rank.
How to install

1. Put Zrank.jar into the plugins folder
2. Install Vault + an economy plugin if you use money costs (Zsystem eco or EssentialsX, etc.)
3. (Optional) PlaceholderAPI
4. Start Paper once
5. Edit plugins/Zrank/gui.yml ranks, plugins/Zrank/config.yml storage/economy, plugins/Zrank/lang.yml messages
6. /zrank reload after edits (or restart)

Commands
Aliases: /zrank, /rank, /ранг
Details:

• /zrank open GUI (player only)
• reload reload configs, ranks, auto rank schedule (does not wipe player progress)
• get set rank for an online player and run commands on buy
• addtime / removetime adjust PLAY_TIME quest progress (hours → minutes). Works for offline players who have played before
• auto toggle your personal auto rank
• reset clear quest statistics for one player, or all players with * / all

Permissions
PlaceholderAPI
Identifier: zrank
Use prefix/suffix in chat or TAB. rank_player / rank_next return the styled name field from gui.yml.
Configs

• plugins/Zrank/config.yml storage (YAML or SQLITE), cache TTL, auto rank interval, Vault preferred provider, debug
• plugins/Zrank/gui.yml menu layout + all ranks
• plugins/Zrank/lang.yml messages, help, quest display strings
• Player data: YAML files or sqlite file (default data.db) under the plugin folder

SQLite tip: set storage.type to SQLITE for larger player counts. YAML is fine for small servers.
bStats
Anonymous metrics (plugin id 33091). Charts: storage_type, ranks_count, auto_rank_default.
Page: https://bstats.org/plugin/bukkit/Zrank/33091
Developer API
Public object org.zoobastiks.zrank.api.ZrankAPI (get/set rank, prefix/suffix, next rank, auto rank, placeholders).
Events: RankChangeEvent, RankPurchaseEvent for other plugins.
Support
Telegram: https://t.me/Zoobastiks
bStats: https://bstats.org/plugin/bukkit/Zrank/33091
If something breaks, tell me your Paper version, Java version, economy plugin, and the error from the console. That saves a lot of back and forth.
Thanks for trying Zrank.