Permissions

Permissions decide who may use which feature of your plugin. On this page you will name permissions properly, declare them in plugin.yml, check them in commands and listeners, give them out with LuckPerms, and build a tiered kit command and ranks with different limits.

What is a permission?

A permission is a piece of text, called a permission node, such as myplugin.heal. Every player either has that node or does not. Your plugin asks "does this player have myplugin.heal?" and acts on the answer. The server owner decides who has what, without touching your code.

Why not just check "is this player an operator"? Because operators can do everything, and servers have more roles than "operator" and "everyone": a moderator who may heal others but not stop the server, a donator rank with a bigger kit, a builder who may use /buildmode. Permissions let one plugin serve all of them.

Naming permission nodes

The convention is lowercase words separated by dots, from the general to the specific: plugin.feature.action. Starting with your plugin's name keeps your nodes from clashing with anyone else's.

Good names are lowercase, use dots (not spaces or underscores to separate levels) and describe the right, not the command. A node called myplugin.heal is better than myplugin.healcommand, because tomorrow a button might also heal.

Declaring permissions in plugin.yml

You do not have to declare a permission to check it. But declaring it is how you say who has it by default, and how permission plugins show your nodes in their lists. This is the plugin.yml of the demo plugin for this page:

1name: PermissionsDemo2version: '1.0.0'3main: com.example.permissionsdemo.PermissionsDemoPlugin4api-version: '26.3'5description: Tiered /kit permissions and numbered home limits.16permissions:7  permissionsdemo.use:28    description: Lets a player use the demo commands at all.39    default: true10  permissionsdemo.kit.starter:11    description: Lets a player take the starter kit.12    default: true13  permissionsdemo.kit.vip:14    description: Lets a player take the VIP kit.415    default: false16  permissionsdemo.kit.builder:17    description: Lets a player take the builder kit.518    default: op619  permissionsdemo.kit.*:20    description: Lets a player take every kit.21    default: op722    children:23      permissionsdemo.kit.starter: true24      permissionsdemo.kit.vip: true25      permissionsdemo.kit.builder: true826  permissionsdemo.homes.limit.3:27    description: Allows 3 homes. Declared only so operators can test the numbered limit.28    default: op29  permissionsdemo.homes.limit.10:30    description: Allows 10 homes. Declared only so operators can test the numbered limit.31    default: op932  permissionsdemo.admin:33    description: Everything this plugin offers.34    default: op35    children:36      permissionsdemo.use: true37      permissionsdemo.kit.*: true

The full list of plugin.yml settings is on plugin.yml explained. The plugin.yml Builder can write the permission block for you.

Checking a permission

The check itself is one method. Every player, and the console, has it: hasPermission("node") returns true or false.

1if (!player.hasPermission("permissionsdemo.kit.vip")) {2    player.sendRichMessage("<red>You need the VIP rank for this kit.");3    return;4}

Behind that one method, Paper follows these steps:

This is why a node declared default: true can still be denied: a permissions plugin can explicitly set it to false for a player or a rank, and an explicit value wins over a default. Two related methods exist for rare cases: isPermissionSet("node") tells you whether the player has an entry for that node at all (an entry can be false, so this is not the same as having the permission), and getEffectivePermissions() lists every node the player has, which you will use for numbered permissions below.

In Brigadier commands: requires

For a Brigadier command, put the check in requires. When the check fails the player cannot run the command, and it disappears from their tab completion. The demo's /kit command does this, and also filters its suggestions by permission:

22static LiteralCommandNode<CommandSourceStack> create() {23    return Commands.literal("kit")124        .requires(source -> source.getSender().hasPermission("permissionsdemo.use"))325        .executes(KitCommand::listKits)426        .then(Commands.argument("name", StringArgumentType.word())527            .suggests(KitCommand::suggestKits)28            .executes(KitCommand::giveKit))29        .build();30}

In simple commands: permission()

With a BasicCommand, override permission() and return the node. Paper checks it for you before execute runs, so your code never sees a player who is not allowed. The demo's /homelimit command works this way:

