Guides & reference

📝 Full Configuration Examples

Survival Server (5 Ranks)

# ranks.yml
default-rank: Guest

ranks:
  Guest:
    display-name: "&7[Guest]"
    next-rank: "Member"
    slot: 10
    material: GRAY_WOOL
    lore:
      - "&7Welcome to the server!"
    chat-prefix: "&7[G]"
    permissions: []
    commands: []
    required-money: 0
    required-xp-level: 0
    required-playtime: 0
    required-mob-kills: 0
    required-block-breaks: 0
    required-items: {}

  Member:
    display-name: "&a[Member]"
    next-rank: "Veteran"
    slot: 13
    material: GREEN_WOOL
    lore:
      - "&7A trusted member."
      - ""
      - "&eRequires:"
      - "  &7$500 | 5 XP | 1 hour"
    chat-prefix: "&a[M]"
    permissions:
      - "essentials.sethome.multiple.2"
    commands:
      - "lp user %player% group set member"
      - "eco take %player% 500"
    required-money: 500
    required-xp-level: 5
    required-playtime: 60
    required-mob-kills: 0
    required-block-breaks: 0
    required-items: {}

  Veteran:
    display-name: "&2[Veteran]"
    next-rank: "Elite"
    slot: 16
    material: EMERALD
    lore:
      - "&7A seasoned player."
    chat-prefix: "&2[V]"
    permissions:
      - "essentials.sethome.multiple.4"
    commands:
      - "lp user %player% group set veteran"
      - "eco take %player% 10000"
      - "give %player% GOLDEN_APPLE 3"
    required-money: 10000
    required-xp-level: 30
    required-playtime: 600
    required-mob-kills: 200
    required-block-breaks: 10000
    required-items:
      DIAMOND: 5

  Elite:
    display-name: "&b[Elite]"
    next-rank: "Legend"
    slot: 22
    material: DIAMOND
    lore:
      - "&7Among the best."
    chat-prefix: "&b[E]"
    permissions:
      - "essentials.sethome.multiple.6"
    commands:
      - "lp user %player% group set elite"
      - "eco take %player% 50000"
    required-money: 50000
    required-xp-level: 60
    required-playtime: 3000
    required-mob-kills: 1000
    required-block-breaks: 100000
    required-items:
      DIAMOND: 32
      NETHERITE_INGOT: 2

  Legend:
    display-name: "&6&l[Legend]"
    next-rank: ""
    slot: 31
    material: NETHER_STAR
    lore:
      - "&6The highest rank."
      - "&7Only the truly dedicated reach this."
    chat-prefix: "&6&l[L]"
    permissions:
      - "essentials.sethome.multiple.10"
    commands:
      - "lp user %player% group set legend"
      - "eco take %player% 200000"
      - "broadcast &6✦ %player% &rhas become a LEGEND! &6✦"
    required-money: 200000
    required-xp-level: 100
    required-playtime: 10000
    required-mob-kills: 5000
    required-block-breaks: 500000
    required-items:
      NETHERITE_INGOT: 10
      DRAGON_EGG: 1
    required-quests:
      - "ender_dragon"

Prison Server (A→Z)

# ranks.yml
default-rank: A

ranks:
  A:
    display-name: "&7[A]"
    next-rank: "B"
    slot: 0
    material: GRAY_WOOL
    lore: ["&7Mine the A mine."]
    chat-prefix: "&7[A]"
    permissions: ["mines.a"]
    commands: []
    required-money: 0
    required-xp-level: 0
    required-playtime: 0
    required-mob-kills: 0
    required-block-breaks: 0
    required-items: {}

  B:
    display-name: "&f[B]"
    next-rank: "C"
    slot: 1
    material: WHITE_WOOL
    lore: ["&7Mine the B mine."]
    chat-prefix: "&f[B]"
    permissions: ["mines.b"]
    commands:
      - "lp user %player% group set B"
      - "eco take %player% 5000"
    required-money: 5000
    required-xp-level: 0
    required-playtime: 0
    required-mob-kills: 0
    required-block-breaks: 500
    required-items: {}

  # ... repeat the pattern through Z ...

  Z:
    display-name: "&6&l[Z] FREE"
    next-rank: ""
    slot: 25
    material: GOLD_BLOCK
    lore:
      - "&6You've earned your freedom!"
    chat-prefix: "&6[FREE]"
    permissions: ["mines.free", "prison.free"]
    commands:
      - "lp user %player% group set free"
      - "eco take %player% 10000000"
      - "broadcast &6%player% has earned their FREEDOM from prison!"
    required-money: 10000000
    required-xp-level: 0
    required-playtime: 0
    required-mob-kills: 0
    required-block-breaks: 1000000
    required-items: {}

