Documentation for v1.4

An API to use the new command UI introduced in Minecraft 1.13

Installation (For server owners)

• Download the v1.4 CommandAPI.jar from the download page here
• Place the CommandAPI.jar file in your server's /plugins/ folder
• That's it!

Using the CommandAPI in your projects (For developers)

• Download the v1.4 CommandAPI.jar from the download page here
• Add the CommandAPI.jar file to your project/environment's build path
• Add the plugin as a dependent in the plugin.yml (depend: [CommandAPI])

Basic usage (For developers)

• Generate a LinkedHashMap<String, Argument> to store your arguments for your command. The insertion order IS IMPORTANT.

  LinkedHashMap<String, Argument> args = new LinkedHashMap<>();
  args.put("time", new IntegerArgument());
  

• Register your command using the CommandAPI instance

  CommandAPI.getInstance().register("mycommand", arguments, (sender, args) -> {
      if(sender instanceof Player) {
       	Player player = (Player) sender;
          player.getWorld().setTime((int) args[0]);
      }
  });
  

Command registration

Arguments

Arguments are found in the io.github.jorelali.commandapi.api.arguments package.

Argument Casting

To access arguments, they are casted in the order of declaration.

LinkedHashMap<String, ArgumentType> arguments = new LinkedHashMap<>();
arguments.put("arg0", new StringArgument());
arguments.put("arg1", new PotionEffectArgument());
arguments.put("arg2", new LocationArgument());

commandRegister.register("cmd", arguments, (sender, args) -> {
	String stringArg = (String) args[0];
	PotionEffectType potionArg = (PotionEffectType) args[1];
	Location locationArg = (Location) args[2];
});

Ranged Arguments

Numerical arguments (int, float and double) can have ranged values.

Entity Selector Arguments

Target selectors are implemented using the EntitySelectorArgument class. This allows you to select specific entities based on certain attributes.

The EntitySelectorArgument class requires an EntitySelector argument to determine what type of data to return. There are 4 types of entity selections which are available:

• EntitySelector.ONE_ENTITY - A single entity, which returns a Entity object.
• EntitySelector.MANY_ENTITIES - A collection of many entities, which returns a Collection<Entity> object.
• EntitySelector.ONE_PLAYER - A single player, which returns a Player object.
• EntitySelector.MANY_PLAYERS - A collection of players, which returns a Collection<Player> object.

The return type is the type to be cast when retrieved from the Object[] args in the command declaration.

//LinkedHashMap to store arguments for the command
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();

//Using a collective entity selector to select multiple entities
arguments.put("entities", new EntitySelectorArgument(EntitySelector.MANY_ENTITIES));

CommandAPI.getInstance().register("kill", arguments, (sender, args) -> {
    
	//Parse the argument as a collection of entities (as stated above in the documentation)
	Collection<Entity> entities = (Collection<Entity>) args[0];
	sender.sendMessage("killed " + entities.size() + "entities");
	for(Entity e : entity)
		e.remove();
});

You can view an example of using the EntitySelectorArgument here

Literal Arguments

Introduced in v1.3 is the LiteralArgument class. This allows you to basically create "lists" in your commands, or specific commands where a desired text option is required.

LiteralArgument(String literal) takes a String input which is the text which the argument represents.

For example, take the /gamemode command. It takes an argument which is the game mode, which is picked from a list: adventure, creative, spectator or survival.

Literal arguments are "technically" not arguments, however they are declared as you would a regular argument.

//Used as a regular argument, in your LinkedHashMap
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("gamemodearg", new LiteralArgument("adventure"));

CommandAPI.getInstance().register("gamemode", arguments, (sender, args) -> {
    if(sender instanceof Player) {
        Player player = (Player) sender;
        player.setGameMode(GameMode.ADVENTURE);
    }
});

Since Literal arguments are not "technically" arguments, LITERAL ARGUMENTS ARE NOT DEFINED IN args. So, with the example above, args is an empty array.

To use lists, you can iterate over a list/map to generate multiple commands at once:

//Create a map of gamemode names to their respective objects
HashMap<String, GameMode> gamemodes = new HashMap<>();
gamemodes.put("adventure", GameMode.ADVENTURE);
gamemodes.put("creative", GameMode.CREATIVE);
gamemodes.put("spectator", GameMode.SPECTATOR);
gamemodes.put("survival", GameMode.SURVIVAL);