24@Override25public String permission() {126    return "permissionsdemo.use";27}

Inside event handlers: if and return

Events have no requires, so check by hand. You saw this on the events page, where players without a permission were stopped from mining diamond ore: check, cancel, tell the player.

What players see when they are denied

A command hidden with requires or permission() behaves, for that player, as if it did not exist: it does not show up in tab completion, and typing it usually gives Minecraft's normal error for a command it does not know. That is good for secrets and bad for explaining. When you want to tell the player what is missing, check inside the command instead and send a message, as the kit command does:

54private static int giveKit(CommandContext<CommandSourceStack> context) {55    if (!(context.getSource().getExecutor() instanceof Player player)) {56        context.getSource().getSender().sendRichMessage("<red>Only players can take a kit.");557        return 0;58    }59    String name = StringArgumentType.getString(context, "name");160    Optional<Kit> found = Kit.byId(name);261    if (found.isEmpty()) {62        player.sendRichMessage("<red>There is no kit called <name>.",63            Placeholder.unparsed("name", name));64        return 0;65    }66    Kit kit = found.get();367    if (!player.hasPermission(kit.permission())) {468        player.sendRichMessage("<red>You do not have access to the <kit> kit.",69            Placeholder.unparsed("kit", kit.id()));70        return 0;71    }672    player.give(kit.items());73    player.sendRichMessage("<green>You received the <kit> kit.",74        Placeholder.unparsed("kit", kit.id()));75    return Command.SINGLE_SUCCESS;76}

The kits themselves are an enum, and the permission node of each kit is built from its name, so adding a kit later is one new line:

18String permission() {119    return "permissionsdemo.kit." + id();20}

The green kits are the ones this player may take; the dark gray ones are locked. A player with the starter kit only gets the first one, and the denial appears when they try /kit vip anyway.

Operators and permission plugins

Out of the box, a Minecraft server knows two kinds of people: operators (ops) and everyone else. An op is made with /op Steve in the console, and has the nodes declared default: op, plus any undeclared ones. That is too crude for most servers. So almost every server installs a permissions plugin. The most popular is LuckPerms. It lets the owner create groups (such as default, vip, moderator), put nodes in groups and players in groups.

You write your plugin only against hasPermission. It works with any permissions plugin, because they all plug into the same system. Server owners then do the rest with commands such as these, typed in the console or in game by an operator:

Limits that depend on rank: numbered permissions

A common request: "regular players may set 1 home, VIPs 5, and the top rank 20". A yes/no permission cannot say that. The classic solution is numbered nodes: the server owner gives permissionsdemo.homes.limit.5 to the VIP group and permissionsdemo.homes.limit.20 to the top group, and the plugin reads the number out of the node name.

Paper has no method for "give me all permissions starting with this". So you loop over the player's getEffectivePermissions(), which lists everything the player has, and pick out the numbers:

13static int highest(Player player, String prefix, int fallback) {114    int best = fallback;215    for (PermissionAttachmentInfo info : player.getEffectivePermissions()) {316        if (!info.getValue() || !info.getPermission().startsWith(prefix)) {17            continue;18        }519        String suffix = info.getPermission().substring(prefix.length());620        if (suffix.isEmpty() || suffix.length() > MAX_DIGITS || !suffix.chars().allMatch(Character::isDigit)) {21            continue;22        }723        best = Math.max(best, Integer.parseInt(suffix));24    }25    return best;26}

13@Override14public void execute(CommandSourceStack source, String[] args) {15    if (!(source.getExecutor() instanceof Player player)) {16        source.getSender().sendRichMessage("<red>Only players have a home limit.");17        return;18    }119    int limit = NumberedPermissions.highest(player, LIMIT_PREFIX, DEFAULT_LIMIT);20    player.sendRichMessage("<gray>You can set up to <white><limit></white> homes.",21        Placeholder.unparsed("limit", String.valueOf(limit)));22}

