LuckPerms Setup Guide: Ranks, Prefixes, Tracks and Debugging

LuckPerms Setup Guide: Ranks, Prefixes, Tracks and Debugging

Most LuckPerms trouble comes from the first hour of setup. A rank layout that works for three ranks falls apart at eight, and a prefix that never shows up in chat sends people searching for a bug that isn't there. This guide builds a structure you can grow, then covers the debugging commands for when a permission still doesn't behave.

The three ideas you need

• Permission nodes are strings like essentials.fly. A plugin checks whether the player has the node.
• Groups hold nodes. A player gets nodes by being in a group, and groups can inherit from other groups.
• Contexts limit a node to one server or world, so a permission can apply in survival but not in lobby.

Give permissions to groups, not individual players. When you give a node to one player directly, you will forget it exists, and so will every other admin.

Install and storage

Put the LuckPerms jar for your platform in plugins/ (Bukkit/Paper) or the proxy's plugins folder (Velocity, BungeeCord), then restart. Out of the box it stores data in a local H2 file, which is fine for one server. If several servers behind a proxy must share ranks, point every one of them at the same MySQL, MariaDB or PostgreSQL database in config.yml, otherwise each server keeps its own separate set of ranks.

Plan the layout before typing commands

Keep donor ranks and staff ranks as separate ladders. Players who buy a rank should never end up inheriting staff permissions. A layout that works:

• default for everyone, weight 0
• supporter, weight 100
• helper, weight 200
• mod, weight 300
• admin, weight 400

Space the weights out by 100. When you need a rank between helper and mod in a year, you can add it without renumbering. Weight decides which group wins when a player is in several and their values conflict, such as two different prefixes. The higher weight wins.

/lp creategroup supporter
/lp creategroup helper
/lp creategroup mod
/lp creategroup admin
/lp group supporter setweight 100
/lp group helper setweight 200
/lp group mod setweight 300
/lp group admin setweight 400

Inheritance, and the default-group trap

Here is the one that catches most people. When you set a player's rank with parent set, it replaces their old group, including default. If mod doesn't inherit default somewhere up its chain, a promoted player loses the basic permissions everyone else has.

Chain your staff groups so each inherits the one below, and the bottom one inherits default:

/lp group helper parent add default
/lp group mod parent add helper
/lp group admin parent add mod
/lp group supporter parent add default

Now a node added to default reaches everyone, and a node added to mod reaches mods and admins. Put each permission in the lowest group that should have it.

Giving permissions

/lp group default permission set essentials.spawn true
/lp group helper permission set essentials.kick true
/lp group mod permission set essentials.mute true

Two warnings. Avoid the * wildcard on anything except a group you would trust with the console, because it grants every node, including ones added by plugins you install next year. And remember that false is an explicit deny, which beats an inherited true. Leaving a node unset is not the same as setting it to false.

LuckPerms accepts any string as a node. If you mistype one, nothing warns you and the permission simply never applies. Always confirm the exact node in the plugin's own documentation, or find it with the verbose tool below.

Prefixes, and why they don't show up

/lp group admin meta addprefix 100 "&c[Admin] "
/lp group mod meta addprefix 100 "&a[Mod] "

The number is the prefix priority. When a player has several prefixes, the highest priority one is displayed.

LuckPerms stores the prefix but does not format chat itself. You need something that reads it:

• EssentialsX Chat with {PREFIX} in its chat format, reading from Vault.
• PlaceholderAPI, where %luckperms_prefix% can go into TAB, a scoreboard or a chat plugin.

If a prefix is set but absent from chat, the cause is almost always the missing second half of this setup.

Tracks: promotions without remembering the ladder

A track is an ordered list of groups, so staff can be promoted with one command:

/lp createtrack staff
/lp track staff append helper
/lp track staff append mod
/lp track staff append admin
/lp user Steve promote staff
/lp user Steve demote staff

Promoting a player who isn't on the track yet starts them at its first group. Tracks are also the clean way to keep a trial period honest, since you can demote in one step.

Temporary ranks and contexts

/lp user Steve parent addtemp supporter 30d
/lp user Steve permission settemp essentials.fly true 1h
/lp group supporter permission set essentials.fly true server=survival

The first two expire on their own. The third applies the permission only on the server named survival, which is how you keep a lobby from handing out survival perks.

Debugging a permission that doesn't work

Work through these in order:

/lp user Steve permission check essentials.fly
/lp user Steve info
/lp verbose on

permission check tells you whether Steve has the node and which group it came from. info lists his groups and their weights. With verbose on, trigger the action in game and LuckPerms prints every permission check as the plugin makes it, which shows you the real node the plugin is asking about. Turn it off with /lp verbose off. This is also how you catch the mistyped node problem above.

The web editor and backups

/lp editor gives you a link to a browser editor, which is much easier than commands once you have more than a few groups. Changes are not live until you save in the editor and then run the /lp applyedits command it shows you in game.

Back up before big changes:

/lp export before-rank-rework
/lp import before-rank-rework

Export writes a file in the LuckPerms folder, and import restores from it.

The mistakes worth avoiding

• Giving staff ranks to people through op instead of through a group
• Using * on a group that isn't the top one
• Forgetting that parent set removes default
• Setting a prefix and never installing anything that displays it
• Editing individual players instead of groups
• Trusting a node name you typed from memory without checking it with verbose

Get the structure right once, and adding a new rank later is two commands.