💡 Best Practices

Rank ID Naming

• Use PascalCase or UPPERCASE: Guest, Member, Veteran or RANK_A, RANK_B
• Avoid spaces and special characters
• Keep IDs short — they appear in logs, commands, and API calls

Requirement Scaling

• Scale requirements exponentially, not linearly. Each rank should be noticeably harder than the last
• Combine multiple requirement types to prevent any single grind path from being exploitable (e.g., money + playtime together prevent AFK farming)
• Use required-block-breaks on survival/skyblock servers; use required-mob-kills on combat servers

LuckPerms Groups

• Create a matching LuckPerms group for every rank before configuring RankForge
• Use commands entries to call lp user %player% group set <group> — this is permanent, unlike the permissions field which is session-based

YAML Editing Safety

• Always run /rank reload after editing ranks.yml, never /reload
• Use a YAML validator before applying changes on a live server
• Take a backup of ranks.yml before major restructuring

MySQL on Networks

• Use MySQL if you run more than one server (BungeeCord/Velocity) and want shared rank data
• Ensure the MySQL user has only SELECT, INSERT, UPDATE, DELETE on the rankforge database (no DROP or CREATE)

❓ Frequently Asked Questions

[RankForge] [SoftDep] Vault=✓ ...

🔍 Troubleshooting

Enable Debug Mode

# config.yml
debug: true

Reload with /rank reload. Debug mode prints detailed logs for:

• Requirement checks per player
• Block-break counter updates
• Cache hits/misses
• Storage read/write operations
• Performance mode transitions

Common Errors

Checking the Startup Log

A healthy startup looks like:

[RankForge] [SoftDep] Vault=✓  LuckPerms=✓  PlaceholderAPI=✓  Floodgate=✗
[RankForge] [Lang] Dynamically indexed 4 language profiles: [en, es, fil, id]
[RankForge] [REST] API server listening on port 4567   ← (if enabled)
[RankForge] RankForge v3.8 successfully loaded! (5 ranks compiled)

If the rank count shows (0 ranks compiled), ranks.yml failed to parse. Check for YAML syntax errors (indentation, missing colons, tab characters).

Checking Player Data

Use /rank debug (run as the player) or the Player List GUI (/rank playerlist) to inspect a player's current rank, XP, and cached data.

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository on GitHub
2. Branch from main: git checkout -b feature/my-feature
3. Code your changes following the existing style (Java 21, no wildcard imports, Javadoc on all public API methods)
4. Test on a local Paper 1.21.4 server
5. Commit with a clear message: git commit -m "feat: add custom statistic requirement support"
6. Open a Pull Request targeting main

Bug Reports

Use GitHub Issues. Include:

