Why permissions instead of op
Operator status is all or nothing. A permissions plugin lets you give a moderator kick and ban without also handing over gamemode, or let every player use a home command without making anyone an operator.
On a Paper server, most commands and features are tied to a permission, a dotted string such as minecraft.command.ban for the vanilla ban command. A permission can be true, false, or not set at all, which usually acts like false. Plugins choose who gets each permission when nothing else decides: Paper's plugin.yml reference says a permission's default falls back to op unless the plugin says otherwise. That is why operators can use new plugin commands straight away and everyone else cannot, and it is the gap LuckPerms fills.
LuckPerms builds on three ideas. Groups hold permissions so you do not set them player by player. Players inherit everything from the groups they are in, which LuckPerms calls parents. And groups can inherit from other groups, so an admin group can include everything a moderator has.
- Permission: a string like minecraft.command.ban, set to true or false
- Group: a named set of permissions
- Parent: a group a player or another group inherits from
- default: the group every player is in from the start
Install LuckPerms on Paper
Download the Bukkit version of LuckPerms from its downloads page; it is the one for Paper and Spigot. The server should have started at least once so its folders exist. Upload the jar into the plugins folder, delete any older LuckPerms jar if there is one, and fully restart the server, then watch the console for LuckPerms enabling. The general steps are in how to install plugins on a Paper server.
LuckPerms must be the only permissions plugin on the server. Its FAQ puts this first: with a second permissions manager installed, LuckPerms will not be used for permission checks. The one exception is a migration from an older plugin, after which you remove the old one.
By default LuckPerms keeps its data in a single H2 database file, luckperms-h2-v2.mv.db, inside plugins/LuckPerms, and its wiki says not to delete it. Because it is a file in the server folder, a normal server backup includes it. A MySQL database is only needed if you run several servers that should share permissions.
- Bukkit jar from luckperms.net, into plugins
- Full restart, not a reload
- Remove any other permissions plugin
- Data: plugins/LuckPerms/luckperms-h2-v2.mv.db
Give yourself access from the console
When LuckPerms is first installed, nobody has permission to use its commands. Its wiki starts every setup the same way: open the server console and give your own account the luckperms.* permission. The asterisk is a wildcard, so this covers every LuckPerms permission. In the console you type commands without the leading slash.
On Bukkit-based servers, operators can also use LuckPerms commands by default, through the commands-allow-op option in its config.yml. Setting your own permission is still the clean start, because it keeps working if you later turn that option off or stop being an operator.
If typing lp only shows the plugin version, you do not have permission for any command yet. Run the console command above and try again.
- lp user <your name> permission set luckperms.* true
- lp user <your name> info, to check what you have
- lp listgroups, to see the groups that exist
Create groups and give them permissions
Create a group with lp creategroup followed by its name, then add permissions to it with lp group <group> permission set <permission> true. Setting a permission to false denies it outright, and permission unset removes the entry again.
Inheritance saves most of the typing. lp group admin parent add mod makes admin inherit everything mod has, and if mod inherits from default, admin gets default's permissions too, because inheritance is recursive. Build the ladder once and each rank only needs its own extras.
Leave the default group's name alone. LuckPerms deliberately does not let you change which group is the default, and its wiki explains why: renaming it later splits your players between the old and new group. If you want players to see a different name, use lp group default setdisplayname. If you prefer a member group, create it and make default inherit from it with lp group default parent add member.
- lp creategroup mod
- lp group mod permission set minecraft.command.ban true
- lp creategroup admin, then lp group admin parent add mod
- lp group mod parent add default
- lp group default setdisplayname Member
Add players to groups, and remove them
A player joins a group through the parent command. lp user <player> parent add <group> adds the group alongside the ones they already have. lp user <player> parent set <group> clears their existing groups first and sets this one as their only group, which is the right tool for a straight change of rank. lp user <player> parent remove <group> takes them out.
For a rank that should run out, such as a trial moderator or an event reward, use parent addtemp with a duration. LuckPerms accepts periods like 1mo3d13h45m or a unix timestamp, and removes the group by itself when the time is up.
After any change, lp user <player> info shows the player's groups and permissions, so you can confirm the result before they ask.
- lp user Alex parent add mod: add a rank
- lp user Alex parent set admin: replace their groups with one
- lp user Alex parent remove mod: take a rank away
- lp user Alex parent addtemp vip 30d: a rank that expires
Find the permission a command needs, or use the web editor
The permission names come from the plugin, not from LuckPerms. Start with the plugin's own documentation. When that is missing or unclear, LuckPerms can show you live: lp verbose record <player> starts recording permission checks for that player, the player runs the command, and lp verbose upload stops the recording and gives you a link to a web viewer listing every permission that was checked. Tab completion in the lp commands also suggests permissions LuckPerms has seen since the server started.
If typing commands is not for you, lp editor opens a web editor for all groups and users. Make your changes in the browser and save. The editor gives you a command to run in the console or in game, and that applies the changes. lp group <group> editor opens a single group.
As your plugin list grows along with your ranks, the Minecraft RAM calculator helps you size the server for it.
- lp verbose record <player>, then lp verbose upload
- lp editor: edit everything in the browser
- Run the command the editor gives you to apply it
Prefixes, testing and common problems
LuckPerms stores prefixes and suffixes but does not draw them in chat. Set one with lp group admin meta setprefix followed by the text, in quotes if it has spaces, then install Vault and a chat formatting plugin to display it. Its FAQ is explicit that on a Bukkit-based server Vault is required as well.
Test with an account that is not an operator. Because plugin permissions default to op, an operator can use a command whether or not your groups are right. Run deop on your test account, or ask a regular player, before you decide a rank works.
If a permission seems ignored, check for a second permissions plugin first, then check the exact permission with verbose. If you want a rank to grant operator status automatically, the auto-op option in LuckPerms' config gives op to anyone with the luckperms.autoop permission, and its wiki recommends that over handing out a single * permission. For a feature no plugin offers, you can commission a custom plugin that plugs into the same permission system.
- Prefix: lp group admin meta setprefix "[Admin] "
- Prefix not showing: install Vault and a chat plugin
- Test ranks on a non-op account
- Only one permissions plugin on the server