The first line is for a player with no numbered node; the second after /lp user Steve permission set permissionsdemo.homes.limit.10 true (or, for an operator on the test server, thanks to the declared nodes). The same trick works for any rank-based number: cooldown lengths, maximum claims, number of warps. LuckPerms has a nicer tool, called meta, but reading it needs LuckPerms' own API; numbered nodes work with every permissions plugin.

The whole demo plugin

Download the permissions demo as a Gradle project and run it. As an operator, /kit shows all three kits unlocked, because the demo's wildcard is default: op. To see the locked state, put LuckPerms on the server and take the node away with /lp user YourName permission set permissionsdemo.kit.vip false.

Mistakes to avoid

• Forgetting to declare a default. A node you never declare is op by default. That is safe, but regular players will not understand why a feature does nothing. Declare default: true for features everybody should have.
• Typos in the node. "myplugin.heal" in plugin.yml and "myplugin.heel" in code are two unrelated permissions, and Java cannot warn you. Keep node names in constants, as the demo does for LIMIT_PREFIX.
• Checking isOp() instead of a permission. It locks out every moderator who is not an operator. Check a permission and let the owner decide.
• Checking the wildcard in code. Do not write hasPermission("myplugin.*"). Check the specific node and let the wildcard grant it.
• Silent denial. A command that does nothing for players without a permission feels broken. Tell them what is missing, unless you want the command hidden.
• Assuming the console is a player. The console has every permission, but it is not a Player. A command that casts the sender to Player must check first.
• Thinking default: op means "no wildcard needed". Operators only get the nodes you declared (or never declared). A node declared default: false is denied even to operators, unless something grants it on purpose: a permissions plugin, or a parent node that lists it as a child, like the demo's permissionsdemo.kit.*.

13static int lowest(Player player, String prefix, int fallback) {14    int best = fallback;15    for (PermissionAttachmentInfo info : player.getEffectivePermissions()) {16        if (!info.getValue() || !info.getPermission().startsWith(prefix)) {17            continue;18        }19        String suffix = info.getPermission().substring(prefix.length());20        if (suffix.isEmpty() || suffix.length() > MAX_DIGITS || !suffix.chars().allMatch(Character::isDigit)) {21            continue;22        }123        best = Math.min(best, Integer.parseInt(suffix));24    }25    return best;26}

21@Override22public void execute(CommandSourceStack source, String[] args) {23    if (!(source.getExecutor() instanceof Player player)) {24        source.getSender().sendRichMessage("<red>Only players can teleport.");25        return;26    }127    int warmupSeconds = NumberedPermissions.lowest(player, WARMUP_PREFIX, DEFAULT_WARMUP_SECONDS);28    player.sendRichMessage("<gray>Teleporting to spawn in <white><seconds>s</white>...",29        Placeholder.unparsed("seconds", String.valueOf(warmupSeconds)));30 231    plugin.getServer().getScheduler().runTaskLater(plugin, () -> {32        if (player.isOnline()) {333            player.teleport(player.getWorld().getSpawnLocation());34        }35    }, warmupSeconds * TICKS_PER_SECOND);36}

Recap

• A permission is a dotted text node such as plugin.feature.action. Players have it or not; the server owner decides who.
• Declare nodes in plugin.yml with a description, a default (true, false, op, not op) and optional children. Wildcards are nodes with children.
• Check with hasPermission, with requires in Brigadier commands and with permission() in BasicCommand.
• A value set by a permissions plugin always beats the default from plugin.yml.
• Never rely on isOp(); check permissions, and tell players what they are missing.
• LuckPerms hands out nodes with /lp user ... permission set and groups with /lp group ....
• Numbered nodes (homes.limit.5) give ranks different limits: loop over getEffectivePermissions() and read the number.

Quick quiz

Next steps

• Patterns: cooldowns, toggles and player state: combine permissions with cooldowns so each rank waits a different time.
• Commands, part 2: Brigadier command trees: more on requires and suggestions.
• Project: Homes: use numbered limits in a complete plugin.
• The LuckPerms wiki: everything you can do on the server owner's side.