Quick summary — what the rank system does

• Tracks per-user XP and computes a level using a simple formula (getLevel(xp)).

• Shows a user’s level/XP, a top-10 leaderboard, and the currently configured reward ladder.

• Lets staff add/remove rewards, set or reset a user’s XP, and enable/disable the rank system.

• Data is persisted to JSON files in the bot’s data/ folder (rankData.json, rankRewards.json, rankSettings.json).

Commands (purpose, syntax, examples, notes)

/rank view [user]

Purpose — Show a user’s current level, XP and progress to the next level. Defaults to the command user when no user is supplied.
Syntax

/rank view [user:@member]

Example

/rank view @SomeMember

Notes

• The command computes level via the built-in getLevel(xp) helper and shows XP: current/nextLevelXP in an embed.

/rank leaderboard

Purpose — Display the top users by XP (top 10).
Syntax

/rank leaderboard

Example

/rank leaderboard

Notes

• The command sorts the on-disk rank data by XP, resolves member usernames (falling back to “Unknown” if a member can’t be fetched), and replies with an embed listing the top scorers.

/rank rewards

Purpose — List level → role mappings currently configured.
Syntax

/rank rewards

Example

/rank rewards

Notes

• The command prints lines like Level 5 ➜ <@&ROLE_ID> by reading rankRewards.json. This shows what roles are mapped to levels. (The mapping is persisted on disk.)

/rank addreward <level> <role>

Purpose — Add or update a role reward for the given level.
Syntax

/rank addreward level:5 role:@SomeRole

Example

/rank addreward level:10 role:@Veteran

Notes

• Writes the mapping to rankRewards.json and confirms success. It stores rewards[level] = role.id and saves to disk. Ensure the bot’s role is high enough to assign reward roles if automated assignment is used elsewhere.

/rank removereward <level>

Purpose — Remove the role mapping for a level.
Syntax

/rank removereward level:10

Example

/rank removereward level:10

Notes

• Deletes the property from the rewards object, writes the file, and replies with a confirmation.

/rank setxp <user> <amount>

Purpose — Manually set a user’s XP value. Useful for corrections or migration.
Syntax

/rank setxp user:@member amount:1200

Example

/rank setxp user:@Player amount:1500

Notes

• The command writes rankData[user.id] = { xp } to disk and confirms the change. After changing XP you can /rank view to verify the new level/progress.

/rank reset <user>

Purpose — Reset a user’s XP/level progress (delete their stored data).
Syntax

/rank reset user:@member

Example

/rank reset user:@Player

Notes

• Deletes the entry from rankData.json and confirms. This is irreversible unless you re-enter XP manually.

/rank enable / /rank disable

Purpose — Turn the server’s leveling system on or off.
Syntax

/rank enable
/rank disable

Notes

• The command toggles the enabled flag inside rankSettings.json. By default the settings file initializes with { enabled: true, xpPerMessage: 10 }. When disabled, the engine that awards XP should cease awarding (the implementation checks this flag).

/rank settings

Purpose — Show the current rank settings: whether the system is enabled, XP-per-message, and number of rewards configured.
Syntax

/rank settings

Example

/rank settings

Notes

• Returns an embed with fields for Enabled, XP Per Message, and Rewards count (pulled from the settings and rewards files). Use this to audit the configured XP policy.

How levels are calculated

The command code uses a simple helper:

function getLevel(xp) {
return Math.floor(0.1 * Math.sqrt(xp));
}

So level scales roughly with the square root of XP; the command also computes next-level XP as Math.pow(level + 1, 2) * 10 for the progress bar. Use /rank view to see the xp/nextXP progress.

Storage & persistence

• rankData.json — per-user XP ({ userId: { xp: number } }).

• rankRewards.json — level → role ID mapping.

• rankSettings.json — simple settings object (enabled, xpPerMessage).
  All three files are created automatically if missing when the command loads. Changes written by the commands are persisted immediately to disk.

Who can run these commands

• The commands are staff-facing management utilities. In most setups you’ll restrict them via Command Permissions (Managers/custom role) so only moderators or admins can run setxp, addreward, removereward, reset, enable, disable. The /rank view and /rank leaderboard are usually safe for everyone to run. If you use Command Permissions, map these to the Manager role(s) as needed.

Best practices

• Test in a staff channel — try /rank view, /rank setxp, and /rank leaderboard in a private staff channel before posting to public channels.

• Use setxp sparingly — prefer adjusting the XP engine or letting natural XP accumulation run; setxp is for fixes or migrations.

• Audit rewards — use /rank rewards after adding rewards with /rank addreward to verify the mapping. Keep role names clear and ensure the bot can manage those roles (see troubleshooting).

• Check rankSettings.json — xpPerMessage is used when awarding XP (the rank engine reads this setting). If you change XP rules externally, remember to update the settings file via your tooling or dashboard.

Troubleshooting

• Leaderboard is empty or missing users

  • Confirm rankData.json contains entries (the leaderboard sorts rankData). If your leveling engine is not awarding XP, check that rankSettings.json.enabled is true. The files are in the bot data/ folder.

• Rewards not showing or role appears as ID

  • /rank rewards shows Level X ➜ <@&ROLE_ID>. If the role mention displays as an ID, the role might have been deleted or the bot lacks access — verify the role exists and the bot can view/mention it. The reward mapping is simply stored in rankRewards.json.

• Bot cannot assign reward roles automatically

  • The current command code only stores the reward mapping. If your server expects automatic role assignment on level up, confirm there is a separate level-award routine that checks rankRewards.json and that the bot has Manage Roles and the bot role is above the roles it must assign. (If automatic assignment is missing, you may need to wire a listener that grants roles when XP crosses a threshold.)

• File write/read errors

  • Ensure the bot process user has filesystem permissions to read/write the data/ directory. The command creates files on first run (ensureFiles()), but will fail if the environment prevents writes.

Quick cheat-sheet

/rank view [user:@member] # View a user's level & XP
/rank leaderboard # Show top 10 users
/rank rewards # List level -> role mappings
/rank addreward level:5 role:@Role
/rank removereward level:5
/rank setxp user:@member amount:1500
/rank reset user:@member
/rank enable
/rank disable
/rank settings # Show enabled, xpPerMessage, reward count