How to set up LuckPerms ranks and permissions

Install LuckPerms on Paper or Purpur

LuckPerms is a plugin for Paper, Purpur, Spigot and Folia. It also comes as a mod for Fabric, Forge and NeoForge and as a proxy plugin for Velocity, with the same commands everywhere. This guide uses a Paper or Purpur server, where it installs from the panel.

1. 1

   Search the catalog

   Open the Plugins tab and type luckperms in Search plugins. The catalog only lists builds for your exact Minecraft version, and LuckPerms has one for 26.2 and 26.3. Press Install.

2. 2

   Restart the server

   Plugins load on a start, so restart from the Console tab. LuckPerms then creates plugins/LuckPerms with config.yml and a database file, luckperms-h2-v2.mv.db, that holds every group and player.

3. 3

   Check that it runs

   Type lp info in the console. LuckPerms answers with its version and storage type. If it says nothing, the plugin did not load, and plugin not loading shows how to read why.

lp is short for luckperms; perm and perms work as well. In our console you type commands without the slash, in the game with one: lp editor in the console is /lp editor in chat.

Give yourself access to the LuckPerms commands

The console can always run every LuckPerms command. In the game, operators can too, because the setting commands-allow-op in its config.yml is on by default. A staff member who is not an operator gets nothing until you give it to them:

lp user RiverFox22 permission set luckperms.* true

The * at the end is a wildcard: every permission that starts with luckperms. That includes giving themselves any other permission, so this belongs to people you would also give the server password.

How LuckPerms groups and inheritance work

A permission is a line of text such as minecraft.command.kick. For each player LuckPerms knows one of three answers: true, false, or not set. Not set usually means no. You rarely give permissions to single players; you give them to a group and put players in it.

• Every player is in `default`. Nobody has to be added, and the name cannot be changed. You can give it a display name with lp group default setdisplayname Member.
• A group can have parents. A group inherits everything its parents have, and their parents' permissions as well. With admin above mod above helper, an admin holds all three sets.
• False beats inherited true when it sits closer to the player. Setting a node to false in the mod group takes it away from moderators, even if helper gives it.
• Weight settles conflicts between groups. When a player is in two groups that disagree, the group with the higher weight wins.

Use parent add for players. parent set throws away every other group they had, which is rarely what you meant.

Create staff ranks step by step

A common setup has three staff ranks on top of the ordinary players. Helpers can kick, moderators can also ban, admins can also change game modes. Run these lines in the console, one by one:

lp creategroup helper
lp creategroup mod
lp creategroup admin
lp group helper parent add default
lp group mod parent add helper
lp group admin parent add mod
lp group helper setweight 100
lp group mod setweight 200
lp group admin setweight 300
lp group helper permission set minecraft.command.kick true
lp group mod permission set minecraft.command.ban true
lp group mod permission set minecraft.command.pardon true
lp group admin permission set minecraft.command.gamemode true
lp user RiverFox22 parent add helper

Why helper gets default as a parent when every player is in default anyway: promoting along a track or using parent set can take default off a player. With the chain helper, mod, admin all leading back to default, a moderator keeps the ordinary player permissions whatever you do to their groups.

Weights go up in steps of 100, as the LuckPerms team advises, so a rank in between later is just setweight 150. Vanilla commands on Paper use minecraft.command. plus the command name. Plugin commands use the plugin's own names; ban, kick and mute and EssentialsX homes, warps and kits list the ones for those plugins.

How to find the permission for a command

A plugin's own documentation is the first place to look. When it is unclear or out of date, let LuckPerms watch what the server actually checks. Start recording for one player, have them run the command that fails, and stop:

lp verbose record RiverFox22
lp verbose upload

Between the two lines, RiverFox22 runs the command in the game. upload stops the recording and gives a link to a page that lists every permission the server checked for that player, with the answer it got. The check that did not come back true is the one the rank needs. lp verbose on RiverFox22 prints the checks straight into the console instead, which gets busy fast on a full server.

