Command registration

To register commands with the CommandAPI, we use the CommandAPICommand class. It follows a simple builder pattern to improve readability.

I think the easiest way to explain it is with an example:

//Create our command
new CommandAPICommand("broadcastmsg")
    .withArguments(new GreedyStringArgument("message")) // The arguments
    .withAliases("broadcast", "broadcastmessage")       // Command aliases
    .withPermission(CommandPermission.OP)               // Required permissions
    .executes((sender, args) -> {
        String message = (String) args[0];
        Bukkit.getServer().broadcastMessage(message);
    }).register();

• First, we create a new CommandAPICommand, with the name of the command that the sender must enter to run it.

• When, we create an argument to add to the command using withArguments. This is described in more detail in the section on arguments.

• In this example, we add an alias, "broadcast", to the command. This allows the sender to use either /broadcastmsg <message> or /broadcast <message>.

• By using withPermission, we require the sender to be an OP in order to run the command.

• We control what the command does using executes (this is described in more detail in the section on command executors).

• Finally, we register the command to the CommandAPI using register.

That's it! This simple snippet of code fully registers the command to the server. You don't need to supply a plugin instance, you don't have to create a custom class and you don't have to mess with the plugin.yml file.

Throughout this documentation, we will use the various different methods for command registration to give you an idea of when and where certain methods are more suitable than others.

CommandAPICommand methods

The CommandAPICommand has various methods, which are outlined below:

Setting the command name

new CommandAPICommand(String commandName)

This constructor creates a new instance of the CommandAPICommand object. This constructor requires the name of the command.

Setting command properties

CommandAPICommand withArguments(List<Argument> arguments)
CommandAPICommand withArguments(Argument... arguments)

The withArguments method is used to add arguments to your command. The arguments parameter is appended to the the list of arguments for the command.

CommandAPICommand withPermission(CommandPermission)
CommandAPICommand withPermission(String)

The withPermission method is used to assign a permission that is required to execute the command. (See the section on permissions for more info).

CommandAPICommand withRequirements(sender -> {})

The withRequirements method is used to assign additional constraints required to execute the command, similar to permissions. (See the section on requirements for more info).

CommandAPICommand withAliases(String... args)

The withAliases method is used to declare a list of aliases that can be used to run this command via. (See the section on aliases for more info).

CommandAPICommand withHelp(String shortDescription, fullDescription)
CommandAPICommand withShortDescription(String shortDescription)
CommandAPICommand withFullDescription(String fullDescription)

The withHelp method, along with its specific withShortDescription and withFullDescription methods are used to declare the help topic for this command which is displayed in the /help command. (See the section on help for more info).

CommandAPICommand withSubcommand(CommandAPICommand subcommand)

The withSubcommand method is used to declare a subcommand that leads on from the current command. (See the section on subcommands for more info).

Setting the command's executor

CommandAPICommand executes((sender, args) -> {})

Executes a command using the CommandSender object.

CommandAPICommand executesPlayer((player, args) -> {})

Executes a command only if the command sender is a Player.

CommandAPICommand executesEntity((entity, args) -> {})

Executes a command only if the command sender is an Entity.

CommandAPICommand executesCommandBlock((cmdblock, args) -> {})

Executes a command only if the command sender is a BlockCommandSender.

CommandAPICommand executesConsole((console, args) -> {})

Executes a command only if the command sender is a ConsoleCommandSender.

CommandAPICommand executesProxy((proxy, args) -> {})

Executes a command only if the command sender is a ProxiedCommandSender.

CommandAPICommand executesNative((proxy, args) -> {})

Executes a command regardless of what the command sender is, using the NativeProxyCommandSender. Read more about native proxied command senders here.

Developer's Note:

Sometimes, the Java compiler throws an error saying that a method is ambiguous for the type CommandAPICommand. This is due to a limitation in Java's type inference system and is not a fault of the CommandAPI. If we take the following code, used to spawn a pig:

new CommandAPICommand("spawnpigs")
     .executesPlayer((player, args) -> {
           for(int i = 0; i < 10; i++) {
               player.getWorld().spawnEntity(player.getLocation(), (EntityType) args[0]);
           }
     })
     .register();

The Java type inference system cannot determine what the type of the lambda (player, args) -> () is, therefore it produces the following compilation error:

The method executesPlayer(PlayerCommandExecutor) is ambiguous for the type CommandAPICommand

This can easily be resolved by declaring the specific type of the command sender and the arguments. For example:

new CommandAPICommand("spawnpigs")
     .executesPlayer((Player player, Object[] args) -> {
           for(int i = 0; i < 10; i++) {
               player.getWorld().spawnEntity(player.getLocation(), (EntityType) args[0]);
           }
     })
     .register();

Registering the command

void register()

Registers the command.

Command loading order

In order to register commands properly, commands must be registered before the server finishes loading. The CommandAPI will output a warning if you register a command after the server has loaded. This means that all command registration must occur during a plugin's onLoad() or onEnable() method. With the CommandAPI, depending on whether you use onLoad() or onEnable() to load your commands depends on whether your plugin is used with Minecraft's functions:

Command unregistration

The CommandAPI has support to unregister commands completely from Minecraft's command list. This includes Minecraft built in commands!

//Unregister the gamemode command from the server (by force)
CommandAPI.unregister("gamemode", true);

// Register our new /gamemode, with survival, creative, adventure and spectator
new CommandAPICommand("gamemode")
    .withArguments(new MultiLiteralArgument("survival", "creative", "adventure", "spectator"))
    .executes((sender, args) -> {
        //Implementation of our /gamemode command
    }).register();