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:
- Requires OP to execute a command:
CommandPermission.OP
- Anyone can execute a command:
CommandPermission.NONE
- Requires a specific permission node to exeucte a command:
CommandPermission.fromString("my.permission")
Registering permissions to commands
To add a permission to a command, you can use any of the following constructors with a valid CommandAPI
instance:
register(String commandName, CommandPermission, LinkedHashMap<String, Argument>, CommandExecutor);
register(String commandName, CommandPermission, String[] aliases, LinkedHashMap<String, Argument>, CommandExecutor)
Example - /god command with permissions
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
//Register the /god command with the permission node "command.god"
CommandAPI.getInstance().register("god", CommandPermission.fromString("command.god"), arguments, (sender, args) -> {
if(sender instanceof Player) {
((Player) sender).setInvulnerable(true);
}
});
//Add a target argument to allow /god <target>
arguments.put("target", new EntitySelectorArgument(EntitySelector.ONE_PLAYER));
//Require "command.god" permission node to execute /god <target>
CommandAPI.getInstance().register("god", CommandPermission.fromString("command.god"), arguments, (sender, args) -> {
((Player) args[0]).setInvulnerable(true);
});
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
LinkedHashMap<String, ArgumentType> arguments = new LinkedHashMap<>();
//Register /kill command normally. Since no permissions are applied, anyone can run this command
CommandAPI.getInstance().register("kill", arguments, (sender, args) -> {
((Player) sender).setHealth(0);
});
//Adds the OP permission to the "target" argument. The sender requires OP to execute /kill <target>
arguments.put("target", new PlayerArgument().withPermission(CommandPermission.OP));
CommandAPI.getInstance().register("kill", arguments, (sender, args) -> {
((Player) args[0]).setHealth(0);
});
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 with
.withPermission()
as it has greater control over arguments.