Annotations

This page outlines in detail the list of all annotations that the CommandAPI's annotation-based command system includes.

Annotations that go on classes

@Command("commandName")

The @Command annotation is used to declare a command. The parameter is the name of the command that will be registered.

@Command("warp")    
public class WarpCommand {

@Alias({...})

The @Alias annotation is used to declare a list of aliases for a command. The parameter is a list of aliases which can be used for the command.

@Command("teleport")    
@Alias({"tp", "tele"})
public class TeleportCommand {

@Permission("permissionNode")

The @Permission annotation is used to add a permission node to a command. Users that want to run this command must have this permission. The parameter is the permission node required to run the command.

@Command("teleport")    
@Permission("myplugin.tp")
class TeleportCommand {

@NeedsOp

The @NeedsOp annotation is used to indicate that a command needs to have operator privileges to run it. This annotation has no parameters.

@Command("teleport")    
@NeedsOp
class TeleportCommand {

@Help("Full description")

The @Help annotation is used to add a help topic to a command. This annotation can take two forms:

A simple form which just uses a string which is used as the full description for a command:

@Command("teleport")
@Help("Teleports yourself to another location")
class TeleportCommand {

A form with two parameters value and shortDescription, to provide the full description (value) and short description (shortDescription) content for a command:

@Command("teleport")    
@Help(value = "Teleports yourself to another location", shortDescription = "TP to a location")
class TeleportCommand {

Annotations that go on methods

To use annotations on methods, methods must be static.

@Default

The @Default annotation indicates that the method is not a subcommand. This acts in a similar way to regular Bukkit commands. Commands with the @Default annotation can be used to run the main code when the command named with the @Command annotation is stated, such as the following:

@Default
public static void warp(CommandSender sender) {
    sender.sendMessage("--- Warp help ---");
    sender.sendMessage("/warp - Show this help");
    sender.sendMessage("/warp <warp> - Teleport to <warp>");
    sender.sendMessage("/warp create <warpname> - Creates a warp at your current location");
}

The @Default annotation does not mean that the command can't have arguments! Arguments can still be used and declared as shown:

@Default
public static void warp(Player player, @AStringArgument String warpName) {
    player.teleport(warps.get(warpName));
}

@Subcommand

The @Subcommand simply tells the CommandAPI that the declared method is a subcommand. This acts in a similar way to the regular CommandAPI's .withSubcommand() method. The subcommand annotation can take in a single string which is the name of the subcommand:

@Subcommand("create")
@Permission("warps.create")
public static void createWarp(Player player, @AStringArgument String warpName) {
    warps.put(warpName, player.getLocation());
}

Or, it can take in a list of strings which represent the aliases that can also be used for the declared subcommand:

@Subcommand({"teleport", "tp"})
public static void teleport(Player player, @APlayerArgument OfflinePlayer target) {
    if(target.isOnline() && target instanceof Player onlineTarget) {
        player.teleport(onlineTarget);
    }
}

@Permission

The @Permission annotation can also be used on methods to indicate that a permission is required to execute a command.

@Subcommand("create")
@Permission("warps.create")
public static void createWarp(Player player, @AStringArgument String warpName) {
    warps.put(warpName, player.getLocation());
}

@NeedsOp

The @NeedsOp annotation can also be used on methods to indicate that the user must be an operator to run the command.

Annotations that go on parameters

The annotations for arguments are really simple, there's just two things you need to know:

• To use an annotation argument, just add the letter A (for 'annotation') at the beginning of it! For example:

  \begin{align} \texttt{StringArgument}&\xrightarrow{A}\texttt{@AStringArgument}\\ \texttt{PlayerArgument}&\xrightarrow{A}\texttt{@APlayerArgument}\\ \texttt{AdvancementArgument}&\xrightarrow{A}\texttt{@AAdvancementArgument}\\ &\hspace{0.75em}\vdots \end{align}

  For example, we use @AStringArgument to indicate that this command takes a StringArgument as its first parameter:

@Default
public static void warp(Player player, @AStringArgument String warpName) {
    player.teleport(warps.get(warpName));
}

• The name of the argument (referred to as "nodeName" in the normal CommandAPI system) is the name of the variable assigned to the parameter. In the above code, this means that the name of the argument is warpName.

Special argument annotations

Certain argument annotations have extra parameters that can be supplied to provide additional customization:

Numerical arguments

The following numerical arguments can take both a min and max value. Both of these are completely optional. This indicates the range of values (inclusive) that is valid for this argument. For example:

@Default
public static void command(CommandSender sender, 
    @ADoubleArgument(min = 0.0, max = 10.0) double someDouble,
    @AFloatArgument(min = 5.0f, max = 10.0f) float someFloat,
    @AIntegerArgument(max = 100) int someInt,
    @ALongArgument(min = -10) long someLong
) {
    // Command implementation here
}

Literal arguments

Both the LiteralArgument and MultiLiteralArgument can be used. When these are used, the name of the variable assigned to the parameter is ignored and not used as the argument's name.

For the @ALiteralArgument annotation, the parameter is the literal to be used for the command. For the @AMultiLiteralArgument, the parameter can be an array of multiple literals to use:

@Default
public static void command(CommandSender sender, 
    @ALiteralArgument("myliteral") String literal,
    @AMultiLiteralArgument({"literal", "anotherliteral"}) String multipleLiterals
) {
    // Command implementation here
}

Other arguments

The LocationArgument, Location2DArgument, EntitySelectorArgument and ScoreHolderArgument can all take an extra parameter in their constructors. As a result, the annotation-equivalent of these arguments also allow you to provide the parameter in the annotation:

@Default
public static void command(CommandSender sender, 
    @ALocationArgument(LocationType.BLOCK_POSITION) Location location,
    @ALocation2DArgument(LocationType.PRECISE_POSITION) Location location2d,
    @AEntitySelectorArgument(EntitySelector.MANY_ENTITIES) Collection<Entity> entities,
    @AScoreHolderArgument(ScoreHolderType.MULTIPLE) Collection<String> scoreHolders
) {
    // Command implementation here
}