Creating ranks

ranks.yml is where your whole progression lives. It is your content: the plugin generates it once with three commented example ranks and never rewrites it after that. Add as many ranks as you want; players progress through them in the order they appear in the file.

The shape of a rank

ranks:
  rank-1:
    display-name: "&aRank I"
    icon: IRON_INGOT
    quests:
      cobblestone:
        type: BREAK_BLOCK
        material: COBBLESTONE
        amount: 300
      mobs:
        type: KILL_MOB
        entity: ANY
        amount: 200
    requirements:
      money:
        type: MONEY
        amount: 25000
        take: true
    on-reach:
      - "lp user {player} parent set rank1"
    rewards:
      money: 5000
      commands:
        - "crates give {player} vote 3"
      broadcast: true

  rank-2:
    display-name: "&bRank II"
    icon: GOLD_INGOT
    # ...

Rank keys

The key under ranks: (rank-1, rank-2, ...) is just an internal id. Order in the file = order of progression.

on-reach commands

on-reach is a list of console commands that run every time a player becomes this rank, no matter how they got there:

• a brand new player joining for the first time (they land on your first rank),
• a player claiming a rank and moving up into the next one,
• an admin running /rank admin setrank <player> <this rank> (setrank to the first rank is a clean reset),
• a player being moved here by a rank permission.

{player} is replaced with the player's name.

This is the right home for your permission-plugin command, so the player's real server group always matches the rank they are on:

rank-2:
  on-reach:
    - "lp user {player} parent set rank2"

on-reach vs rewards.commands. on-reach runs on every arrival and is for state that must be kept in sync (the permission group). rewards.commands runs only on a genuine claim and is for one-time prizes (crate keys, cosmetics). An admin setrank fires on-reach but not rewards.commands, so moving a player around never re-hands them prizes.

Things to keep in mind

• Quest count vs menu slots. Quest icons are placed on the slots from gui.quest-slots in config.yml. If a rank has more quests than there are slots, the console warns you; add more slots to the list. See Configuration.
• Applying changes. Run /rank admin reload after editing. No restart needed.
• Renaming quest ids mid-run. A player's saved progress is stored per quest id. If you rename or remove a quest id while players are mid-rank, their progress for that id no longer matches. Prefer finishing your design before opening to players, or accept the reset.
• Sync with your permission plugin. zQuestRank tracks its own ladder. To move the player's actual server rank, put your permission plugin's command in the rank's on-reach list (for example LuckPerms lp user {player} parent set rank2). Using parent set keeps the player on exactly one group and clears the others.

A quick checklist for a new rank