Ranks, Levels and Rewards: Settings and Troubleshooting

From the XP that members collect, Kage derives two independent kinds of progress: the fine-grained level (1, 2, 3, …) and the coarse, named rank (for example Member, VIP). Both are based on the same total XP, but they have separate settings and separate roles. That lets you, for example, reward level 20 with a special role while also maintaining five ranks with a role swap.

Where XP comes from is covered in Levels and XP: Sources, Limits and Anti-Farming. Commands, multipliers and the season reset are explained in Managing levels and XP. For a short walkthrough on roles, see the guide Assigning level roles.

Requirements

• Access to the module: You sign in to the dashboard with Discord and need the Manage Server permission (or access granted for this module).
• Turn the module on: "Rank/XP system active" must be on.
• Roles in Discord: Create the roles for ranks, newcomers and level rewards.
• Role order and permission: Kage's role must be above all rank and reward roles in the role list. Kage also needs the Manage Roles permission (part of the standard invite).
• For messages: Kage must be allowed to send messages in the chosen channel.

Levels

The level curve

Kage calculates the total XP needed for level *n* as base × n². The formula base is 100 by default:

Early levels come quickly; later ones cost noticeably more. Under Custom level thresholds you set an exact XP number for individual levels. Such an entry applies to exactly that level; all other levels keep following the formula. The highest possible level is 1000.

Level rewards

Under Level rewards you assign a role to a level:

• The reward is granted from that level on. If a member skips the level (for example from 9 to 11 through bonus XP), they still get the role.
• Members who already passed the threshold earlier get the role afterwards once automatically (within a few minutes, in small steps so Discord isn't overloaded). A newly added or changed reward is caught up once as well. If you later remove the role from someone on purpose, Kage doesn't grant it again.
• Roles stack: Kage does not remove an earlier reward role. This is different from rank roles.
• Only one reward per level is possible, and each row needs a level and a role, otherwise the dashboard refuses to save.
• If a member jumps over several levels through a large grant (for example by an admin command), Kage grants only the reward of the level that was reached. Rewards for skipped levels are not granted retroactively.

Level-up message

Kage sends a message when a member reaches a new level, but only if you have chosen a level-up channel. Without a channel it stays silent, so that frequent promotions do not create spam by accident. In the text you can use the placeholders {member} (mention) and {level}. The pre-filled default text is German and can be changed freely.

Ranks

The five tiers

Kage knows five rank tiers in a fixed order. You set the label and role per tier; the default thresholds are:

A tier only counts as reached when all previous tiers have also reached their threshold: a tier's effective threshold is the maximum of its own and all its predecessors' thresholds. If you accidentally leave VIP at 0 while Premium Member is at 1,000, VIP is still only granted from 1,000 XP. /level-info shows the thresholds that actually apply.

A tier without a chosen role assigns no role and does not appear in the /level-info list. The tier name itself is not shown in /level or /leaderboard, they only show level and XP.

What happens on a rank promotion

When a member reaches a new tier through XP:

1. Kage assigns the role of the new tier.
2. If "Remove the previous rank role on promotion (instead of stacking)" is on (default) and the new tier has a role, Kage removes all other rank roles (including the newcomer role), not just the arithmetically previous one. That way exactly one rank role remains even if tiers were skipped.
3. Kage sends the rank-up message, depending on Send to: *Channel*, *Direct message* or *No message*. For *Channel* you must choose a rank-up channel, otherwise no message is sent. Placeholders: {member} and {rank}.
4. The event appears in the module's Logs tab.

If the rank drops because of an XP deduction, Kage adjusts the rank role as well. The dashboard option "Automatically demote on XP reduction" is currently not evaluated by the bot.

Newcomer → Member

Promotion out of Newcomer does not run on XP but on conditions:

1. Joining: Anyone who joins the server gets the newcomer role, provided the module is on and a newcomer role has been chosen. Bots are excluded. Members who were already on the server before setup do not get it retroactively.
2. Progress: Kage counts how many messages, reactions and voice minutes the member has collected. A message counts even if it is shorter than the XP minimum length.
3. Conditions: By default it takes 1 message and 1 reaction; voice minutes are no condition at 0. As soon as all enabled conditions are met, Kage swaps the newcomer role for the role of the *Member* tier once.
4. The promotion is permanent and is never reset, even if you raise the thresholds later. Kage does not send a message for this promotion.

Without a chosen newcomer role, Kage does not count the progress at all. Exclusion roles and fully excluded channels block the progress just like XP.

Whether reactions on your own messages count is decided solely by the XP setting "Reactions on your own messages give no XP". The checkbox "Reactions on your own messages count toward the newcomer condition" is currently not evaluated.

Settings at a glance

Checking the result

1. A member's status: /level shows level, total XP and progress toward the next level.
2. Leaderboard: /leaderboard (German /rangliste) shows the top 10 with place, name and level.
3. Server rules: /level-info lists the rank tiers with role and effective threshold.
4. Roles in Discord: With a test account, check that the expected role was assigned and the previous one removed.
5. Log: The Logs tab shows level and rank promotions.

Troubleshooting

The rank or reward role is not assigned

Usually it is the role order: Kage's role must be above the role, and Kage must have the Manage Roles permission. Discord shows no message for this; the error appears only in the operating log. Also check that the role still exists in Discord, since Kage skips a deleted role.

A member lacks the rank although they have enough XP

Check whether a role is chosen for that tier and whether the thresholds of the previous tiers are lower (the running maximum applies). /rank-xp recalculate-roles reconciles a member's rank role with their current XP.

A member is stuck in the newcomer role

Check that a newcomer role is chosen and saved, whether the conditions are achievable (for example voice minutes), and whether the member is blocked by an exclusion role or an excluded channel. A reaction on your own message does not count by default.

Too many members become Member immediately

With threshold 0, the *Member* tier applies from 0 XP. The swap out of the newcomer role still depends on the newcomer conditions. Note that /rank-xp recalculate-roles sets the role purely by XP and does not check the newcomer conditions.

The level-up message is missing

Kage only sends it when a level-up channel is chosen, even though the dashboard offers "post in the message's channel" in the channel list. Also check that Kage may send messages in the channel.

The level reward is missing

Possible reasons: the member skipped the level, already has the role, the role was deleted, or it sits above Kage's role.

The rank message is missing

Check "Send to" and, for *Channel*, whether a rank-up channel is chosen. With *Direct message*, delivery fails if the member has blocked direct messages from server members.

Further reading

Sources and limits of XP: Levels and XP: Sources, Limits and Anti-Farming. Commands, multipliers and season reset: Managing levels and XP. Roles in general: Auto roles and Reaction roles.