Permissions

Permissions let you control which players are allowed to execute which commands. This is handled using the CommandPermission class, which has the following uses:

PermissionWhat it does
CommandPermission.OPRequires OP to execute the command
CommandPermission.NONEAnyone can execute the command
CommandPermission.fromString("my.permission")Requires a specific permission node to execute the command

In addition to the CommandPermission class, there are two different ways to assign permissions (compared to the simple CommandSender.hasPermission() method that is provided by Bukkit).

Adding permissions to commands

To add a permission to a command, you can use the withPermission(CommandPermission) method when declaring a command.

Example - /god command with permissions

Say we created a command /god that sets a player as being invulnerable. Since this is a pretty non-survival command, we want to restrict who can run this command. As such, we want our player to have the permission command.god in order to run this command. To do this, we simply use the withPermission(CommandPermission) method from our command builder:

// Register the /god command with the permission node "command.god"
new CommandAPICommand("god")
	.withPermission(CommandPermission.fromString("command.god"))
	.executesPlayer((player, args) -> {
		player.setInvulnerable(true);
	})
	.register();

Registering permissions to arguments

For further fine-tuning of permission management, the CommandAPI allows you to add permissions to individual arguments. This prevents the user from executing a command with a specific argument if they do not have a specific permission.

This is done by using the withPermission(CommandPermission) method at the end of an argument.

If a player does not have the required permission:

  • The argument hover text which suggests what the command is will not be shown
  • The player will receive an error if they try to type something in for that argument
  • Suggestions, such as a list of materials or players, will not be shown

Example - /kill command with argument permissions

For example, say we're registering a command /kill:

/kill          - Kills yourself
/kill <target> - Kills a target player

We first declare the command as normal. Nothing fancy is going on here:

// Register /kill command normally. Since no permissions are applied, anyone can run this command
new CommandAPICommand("kill")
	.executesPlayer((player, args) -> {
		player.setHealth(0);
	})
	.register();

Now we declare our command with arguments. We use a PlayerArgument and apply the permission to the argument. After that, we register our command as normal:

// Declare our arguments
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("target", new PlayerArgument().withPermission(CommandPermission.OP));

// Adds the OP permission to the "target" argument. The sender requires OP to execute /kill <target>
new CommandAPICommand("kill")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		((Player) args[0]).setHealth(0);
	})
	.register();

Developer's Note:

As you can see, there are multiple ways of applying permissions to commands with arguments. In the /god command shown above, the permission was applied to the whole command. In the /kill command shown above, the permission was applied to the argument.

There's not really much difference between the two methods, but I personally would use argument permissions as it has greater control over arguments.