Official Guide

Configuration

Explore the complete configuration documentation below for RankForge.

📄 Configuration Files

`config.yml`

The master configuration file. Every section is explained below.

# ─────────────────────────────────────────────────────────────
#  RankForge — config.yml
#  Reload at any time with: /rank reload
# ─────────────────────────────────────────────────────────────

# ── Language ────────────────────────────────────────────────
language:
  # Default language code. Must match a file in plugins/RankForge/lang/.
  # Bundled: en, es, fil, id
  default: "en"
  # Allow players to set their own language with /rank lang set <code>
  per-player: true

# ── Announcements (rankup notifications) ────────────────────
announcements:
  enabled: true
  rankup:
    # Server-wide chat broadcast
    broadcast: true
    message: "&6[RankForge] &e%player% &aranked up to &6%rank%&a!"

    # Full-screen title shown to the ranking-up player
    title:
      enabled: true
      title: "&6✦ Rank Up! ✦"
      subtitle: "&eYou are now &a%rank%"
      fade-in: 10    # ticks (20 ticks = 1 second)
      stay: 60
      fade-out: 10

    # Action bar shown to the ranking-up player
    action-bar:
      enabled: true
      message: "&a✦ You ranked up to &e%rank% &a✦"

# ── Cosmetics ────────────────────────────────────────────────
cosmetic:
  # Boss bar shown to the player on rankup and progress checks
  bossbar:
    enabled: true
    duration-ticks: 100   # How long the boss bar stays visible (100 ticks = 5 seconds)

  # Tablist prefix: shows the player's rank prefix in the player list
  tablist:
    enabled: true
    # Available tokens: {prefix} {player}
    format: "{prefix}{player}"

  # Particle trail spawned around the player on rankup (auto-expires)
  particles:
    enabled: true

# ── Data Storage ─────────────────────────────────────────────
# Options: mysql, yaml (yaml = local file fallback)
storage:
  type: yaml
  mysql:
    host: "localhost"
    port: 3306
    database: "rankforge"
    username: "root"
    password: "password"
    pool-size: 10

# ── Sync (YAML mode only) ────────────────────────────────────
sync:
  # How often online player data is flushed to the YAML file (in ticks)
  interval-ticks: 200

# ── Block Break Tracker ──────────────────────────────────────
tracker:
  # How often the in-memory block-break counts are flushed to storage (ticks)
  block-break-flush-ticks: 100

# ── Performance ──────────────────────────────────────────────
performance:
  modes:
    # TPS at or above this → HIGH mode (all cosmetics enabled)
    high-tps-threshold: 18.0
    # TPS at or above this → MEDIUM mode (reduced cosmetics)
    medium-tps-threshold: 14.0
    # TPS below medium threshold → LOW mode (cosmetics disabled)

# ── Crossplay (Geyser / Floodgate) ──────────────────────────
crossplay:
  # Bedrock player names are prefixed with this character by Floodgate.
  # RankForge strips this prefix from display names automatically.
  bedrock-prefix: "."

# ── REST API ─────────────────────────────────────────────────
rest-api:
  enabled: false
  port: 4567
  # Bearer token for authentication. Leave empty to disable auth (dev only!).
  token: ""

# ── Debug ────────────────────────────────────────────────────
debug: false

`ranks.yml`

Defines every rank. Each rank is a YAML key (the rank ID) containing its display properties, GUI position, requirements, and rewards.

# ─────────────────────────────────────────────────────────────
#  RankForge — ranks.yml
# ─────────────────────────────────────────────────────────────

# The rank ID assigned to players who have no stored data.
default-rank: Guest