• Server software and exact version (e.g., Paper 1.21.4 #123)
• Java version (java -version)
• Full error from logs/latest.log
• Your config.yml and ranks.yml (remove credentials)
• Steps to reproduce

💬 Support

📄 License

MIT License

Copyright (c) 2024 JoshuaOP

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

See LICENSE for the full text.

🙏 Credits

Behind the Scenes: Automatic Schema Handling

No manual configuration changes are ever required for playtime tracking. The playtime key in ranks.yml stays the same whether you use whole minutes or the new duration-string format:

1. RankForge automatically keeps the YAML playerdata schema up to date, adding playtime: 0 to any record that doesn't already have it.
2. For MySQL, a playtime_minutes column is added automatically via ALTER TABLE on startup if it doesn't exist.
3. Any player without existing wall-clock playtime data starts at 0 real minutes and accumulates from that point onward.

Tips and Best Practices

• Start low. Begin with shorter playtime requirements (30–60 minutes) and increase them based on your player feedback.
• Combine with other requirements. Playtime alone doesn't show engagement. Pair it with block-breaks or mob-kills for a richer progression curve.
• AFK players. Playtime counts even while AFK. If you want to exclude AFK time, use a compatible AFK plugin that removes players from the server (which stops the timer), or use an activity-based requirement like block-breaks as the primary gate.
• Test before going live. Use /rank set <yourself> <rank> and /rank progress to verify requirements display correctly.
• Reload safely. Always use /rank reload — never /reload. A server reload can corrupt the tracker's session state.

Troubleshooting Playtime

❓ Frequently Asked Questions

General

Q: Does RankForge work without Vault, LuckPerms, or PlaceholderAPI? A: Yes. All three are optional. Without Vault, money requirements are skipped. Without LuckPerms, a Bukkit PermissionAttachment is used as fallback. Without PlaceholderAPI, the %rankforge_*% placeholders are simply unavailable.

Q: Can I have unlimited ranks? A: Yes. RankForge loads every rank defined in ranks.yml with no hardcoded limit.

Q: Does RankForge support Bedrock players (Geyser/Floodgate)? A: Yes. All storage and checks use UUID, not player name. The Bedrock prefix (. by default) is stripped from display names automatically.

Q: Will /reload (vanilla server reload) break the plugin? A: It can. Always use /rank reload instead. The vanilla reload can corrupt in-memory state and discard unsaved playtime data.

Playtime

Q: How is playtime measured? A: Using System.currentTimeMillis() — real wall-clock time measured in milliseconds and stored as whole minutes. This is completely independent of server TPS.

Q: Does playtime count while the player is AFK? A: Yes, by default. The timer runs from join to quit regardless of activity. If you need AFK detection, use an external AFK plugin that disconnects inactive players, or gate progression on activity-based requirements like block-breaks.

Q: Why does a player show 0 playtime even though they've played before? A: This happens if a player's record predates wall-clock tracking being enabled on your server. The vanilla PLAY_ONE_MINUTE statistic (tick-based) is intentionally not used to back-fill this value, since it can be skewed by lag. Playtime accumulates accurately from that point onward.

Q: What happens to playtime if the server crashes? A: Playtime is periodically flushed to storage (every sync.interval-ticks, default 10 seconds). On a crash, up to 10 seconds of playtime may be lost. Clean shutdowns always flush everything before stopping.

Q: Can I manually set a player's playtime? A: Currently, this must be done by editing playerdata.yml while the server is stopped (or via a MySQL UPDATE). A /rank playtime set admin command may be added in a future version.

Q: My playtime requirement shows "0min" in /rank progress even though I've been online for an hour. A: This can happen if the tracker didn't initialize on join (e.g., the plugin reloaded while you were online). Rejoin the server — the tracker will re-register your session start. If the issue persists, check console for errors.

Q: Does playtime in ranks.yml still work without changes? A: Yes. The configuration key is identical. No migration of ranks.yml is required — only the underlying implementation changed.

Storage

Q: Which storage backend should I use? A: YAML is suitable for single servers. MySQL is recommended for networks, bungeecord/velocity proxies, or servers with more than a few hundred players. MySQL is also required if you want to query player data from external tools (dashboards, Discord bots, etc.).

Q: My MySQL connection fails. Will the server error out? A: No. RankForge automatically falls back to YAML storage when MySQL is unavailable, logs a single info-level message, and continues loading normally.

Q: How do I migrate from YAML to MySQL? A: Start the server with MySQL configured. RankForge will create the tables. Then manually export data from playerdata.yml and insert it into rf_players. A built-in migration tool may be added in a future version.

🔧 Troubleshooting

Plugin fails to load

1. Check Java version: java -version must be 21 or higher.
2. Confirm you are running Spigot or Paper 1.17+.
3. Review the console for [SEVERE] messages from RankForge on startup.

Ranks not loading

1. Ensure ranks.yml is valid YAML. Use yaml-online-parser.appspot.com to validate.
2. Verify the default-rank value matches an actual rank key.
3. Run /rank reload after editing the file.

/rank up does nothing

1. Run /rank progress — this shows which requirements are unmet.
2. Confirm the current rank has a next-rank set.
3. Ensure you are not at the final rank (empty next-rank).

Playtime not advancing

1. Check startup log — PlaytimeTracker registers on load. If there are errors, address them.
2. Relog: the join event re-registers your session start.
3. Check if /rank requirements shows a playtime line. If absent, the rank has playtime: 0 (no requirement).

Playtime not saving after restart

1. Check write permissions on plugins/RankForge/data/playerdata.yml.
2. Confirm no [YamlStorage] Failed to save errors appear in console.
3. For MySQL: check for [DB] MySQL save failed warnings.

GUI not opening

1. Ensure no other plugin is cancelling inventory open events.
2. Check for GuiClickShieldManager warnings in console.
3. Confirm the player has rankforge.rank.use permission.

LuckPerms permissions not applying

1. LuckPerms must load before RankForge. Add depend: [LuckPerms] to LuckPerms's plugin.yml or ensure load order.
2. Verify the permission nodes in ranks.yml are valid (no spaces, valid format).
3. Use /rank set <player> <rank> to force a re-apply after fixing configuration.

MySQL tables not created

1. Verify credentials in config.yml are correct.
2. Ensure the database user has CREATE TABLE, ALTER, and INSERT privileges.
3. Check console for [DB] Failed to create MySQL tables with the specific SQL error.

🛠️ Setup & Configuration Guide

This guide walks through every step of installing and configuring RankForge from scratch.

📥 Installation Guide

Step 1 — Download RankForge

Download the latest RankForge-*.jar from the SpigotMC resource page.

Step 2 — Install the plugin

Drop the JAR into your server's plugins/ folder:

server/
└── plugins/
    └── RankForge-3.8.jar

Step 3 — Install optional dependencies

Install any of the following soft dependencies for additional features:

None are required — RankForge works out of the box with no dependencies.

Step 4 — Start the server

Start your server once. RankForge auto-generates all configuration files:

plugins/RankForge/
├── config.yml
├── ranks.yml
├── gui.yml
└── lang/
    ├── en.yml
    ├── es.yml
    ├── fil.yml
    └── id.yml

Step 5 — Configure the plugin

Edit the generated files (see the Configuration Guide below).

Step 6 — Reload or restart

Apply your changes without a full restart:

/rank reload

⚙️ Configuration Guide

config.yml

The master settings file. Key sections:

ranks.yml

Defines every rank. Each top-level key under ranks: is a rank ID.

default-rank: Guest   # Rank assigned to new / unknown players

ranks:
  RankId:
    display-name: "&aDisplay Name"
    next-rank: "NextRankId"       # Empty string = final rank
    slot: 11                      # GUI inventory slot (0–53)
    material: GREEN_WOOL          # Bukkit Material name
    lore:
      - "&7Description line"
    chat-prefix: "&a[Tag]"
    permissions:
      - "some.permission.node"
    commands:
      - "lp user %player% group set rankid"
    requirements:
      money: 1000
      xp-level: 10
      playtime: 1hr               # Human-readable duration format (see Requirements Guide)
      mob-kills: 50
      block-breaks: 500
      permission: "some.required.node"
      statistic-id: "FISH_CAUGHT"
      statistic-value: 10
      quests:
        - "quest_id"
      worlds:
        - "world"
      items:
        DIAMOND: 5

Language files (lang/en.yml, lang/fil.yml, lang/id.yml, lang/es.yml)

Located in plugins/RankForge/lang/. Each file contains:

• prefix: — the [RankForge] prefix shown before messages
• messages: — every translatable message string

To add a language, copy en.yml to a new file (e.g., de.yml), translate the messages block, and run /rank reload. Players switch languages with /rank lang set de.

gui.yml

Controls all GUI titles, border materials, slot positions, icons, and themes. Every GUI in RankForge is configurable here without touching any Java code. Apply changes with /rank reload.

YAML storage

Default. Player data is stored in plugins/RankForge/data/playerdata.yml and synced every sync.interval-ticks (default: 200 ticks = 10 seconds). A final flush always runs on clean shutdown.

MySQL storage

storage:
  type: mysql
  mysql:
    host: "localhost"
    port: 3306
    database: "rankforge"
    username: "rankforge_user"
    password: "your_password"
    pool-size: 10

Tables are created automatically. HikariCP handles connection pooling. If the connection fails at startup, RankForge falls back to YAML automatically.

🏅 Rank Creation Guide

Creating a rank

Add a new key under ranks: in ranks.yml:

ranks:
  Builder:
    display-name: "&e[Builder]"
    next-rank: "Veteran"
    slot: 13
    material: BRICKS
    lore:
      - "&7A creative builder."
    chat-prefix: "&e[Builder]"

Reload with /rank reload. You can also create ranks in-game with /rank create <id>.

Linking rank chains

Each rank points to the next via next-rank. Leave it empty for the final rank:

Guest → Member → Veteran → Elite → (empty, final rank)

Configuring rewards

ranks:
  Member:
    permissions:
      - "essentials.sethome.multiple.2"   # Applied when player holds this rank
    commands:
      - "lp user %player% group set member"   # Runs on rankup
      - "eco take %player% 1000"

Configuring permissions

• permissions: — nodes granted while the player holds this rank (managed by LuckPerms or Bukkit attachment)
• commands: — console commands executed at the moment of rankup (%player% is replaced with the player's name)

Configuring requirements

See the Requirements Guide below for all supported types and the new playtime format.

📋 Requirements Guide

All requirements are defined inside a requirements: block within each rank entry.

Playtime Requirement Format

The playtime key uses a single human-readable string. This is the recommended format.

Supported units:

Units are case-insensitive (D, HR, M, S all work). Extra whitespace is ignored. Any combination of units is accepted.

Examples:

requirements:
  playtime: 30m           # 30 minutes

requirements:
  playtime: 2hr           # 2 hours (120 minutes)

requirements:
  playtime: 7d            # 7 days (10,080 minutes)

requirements:
  playtime: 1d 12hr       # 1 day and 12 hours (2,160 minutes)

requirements:
  playtime: 5d 5hr 5m 5s  # 5 days, 5 hours, 5 minutes (seconds truncated)

requirements:
  playtime: 45s           # 45 seconds → 0 whole minutes (no requirement in effect)

Backward compatibility:

Existing configurations using playtime continue to work without any changes:

requirements:
  playtime: 60    # Still fully supported — equals "1hr"

The loader checks for playtime first; if absent, it falls back to playtime. No edits to existing ranks.yml files are required.

Full example rank using the duration format:

ranks:
  Veteran:
    display-name: "&2[Veteran]"
    next-rank: "Elite"
    slot: 15
    material: EMERALD
    chat-prefix: "&2[Veteran]"
    commands:
      - "lp user %player% group set veteran"
    requirements:
      money: 10000
      xp-level: 30
      playtime: 10hr
      mob-kills: 100
      block-breaks: 5000
      items:
        DIAMOND: 10

⌨️ Commands Guide

Player Commands

Admin Commands

🔑 Permissions Guide

Player Permissions

Administrator Permissions

Wildcard Permissions

Quest Permission

📊 PlaceholderAPI Guide

With PlaceholderAPI installed, all %rankforge_*% placeholders are available in any PAPI-compatible plugin (scoreboards, chat formatters, holograms, tab lists, etc.).

❓ FAQ / Troubleshooting

Rank not updating after /rank up Run /rank progress to see which requirements are unmet. Confirm next-rank is set correctly on the current rank.

PlaceholderAPI not working Ensure PlaceholderAPI is installed and loaded before RankForge. Run /papi list to confirm rankforge is registered. Use /rank reload after installing PAPI.

Vault not detected Vault must be installed and an economy provider (e.g., EssentialsX) must also be present. Check startup log for [SoftDep] Vault=✓.

LuckPerms integration not applying permissions LuckPerms must load before RankForge. Verify with /rank version that the plugin loaded successfully. Check that permission nodes in ranks.yml have no spaces or typos.

MySQL connection problems Verify credentials in config.yml. Ensure the database user has CREATE, ALTER, and INSERT privileges. Check console for [DB] Failed to create MySQL tables and the specific SQL error. RankForge automatically falls back to YAML if MySQL is unreachable.

Playtime requirement not progressing Check that PlaytimeTracker initialized on startup (look for errors in the console). Relog — the PlayerJoinEvent re-registers your session start. Confirm the rank's playtime value is greater than zero. Use /rank requirements to see the playtime line.

Old playtime config stopped working It has not stopped working. The key is fully supported. Add playtime: 1hr to new ranks going forward; existing playtime entries require no changes.

Invalid playtime format error Ensure the value uses only the supported units (d, hr, m, s) with whole numbers and no special characters. Valid: 1d 12hr 30m. Invalid: 1.5d, 2hours, 90.

Configuration mistakes Use a YAML validator (e.g., yaml-online-parser.appspot.com) to check ranks.yml for syntax errors. All invalid ranks are logged and skipped — look for [YamlLoader] Skipped rank warnings in the console.

💡 Best Practices

Organizing rank chains

• Keep rank IDs simple and consistent (Guest, Member, Veteran) — they are stored in player data.
• Always set next-rank for every non-final rank to avoid silent dead-ends.
• Use the slot field to arrange ranks visually in the GUI from left to right.

Optimizing performance

• Use YAML storage for single servers; MySQL for networks with many concurrent players.
• Keep sync.interval-ticks at 200 (10 seconds) or higher to reduce disk I/O.
• Disable cosmetics you don't use (particles, bossbar) to reduce per-player overhead on busy servers.
• The TPS-aware performance system automatically suppresses heavy effects when the server is under load.

Creating balanced progression

• Start playtime requirements low (30m–1hr for the first rank) and increase gradually.
• Combine playtime with activity-based requirements (block-breaks, mob-kills) so idle AFK players don't auto-rank.
• Test all requirements on yourself with /rank set <yourself> <rank> and /rank progress before opening to players.

Maintaining configuration files

• Always use /rank reload — never /reload.
• Back up ranks.yml and playerdata.yml (or your MySQL database) before making major changes.
• When renaming a rank ID, update default-rank and all next-rank references, then use /rank reload. Players with the old ID are automatically repaired to default-rank.
• Use the in-game admin editor (/rank editor) for safe edits that automatically validate and save the file.