Configuring Tiers, Ranks & Rewards in RankForge

Tiers are configured under the tiers: section in config.yml. Each tier has a unique key (identifier) and a minimum points requirement.

Tier Structure

tiers:
  lt_5:
    min: 100
    display: "<#CCCCCC>LT5</#999999>"
    sound: "ENTITY_PLAYER_LEVELUP"
    title:
      main: "&a&lRANK UP!"
      sub: "&7You have advanced to <#CCCCCC>LT5</#999999>"
    rewards:
      - "eco give <player> 10000"

Key	Required	Description
ID (lt_5)	Yes	Used in %rankforge_rank_id% and tracks claimed rewards. Do not change after players claim rewards.
min	Yes	Minimum score required for this tier.
display	Recommended	Formatted name. Supports hex & gradients. Defaults to ID if omitted.
sound	No	Bukkit Sound enum name (e.g. ENTITY_PLAYER_LEVELUP). Defaults to ENTITY_PLAYER_LEVELUP.
title.main / title.sub	No	Screen title and subtitle displayed upon rank-up.
rewards	No	List of console commands. Placeholder: <player>.

Key Mechanics

1. Ordering is automatic. RankForge sorts tiers dynamically by min descending at boot.

2. Tier evaluation. A player receives the highest tier where min ≤ player points. Players below the lowest tier minimum are Unranked (%rankforge_rank% displays Unranked, %rankforge_rank_id% displays none).

3. Rewards are awarded once. Claimed tier IDs are persisted in player data. Point drops and rebounds will not re-trigger rewards.

4. Promotions trigger upon kills. Reward commands, screen titles, sounds, and global broadcast messages occur when an opponent is slain.

5. Console commands. All rewards run with console privilege.

Tier changes via commands or API

Commands like /rankforge setpoints adjust points without executing automatic tier rewards. If you need rewards triggered from external plugins, listen for PlayerTierUpEvent via the Developer API.

Custom Tier Example

tiers:
  master:
    min: 8000
    display: "<#B388FF>&lMASTER</#7C4DFF>"
    sound: "UI_TOAST_CHALLENGE_COMPLETE"
    title:
      main: "<#B388FF>&lMASTER!</#7C4DFF>"
      sub: "&7You reached tier <#B388FF>MASTER</#7C4DFF>"
    rewards:
      - "broadcast &6<player> &ehas reached tier MASTER!"
      - "give <player> diamond 16"

Execute /rankforge reload to apply.

LuckPerms Group Rewards

rewards:
  - "lp user <player> parent add pvp-elite"