//Iterate over the map
for(String key : gamemodes.keySet()) {
    
    //Create our arguments as usual, using the LiteralArgument for the name of the gamemode
	LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
	arguments.put(key, new LiteralArgument(key));
    
    //Register the command as usual
	CommandAPI.getInstance().register("gamemode", arguments, (sender, args) -> {
	    if(sender instanceof Player) {
	        Player player = (Player) sender;
            
            //Retrieve the object from the map via the key and NOT the args[]
	        player.setGameMode(gamemodes.get(key));
	    }
	});
}

Be aware that large nested lists are HIGHLY discouraged, as described in this comment

Failing to define a value for a literal (either by using null or an empty String) will result in a BadLiteralException

Strings, Greedy Strings and Text arguments

StringArgument

The StringArgument is used to represent a single word. These words can only contain alphanumeric characters (A-Z, a-z and 0-9), and the underscore character.

Accepted StringArgument values:

/mycommand hello
/mycommand 123
/mycommand hello123

Rejected StringArgument values:

/mycommand hello@gmail.com
/mycommand yesn't

Potential Uses

• Entering Strings to identify offline players

TextArgument

The TextArgument acts similar to any String in Java. These can be single words, like to the StringArgument, or have additional values such as special characters if quoted. To type quotation marks, you can use \" (as similar to Java) to escape these special characters.

Accepted TextArgument values:

/mycommand hello
/mycommand "hello world!"
/mycommand "hello@gmail.com"
/mycommand "this has \" <<-- speech marks! "

Rejected TextArgument values:

/mycommand hello world
/mycommand 私
/mycommand "speech marks: ""

Potential Uses

• A command to edit the contents on a sign
• Any command that may require multiple text arguments

GreedyStringArgument

The GreedyStringArgument takes the TextArgument a step further. Any characters and symbols are allowed and quotation marks are not required. However, the GreedyStringArgument uses the entirety of the argument array from its position.

For example, say we have a command /msg <target> <message>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("target", new PlayerArgument());
arguments.put("message", new GreedyStringArgument());
CommandAPI.getInstance().register("msg", arguments, (sender, args) -> {
	((Player) args[0]).sendMessage((String) args[1]);
});

Any text entered after the <target> argument would be sent to the player. For example, the command:

/msg Skepter hello how are you? I'm doing great! Last week I sent an email to blah@mail.com

would send Skepter a message saying hello how are you? I'm doing great! Last week I sent an email to blah@mail.com.

Due to the fact that the GreedyStringArgument has no terminator (it has infinite length), a GreedyStringArgument must be defined at the end of the LinkedHashMap (otherwise the CommandAPI will throw a GreedyStringException)

For example, if the syntax was/msg <message> <target>, it would not be able to determine where the message ends and the <target> argument begins.

Potential Uses

• A messaging/whisper command
• A mailing command
• Any command involving lots of text, such as a book writing command*
• Any command which involves an unreasonable/unknown amount of arguments
• Any command where you want to parse arguments similar to how regular Bukkit would

*New feature potentially coming soon!

Multiple command arguments

Sometimes, you'll want one command to have different arguments. For example:

• /walkspeed <speed> to change your walk speed
• /walkspeed <speed> <target> to change the walk speed of another player

To accommodate for this, just register the command twice, each with different arguments:

LinkedHashMap<String, ArgumentType> arguments = new LinkedHashMap<>();
arguments.put("speed", new FloatArgument(0.0, 1.0)); //args[0]

//Register the command
CommandAPI.getInstance().register("walkspeed", arguments, (sender, args) -> {
	float speed = (float) args[0]; //speed argument
	//Code here to change the player's speed
});

//We can still use the arguments variable to add new arguments as the first command has already been registered
arguments.put("target", new PlayerArgument()); //args[1]

//Register the command
CommandAPI.getInstance().register("walkspeed", arguments, (sender, args) -> {
	float speed = (float) args[0]; //speed argument
	Player target = (Player) args[1]; //target player
	//Code here to change the target's speed
});

Permissions

Permissions are created using the CommandPermission class.

CommandExecutor

