Level roles

Map XP thresholds to Discord roles. Crossing the threshold grants the role automatically.

How it works

Define a ladder of rungs. Each rung has:

• Required XP — the threshold to cross.
• Role — the Discord role to grant.
• Removable — whether /plevel reset strips it.

Members cross a rung the moment their XP meets/exceeds the requirement. Phantom applies the role + (if enabled) posts the level-up announcement.

Example ladder

Level	XP	Role
5	1118	@Member
10	3162	@Active
25	12500	@Veteran
50	35355	@Pillar
100	100000	@Legend

You can have up to 50 rungs.

Stack vs replace

Configured on the XP rules page, not here:

• Stack — a level-100 member has @Member, @Active, @Veteran, @Pillar, @Legend.
• Replace — a level-100 member only has @Legend; lower rungs auto-stripped.

Stack is the default. Replace is right for tiered "rank" ladders where you only want the highest visible.

Setup

1. Create the roles in Discord first. Make sure Phantom's role is above every one in the hierarchy (Server Settings → Roles → drag Phantom up).
2. On Levelling → Level Roles, click Add rung.
3. Pick the XP threshold + Discord role.
4. Repeat for as many rungs as you want.
5. Save.

The bot re-checks every member's rungs on the next XP gain. To force a sweep across all members, use the Recompute now button (rate-limited; runs in the background and can take a minute on large servers).

Hierarchy gotcha

A common cause of "rewards aren't applying": Phantom's role is below one of the level-role rewards in the server's role list. Discord doesn't let a bot manage roles above its own.

Fix: drag Phantom up. The Error Log will tell you "role_hierarchy" when this is the case.

Permissions

• levelling.view — see the ladder
• levelling.edit — add / edit / remove rungs, run recompute

Limits

• 50 level roles per guild

Behaviour

• Phantom checks rungs the moment a member earns XP, so reaching a threshold grants the role immediately — no waiting for a refresh.
• A member's existing roles outside the ladder are never touched.
• Removing a rung from the ladder doesn't strip the role from members who already have it — manual cleanup is up to you.

Related pages

• XP rules
• Overview — the {role} placeholder for announcements