ranks:

  # ── Rank ID ─────────────────────────────────────────────
  Guest:
    # Text shown in GUIs and messages. Supports & color codes.
    display-name: "&7[Guest]"
    # The rank ID this rank promotes to. Leave empty for the final rank.
    next-rank: "Member"
    # GUI inventory slot (0–53). Use the drag editor to reorder visually.
    slot: 11
    # Material for the GUI icon.
    material: GRAY_WOOL
    # Lore lines on the GUI icon. Supports & color codes.
    lore:
      - "&7Starting rank."
    # Chat prefix injected into the tablist and cosmetics.
    chat-prefix: "&7[Guest]"
    # Permission nodes granted to the player when they hold this rank.
    permissions:
      - "essentials.chat.color"
    # Console commands executed when this rank's requirements are met and player ranks up.
    commands: []
    # ── Requirements (all must be met to rank up FROM this rank) ──
    required-money: 0
    required-xp-level: 0
    required-permission: ""
    required-playtime: 0
    required-mob-kills: 0
    required-block-breaks: 0
    required-statistic-id: ""
    required-statistic-value: 0
    required-quests: []
    required-worlds: []
    required-items: {}

  Member:
    display-name: "&a[Member]"
    next-rank: "Veteran"
    slot: 13
    material: GREEN_WOOL
    lore:
      - "&7A trusted community member."
      - ""
      - "&eRequirements:"
      - "  &7$1,000"
      - "  &710 XP levels"
      - "  &760 minutes playtime"
    chat-prefix: "&a[Member]"
    permissions:
      - "essentials.sethome.multiple.member"
    commands:
      - "lp user %player% group set member"
    required-money: 1000
    required-xp-level: 10
    required-playtime: 60
    required-mob-kills: 0
    required-block-breaks: 0
    required-items: {}
    required-quests: []
    required-worlds: []

  Veteran:
    display-name: "&2[Veteran]"
    next-rank: "Elite"
    slot: 15
    material: EMERALD
    lore:
      - "&7A seasoned survivor."
    chat-prefix: "&2[Veteran]"
    permissions:
      - "essentials.sethome.multiple.veteran"
    commands:
      - "lp user %player% group set veteran"
      - "give %player% GOLDEN_APPLE 5"
    required-money: 10000
    required-xp-level: 30
    required-playtime: 600
    required-mob-kills: 100
    required-block-breaks: 5000
    required-items:
      DIAMOND: 10
    required-quests:
      - "first_quest"
    required-worlds: []

  Elite:
    display-name: "&b[Elite]"
    next-rank: ""
    slot: 31
    material: DIAMOND
    lore:
      - "&7The pinnacle of achievement."
    chat-prefix: "&b[Elite]"
    permissions:
      - "essentials.sethome.multiple.elite"
    commands:
      - "lp user %player% group set elite"
    required-money: 100000
    required-xp-level: 75
    required-playtime: 3000
    required-mob-kills: 1000
    required-block-breaks: 50000
    required-statistic-id: "FISH_CAUGHT"
    required-statistic-value: 50
    required-items:
      NETHERITE_INGOT: 5
      DIAMOND: 32
    required-quests:
      - "main_quest"
      - "side_quest_a"
    required-worlds:
      - "world"

Rank Property Reference

Property	Type	Description
`display-name`	String	Name shown to players. Supports `&` color codes.
`next-rank`	String	The rank ID this rank promotes to. Empty string = final rank.
`slot`	Integer	Inventory slot (0–53) in the rank tree GUI.
`material`	String	Bukkit `Material` name for the GUI icon.
`lore`	List\<String\>	Lore lines on the GUI icon.
`chat-prefix`	String	Prefix shown in the tablist.
`permissions`	List\<String\>	Permissions granted when the player holds this rank.
`commands`	List\<String\>	Console commands run on rankup. Use `%player%` for the player's name.
`required-money`	Double	Vault balance required. `0` = no requirement.
`required-xp-level`	Integer	Vanilla XP level required.
`required-permission`	String	A single permission node required to rank up.
`required-playtime`	Long	Total server playtime required (minutes).
`required-mob-kills`	Integer	Total mob kills required (`MOB_KILLS` statistic).
`required-block-breaks`	Integer	Exact block breaks tracked by RankForge's counter.
`required-statistic-id`	String	Any untyped `Bukkit.Statistic` enum name.
`required-statistic-value`	Integer	The required value for the above statistic.
`required-quests`	List\<String\>	Quest IDs. Each is checked as `rankforge.quest.completed.<id>`.
`required-worlds`	List\<String\>	Player must currently be in one of these world names.
`required-items`	Map	`MATERIAL_NAME: amount` pairs. Items must be in inventory.

Language Files

Language files live in plugins/RankForge/lang/. RankForge ships with four built-in files and dynamically loads any .yml file placed in that folder.

File	Language
`en.yml`	English (default)
`es.yml`	Spanish
`fil.yml`	Filipino
`id.yml`	Indonesian

Adding a custom language:

Create plugins/RankForge/lang/de.yml (or any ISO code)
Copy en.yml as a template and translate the messages section
Run /rank reload — RankForge discovers the file automatically
Players can switch with /rank lang set de