The CommandExecutor class (not to be confused with Bukkit's CommandExecutor class) is a functional interface which executes when the command is performed. It consists of two parameters, CommandSender sender and Object[] args.

CommandExecutor format (Java 8 lambda)

CommandExecutor executor = (sender, args) -> {
	//Code here
};

CommandExecutor format (Java 7)

CommandExecutor executor = new CommandExecutor() {
	@Override
	public void run(CommandSender sender, Object[] args) {
		//Code here
	}
};

Command name checking and permission checks aren't required as these are checked when the player types the command.

ProxiedCommandSenders

As of v1.3, the CommandAPI now has some support for the /execute command, which is implemented using the ProxiedCommandSender

When using a command generated by the CommandAPI, it will modify the CommandSender when run depending of the CommandSender was changed in execution.

For example:

• Running /mycommand as a player in game will return a regular CommandSender, which can be cast to a Player object. (Player player = (Player) sender)
• Running /execute as @e[type=cow] run mycommand as a player in game will return a ProxiedCommandSender, with callee as a cow and caller as a player.

Examples examples examples!

Give Command

/give <item> <amount>
/give <target> <item> <amount>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("item", new ItemStackArgument()); //args[0]
arguments.put("amount", new IntegerArgument(1, 64)); //args[1]

CommandAPI.getInstance().register("give", new CommandPermission(PermissionNode.OP), new String[] {"i", "item"}, arguments, (sender, args) -> {
	if(sender instanceof Player) {
		Player player = (Player) sender;
		ItemStack is = (ItemStack) args[0];
		is.setAmount((int) args[1]);
		player.getInventory().addItem(is);
	}
});

arguments = new LinkedHashMap<>();
arguments.put("target", new PlayerArgument()); //args0[0]
arguments.put("item", new ItemStackArgument()); //args[1]
arguments.put("amount", new IntegerArgument(1, 64)); //args[2]

CommandAPI.getInstance().register("give", new CommandPermission(PermissionNode.OP), new String[] {"i", "item"}, arguments, (sender, args) -> {
	Player target = (Player) args[0];
	ItemStack is = (ItemStack) args[1];
	is.setAmount((int) args[2]);
	target.getInventory().addItem(is);
});

Enchant Command

/enchant <level> <force enchant>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("level", new IntegerArgument()); //args[0]
arguments.put("force enchant", new BooleanArgument()); //args[1]

CommandAPI.getInstance().register("enchant", new CommandPermission("plugin.enchant"), arguments, (sender, args) -> {
	if(sender instanceof Player) {
		Player player = (Player) sender;
		if((boolean) args[1]) {
			player.getInventory().getItemInMainHand().addUnsafeEnchantment((Enchantment) args[1], (int) args[0]);
		} else {
			player.getInventory().getItemInMainHand().addEnchantment((Enchantment) args[1], (int) args[0]);
		}
	}
});

SetBlock Command

/setblock <location> <type>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("location", new LocationArgument()); //args[0]
arguments.put("type", new ItemStackArgument()); //args[1]

CommandAPI.getInstance().register("setblock", arguments, (sender, args) -> {
	if(sender instanceof Player) {
		Player player = (Player) sender;
		Material type = ((ItemStack) args[1]).getType();
		player.getWorld().getBlockAt((Location) args[0]).setType(type);
	}
});

Message Command

/message <target> <message>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("target", new PlayerArgument()); //args[0]
arguments.put("message", new TextArgument()); //args[1]

CommandAPI.getInstance().register("message", arguments, (sender, args) -> {
	Player target = (Player) args[0];
	target.sendMessage((String) args[1]);
});

FAQ

Why does the PlayerArgument only produce one player when @a is an option?

A: Simplicity. The old command system which involved using Bukkit.getPlayer() and parsing a username only produces one player. To make it as simple to use, this was the best option. Alternatively, you can use the new EntitySelectorArgument to select multiple players.

What about the other argument types?

Q: There's loads more argument types, including NBT tags, rotational position (i.e. pitch/yaw), inventory slots, scoreboards.... why aren't they implemented?

A: Again, for simplicity. NBT tags would require lots of NMS code to convert (and isn't majorly supported by Bukkit on its own). Rotational position isn't a majorly important argument - floating point arguments work fine. I don't really know much about how scoreboards work (if someone wants to help, I'm open to collaboration)