To see whether a player holds one specific node, and why, run lp user RiverFox22 permission check minecraft.command.ban.

How to add a rank prefix in chat

A prefix is the tag in front of a name in chat, such as [Mod] RiverFox22: hi. LuckPerms stores prefixes, but it does not change the chat itself. That takes a second plugin that reads the prefix from LuckPerms.

lp group helper meta setprefix 100 "[Helper] "
lp group mod meta setprefix 200 "[Mod] "
lp group admin meta setprefix 300 "[Admin] "

The quotes keep the space after the bracket. An admin inherits all three prefixes through the chain, and the one with the highest number is shown, so give each prefix the same number as its rank's weight. lp user RiverFox22 meta info lists every prefix a player has, ordered by weight.

The catalog only lists a plugin when it has a build for your exact version, so what you find under chat depends on the version your server runs. Colour codes in a prefix follow the chat plugin: LPC uses MiniMessage tags such as <red>, EssentialsX Chat uses codes such as &c.

Use the LuckPerms web editor instead of commands

For bigger changes, the web editor is quicker than typing. Run lp editor and LuckPerms sends a link that opens all your groups and players with special permissions in the browser. Type a node into the add box and the editor suggests permissions the server has seen since it started.

1. 1

   Open a session

   lp editor opens everything, lp group mod editor only the mod group. Click the link the console or chat shows.

2. 2

   Edit

   Add, change or remove lines. Parents, weights and prefixes are lines too: group.helper makes helper a parent, weight.200 sets the weight, prefix.200.[Mod] adds a prefix.

3. 3

   Save and apply

   Press Save. The editor shows a command that starts with lp applyedits. Nothing changes on your server until you run that command in the console, and LuckPerms then lists what it changed.

Promote along a track, or give a rank for 30 days

A track is a ladder of groups. With one for staff, promoting someone is a single command, and it takes the previous rank off as it adds the next one:

lp createtrack staff
lp track staff append helper
lp track staff append mod
lp track staff append admin
lp user RiverFox22 promote staff
lp user RiverFox22 demote staff

A player who is not on the track yet starts on its first group, helper. A track only decides the order of promotion. It does not make mod inherit helper; that is still the parent add from the ranks above.

Ranks and permissions can also run out by themselves. Give a supporter rank for a month, or flight for an event evening:

lp creategroup supporter
lp user RiverFox22 parent addtemp supporter 30d
lp user MossyOak permission settemp essentials.fly true 3h

Durations combine units, such as 1mo3d12h. Running addtemp again while the first one still runs fails by default; add accumulate after the duration to add the new time to what is left.

Give a permission in one world only

A permission can carry a condition, which LuckPerms calls a context. Put it at the end of the command. Builders who may use WorldEdit only in a creative world named build:

lp creategroup builder
lp group builder permission set worldedit.* true world=build

• `world=` uses the world's folder name, such as world, world_nether or the name you gave it in Multiverse.
• `gamemode=creative` applies only while the player is in that game mode.
• `dimension-type=the_nether` applies in every Nether-type world at once.

One line holds one world. For a second world, set the same permission again with the other name.

Back up your ranks and move them to another server

Before a big change, or when you move to another server, export everything to one file:

lp export ranks-backup
lp import ranks-backup.json.gz

The export lands in plugins/LuckPerms as ranks-backup.json.gz, and LuckPerms refuses to overwrite a file that already exists. On the other server, put the file in the same folder and import it. An import merges with the groups that are there; add --replace to wipe them first. The file works whatever storage the other server uses. Our server backups on the Backups tab include the whole plugins folder as well, and moving to a new host covers the rest of the server.

Several servers behind a Velocity network each keep their own ranks. Export the groups on one server and import them on the others, and repeat that after a change. LuckPerms can also keep one shared set when every server points storage-method in its config.yml at the same MySQL database.

Why a LuckPerms permission is not working