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.get("message");
Bukkit.getServer().broadcastMessage(message);
})
.register();
// Create our command
CommandAPICommand("broadcastmsg")
.withArguments(GreedyStringArgument("message")) // The arguments
.withAliases("broadcast", "broadcastmessage") // Command aliases
.withPermission(CommandPermission.OP) // Required permissions
.executes(CommandExecutor { sender, args ->
val message = args["message"] as String
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. -
Then, 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 withHelp(HelpTopic helpTopic)
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) -> {})
CommandAPICommand executes(info -> {})
Executes a command using the CommandSender
object.
CommandAPICommand executesPlayer((player, args) -> {})
CommandAPICommand executesPlayer(info -> {})
Executes a command only if the command sender is a Player
.
CommandAPICommand executesEntity((entity, args) -> {})
CommandAPICommand executesEntity(info -> {})
Executes a command only if the command sender is an Entity
.
CommandAPICommand executesCommandBlock((cmdblock, args) -> {})
CommandAPICommand executesCommandBlock(info -> {})
Executes a command only if the command sender is a BlockCommandSender
.
CommandAPICommand executesConsole((console, args) -> {})
CommandAPICommand executesConsole(info -> {})
Executes a command only if the command sender is a ConsoleCommandSender
.
CommandAPICommand executesProxy((proxy, args) -> {})
CommandAPICommand executesProxy(info -> {})
Executes a command only if the command sender is a ProxiedCommandSender
.
CommandAPICommand executesNative((proxy, args) -> {})
CommandAPICommand executesNative(info -> {})
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.get(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, CommandArguments args) -> { for(int i = 0; i < 10; i++) { player.getWorld().spawnEntity(player.getLocation(), (EntityType) args.get(0)); } }) .register();
Registering the command
void register()
Registers the command with the default minecraft
namespace. If you are shading you can set the default namespace using CommandAPIConfig#setNamespace(String)
or CommandAPIBukkitConfig#usePluginNamespace()
.
void register(String namespace)
Registers the command with a custom provided namespace.
void register(JavaPlugin plugin)
Registers the command with the provided plugin's name.
Command loading order
It is recommended to register commands in either the 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:
When to load | What to do |
---|---|
onLoad() method | Register commands to be used in Minecraft functions (see the Function section for more info) |
onEnable() method | Register regular commands |
The CommandAPI does support registering commands outside of these methods while the server is running. Commands registered after the server is done loading should work the same as commands registered in onEnable
.