Introduction

Welcome to the documentation for the CommandAPI. The CommandAPI lets you create vanilla Minecraft commands which utilize the new command features which were implemented in Minecraft 1.13, including but not limited to:

• Having commands compatible with the vanilla /execute command
• Having commands which can be run using Minecraft functions
• Having better auto-completion and suggestions
• Having command type checks before execution (e.g. ensuring a number is within a certain range)

How the CommandAPI works

Developer's Note:

This is a pretty important section, I would recommend reading before implementing the CommandAPI in your own projects. This section tells you about setup which is not stated anywhere else in the documentation. Think of it as the "knowledge you should know before using this API".

The CommandAPI does not follow the "standard" method of registering commands. In other words, commands which are registered with the CommandAPI will be registered as pure vanilla Minecraft commands as opposed to Bukkit or Spigot commands. This means that the following implications exist:

• Commands do not need to be declared in the plugin.yml file
• Commands are not "linked" to a certain plugin. In other words, you cannot look up which commands are registered by which plugin.

How this documentation works

This documentation is split into the major sections that build up the CommandAPI. It's been designed in such a way that it should be easy to find exactly what you want to help you get started with the CommandAPI, and how to make effective use of it. Each step of the way, the documentation will include examples which showcase how to use the CommandAPI.

You can use the side bar on the left to access the various sections of the documentation and can change the theme to your liking using the paintbrush icon in the top left corner.

Using the search icon in the top left corner, you can search for anything in this entire documentation. For example, typing "Example" will show a list of examples which are included throughout the documentation.

Documentation changelog

Here's the list of changes to the documentation between each update. You can view the current documentation version at the top of this page.

Documentation changes 4.2 \(\rightarrow\) 4.3:

• Improve the documentation for 2. Configuration for server owners by using simple YAML lists (using the - symbol) and update the command conversion syntax for all commands using the ~ syntax
• Adds the command sender priority to 6.1. Normal command executors
• Adds new method and example for converting specific commands internally in 13. Command conversion
• Adds two sneaky little buttons in the main title toolbar at the top of the page

Documentation changes 4.1 \(\rightarrow\) 4.2:

• Adds a warning about using redirected commands for suggestions that depend on previous arguments in 7.1. Argument suggestions
• Adds a new section 6.3. Native commandsenders
• Update documentation for 6.1. Normal command executors to include the .executesNative() method for native command senders

Documentation changes 4.0 \(\rightarrow\) 4.1:

• Adds a new section 7.3. Argument suggestions with tooltips
• Adds documentation for the MultiLiteralArgument in section 8.11.2. Multi literal arguments
• Adds a new section 4. Shading the CommandAPI into your plugins
• Update documentation for 14. Brigadier + CommandAPI with new (overloaded) function argBuildOf
• Update Afterword

Documentation changes 3.4 \(\rightarrow\) 4.0:

• Update the maven and gradle documentation to state that it is provided and compileOnly
• The project has been renamed from the "1.13 Command API" to simply the "CommandAPI". This has changed a few things, such as various links. See the section Upgrading guide to view the relevant changes with regards to maven.
• Updated 3. Setting up your development environment to include new Maven repository links
• Fixed stronkage with Java versions - there's now no random warning boxes about incompatibility with Java 12!
• Arguments now include pictures that showcase how they work!
• Reorganised the sections - arguments is now split up into two sections: 6. Arguments (in general) and 7. Argument types
• Adds documentation for 6.2. Safe argument suggestions
• Adds documentation for 7.8.3. BlockState arguments
• Adds documentation for new arguments:
  • UUIDArgument: 7.8.14. UUID arguments
  • BlockPredicateArgument: 7.9.1. Block predicate arguments
  • ItemStackPredicateArgument: 7.9.2. ItemStack predicate arguments
• Adds page Incompatible version information outlining what parts of the CommandAPI are incompatible with what versions of Minecraft
• Adds getCommands() documentation to the 8.2. The FunctionWrapper class page
• Adds page 13. Brigadier + CommandAPI which shows how the CommandAPI can be used with Brigadier side-by-side
• Adds page 10. Requirements for the requirements feature to help restrict commands
• Adds page 14. Predicate tips with information on how to reduce the amount of repeated code when using requirements
• Update Afterword

Documentation changes 3.3 \(\rightarrow\) 3.4:

• Moves configuration for server owners to a new section 2. Configuration for server owners. This has the side-effect of also re-numbering all of the sections on the left. Sorry!
• Adds server owner documentation for the CommandAPI's config command conversion system in section 2. Configuration for server owners
• Update the conversion page 10. Command conversion so it should be much easier to follow and understand
• Changed the list of Java versions that the CommandAPI is compatible with in the Troubleshooting section

Documentation changes 3.1 \(\rightarrow\) 3.3:

• Adds information on how functions are loaded in 1.16+ in section 6. Functions & Tags
• Added function error messages to section Troubleshooting

Documentation changes 3.0 \(\rightarrow\) 3.1:

• Adds new section 5.1 Argument suggestions to cover how to override suggestions - Having it all in section 5. Arguments was a bit too content-heavy
• Adds documentation for the new .overrideSuggestions() method in section 5.1 Argument suggestions
• Simplified the description of the documentation updates
• Changed the artifact ID for the dependency of the CommandAPI. Instead of being commandapi, it is now commandapi-core. You can view the changes in section 2 Setting up your development environment
• Changed the repository information for gradle in section 2 Setting up your development environment. You now have to include the NBTAPI repository because gradle can't automatically detect this for some reason. Kinda stupid tbh.
• Adds a section on using multiple or optional arguments in section 5 Arguments

Documentation changes 2.1 \(\rightarrow\) 3.0:

Developer's Note:

Lots of changes occurred in version 3.0. I highly recommend reading the Upgrading guide section which covers the changes in more detail and how to update your plugin for this version.

• Sections on the left have been tidied up and should be more "approachable"
• Installation section (1. Installation for server owners) now includes information about additional dependencies
• Dependency section (2. Setting up your development environment) updated to use the new dependency Group ID
• Command registration section (3. Command registration) updated to reflect new API changes
• Command execution section (4. Command Executors) updated to reflect new API changes
• Arguments section (5. Arguments) completely rewritten to reflect new API changes. Adds more detailed examples for each argument
• Function arguments section (6.3 Function Arguments) updated to reflect new API changes
• Permissions section (7. Permissions) updated to reflect new API changes
• Aliases section (8. Aliases) updated to reflect new API changes
• Command conversion section (9. Command conversion) rewrite example to be more detailed

Installation

Installing the CommandAPI is easy! Just download the latest CommandAPI.jar file using the button below and place it in your server's plugins folder!

Download latest CommandAPI.jar

Additional dependencies

• If you use NBT data, you'll also need the NBT API. (You can find out from your developers if you need this or not)
• If you are using raw JSON chat data, you'll need to be running Spigot or another spigot-related server such as Paper Spigot or Taco Spigot. (Again, you can find out from your developers if you need this or not)

Configuration for server owners

The CommandAPI has a few configuration options to change how it functions. These options can be configured in the plugins/CommandAPI/config.yml file, which is generated automatically when the CommandAPI runs for the first time.

The default config.yml is shown below:

verbose-outputs: true
create-dispatcher-json: false
plugins-to-convert: []

Configuration settings:

• verbose-outputs - If true, outputs command registration and unregistration logs in the console
• create-dispatcher-json - If true, creates a command_registration.json file showing the mapping of registered commands. This is not designed to by developers - setting this to false will improve command registration performance
• plugins-to-convert - Controls the list of plugins to process for command conversion. See below for more information

Command Conversion

The CommandAPI has the ability to convert plugin commands into "Vanilla compatible" commands automatically on startup. This allows you to use /execute and Minecraft functions/tags for plugins that do not use the CommandAPI. For example, if you want to use the /hat command from the plugin Essentials, you can use the CommandAPI's command conversion setting to do so.

To convert plugin commands, there are two things you need to do:

1. Update the plugin's plugin.yml file with loadbefore: [CommandAPI]
2. Populate the CommandAPI's config.yml file with the plugin (and any commands to be converted)

We explain these steps in detail below with examples, so don't worry!

Updating plugin.yml files with loadbefore

For command conversion to work, the plugin must be loaded before the CommandAPI. To do this, you need to edit the plugin's plugin.yml file. The plugin.yml file can be found inside the plugin's .jar file, which can be opened using any archive tool such as 7-Zip or WinRAR.

Next, you want to edit the plugin.yml file and add the following line:

loadbefore: [CommandAPI]

The best place to put this line is before commands or permissions (underneath version would work fine if you're worried about where to put this line).

After you've done this, save the plugin.yml file, put the updated plugin.yml file back inside the .jar file and you're good to go!

name: Essentials
main: com.earth2me.essentials.Essentials
version: 2.18.0.0
website: http://tiny.cc/EssentialsCommands
description: Provides an essential, core set of commands for Bukkit.
softdepend: [Vault, LuckPerms]
authors: [Zenexer, ementalo, Aelux, Brettflan, KimKandor, snowleo, ceulemans, Xeology, KHobbits, md_5, Iaccidentally, drtshock, vemacs, SupaHam, md678685]
api-version: "1.13"
loadbefore: [CommandAPI]
commands:
  afk:
    description: Marks you as away-from-keyboard.
    usage: /<command> [player/message...]
    aliases: [eafk,away,eaway]

# (other config options omitted)

Converting specific plugin commands

To use the command conversion, you need to first populate the config.yml with the list of plugins and commands to be processed. To illustrate this, we'll use an example:

/execute as @p run afk
/execute as @p run hat

verbose-outputs: true
create-dispatcher-json: false
plugins-to-convert: 
  - Essentials: 
    - hat
    - afk

Converting all plugin commands

If you want to convert all of the plugin commands that a plugin has, use a ~ character instead of a list of commands. For example, if you wanted to convert all commands that EssentialsX has, you can use the following config.yml:

verbose-outputs: true
create-dispatcher-json: false
plugins-to-convert: 
  - Essentials: ~

Setting up your development environment

To use the CommandAPI in your plugins, there are a few methods of adding it to your development environment.

Manually using the .jar

• Download the latest CommandAPI.jar from the download page here

• Add the CommandAPI.jar file to your project/environment's build path:

  

• Add the CommandAPI as a dependent in the plugin.yml (depend: [CommandAPI])

Using Maven (recommended)

Developer's Note:

If you've never used maven before, I highly recommend it! It makes it easier to keep your code updated with the latest dependency updates. For information on how to set up a plugin using maven, you can read Bukkit's plugin tutorial.

• Add the maven repository to your pom.xml file:

  <repositories>
      <repository>
          <id>commandapi</id>
          <url>https://raw.githubusercontent.com/JorelAli/CommandAPI/mvn-repo/</url>
      </repository>
  </repositories>
  

• Add the dependency to your pom.xml:

  <dependencies>
      <dependency>
          <groupId>dev.jorel</groupId>
          <artifactId>commandapi-core</artifactId>
          <version>4.3</version>
          <scope>provided</scope>
      </dependency>
  </dependencies>
  

• Add the CommandAPI as a dependent in the plugin.yml (depend: [CommandAPI])

Using Gradle

• Add the repositories to your build.gradle file (the second repository is required because the CommandAPI depends on the NBT-API):

  repositories {
      maven { url = "https://raw.githubusercontent.com/JorelAli/CommandAPI/mvn-repo/" }
      maven { url = "https://repo.codemc.org/repository/maven-public/" }
  }
  

• Add the dependency to your list of dependencies in your build.gradle file:

  dependencies {
      compileOnly "dev.jorel:commandapi-core:4.3"
  }
  

• Add the CommandAPI as a dependent in the plugin.yml (depend: [CommandAPI])

Shading the CommandAPI in your plugins

After 2 years, this most requested feature is finally here...

The CommandAPI can now be shaded into your own plugins! "Shading" is the process of including the CommandAPI inside your plugin, rather than requiring the CommandAPI as an external plugin. In other words, if you shade the CommandAPI into your plugin, you don't need to include the CommandAPI.jar in your server's plugins folder.

Shading requirements

For the CommandAPI to function as normal, you must call the CommandAPI's initializers in the onLoad() and onEnable() methods of your plugin:

CommandAPI.onLoad(boolean verbose);
CommandAPI.onEnable(Plugin plugin);

The onLoad(boolean) method initializes the CommandAPI's loading sequence. This must be called before you start to access the CommandAPI and must be placed in your plugin's onLoad() method. The argument verbose is used to enable verbose logging output.

The onEnable(Plugin) method initializes the CommandAPI's enabling sequence. As with the onLoad(boolean) method, this one must be placed in your plugin's onEnable() method. This isn't as strict as the onLoad(boolean) method, and can be placed anywhere in your onEnable() method. The argument plugin is your current plugin instance.

public class MyPlugin extends JavaPlugin {

	@Override
	public void onLoad() {
		CommandAPI.onLoad(true); //Load with verbose output
        
        new CommandAPICommand("ping")
            .executes((sender, args) -> {
                sender.sendMessage("pong!");
            })
            .register();
	}
	
	@Override
	public void onEnable() {
		CommandAPI.onEnable(this);
		
		//Register commands, listeners etc.
	}

}

Shading with Maven

To shade the CommandAPI into a maven project, you'll need to use the commandapi-shade dependency, which is optimized for shading and doesn't include plugin-specific files (such as plugin.yml):

<dependencies>
	<dependency>
		<groupId>dev.jorel</groupId>
        <artifactId>commandapi-shade</artifactId>
        <version>4.2</version>
    </dependency>
</dependencies>

Once you've added this this, you can shade the CommandAPI easily by adding the maven-shade-plugin to your build sequence:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.2.4</version>
            <executions>
                <execution>
                    <id>shade</id>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <relocations>
                    <relocation>
                        <pattern>dev.jorel.commandapi-shade</pattern>
                    </relocation>
                </relocations>
            </configuration>
        </plugin>
    </plugins>
</build>

Of course, if you shade the CommandAPI into your plugin, you don't need to add depend: [CommandAPI] to your plugin.yml file.

Shading with Gradle

To shade the CommandAPI into a Gradle project, we'll use the Gradle Shadow Plugin. Add this to your list of plugins:

plugins {
    id 'java'
    id 'com.github.johnrengelman.shadow' version '6.0.0'
}

Next, we declare our dependencies:

dependencies {
    compile "dev.jorel:commandapi-shade:4.3"   
}

Then we add it to the shadowJar task configuration:

shadowJar {
	dependencies {
		include dependency("dev.jorel:commandapi-shade:4.3")
	}
}

Finally, we can build the shaded jar using the following command:

gradlew build shadowJar

Again, as we're shading the CommandAPI into your plugin, we don't need to add depend: [CommandAPI] to your plugin.yml file.

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 arguments
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("message", new GreedyStringArgument());

//Create our command
new CommandAPICommand("broadcastmsg")
	.withArguments(arguments)                     // 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 our arguments for the command. This is described in more detail in the section on arguments.
• We then create a new CommandAPICommand, with the name of the command that the sender must enter to run it.
• We then add the arguments to the command with withArguments.
• 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. No hassling with a plugin instance, no messing with plugin.yml files.

CommandAPICommand methods

The CommandAPICommand has various methods, which are outlined below:

Setting the command name

• new CommandAPICommand(String) - This constructor is used to set the command's name.

Setting command properties

• withArguments(LinkedHashMap<String, Argument>) - The list of arguments.

  The CommandAPI requires a list of arguments which are used for the command. The argument map consists of a key which is the prompt that is displayed as a prompt to users entering commands, and a value which is an instance of an argument (See the section on arguments). This list of arguments is interpreted in the order that arguments are added to the LinkedHashMap.

• withPermission(CommandPermission) - The required permission to execute a command. (See the section on permissions).

• withAliases(String... args) - An array of aliases that the command can be run via.

Setting the command's executor

• executes((sender, args) -> {}) - Executes a command using the CommandSender object.
• executesPlayer((player, args) -> {}) - Executes a command using the Player object.
• executesEntity((entity, args) -> {}) - Executes a command using the Entity object.
• executesCommandBlock((cmdblock, args) -> {}) - Executes a command using the BlockCommandSender object.
• executesConsole((console, args) -> {}) - Executes a command using the ConsoleCommandSender object.
• executesProxy((proxy, args) -> {}) - Executes a command using the ProxiedCommandSender object.

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

• 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 prevent command registration after the server has loaded. This basically 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);

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();

/* Arguments for the gamemode command. In this sample, I'm just 
 * using a simple literal argument which allows for /gamemode survival */
arguments.put("gamemode", new LiteralArgument("survival"));

new CommandAPICommand("gamemode")
    .withArguments(arguments)
    .executes((sender, args) -> {
        //Implementation of our /gamemode command
    }).register();

Command executors

Developer's Note:

This section can be a little bit difficult to follow. If you only want the bare basic features (executes a command), read the section on Normal command executors - this behaves very similar to the onCommand method in Bukkit.

The CommandAPI provides various command executors which are lambdas which execute the code you want when a command is called. With a lot of simplification, there are two main types of command executors:

• Ones that just runs the command (let's call it a normal command executor)
• Ones that returns an integer as a result (let's call it a resulting command executor)

Developer's Note:

In general, you need not focus too much on what type of command executor to implement. If you know for certain that you're going to be using your command with command blocks, and specifically want to state whether a command returns a value, just ensure you return an integer at the end of your declared command executor. Java will infer the type (whether it's a normal command executor or a resulting command executor) automatically, so feel free to return an integer or not.

In addition to these two types of command executors, there are ways to restrict the execution of commands to certain CommandSender subclasses. In other words, you can make commands executable by players in game only for instance. These restrictions are covered in more detail in Normal command executors.

Normal command executors

Command executors are of the following format, where sender is a CommandSender, and args is an Object[], which represents arguments which are parsed by the CommandAPI.

new CommandAPICommand("...").executes((sender, args) -> {
    //Code here  
}).register();

With normal command executors, these do not need to return anything. By default, this will return a success value of 1 if it runs successfully, and a success value of 0 if it runs unsuccessfully, either by throwing an exception (RuntimeException) or by forcing the command to fail (See the section on handling command failures.

In short, this is what values are returned when a command is executed from a normal command executor:

// Create our arguments
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("message", new GreedyStringArgument());

//Create our command
new CommandAPICommand("broadcastmsg")
    .withArguments(arguments)                     // 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();

boolean onCommand(CommandSender, Command, String, String[])

Restricting who can run your command

The CommandAPICommand has multiple different executes...() methods that can restrict the command sender to any of the following objects:

• CommandSender - No restriction, players, the console etc. can use this command. This is what Bukkit normally uses.
• Player - Only in-game players can run this command
• Entity - Only entities (therefore, players as well) can run this command
• BlockCommandSender - Only command blocks can run this command
• ConsoleCommandSender - Only the console can run this command
• ProxiedCommandSender - Only proxied command senders (e.g. other entities via the /execute as ... command)
• NativeProxyCommandSender - This type has special rules governing it. See Native commandsenders for more information

This is done using the respective method:

new CommandAPICommand("suicide")
    .executesPlayer((player, args) -> {
		player.setHealth(0);
    }).register();

Multiple command executor implementations

The CommandAPI allows you to chain different implementations of the command depending on the type of CommandSender. This allows you to easily specify what types of CommandSenders are required to run a command.

Extending on the suicide example above, we could write another implementation for a different CommandSender. Here, we write an implementation to make entities (non-player) go out with a bang when they run the command (using /execute as <entity> run <command> command).

new CommandAPICommand("suicide")
    .executesPlayer((player, args) -> {
		player.setHealth(0);
    })
    .executesEntity((entity, args) -> {
        entity.getWorld().createExplosion(e.getLocation(), 4);
		entity.remove();
    }).register();

The different command sender priority is the following (from highest priority to lowest priority):

\begin{align} &\quad\texttt{.executesNative()} && \texttt{(Always chosen if used)}\\ &\quad\texttt{.executesPlayer()} \\ &\quad\texttt{.executesEntity()} \\ &\quad\texttt{.executesConsole()} \\ &\quad\texttt{.executesCommandBlock()} \\ &\quad\texttt{.executesProxy()} \\ &\quad\texttt{.executes()} \end{align}

Proxied commandsenders

The CommandAPI has extra support for vanilla Minecraft's /execute command, by allowing the CommandSender to be an instance of the ProxiedCommandSender class. This allows the CommandSender to contain two extra pieces of information: The "proxied sender" and the original sender.

new CommandAPICommand("killme")
    .executesPlayer((player, args) -> {
		player.setHealth(0);
	})
    .register();

/execute as @e[type=chicken] run killme

new CommandAPICommand("killme")
    .executesPlayer((player, args) -> {
		player.setHealth(0);
	})
    .executesProxy((proxy, args) -> {
		//Check if the callee is an Entity
		if(proxy.getCallee() instanceof LivingEntity) {

			//If so, kill the entity
			LivingEntity target = (LivingEntity) proxy.getCallee();
			target.setHealth(0);
		}
    })
    .register();

Native commandsenders

In a similar way that the ProxiedCommandSender is used to store information about two command senders: a caller (the one that wrote the command) and a callee (the one that ends up executing the command), the CommandAPI also has a special NativeProxyCommandSender class which is a more powerful representation of the ProxiedCommandSender class. In addition to inheriting all of the methods from ProxiedCommandSender, this class also has the following two methods:

public World getWorld();
public Location getLocation();

These methods contain additional information about the command executor's state, and are primarily designed to be used with Minecraft's /execute command.

Minecraft's /execute arguments

The following table represents how the different /execute arguments affect the NativeProxyCommandSender class:

Using the native commandsender

As described in the section about normal command executors, there are multiple methods to register a command executor. For the NativeProxyCommandSender, the .executesNative() method should be used.

Note:

The .executesNative() method has the highest priority over all over .executesXXX() methods - if you use the .executesNative() method, no other execution method will be run.

Because this method has the highest priority over all other executes methods, this also means that the .getCallee() method can return null.

/break

new CommandAPICommand("break")
    .executesNative((sender, args) -> {
        Location location = (Location) sender.getLocation();
        if(location != null) {
            location.getBlock().breakNaturally();
        }
    })
    .register();

/execute positioned 100 62 50 run break

/execute at @e[type=pig] run break

/execute in minecraft:overworld positioned 20 60 -20 run break

Resulting command executors

Resulting command executors are very similar to normal command executors, except they can return an integer result value.

(sender, args) -> {
	//Code here
	return /*some integer here*/ ;
};

Similarly, these will return a success value of 1 if it runs successfully, and a success value of 0 if it runs unsuccessfully. If a success value of 0 occurs, the result value will be 0. In short:

The concept of result values are better explained through examples:

new CommandAPICommand("randnum")
    .executes((sender, args) -> {
        return new Random().nextInt();
    })
    .register();

/randomnumber        - returns a random number between 1 and 99 (inclusive)
/givereward <player> - gives a player 64 diamonds and broadcasts it in the chat

//Register random number generator command from 1 to 99 (inclusive)
new CommandAPICommand("randomnumber")
    .executes((sender, args) -> {
        return ThreadLocalRandom.current().nextInt(1, 100); //Returns random number from 1 <= x < 100
    })
    .register();

//Register reward giving system for a target player
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("target", new EntitySelectorArgument(EntitySelector.ONE_PLAYER));

new CommandAPICommand("givereward")
    .withArguments(arguments)
    .executes((sender, args) -> {
        Player player = (Player) args[0];
        player.getInventory().addItem(new ItemStack(Material.DIAMOND, 64));
        Bukkit.broadcastMessage(player.getName() + " won a rare 64 diamonds from a loot box!");
    })
    .register();

/execute store result score SomePlayer randVal run randomnumber

/execute if score SomePlayer randVal matches 1 run givereward SomePlayer

Handling command failures

Sometimes, you want your command to fail on purpose. This is basically the way to "gracefully" handle errors in your command execution. This is performed using the following method:

CommandAPI.fail("Error message goes here");

When the CommandAPI calls the fail method, it will cause the command to return a success value of 0, to indicate failure.

//Array of fruit
String[] fruit = new String[] {"banana", "apple", "orange"};

//Argument accepting a String, suggested with the list of fruit
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("item", new StringArgument().overrideSuggestions(fruit));

//Register the command
new CommandAPICommand("getfruit")
    .withArguments(arguments)
    .executes((sender, args) -> {
        String inputFruit = (String) args[0];
        if(fruit.contains(inputFruit)) {
            //Do something with inputFruit
        } else {
            //The player's input is not in the list of fruit
            CommandAPI.fail("That fruit doesn't exist!");
        }
	})
    .register();

Developer's Note:

In general, it's a good idea to handle unexpected cases with the CommandAPI.fail() method. Most arguments used by the CommandAPI will have their own built-in failsafe system (e.g. the EntitySelectorArgument will not execute the command executor if it fails to find an entity), so this feature is for those extra cases.

Arguments

Arguments in the CommandAPI are registered by using a LinkedHashMap<String, Argument> object. There are two things you need to keep in mind when creating arguments:

• The order which they will be used
• The type of each argument

By definition of a LinkedHashMap, the order of the elements inserted into it are preserved, meaning the order you add arguments to the LinkedHashMap will be the resulting order of which arguments are presented to the user when they run that command.

Adding arguments for registration is simple:

//Create LinkedHashMap
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();

//Add an argument called "target", which is a PlayerArgument
arguments.put("target", new PlayerArgument());

The String value is the prompt that is shown to a player when they are entering the command.

Argument Casting

To access arguments, they have to be casted to the type that the argument represents. The order of the arguments in the args[] is the same as the order in which the arguments were declared.

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

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

The type to cast each argument (declared in the dev.jorel.commandapi.arguments package) is listed below:

Optional/Different Arguments

Sometimes, you want to register a command that has a different effect whether arguments are included or not. For example, take the /kill command. If you run /kill on its own, it will kill the command sender. If however you run /kill <target>, it will kill the target. In other words, we have the following command structure:

/kill          - Kills yourself
/kill <target> - Kills a target player

As shown by the command structure, we need to register two commands.

/kill          - Kills yourself
/kill <target> - Kills a target player

new CommandAPICommand("kill")
    .executesPlayer((player, args) -> {
        player.setHealth(0);
    })
    .register();

// Declare our arguments
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("target", new PlayerArgument());

// Register our second /kill <target> command
new CommandAPICommand("kill")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        ((Player) args[0]).setHealth(0);
    })
    .register();

Argument suggestions

Sometimes, you want to override the list of suggestions that are provided by an argument. To handle this, CommandAPI arguments contain three methods to override suggestions:

Argument overrideSuggestions(String... suggestions);
Argument overrideSuggestions(Function<CommandSender, String[]> suggestions);
Argument overrideSuggestions(BiFunction<CommandSender, Object[], String[]> suggestions);

We will describe these methods in detail in this section.

Suggestions with a String Array

The first method, overrideSuggestions(String... suggestions), allows you to replace the suggestions normally associated with that argument with an array of strings.

/tpworld <world>

//Populate a String[] with the names of worlds on the server
String[] worlds = Bukkit.getWorlds().stream().map(World::getName).toArray(String[]::new);

//Override the suggestions of the StringArgument with the aforementioned String[]
LinkedHashMap<String, ArgumentType> arguments = new LinkedHashMap<>();
arguments.put("world", new StringArgument().overrideSuggestions(worlds));

new CommandAPICommand("tpworld")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
       	String world = (String) args[0];
		player.teleport(Bukkit.getWorld(world).getSpawnLocation());
    })
    .register();

Suggestions depending on a command sender

The overrideSuggestions(Function<CommandSender, String[]> suggestions) method allows you to replace the suggestions normally associated with that argument with an array of strings that are evaluated dynamically using information about the command sender.

/friendtp <friend>

public class Friends {
    public static String[] getFriends(CommandSender sender) {
        if(sender instanceof Player) {
            return //Look up friends in a database or file
        } else {
            return new String[0];
        }
    }
}

LinkedHashMap<String, ArgumentType> arguments = new LinkedHashMap<>();
arguments.put("friend", new PlayerArgument().overrideSuggestions((sender) -> {
    Friends.getFriends(sender);
}));

new CommandAPICommand("friendtp")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
       	Player target = (Player) args[0];
		player.teleport(target);
    })
    .register();

Suggestions depending on previous arguments

The overrideSuggestions(BiFunction<CommandSender, Object[], String[]> suggestions) method is the most powerful suggestion overriding function that the CommandAPI offers. It has the capability to suggest arguments based on the values of previously inputted arguments.

This method requires a function that takes in a command sender and the list of previous arguments and must return a String[] of suggestions. The arguments are parsed exactly like any regular CommandAPI command argument.

/mycommand arg1 arg2 arg3

/execute run mycommand <suggestions>

/localmsg <radius> <target> <message>

// Declare our arguments as normal
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("radius", new IntegerArgument());

// Override the suggestions for the PlayerArgument, using (sender, args) as the parameters
// sender refers to the command sender that is running this command
// args refers to the Object[] of PREVIOUSLY DECLARED arguments (in this case, the IntegerArgument radius)
arguments.put("target", new PlayerArgument().overrideSuggestions((sender, args) -> {

    // Cast the first argument (radius, which is an IntegerArgument) to get its value
	int radius = (int) args[0];
	
    // Get nearby entities within the provided radius
	Player player = (Player) sender;
	Collection<Entity> entities = player.getWorld().getNearbyEntities(player.getLocation(), radius, radius, radius);
	
    // Get player names within that radius
	return entities.stream()
		.filter(e -> e.getType() == EntityType.PLAYER)
		.map(Entity::getName)
		.toArray(String[]::new);
}));
arguments.put("message", new GreedyStringArgument());

// Declare our command as normal
new CommandAPICommand("localmsg")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		Player target = (Player) args[1];
		String message = (String) args[2];
		target.sendMessage(message);
	})
	.register();

Safe argument suggestions

So far, we've covered how to override suggestions using the overrideSuggestions() method. The issue with using Strings for suggestion listings is that they are prone to errors. As a result, some arguments include the safeOverrideSuggestions(), which provides type-safety checks for argument suggestions, as well as automatic "Bukkit-to-suggestion" conversion.

The whole point of the safe argument suggestions method is that parameters entered in this method are guaranteed to work.

The use of the safe override suggestions function is basically the same as overrideSuggestions() from the previous section, except instead of returning a String[], you now return a T[], where T is the class corresponding to the argument. This is described in more detail in the table below.

Argument safeOverrideSuggestions(T... suggestions);
Argument safeOverrideSuggestions(Function<CommandSender, T[]> suggestions);
Argument safeOverrideSuggestions(BiFunction<CommandSender, Object[], T[]> suggestions);

Supported arguments

Not all arguments support safe suggestions. This is mostly due to implementation constraints or inadequate support by the Bukkit API.

The list of supported arguments are displayed in the following table. The parameter T (shown in the method signatures above) are also provided for each argument. This parameter is the same as the cast argument described in Argument Casting, except for a few exceptions which are outlined in bold.

Safe time arguments

While most of the arguments are fairly straight forward, I'd like to bring your attention to the TimeArgument's safe suggestions function. This uses dev.jorel.commandapi.wrappers.Time as the class for T to ensure type-safety. The Time class has three static methods:

Time ticks(int ticks);
Time days(int days);
Time seconds(int seconds);

These create representations of ticks (e.g. 40t), days (e.g. 2d) and seconds (e.g. 60s) respectively.

Safe function arguments

Although all safe arguments are indeed "type-safe", the function argument uses a NamespacedKey which cannot be checked fully at compile time. As a result, this is argument should be used with caution - providing a NamespacedKey suggestion that does not exist when the server is running will cause that command to fail if that suggestion is used.

Safe scoreboard slot arguments

Scoreboard slots now include two new static methods so they can be used with safe arguments:

ScoreboardSlot of(DisplaySlot slot);
ScoreboardSlot ofTeamColor(ChatColor color);

This allows you to create ScoreboardSlot instances which can be used with the safe override suggestions method.

Examples

While this should be fairly straight forward, here's a few examples of how this can be used in practice:

// Create our itemstack
ItemStack emeraldSword = new ItemStack(Material.DIAMOND_SWORD);
ItemMeta meta = emeraldSword.getItemMeta();
meta.setDisplayName("Emerald Sword");
meta.setUnbreakable(true);
emeraldSword.setItemMeta(meta);

// Create and register our recipe
ShapedRecipe emeraldSwordRecipe = new ShapedRecipe(new NamespacedKey(this, "emerald_sword"), emeraldSword);
emeraldSwordRecipe.shape(
	"AEA", 
	"AEA", 
	"ABA"
);
emeraldSwordRecipe.setIngredient('A', Material.AIR);
emeraldSwordRecipe.setIngredient('E', Material.EMERALD);
emeraldSwordRecipe.setIngredient('B', Material.BLAZE_ROD);
getServer().addRecipe(emeraldSwordRecipe);

... // Omitted, more itemstacks and recipes

// Safely override with the recipe we've defined
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("recipe", new RecipeArgument().safeOverrideSuggestions(emeraldSwordRecipe, /* Other recipes */));

// Register our command
new CommandAPICommand("giverecipe")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		Recipe recipe = (Recipe) args[0];
		player.getInventory().addItem(recipe.getResult());
	})
	.register();

/spawnmob <mob>

EntityType[] forbiddenMobs = new EntityType[] {EntityType.ENDER_DRAGON, EntityType.WITHER};
List<EntityType> allowedMobs = new ArrayList<>(Arrays.asList(EntityType.values()));
allowedMobs.removeAll(Arrays.asList(forbiddenMobs)); //Now contains everything except enderdragon and wither

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("mob", new EntityTypeArgument().safeOverrideSuggestions(
	sender -> {
		if(sender.isOp()) {
			return EntityType.values(); //All entity types
		} else {
			return allowedMobs.toArray(new EntityType[0]); //Only allowsMobs
		}
	})
);

new CommandAPICommand("spawnmob")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		EntityType entityType = (EntityType) args[0];
		player.getWorld().spawnEntity(player.getLocation(), entityType);
	})
	.register();

/removeeffect <player> <potioneffect>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("target", new EntitySelectorArgument(EntitySelector.ONE_PLAYER));
arguments.put("potioneffect", new PotionEffectArgument().safeOverrideSuggestions(
	(sender, prevArgs) -> {
		Player target = (Player) prevArgs[0];
        
        //Convert PotionEffect[] into PotionEffectType[]
		return target.getActivePotionEffects().stream()
			.map(PotionEffect::getType)
			.toArray(PotionEffectType[]::new);
	})
);

new CommandAPICommand("removeeffect")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		EntityType entityType = (EntityType) args[0];
		player.getWorld().spawnEntity(player.getLocation(), entityType);
	})
	.register();

Argument suggestions with tooltips

The CommandAPI can also display tooltips for specific argument suggestions. These are shown to the user when they hover over a given suggestion and can be used to provide more context to a user about the suggestions that are shown to them. In this section, we'll outline the two ways of creating suggestions with tooltips:

• Normal (String) suggestions with tooltips
• Safe suggestions with tooltips

Tooltips with normal (String) suggestions

To use these features, the CommandAPI includes the overrideSuggestionsT methods for arguments, that accept StringTooltip objects instead of String objects:

Argument overrideSuggestionsT(StringTooltip... suggestions);
Argument overrideSuggestionsT(Function<CommandSender, StringTooltip[]> suggestions);
Argument overrideSuggestionsT(BiFunction<CommandSender, Object[], StringTooltip[]> suggestions);

The StringTooltip object has two static methods to construct it easily:

StringTooltip none(String suggestion);
StringTooltip of(String suggestion, String tooltip);

The first method, StringTooltip.none(String) creates a normal suggestion entry with no tooltip, whereas the StringTooltip.of(String, String) method creates a suggestion with the provided tooltip text.

Lastly, the StringTooltip object also has a static method arrayOf(StringTooltip...) to easily construct a StringTooltip[].

/emote <emote> <target>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("emote", new StringArgument()
	.overrideSuggestionsT( 
		StringTooltip.arrayOf(
			StringTooltip.of("wave", "Waves at a player"),
			StringTooltip.of("hug", "Gives a player a hug"),
			StringTooltip.of("glare", "Gives a player the death glare")
		)
	));
arguments.put("target", new PlayerArgument());

new CommandAPICommand("emote")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		String emote = (String) args[0];
		Player target = (Player) args[1];
		
		switch(emote) {
		case "wave":
			target.sendMessage(player.getName() + " waves at you!");
			break;
		case "hug":
			target.sendMessage(player.getName() + " hugs you!");
			break;
		case "glare":
			target.sendMessage(player.getName() + " gives you the death glare...");
			break;
		}
	})
	.register();

Tooltips with safe suggestions

Using tooltips with safe suggestions is almost identical to the method described above for normal suggestions, except for two things. Firstly, you must use safeOverrideSuggestionsT method instead of the overrideSuggestionsT method and secondly, instead of using StringTooltip, you must use Tooltip<S>. Let's look at these differences in more detail.

The safeOverrideSuggestionsT methods are fairly similar to the overrideSuggestionsT methods, except instead of using StringTooltip, it simply uses Tooltip<S>.

Argument safeOverrideSuggestionsT(Tooltip<S>... suggestions);
Argument safeOverrideSuggestionsT(Function<CommandSender, Tooltip<S>[]> suggestions);
Argument safeOverrideSuggestionsT(BiFunction<CommandSender, Object[], Tooltip<S>[]> suggestions);

The Tooltip<S> class represents a tooltip for a given object S. For example, a tooltip that is for a LocationArgument would be a Tooltip<Location> and a tooltip for an EnchantmentArgument would be a Tooltip<Enchantment>.

Just like the StringTooltip class, the Tooltip<S> class provides the following static methods, which operate exactly the same as the ones in the StringTooltip class:

Tooltip<S> none(S object);
Tooltip<S> of(S object, String tooltip);
Tooltip<S>[] arrayOf(Tooltip<S>... tooltips);

The use of arrayOf is heavily recommended as it provides the necessary type safety for Java code to ensure that the correct types are being passed to the safeOverrideSuggestionsT method.

/warp <location>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("location", new LocationArgument()
	.safeOverrideSuggestionsT((sender) -> {
		return Tooltip.arrayOf(
			Tooltip.of(((Player) sender).getWorld().getSpawnLocation(), "World spawn"),
			Tooltip.of(((Player) sender).getBedSpawnLocation(), "Your bed"),
			Tooltip.of(((Player) sender).getTargetBlockExact(256).getLocation(), "Target block")
		);
	}));

new CommandAPICommand("warp")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		player.teleport((Location) args[0]);
	})
	.register();

Argument types

Primitive arguments

Primitive arguments are arguments that represent Java primitive types, such as int, float, double, boolean and long. These arguments are defined in their respective classes:

These arguments simply cast to their primitive type and don't need any extra work.

Boolean arguments

The BooleanArgument class represents the Boolean values true and false.

/editconfig <config-key> <value>

// Load keys from config file
String[] configKeys = getConfig().getKeys(true).toArray(new String[0]);

// Create arguments with the config key and a boolean value to set it to
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("config-key", new TextArgument().overrideSuggestions(configKeys));
arguments.put("value", new BooleanArgument());

// Register our command
new CommandAPICommand("editconfig")
    .withArguments(arguments)
    .executes((sender, args) -> {
        // Update the config with the boolean argument
        getConfig().set((String) args[0], (boolean) args[1]);
    })
    .register();

Numerical arguments

Numbers are represented using the designated number classes:

Each numerical argument can have ranges applied to them, which restricts the user to only entering numbers from within a certain range. This is done using the constructor, and the range specified:

Each range is inclusive, so it includes the number given to it. If the minimum value provided is larger than the maximum value, an InvalidRangeException is thrown.

Ranged arguments

Ranged arguments allow players to provide a range between two numbers, all within a single argument. The CommandAPI provides two ranged arguments, IntegerRangeArgument for ranges with only integer values, and FloatRangeArgument for ranged with potential floating point values.

These consist of values such as:

This allows you to let users define a range of values, which can be used to limit a value, such as the number of players in a region or for a random number generator.

The IntegerRange & FloatRange class

The CommandAPI returns an IntegerRange from the IntegerRangeArgument, and a FloatRange from the FloatRangeArgument, which represents the upper and lower bounds of the numbers provided by the command sender, as well as a method to check if a number is within that range.

The IntegerRange class has the following methods:

class IntegerRange {
    public int getLowerBound();
    public int getUpperBound();
    public boolean isInRange(int);
}

The FloatRange class has the following methods:

class FloatRange {
    public float getLowerBound();
    public float getUpperBound();
    public boolean isInRange(float);
}

/searchchests <range> <item>

// Declare our arguments for /searchrange <IntegerRange> <ItemStack>
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("range", new IntegerRangeArgument());
arguments.put("item", new ItemStackArgument());

new CommandAPICommand("searchrange")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        // Retrieve the range from the arguments
        IntegerRange range = (IntegerRange) args[0];
        ItemStack itemStack = (ItemStack) args[1];

        // Store the locations of chests with certain items
        List<Location> locations = new ArrayList<>();

        // Iterate through all chunks, and then all tile entities within each chunk
        for(Chunk chunk : player.getWorld().getLoadedChunks()) {
            for(BlockState blockState : chunk.getTileEntities()) {

                // The distance between the block and the player
                int distance = (int) blockState.getLocation().distance(player.getLocation());

                // Check if the distance is within the specified range 
                if(range.isInRange(distance)) {

                    // Check if the tile entity is a chest
                    if(blockState instanceof Chest) {
                        Chest chest = (Chest) blockState;

                        // Check if the chest contains the item specified by the player
                        if(chest.getInventory().contains(itemStack.getType())) {
                            locations.add(chest.getLocation());
                        }
                    }
                }

            }
        }

        // Output the locations of the chests, or whether no chests were found
        if(locations.isEmpty()) {
            player.sendMessage("No chests were found");
        } else {
            player.sendMessage("Found " + locations.size() + " chests:");
            locations.forEach(location -> {
                player.sendMessage("  Found at: " 
                        + location.getX() + ", " 
                        + location.getY() + ", " 
                        + location.getZ());
            });
        }
    })
    .register();

String arguments

There are three types of arguments that return Java's String object. Each have their own unique set of features which make them suitable for specific needs.

String argument

The StringArgument class 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:

Hello
123
hello123
Hello_world

Rejected StringArgument values:

hello@email.com
yesn't

Text argument

The TextArgument acts similar to any String in Java. These can be single words, like to the StringArgument, or have additional characters (e.g. spaces, symbols) if surrounded by quotes. To type quotation marks, you can use \" (as similar to Java) to escape these special characters.

Accepted TextArgument values:

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

Rejected TextArgument values:

hello world
私
"speech marks: ""

Greedy string argument

Greedy Arguments:

The GreedyStringArgument, similar to the ChatArgument uses the entire argument array from its current position. This means that it never ends, therefore if it is used, it must be the last element of your LinkedHashMap of arguments.

For example, if you have a command /message <message> <target>, it would not be able to determine where the message ends and the <target> argument begins.

If a GreedyStringArgument or ChatArgument is not declared at the end of the LinkedHashMap of arguments, or multiple of these arguments are used in the same LinkedHashMap, the CommandAPI throws a GreedyArgumentException.

The GreedyStringArgument takes the TextArgument a step further. Any characters and symbols are allowed and quotation marks are not required.

/message <target> <message>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("target", new PlayerArgument());
arguments.put("message", new GreedyStringArgument());

new CommandAPICommand("message")
    .withArguments(arguments)
    .executes((sender, args) -> {
		((Player) args[0]).sendMessage((String) args[1]);
	})
    .register();

/message Skepter This is some incredibly long string with "symbols" and $p3c!aL characters~

Position-based arguments

Location arguments

In the CommandAPI, there are two arguments used to represent location. The LocationArgument argument, which represents a 3D location \( (x, y, z) \) and the Location2DArgument, which represents 2D location \( (x, z) \).

Location (3D space)

The LocationArgument class is used to specify a location in the command sender's current world, returning a Bukkit Location object. It allows the user to enter three numbers as coordinates, or use relative coordinates (i.e. the ~ and ^ operators).

The LocationArgument constructor requires a LocationType, which specifies the type of location that is accepted by the command. The LocationType enum consists of two values:

LocationType.BLOCK_POSITION

BLOCK_POSITION refers to integer block coordinates. When in-game as a player, the suggested location is the coordinates of block you are looking at when you type the command.

LocationType.PRECISE_POSITION

PRECISE_PRECISION uses exact coordinates, using the double primitive type. When in-game as a player, the suggested location is the exact coordinates of where your cursor is pointing at when you type the command.

If no LocationType is provided, the LocationArgument will use PRECISE_POSITION by default.

/break <location>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();

//We want to target blocks in particular, so use BLOCK_POSITION
arguments.put("block", new LocationArgument(LocationType.BLOCK_POSITION));

new CommandAPICommand("break")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        ((Location) args[0]).getBlock().setType(Material.AIR);
    })
    .register();

Location (2D space)

The Location2DArgument is pretty much identical in use to the LocationArgument for 3D coordinates, except instead of returning a Location object, it instead returns a Location2D object that extends Location (thus, being compatible anywhere you would normally be able to use Location).

Rotation arguments

The RotationArgument allows users to specify a pair of pitch and yaw coordinates. By default (using the ~ symbol), this refers to the player's current pitch and yaw of where they are looking at.

The RotationArgument class returns a Rotation object, which consists of the following methods:

/rotate <rotation> <target>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("rotation", new RotationArgument());
arguments.put("target", new EntitySelectorArgument(EntitySelector.ONE_ENTITY));

new CommandAPICommand("rotate")
    .withArguments(arguments)
    .executes((sender, args) -> {
        Rotation rotation = (Rotation) args[0];
        Entity target = (Entity) args[1];

        if(target instanceof ArmorStand) {
            ArmorStand a = (ArmorStand) target;
            a.setHeadPose(new EulerAngle(Math.toRadians(rotation.getPitch()), Math.toRadians(rotation.getYaw() - 90), 0));
        }
    })
    .register();

AxisArgument

The AxisArgument class refers to the x, y and z axes. When used with the CommandAPI, it returns an EnumSet<Axis> (You can view the documentation for EnumSet here).

Chat arguments

The CommandAPI provides three main classes to interact with chat formatting in Minecraft.

Chat color argument

The ChatColorArgument class is used to represent a given chat color (e.g. red or green)

/namecolor <chatcolor>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("chatcolor", new ChatColorArgument());

new CommandAPICommand("namecolor")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        ChatColor color = (ChatColor) args[0];
	    player.setDisplayName(color + player.getName());
    })
    .register();

Spigot-based chat arguments

Developer's Note:

The two following classes, ChatComponentArgument and ChatArgument depend on a Spigot based server. This means that these arguments will not work on a non-Spigot based server, such as CraftBukkit. If you use this class on a non-Spigot based server, it will throw a SpigotNotFoundException

Spigot based servers include, but are not limited to:

• Spigot
• PaperSpigot
• TacoSpigot

Chat component argument

The ChatComponentArgument class accepts raw chat-based JSON as valid input. Despite being regular JSON, it must conform to the standard declared here, which consists of JSON that has a limited subset of specific keys (In other words, you can have a JSON object that has the key text, but not one that has the key blah).

This is converted into Spigot's BaseComponent[], which can be used for the following:

• Broadcasting messages to all players on the server using:

  Bukkit.getServer().spigot().broadcast(BaseComponent[]);
  

• Adding and setting pages to books using BookMeta:

  BookMeta meta = // ...
  meta.spigot().setPages(BaseComponent[]);
  

• Sending messages to Player objects:

  Player player = // ...
  player.spigot().sendMessage(BaseComponent[]);
  

• Sending messages to CommandSender objects:

  CommandSender sender = // ...
  sender.spigot().sendMessage(BaseComponent[]);
  

["", {
    "text": "Once upon a time, there was a guy call "
}, {
    "text": "Skepter",
    "color": "light_purple",
    "hoverEvent": {
        "action": "show_entity",
        "value": "Skepter"
    }
}, {
    "text": " and he created the "
}, {
    "text": "CommandAPI",
    "underlined": true,
    "clickEvent": {
        "action": "open_url",
        "value": "https://github.com/JorelAli/CommandAPI"
    }
}]

["[\"\",{\"text\":\"Once upon a time, there was a guy call \"},{\"text\":\"Skepter\",\"color\":\"light_purple\",\"hoverEvent\":{\"action\":\"show_entity\",\"value\":\"Skepter\"}},{\"text\":\" and he created the \"},{\"text\":\"CommandAPI\",\"underlined\":true,\"clickEvent\":{\"action\":\"open_url\",\"value\":\"https://github.com/JorelAli/CommandAPI\"}}]"]

/makebook <player> <contents>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("player", new PlayerArgument());
arguments.put("contents", new ChatComponentArgument());

new CommandAPICommand("makebook")
    .withArguments(arguments)
    .executes((sender, args) -> {
        Player player = (Player) args[0];
        BaseComponent[] arr = (BaseComponent[]) args[1];
        
        //Create book
        ItemStack is = new ItemStack(Material.WRITTEN_BOOK);
        BookMeta meta = (BookMeta) is.getItemMeta(); 
        meta.setTitle("Custom Book");
        meta.setAuthor(player.getName());
        meta.spigot().setPages(arr);
        is.setItemMeta(meta);
        
        //Give player the book
        player.getInventory().addItem(is);
    })
    .register();

Chat argument

Note:

The ChatArgument class is an argument similar to the GreedyStringArgument, in the sense that it has no terminator and must be defined at the end of your LinkedHashMap of arguments. For more information on this, please read the section on Greedy arguments.

The ChatArgument is basically identical to the GreedyStringArgument, with the added functionality of enabling entity selectors, such as @e, @p and so on. The ChatArgument also returns a BaseComponent[], similar to the ChatComponentArgument.

/pbroadcast <message>

/pbroadcast Hello @p

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("message", new ChatArgument());

new CommandAPICommand("pbroadcast")
    .withArguments(arguments)
    .executes((sender, args) -> {
        BaseComponent[] message = (BaseComponent[]) args[0];
    
        //Broadcast the message to everyone on the server
        Bukkit.getServer().spigot().broadcast(message);
    })
    .register();

Entity & player arguments

Entity selector argument

Minecraft's target selectors (e.g. @a or @e) are implemented using the EntitySelectorArgument class. This allows you to select specific entities based on certain attributes.

The EntitySelectorArgument constructor 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.

/remove <player>
/remove <mob type>
/remove <radius>

//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));

new CommandAPICommand("remove")
    .withArguments(arguments)
    .executes((sender, args) -> {
        //Parse the argument as a collection of entities (as stated above in the documentation)
        @SuppressWarnings("unchecked")
        Collection<Entity> entities = (Collection<Entity>) args[0];
        
        sender.sendMessage("Removed " + entities.size() + " entities");
        for(Entity e : entities) {
            e.remove();
        }
    })
    .register();

Player argument

The PlayerArgument class is very similar (almost identical) to EntitySelectorArgument, with the EntitySelector ONE_PLAYER. It also allows you to select a player based on their UUID.

Developer's Note:

I've not tested the PlayerArgument enough to recommend using it over the EntitySelectorArgument(EntitySelector.ONE_PLAYER). There may be other advantages to using this than the regular EntitySelectorArgument, but as of writing this documentation, I know not of the advantages nor disadvantages to using this argument type. Internally, the PlayerArgument uses the GameProfile class from Mojang's authlib, which may be able to retrieve offline players (untested).

(Of course, if anyone is able to confirm any major differences between the PlayerArgument and the EntitySelectorArgument(EntitySelector.ONE_PLAYER), I would be more than happy to include your findings in the documentation. If so, feel free to make a documentation amendment here.)

Entity type argument

The EntityTypeArgument class is used to retrieve a type of entity as defined in the EntityType enum. In other words, this is an entity type, for example a pig or a zombie.

/spawnmob <entity> <amount>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();

arguments.put("entity", new EntityTypeArgument());
arguments.put("amount", new IntegerArgument(1, 100)); //Prevent spawning too many entities

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

Scoreboard arguments

The scoreboard arguments that the CommandAPI provides allows you to interact with various scoreboard elements, such as objectives, teams and score holders. Since commands are registered in the onEnable() or onLoad() method of a plugin, this means that these are registered before Bukkit's main scoreboard is loaded.

This means that calling Bukkit.getScoreboardManager().getMainScoreboard() will always result in a NullPointerException. To avoid this scenario, try using a lambda which delays the call that gets Bukkit's main scoreboard to the moment when the command is executed, which typically occurs after the server has initialized it. For example, if you wanted to populate a TeamArgument with a list of all registered teams on the server, you should use the following:

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
	        	
arguments.put("team", new TeamArgument().safeOverrideSuggestions(s ->
    Bukkit.getScoreboardManager().getMainScoreboard().getTeams().toArray(new Team[0]))
);

Scoreboard arguments

The CommandAPI uses two classes to provide information about a scoreboard:

• The ScoreHolderArgument class represents score holder - a player's name or an entity's UUID that has scores in an objective. This is described in more detail on the Minecraft Wiki.
• The ScoreboardSlotArgument class represents a display slot (sidebar, list or belowName) as well as the team color if the display is the sidebar. This is described in more detail on the Minecraft Wiki.

Score holder argument

The score holder argument can accept either a single entity or a collection of multiple entities. In order to specify which one to use, you must provide a ScoreHolderType enum value to the ScoreHolderArgument constructor, which is either ScoreHolderType.SINGLE or ScoreHolderType.MULTIPLE:

new ScoreHolderArgument(ScoreHolderType.SINGLE);
new ScoreHolderArgument(ScoreHolderType.MULTIPLE);

Depending on which constructor is used, the cast type changes. If you use a ScoreHolderType.SINGLE, the argument must be casted to a String. Otherwise, if you use ScoreHolderType.MULTIPLE, the argument must be casted to a Collection<String>.

/reward <players>

/reward @e[type=player,scores={deaths=..9}]

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
//We want multiple players, so we use ScoreHolderType.MULTIPLE in the constructor
arguments.put("players", new ScoreHolderArgument(ScoreHolderType.MULTIPLE));

new CommandAPICommand("reward")
    .withArguments(arguments)
    .executes((sender, args) -> {
        //Get player names by casting to Collection<String>
        @SuppressWarnings("unchecked")
        Collection<String> players = (Collection<String>) args[0];
        
        for(String playerName : players) {
            Bukkit.getPlayer(playerName).getInventory().addItem(new ItemStack(Material.DIAMOND, 3));
        }
    })
    .register();

Developer's Note:

In the example above, we have our user use the @e[type=player] entity selector to restrict the Collection<String> so it only returns player names, which allows us to use Bukkit.getPlayer(playerName). In practice, we cannot guarantee that such a selector will be used, so we could update the code to accept both entities and players. For example, we can differentiate between players and entities by using the UUID.fromString(String) method:

Collection<String> entitiesAndPlayers = (Collection<String>) args[0];
for(String str : entitiesAndPlayers) {
    try {
        UUID uuid = UUID.fromString(str);
        //Is a UUID, so it must by an entity
        Bukkit.getEntity(uuid);
    } catch(IllegalArgumentException exception) {
        //Not a UUID, so it must be a player name
        Bukkit.getPlayer(str); 
    }
}

Scoreboard slot argument

The ScoreboardSlotArgument represents where scoreboard information is displayed. Since the Bukkit scoreboard DisplaySlot is not able to represent the case where team colors are provided, the CommandAPI uses the ScoreboardSlot wrapper class as the representation of the ScoreboardSlotArgument.

ScoreboardSlot wrapper

The ScoreboardSlot wrapper class has 3 methods:

class ScoreboardSlot {
    public DisplaySlot getDisplaySlot();
    public ChatColor getTeamColor();
    public boolean hasTeamColor();
}

The getDisplaySlot() method returns the display slot that was chosen. If the display slot is DisplaySlot.SIDEBAR and hasTeamColor() returns true, then it is possible to use getTeamColor() to get the team color provided.

/clearobjectives <slot>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("slot", new ScoreboardSlotArgument());

new CommandAPICommand("clearobjectives")
    .withArguments(arguments)
    .executes((sender, args) -> {
		Scoreboard scoreboard = Bukkit.getScoreboardManager().getMainScoreboard();
        DisplaySlot slot = ((ScoreboardSlot) args[0]).getDisplaySlot();
        scoreboard.clearSlot(slot);
    })
    .register();

Objective arguments

In the CommandAPI, objectives are split into two classes:

• The ObjectiveArgument class, which represents objectives as a whole
• The ObjectiveCriteriaArgument class, which represents objective criteria

Objective argument

The objective argument refers to a single scoreboard objective. Unconventionally, the ObjectiveArgument must be cast to String due to implementation limitations.

Developer's Note:

The two classes ObjectiveArgument and TeamArgument must both be cast to String, as opposed to Objective and Team respectively. This is due to the fact that commands are typically registered in the onLoad() method during a plugin's initialization. At this point in the server start-up sequence, the main server scoreboard is not initialized, so it cannot be used.

/sidebar <objective>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("objective", new ObjectiveArgument());

new CommandAPICommand("sidebar")
    .withArguments(arguments)
    .executes((sender, args) -> {
        //The ObjectArgument must be casted to a String
        String objectiveName = (String) args[0];
        
        //An objective name can be turned into an Objective using getObjective(String)
        Objective objective = Bukkit.getScoreboardManager().getMainScoreboard().getObjective(objectiveName);
        
        //Set display slot
        objective.setDisplaySlot(DisplaySlot.SIDEBAR);
    })
    .register();

Objective criteria argument

The ObjectiveCriteriaArgument is fairly straight forward - it represents the criteria for an objective. Similar to Bukkit, the objective criteria is simply represented as a String, so it must be casted to a String when being used.

/unregisterall <objective critera>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("objective criteria", new ObjectiveCriteriaArgument());

new CommandAPICommand("unregisterall")
    .withArguments(arguments)
    .executes((sender, args) -> {
        String objectiveCriteria = (String) args[0];
        Set<Objective> objectives = Bukkit.getScoreboardManager().getMainScoreboard().getObjectivesByCriteria(objectiveCriteria);
        
        //Unregister the objectives
        for(Objective objective : objectives) {
            objective.unregister();
        }
    })
    .register();

Team arguments

The TeamArgument class interacts with the Minecraft scoreboard and represents a team. Similar to the ObjectiveArgument class, the TeamArgument class must be casted to a String.

/togglepvp <team>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("team", new TeamArgument());

new CommandAPICommand("togglepvp")
    .withArguments(arguments)
    .executes((sender, args) -> {
        //The TeamArgument must be casted to a String
        String teamName = (String) args[0];
        
        //A team name can be turned into a Team using getTeam(String)
        Team team = Bukkit.getScoreboardManager().getMainScoreboard().getTeam(teamName);
        
        //Toggle pvp
        team.setAllowFriendlyFire(team.allowFriendlyFire());
    })
    .register();

Miscellaneous arguments

Advancement arguments

The AdvancementArgument class represents in-game advancements. As expected, the AdvancementArgument can be casted to Bukkit's Advancement class.

/award <player> <advancement>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("player", new PlayerArgument());
arguments.put("advancement", new AdvancementArgument());

new CommandAPICommand("award")
    .withArguments(arguments)
    .executes((sender, args) -> {
        Player target = (Player) args[0];
        Advancement advancement = (Advancement) args[1];
        
        //Award all criteria for the advancement
        AdvancementProgress progress = target.getAdvancementProgress(advancement);
        for(String criteria : advancement.getCriteria()) {
            progress.awardCriteria(criteria);
        }
    })
    .register();

Biome arguments

In Minecraft 1.16, they added the ability to refer to in-game biomes. The CommandAPI implements this using the BiomeArgument. As expected, this returns Bukkit's Biome enum when used.

/setbiome <biome>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("biome", new BiomeArgument());

new CommandAPICommand("setbiome")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		Biome biome = (Biome) args[0];

		Chunk chunk = player.getLocation().getChunk();
		player.getWorld().setBiome(chunk.getX(), player.getLocation().getBlockY(), chunk.getZ(), biome);
	})
	.register();

BlockState arguments

The BlockStateArgument is used to represent data about blocks in the world. These refer to any blocks that have data or states, such as dispensers, signs, doors and pistons. The BlockStateArgument creates a Bukkit BlockData object when used.

Developer's Note:

Make sure to not confuse the cast type with BlockState. The naming of this argument refers to the internal Minecraft vanilla argument naming convention - this argument casts to BlockData and NOT BlockState.

/set <block>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("block", new BlockStateArgument());

new CommandAPICommand("set")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		BlockData blockdata = (BlockData) args[0];
		Block targetBlock = player.getTargetBlockExact(256);
		
        // Set the block, along with its data
		targetBlock.setType(blockdata.getMaterial());
		targetBlock.getState().setBlockData(blockdata);
	})
	.register();

Enchantment argument

The EnchantmentArgument class lets users input a specific enchantment. As you would expect, the cast type is Bukkit's Enchantment class.

/enchantitem <enchantment> <level>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("enchantment", new EnchantmentArgument());
arguments.put("level", new IntegerArgument(1, 5));

new CommandAPICommand("enchantitem")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
		Enchantment enchantment = (Enchantment) args[0];
		int level = (int) args[1];
		
		//Add the enchantment
		player.getInventory().getItemInMainHand().addEnchantment(enchantment, level);
    })
    .register();

Environment arguments

The EnvironmentArgument class allows a command sender to refer to a specific world environment, declared in Bukkit's World.Environment class. This includes the following three environments: NORMAL, NETHER and THE_END.

/createworld <worldname> <type>

// Declare our arguments
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("worldname", new StringArgument());
arguments.put("type", new EnvironmentArgument());

new CommandAPICommand("createworld")
    .withArguments(arguments)
    .executes((sender, args) -> {
        String worldName = (String) args[0];
        Environment environment = (Environment) args[1];

        // Create a new world with the specific world name and environment
        Bukkit.getServer().createWorld(new WorldCreator(worldName).environment(environment));
        sender.sendMessage("World created!");
    })
    .register();

Itemstack arguments

The ItemStackArgument class represents in-game items. As expected, this should be casted to Bukkit's ItemStack object.

/item <itemstack>

// Declare our arguments
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("itemstack", new ItemStackArgument());

new CommandAPICommand("item")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        player.getInventory().addItem((ItemStack) args[0]);
    })
    .register();

LootTable argument

The LootTableArgument class can be used to get a Bukkit LootTable object.

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("loottable", new LootTableArgument());

new CommandAPICommand("giveloottable")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        LootTable lootTable = (LootTable) args[0];
    
    	LootContext context = /* Some generated LootContext relating to the lootTable*/
		lootTable.fillInventory(player.getInventory(), new Random(), context);
    })
    .register();

MathOperation arguments

The CommandAPI's MathOperationArgument is used to represent the Minecraft scoreboard arithmetic operation to alter scoreboard scores. Since there is no default representation in the Bukkit API, the CommandAPI provides the MathOperation class to represent each operation:

The MathOperation also has two methods:

public int apply(int val1, int val2);
public float apply(float val1, float val2);

These methods are used to provide a basic implementation of these math operations on a given input. Given the values val1 and val2, these are the operation that the apply(val1, val2) method performs:

/xp set <player> <level>
/xp add <player> <levels>

/changelevel <player> <operation> <value>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("player", new PlayerArgument());
arguments.put("operation", new MathOperationArgument());
arguments.put("value", new IntegerArgument());

new CommandAPICommand("changelevel")
    .withArguments(arguments)
    .executes((sender, args) -> {
        Player target = (Player) args[0];
        MathOperation op = (MathOperation) args[1];
        int value = (int) args[2];

        target.setLevel(op.apply(target.getLevel(), value));
    })
	.register();

Particle arguments

The ParticleArgument class represents Minecraft particles. As expected, this is casted to the Bukkit Particle class.

/showparticle <particle>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("particle", new ParticleArgument());

new CommandAPICommand("showparticle")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        player.getWorld().spawnParticle((Particle) args[0], player.getLocation(), 1);
    })
    .register();

Potion effect arguments

The PotionEffectArgument class represents Minecraft potion effects. When used, this argument is casted to Bukkit's PotionEffectType class.

/potion <target> <potion> <duration> <strength>

//Declare our arguments
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("target", new PlayerArgument());
arguments.put("potion", new PotionEffectArgument());
arguments.put("duration", new TimeArgument());
arguments.put("strength", new IntegerArgument());

new CommandAPICommand("potion")
    .withArguments(arguments)
    .executes((sender, args) -> {
        Player target = (Player) args[0];
        PotionEffectType potion = (PotionEffectType) args[1];
        int duration = (int) args[2];
        int strength = (int) args[3];
        
        //Add the potion effect to the target player
        target.addPotionEffect(new PotionEffect(potion, duration, strength));
    })
    .register();

Recipe arguments

The RecipeArgument class lets you retrieve Bukkit's Recipe object. Unlike the other arguments, this argument has a slightly different implementation for Minecraft 1.15+.

Developer's Note:

In Minecraft 1.15 and onwards, Bukkit now has the ComplexRecipe class. This class is a subclass of the typical Recipe class, so casting still works when casting to Recipe. The only major difference is the ComplexRecipe class also inherits the Keyed interface, allowing you to access its NamespacedKey. This is used to grant the recipe to players. (This is shown in the second example below).

/giverecipe <recipe>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("recipe", new RecipeArgument());

new CommandAPICommand("giverecipe")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        Recipe recipe = (Recipe) args[0];
    	player.getInventory().addItem(recipe.getResult());
    })
    .register();

/unlockrecipe <player> <recipe>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("player", new PlayerArgument());
arguments.put("recipe", new RecipeArgument());

new CommandAPICommand("unlockrecipe")
    .withArguments(arguments)
    .executes((sender, args) -> {
        Player target = (Player) args[0];
        Recipe recipe = (Recipe) args[1];
		
        //Check if we're running 1.15+
        if(recipe instanceof ComplexRecipe) {
            ComplexRecipe complexRecipe = (ComplexRecipe) recipe;
            target.discoverRecipe(complexRecipe.getKey());
        } else {
            //Error here, can't unlock recipe for player
            CommandAPI.fail("Cannot unlock recipe for player (Are you using version 1.15 or above?)");
        }
    })
    .register();

Sound arguments

The SoundArgument class allows a command sender to retrieve the Bukkit Sound object to represent in-game sound effects (such as mob sounds or ambient sound effects), as well as in-game music.

/sound <sound>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("sound", new SoundArgument());

new CommandAPICommand("sound")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        player.getWorld().playSound(player.getLocation(), (Sound) args[0], 100.0f, 1.0f);
    })
    .register();

Time arguments

The TimeArgument class represents in-game time, in the number of in-game ticks. This allows command senders to specify a certain number of ticks in a simpler way, by including the characters d to specify the numbers of days, s to specify the number of seconds or t to specify a number of ticks.

The CommandAPI converts the inputs provided by the command sender into a number of ticks as an integer.

Developer's Note:

The TimeArgument provides inputs such as 2d (2 in-game days), 10s (10 seconds) and 20t (20 ticks), but does not let you combine them, such as 2d10s.

/bigmsg <duration> <message>

//Declare our arguments
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("duration", new TimeArgument());
arguments.put("message", new GreedyStringArgument());

new CommandAPICommand("bigmsg")
    .withArguments(arguments)
    .executes((sender, args) -> {
        //Duration in ticks
        int duration = (int) args[0];
        String message = (String) args[1];

        for(Player player : Bukkit.getOnlinePlayers()) {
            //Display the message to all players, with the default fade in/out times (10 and 20).
            player.sendTitle(message, "", 10, duration, 20);
        }
    })
    .register();

UUID arguments

The UUID argument is used to uniquely identify players, entities and attribute modifiers. As a result, its cast type is Java's UUID.

Predicate arguments

Block predicate arguments

The BlockPredicateArgument is used to represent a "test" for Minecraft blocks. This can consist of tags, such as the ones listed here on the MinecraftWiki, or individual blocks. If a block matches the tag or block, then the predicate is satisfied.

For example, if we were to use the predicate #leaves, then the following blocks will be satisfied by that predicate: jungle_leaves, oak_leaves, spruce_leaves, dark_oak_leaves, acacia_leaves, birch_leaves.

When used, this argument must be casted to a Predicate<Block>. As with other similar arguments with parameterized types, you can ignore Java's unchecked cast type safety warning.

/replace <radius> <fromBlock> <toBlock>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("radius", new IntegerArgument());
arguments.put("fromBlock", new BlockPredicateArgument());
arguments.put("toBlock", new BlockStateArgument());

new CommandAPICommand("replace")
.withArguments(arguments)
.executesPlayer((player, args) -> {
	
	// Parse the arguments
	int radius = (int) args[0];
	@SuppressWarnings("unchecked")
	Predicate<Block> predicate = (Predicate<Block>) args[1];
	BlockData blockData = (BlockData) args[2];
	
	// Find a (solid) sphere of blocks around the player with a given radius
	Location center = player.getLocation();
	for (int Y = -radius; Y < radius; Y++) {
		for (int X = -radius; X < radius; X++) {
			for (int Z = -radius; Z < radius; Z++) {
				if (Math.sqrt((X * X) + (Y * Y) + (Z * Z)) <= radius) {
					Block block = center.getWorld().getBlockAt(X + center.getBlockX(), Y + center.getBlockY(), Z + center.getBlockZ());
                    
                    // If that block matches a block from the predicate, set it
                    if(predicate.test(block)) {
                        block.setType(blockData.getMaterial());
						block.setBlockData(blockData);
                    }
				}
			}
		}
	}
    return;
})
.register();

ItemStack predicate arguments

Similar to the BlockPredicateArgument, the ItemStackPredicateArgument is a way of performing predicate checks on ItemStack objects. These can represent tags, such as the ones declared here on the MinecraftWiki, or individual items. The cast type for this argument is Predicate<ItemStack>.

/rem <item>

// Declare our arguments
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("items", new ItemStackPredicateArgument());

// Register our command
new CommandAPICommand("rem")
.withArguments(arguments)
.executesPlayer((player, args) -> {
	
    // Get our predicate
	@SuppressWarnings("unchecked")
	Predicate<ItemStack> predicate = (Predicate<ItemStack>) args[0];
    
	for(ItemStack item : player.getInventory()) {
		if(predicate.test(item)) {
			player.getInventory().remove(item);
		}
	}
})
.register();

NBT arguments

The CommandAPI includes support for NBT compounds by using the NBT API by tr7zw. To use NBT, use the NBTCompoundArgument and simply cast the argument to an NBTContainer.

Since this argument depends on the NBT API, if this is used and the NBT API is not available on the server, an NBTAPINotFoundException will be thrown.

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("nbt", new NBTCompoundArgument());

new CommandAPICommand("award")
    .withArguments(arguments)
    .executes((sender, args) -> {
        NBTContainer nbt = (NBTContainer) args[0];
        
        //Do something with "nbt" here...
    })
    .register();

Developer's Note:

I haven't personally explored much with using this argument, so this example isn't great. If you believe you can supply a suitable example for this page, feel free to send an example on the CommandAPI issues page.

Literal arguments

Literal arguments

Literal arguments are used to represent "forced options" for a command. For instance, take Minecraft's /gamemode command. The syntax consists of the following:

/gamemode <mode> [player]

It consists of a gamemode, followed by an optional player argument. The list of gamemodes are as follows:

/gamemode survival 
/gamemode creative
/gamemode adventure
/gamemode spectator

Unlike regular commands (as those implemented by Bukkit for example), these four options are "hardcoded" - they're not "suggestions". The user can only enter one of these four examples, no other values are allowed.

Literal arguments vs regular arguments

Unlike regular arguments that are shown in this chapter, the literal argument is technically not an argument. Due to this fact, the literal argument is not present in the args[] for the command declaration.

/mycommand <literal> <text>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("literal", new LiteralArgument("hello"));
arguments.put("text", new TextArgument());

new CommandAPICommand("mycommand")
    .withArguments(arguments)
    .executes((sender, args) -> {
        // This gives the variable "text" the contents of the TextArgument, and not the literal "hello"
		String text = (String) args[0];
    })
    .register();

/mycommand hello goodbye

//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
    new CommandAPICommand("changegamemode")
        .withArguments(arguments)
        .executesPlayer((player, args) -> {
            //Retrieve the object from the map via the key and NOT the args[]
	        player.setGameMode(gamemodes.get(key));
        })
        .register();
}

Literal argument warnings

Literal arguments require a string in the constructor. If the literal is an empty String or is null, the CommandAPI will throw a BadLiteralException.

Because literal arguments are "hardcoded", each literal is effectively mapped to a single command. This is shown when using the configuration option create-dispatcher-json: true which shows the JSON result of registered commands. For instance, take the /defaultgamemode command:

"defaultgamemode": {
    "type": "literal",
    "children": {
        "adventure": {
            "type": "literal",
            "executable": true
        },
        "creative": {
            "type": "literal",
            "executable": true
        },
        "spectator": {
            "type": "literal",
            "executable": true
        },
        "survival": {
            "type": "literal",
            "executable": true
        }
    }
},

Each option produces a new "command" in the tree of commands. This means that having exceptionally large lists of literals, or nested literals (e.g. /command <literal1> <literal2>) can cause very large trees which cannot be sent to the clients (it can cause clients to crash).

Developer's Note:

Take care when using literal arguments. If your list of arguments is exceptionally large, or contains many nested arguments, the server may be unable to send the command information to the client. If many command argument choices are required, consider using a StringArgument and using .overrideSuggestions() to create your own list of required arguments.

Multi literal arguments

So far, we've described normal arguments and literal arguments. We've described the nuances with literal arguments and how they're not really "arguments", so they don't appear in the args[] for commands.

Now forget all of that. Multi literal arguments are the same as literal arguments but they do appear in the args[] for commands. Multi literal arguments are just a way better alternative to literal arguments. The multi literal argument constructor allows you to provide a String[] of possible values which you can use for your command declaration.

The multi literal argument has all of the same benefits of a regular literal argument - they are hardcoded options that the user must enter - they don't allow other values.

Developer's Note:

The only reason that LiteralArgument still exists is for legacy purposes. MultiLiteralArgument is much more recommended because it's easier to understand and implement. The LiteralArgument has a very slight performance improvement over the MultiLiteralArgument, but it's basically unnoticeable.

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("gamemode", new MultiLiteralArgument("adventure", "creative", "spectator", "survival"));

new CommandAPICommand("gamemode")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        // The literal string that the player enters IS available in the args[]
        switch((String) args[0]) {
            case "adventure":
                player.setGameMode(GameMode.ADVENTURE);
                break;
            case "creative":
                player.setGameMode(GameMode.CREATIVE);
                break;
            case "spectator":
                player.setGameMode(GameMode.SPECTATOR);
                break;
            case "survival":
                player.setGameMode(GameMode.SURVIVAL);
                break;
        }
    }) 
    .register();

Custom arguments

Custom arguments are arguably the most powerful argument that the CommandAPI offers. This argument is used to represent any String, or Minecraft key (Something of the form String:String, such as minecraft:diamond). They basically represent StringArgument with overrideable suggestions and a built-in parser for any object of your choice. They are designed to be used for multiple commands - you define the argument once and can use it wherever you want when declaring commands.

The CustomArgument<T> has two constructors, declared as follows:

public CustomArgument(CustomArgumentFunction<T> parser);
public CustomArgument(CustomArgumentFunction<T> parser, boolean keyed);

The first argument is the CustomArgumentFunction, which is a lambda that takes in a String and returns some custom object of type T. The first constructor will construct a CustomArgument which uses the StringArgument as a base (thus, only simple strings). The second argument has the field keyed. When this field is set to true, the CustomArgument will use a Minecraft key as a base, allowing you to use Minecraft keys as input.

Developer's Note:

I may have complicated this too much, so let me clarify what I mean. The CustomArgument constructor is of the following forms:

CustomArgument((String) -> { ... return T; });
CustomArgument((String) -> { ... return T; }, boolean keyed);

Both constructors take in a String as input and return T. When enabling keyed, it allows the input to be of the form of a Minecraft key, but doesn't change the input type.

The custom argument requires the type of the target object that the custom argument will return when parsing the arguments for a command. For instance, if you have a CustomArgument<Player>, then when parsing the arguments for the command, you would cast it to a Player object.

//Function that returns our custom argument
public Argument worldArgument() {

    //List of worlds on the server, as Strings
    String[] worlds = Bukkit.getWorlds().stream().map(World::getName).toArray(String[]::new);

    //Construct our CustomArgument that takes in a String input and returns a World object
    return new CustomArgument<World>((input) -> {
        //Parse the world from our input
        World world = Bukkit.getWorld(input);

        if(world == null) {
            throw new CustomArgumentException(new MessageBuilder("Unknown world: ").appendArgInput());
        } else {
            return world;
        }
    }).overrideSuggestions(worlds);
}

new CustomArgumentException(String message);
new CustomArgumentException(MessageBuilder message);

/tpworld <world>

LinkedHashMap<String, ArgumentType> arguments = new LinkedHashMap<>();
arguments.put("world", worldArgument());

new CommandAPICommand("tpworld")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        player.teleport(Bukkit.getWorld((World) args[0])).getSpawnLocation());
    })
    .register();

Message Builders

The MessageBuilder class is a class to easily create messages to describe errors when a sender sends a command which does not meet the expected syntax for an argument. It acts in a similar way to a StringBuilder, where you can append content to the end of a String.

The following methods are as follows:

new MessageBuilder("Unknown world: /").appendFullInput().appendHere();

Functions

The CommandAPI has support to use Minecraft's functions within your plugins. This is handled by using a class provided by the CommandAPI called FunctionWrapper, which allows you to execute functions. The CommandAPI also provides support to let you run your own commands within Minecraft function files.

Functions in 1.16+

Developer's Note:

Minecraft 1.16+ change the way that datapacks are loaded on the server, so that they load before plugins are enabled. This means that non-vanilla commands that are declared in functions and tags will be detected as invalid, causing the server to throw a lot of errors at the very start.

The CommandAPI reloads datapacks once the server has finished loading using all declared commands, therefore the error messages at the start of the server can be ignored.

Using custom commands in functions

In order to use a command from your plugin in a .mcfunction file, you must register your command in your plugin's onLoad() method, instead of the onEnable() method. Failure to do so will not allow the command to be registered for Minecraft functions, causing the function file to fail to load during the server startup phase.

Developer's Note:

In short, if you want to register a command which can be used in Minecraft functions, register it in your plugin's onLoad() method.

public class Main extends JavaPlugin {

	@Override
	public void onLoad() {
		//Commands which will be used in Minecraft functions are registered here

        new CommandAPICommand("killall")
            .executes((sender, args) -> {
                //Kills all enemies in all worlds
                Bukkit.getWorlds().forEach(w -> w.getLivingEntities().forEach(e -> e.setHealth(0)));
        	})
            .register();
	}
    
    @Override
    public void onEnable() {
        //Register all other commands here
    } 
}

Setting up functions & tags

Developer's Note:

Most developers can completely skip this section. This is for those that are unfamiliar with functions and tags and is less about how the CommandAPI works.

This section explains how functions are declared and set up for use in a Minecraft server. This is ideal for server owners who've never set up functions, or developers (like the Command API's creator) that has no idea how to set this sort of thing up.

Creating functions

Functions are text files (with the .mcfunction extension) which contains lists of functions which are executed one after another. Each line of the file is a valid Minecraft command. Say we have text.mcfunction:

killall
say Killed all living entities on the server

This will run the custom command killall (as declared in Chapter 6 - Functions & Tags), and then broadcast a message to all players stating that all entities were killed.

Creating tags

Tags are json files which contain a list of functions. Tags let you run multiple functions at a time. Say we have a tag called mytag.json:

{
    "values": [
    	"mycustomnamespace:test",
    	"mycustomnamespace:test2"
    ]
}

This will run the function test and the function test2, which are in the namespace mycustomnamespace.

Namespaces & where to place everything

The following hierarchy explains where functions and tags go. In this diagram, the two functions test and test2 are in a directory called functions. There is also a tag called mytag which is placed in the tags directory under functions. These are all under the namespace called mycustomnamespace

server/
├── world/
│   ├── advancements/
│   ├── data/
│   ├── datapacks/
│   │   └── bukkit/
│   │       ├── pack.mcmeta
│   │       └── data/
│   │           └── mycustomnamespace/
│   │               ├── functions/
│   │               │   ├── test.mcfunction
│   │               │   └── test2.mcfunction
│   │               └── tags/
│   │                   └── functions/
│   │                       └── mytag.json
│   └── ...
├── world_nether/
├── world_the_end/
├── ...
└── spigot.jar

To execute the test function, you would run the following command:

/function mycustomnamespace:test

To execute the mytag tag, you would run the following command:

/function #mycustomnamespace:mytag

The FunctionWrapper

The CommandAPI includes the FunctionWrapper class which is a wrapper for Minecraft's functions. It allows you to execute the commands that are represented by the respective .mcfunction file.

FunctionWrapper methods

The FunctionWrapper class has the following methods:

String[] getCommands();
void run();
void runAs(Entity e);
NamespacedKey getKey();

These methods allow you to interact with the Minecraft function that this class wraps.

getCommands()

The getCommands() method returns a String[] that contains the list of commands that the Minecraft function "holds". In other words, running this Minecraft function is basically as simple as iterating through its commands and running them in order. The commands that this String[] holds are the raw strings that this function represents - in other words, it can include things such as @p and ~ ~ ~ instead of "filled in" values.

run()

The run() method basically does what it says on the tin - it runs the function. The command executor that runs this function is the command executor that was used to retrieve it. For example, if a player in-game populated this argument, then the player will be filled in for @p and the player's location would be used for things such as ~ ~ ~:

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("function", new FunctionArgument());

new CommandAPICommand("runfunc")
    .withArguments(arguments)
	.executes((sender, args) -> {
        FunctionWrapper[] functions = (FunctionWrapper[]) args[0];
        for(FunctionWrapper function : functions) {
            function.run(); // The command executor in this case is 'sender'
        }
    })
    .register();

runAs(Entity)

The runAs(Entity) is basically the same as the run() method, but it allows you to change the command executor to another entity.

Function arguments

The FunctionArgument class is used to represent a function or a tag in Minecraft. When retrieving an instance of the argument, it will return a FunctionWrapper[], where each FunctionWrapper consists of a Minecraft function.

Therefore, if a user supplies a single function, the FunctionWrapper[] will be of size 1, and if the user supplies a tag which can consist of multiple functions, the FunctionWrapper[] will consist of the array of functions as declared by that tag.

/runfunction <function>

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("function", new FunctionArgument());

new CommandAPICommand("runfunction")
    .withArguments(arguments)
    .executes((sender, args) -> {
        FunctionWrapper[] functions = (FunctionWrapper[]) args[0];

        //Run all functions in our FunctionWrapper[]
        for(FunctionWrapper function : functions) {
            function.run();
        }
    })
    .register();

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:

In addition to the CommandPermission class, there are two different ways to assign permissions (compared to the simple CommandSender.hasPermission() method that is provided by Bukkit).

Adding permissions to commands

To add a permission to a command, you can use the withPermission(CommandPermission) method when declaring a command.

// Register the /god command with the permission node "command.god"
new CommandAPICommand("god")
	.withPermission(CommandPermission.fromString("command.god"))
	.executesPlayer((player, args) -> {
		player.setInvulnerable(true);
	})
	.register();

Adding 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

/kill          - Kills yourself
/kill <target> - Kills a target player

// Register /kill command normally. Since no permissions are applied, anyone can run this command
new CommandAPICommand("kill")
	.executesPlayer((player, args) -> {
		player.setHealth(0);
	})
	.register();

// Declare our arguments
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("target", new PlayerArgument().withPermission(CommandPermission.OP));

// Adds the OP permission to the "target" argument. The sender requires OP to execute /kill <target>
new CommandAPICommand("kill")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		((Player) args[0]).setHealth(0);
	})
	.register();

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 as it has greater control over arguments.

Requirements

Requirements is a feature that allows you to put a constraint on commands and arguments. Similar to permissions, a requirement is something that must be fulfilled in order to use a given command or argument.

This section is broken up into four parts:

• Adding requirements to commands
• Adding requirements to arguments
• Updating requirements
• Multiple requirements

Please don't skip the section on updating requirements - the last section is necessary to get requirements to work as you'd want!

Adding requirements to commands

To add a requirement to a command, similar to adding permissions to commands, use the withRequirement method:

withRequirement(Predicate<CommandSender> sender);

The withRequirement method requires a predicate that determines if the sender is able to run the command - if the predicate is satisfied, then the command sender will be able to execute that command.

/repair

new CommandAPICommand("repair")
    .withRequirement(sender -> ((Player) sender).getLevel() >= 30)
	.executesPlayer((player, args) -> {
		
		//Repair the item back to full durability
		ItemStack is = player.getInventory().getItemInMainHand();
		ItemMeta itemMeta = is.getItemMeta();
		if(itemMeta instanceof Damageable) {
			((Damageable) itemMeta).setDamage(0);
			is.setItemMeta(itemMeta);
		}
		
		//Subtract 30 levels
		player.setLevel(player.getLevel() - 30);
	})
	.register();

Adding requirements to arguments

In a similar way that you can restrict certain arguments by adding permissions to them, you can restrict them by using arbitrary predicates by using the withRequirement method on the arguments themselves.

/party create <partyName>
/party tp <player>

Map<UUID, String> partyMembers = new HashMap<>();

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();

// The "create" literal, with a requirement that a player must have a party
arguments.put("createParty", new LiteralArgument("create")
	.withRequirement(sender -> {
		
		return !partyMembers.containsKey(((Player) sender).getUniqueId());
		
	}));
arguments.put("partyName", new StringArgument());

new CommandAPICommand("party")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		
		//Get the name of the party to create
		String partyName = (String) args[0];
		
		partyMembers.put(player.getUniqueId(), partyName);
	})
	.register();

arguments = new LinkedHashMap<>();
arguments.put("teleport", new LiteralArgument("tp")
	.withRequirement(sender -> {
		
		return partyMembers.containsKey(((Player) sender).getUniqueId());
        
	}));
arguments.put("player", new PlayerArgument()
	.safeOverrideSuggestions((sender) -> {
		
		//Store the list of party members to teleport to
		List<Player> playersToTeleportTo = new ArrayList<>();
		
		String partyName = partyMembers.get(((Player) sender).getUniqueId());
		
		//Find the party members
		for(UUID uuid : partyMembers.keySet()) {
			
			//Ignore yourself
			if(uuid.equals(((Player) sender).getUniqueId())) {
				continue;
			} else {
				//If the party member is in the same party as you
				if(partyMembers.get(uuid).equals(partyName)) {
					Player target = Bukkit.getPlayer(uuid);
					if(target.isOnline()) {
						//Add them if they are online
						playersToTeleportTo.add(target);
					}
				}
			}
		}
		
		return playersToTeleportTo.toArray(new Player[0]);
	}));

new CommandAPICommand("party")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		Player target = (Player) args[0];
		player.teleport(target);
	})
	.register();

Updating requirements

Finally, the part you've all been waiting for - how to update requirements. With the way requirements work, they need to be updated manually. To illustrate why this is the case, I'll explain using the example of the /repair command:

When a player joins the game, the server tells the client the list of all commands that the client can run (don't worry, this is completely normal, as declared here). Let's say that the player has joined and has less than 30 levels.

When a player has less than 30 levels, they are unable to execute the /repair command, because the list of commands that the server sent to the client did not contain the /repair command. Eventually, the player will fight some mobs or mine some ores and eventually will reach 30 levels. Despite this, the player's client doesn't actually know that they're now able to use the /repair command until the server tells them. As such, the server needs to somehow update the requirements that a player has so a player knows they can run the command.

The CommandAPI handles this in a very simple method call:

CommandAPI.updateRequirements(player);

To illustrate how to use this, we'll go over the two examples above:

@EventHandler
public void onExpChange(PlayerExpChangeEvent event) {
    CommandAPI.updateRequirements(event.getPlayer());
}

@Override
public void onEnable() {
    getServer().getPluginManager().registerEvents(this, this);
}

/party create <partyName>
/party tp <player>

new CommandAPICommand("party")
	.withArguments(arguments)
	.executesPlayer((player, args) -> {
		
		//Get the name of the party to create
		String partyName = (String) args[0];
		
		partyMembers.put(player.getUniqueId(), partyName);
        
        CommandAPI.updateRequirements(player);
	})
	.register();

Multiple requirements

The CommandAPI lets you handle multiple requirements really easily! The withRequirement method can be called multiple times, so you don't have to worry about shoving everything in one expression.

new CommandAPICommand("someCommand")
	.withRequirement(sender -> ((Player) sender).getLevel() >= 30)
	.withRequirement(sender -> ((Player) sender).getInventory().contains(Material.DIAMOND_PICKAXE))
	.withRequirement(sender -> ((Player) sender).isInvulnerable())
	.executesPlayer((player, args) -> {
		//Code goes here
	})
	.register();

Aliases

Aliases for commands can be added by using the withAliases() method when registering a command. Aliases allow you to run the same command with a different 'name' from the original registered command name.

new CommandAPICommand("getpos")
    // Declare your aliases
    .withAliases("getposition", "getloc", "getlocation", "whereami")
  
    //Declare your implementation
    .executesEntity((entity, args) -> {
        entity.sendMessage(String.format("You are at %d, %d, %d", 
            entity.getLocation().getBlockX(), 
            entity.getLocation().getBlockY(), 
            entity.getLocation().getBlockZ())
        );
    })
    .executesCommandBlock((block, args) -> {
        block.sendMessage(String.format("You are at %d, %d, %d", 
            block.getBlock().getLocation().getBlockX(), 
            block.getBlock().getLocation().getBlockY(), 
            block.getBlock().getLocation().getBlockZ())
        );
    })
  
    //Register the command
    .register();

Command conversion

Developer's Note:

If you're a server owner, you're probably lost! This section is for developer command conversion. If you're looking for how to convert plugins with the config.yml file, you want 2. Configuration for server owners.

The CommandAPI has the ability to convert plugin commands to vanilla Minecraft commands using its config.yml's plugins-to-convert option. Nevertheless, the API for command conversion is not hidden and you're free to use it as you see fit!

Before you continue, let's clear up a few naming conventions which is used in the following sections!

• Target plugin - This refers to a non-CommandAPI plugin which registers normal Bukkit commands. This typically uses the old getCommand(...).setExecutor(...) method
• Your plugin - This refers to your plugin, the one that uses the CommandAPI and wants to add compatibility to a target plugin

Entire plugins

To register all commands that are declared by a target plugin, the Converter.convert(Plugin) method can be used. This attempts to register all commands declared in a target plugin's plugin.yml file, as well as any aliases or permissions stated in the plugin.yml file.

name: TargetPlugin
main: some.random.package.Main
version: 1.0
commands:
  gmc:
    aliases: gm1
  gms:
  i:
    permission: item.permission

name: TargetPlugin
main: some.random.package.Main
loadbefore: [CommandAPI]
version: 1.0
commands:
  gmc:
    aliases: gm1
  gms:
  i:
    permission: item.permission

public class YourPlugin extends JavaPlugin {
    
    @Override
    public void onEnable() {
        Converter.convert(Bukkit.getPluginManager().getPlugin("TargetPlugin"));
        //Other code goes here...
    }
    
}

Only specific commands

In addition to converting all commands from a target plugin, the CommandAPI allows you to convert single commands at a time using the following methods from the Converter class:

public static convert(Plugin plugin, String cmdName);
public static convert(Plugin plugin, String cmdName, LinkedHashMap<String, Argument> arguments);

In these commands, the plugin refers to the plugin which has the command you want to convert and cmdName is the name of the command declared in the target plugin's plugin.yml file (just the main command, not the aliases!).

The LinkedHashMap<String, Argument> can be used to provide argument checks that lets you apply the command UI to a bukkit command.

  speed:
    description: Change your speed limits.
    usage: /<command> [type] <speed> [player]
    aliases: [flyspeed,eflyspeed,fspeed,efspeed,espeed,walkspeed,ewalkspeed,wspeed,ewspeed]

/speed <speed>
/speed <speed> <target>
/speed <walk/fly> <speed>
/speed <walk/fly> <speed> <target>

Plugin essentials = Bukkit.getPluginManager().getPlugin("Essentials");

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();

// /speed <speed>
arguments.put("speed", new IntegerArgument(0, 10));
Converter.convert(essentials, "speed", arguments);

// /speed <target>
arguments.put("target", new PlayerArgument());
Converter.convert(essentials, "speed", arguments);

arguments.clear();

// /speed <walk/fly> <speed>
arguments.put("type", new MultiLiteralArgument("walk", "fly"));
arguments.put("speed", new IntegerArgument(0, 10));
Converter.convert(essentials, "speed", arguments);

// /speed <walk/fly> <speed> <target>
arguments.put("target", new PlayerArgument());
Converter.convert(essentials, "speed", arguments);

Brigadier + CommandAPI

So far, we've been using only the CommandAPI to register commands. As a result, this makes the CommandAPI's features limited by whatever the CommandAPI has implemented. To push past these limits, the CommandAPI includes some extra methods to help with invoking brigadier methods. Of course, to use these methods, brigadier is required. The brigadier dependency's installation instructions can be found here.

Developer's Note:

For those that are unaware, brigadier is Mojang's command parser and dispatching framework. This is basically what the CommandAPI wraps around and is the main underlying source of its functionality.

The CommandAPI has been designed in such a way that you shouldn't have to access NMS in order to make use of the more "advanced" arguments and features - if you find that NMS is required to do something, please make a new issue!

Brigadier support functions

The CommandAPI offers the following methods in the dev.jorel.commandapi.CommandAPIHandler.Brigadier class:

public static CommandDispatcher getCommandDispatcher();
public static RootCommandNode getRootNode();
public static LiteralCommandNode registerNewLiteral(String name);
public static RedirectModifier fromPredicate(BiPredicate<CommandSender, Object[]> predicate, LinkedHashMap<String, Argument> args);
public static Command fromCommand(CommandAPICommand command);
public static RequiredArgumentBuilder argBuildOf(LinkedHashMap<String, Argument> args, String prompt);
public static RequiredArgumentBuilder argBuildOf(String prompt, Argument argument);

Briefly, here's what each of these functions do (you can view the JavaDocs for more information):

Examples

I hope these examples help understand how the CommandAPI can help with registering more "powerful" commands with the use of brigadier as well! Please bear with with it - these examples can be long, but I'm certain that they've been explained well and will be useful!

/execute if randomchance 1 4 run say Hello!

LiteralCommandNode randomChance = Brigadier.registerNewLiteral("randomchance");

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("numerator", new IntegerArgument(0));
arguments.put("denominator", new IntegerArgument(1));

ArgumentBuilder numerator = Brigadier.argBuildOf(arguments, "numerator");
ArgumentBuilder denominator = Brigadier.argBuildOf(arguments, "denominator");

denominator = denominator
	.fork(Brigadier.getRootNode().getChild("execute"), Brigadier.fromPredicate((sender, args) -> {
		//Parse arguments like normal
		int num = (int) args[0];
		int denom = (int) args[1];
		
		//Return boolean with a num/denom chance
		return Math.ceil(Math.random() * (double) denom) <= (double) num;
	}, arguments));

//Add <numerator> <denominator> as a child of randomchance
randomChance.addChild(numerator.then(denominator).build());

//Add (randomchance <numerator> <denominator>) as a child of (execute -> if)
Brigadier.getRootNode().getChild("execute").getChild("if").addChild(randomChance);

//Register literal "randomchance"
LiteralCommandNode randomChance = Brigadier.registerNewLiteral("randomchance");

//Declare arguments like normal
LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("numerator", new IntegerArgument(0));
arguments.put("denominator", new IntegerArgument(1));

//Get brigadier argument objects
ArgumentBuilder numerator = Brigadier.argBuildOf(arguments, "numerator");
ArgumentBuilder denominator = Brigadier.argBuildOf(arguments, "denominator")
    //Fork redirecting to "execute" and state our predicate
	.fork(Brigadier.getRootNode().getChild("execute"), Brigadier.fromPredicate((sender, args) -> {
		//Parse arguments like normal
		int num = (int) args[0];
		int denom = (int) args[1];
		
		//Return boolean with a num/denom chance
		return Math.ceil(Math.random() * (double) denom) <= (double) num;
	}, arguments));

//Add <numerator> <denominator> as a child of randomchance
randomChance.addChild(numerator.then(denominator).build());

//Add (randomchance <numerator> <denominator>) as a child of (execute -> if)
Brigadier.getRootNode().getChild("execute").getChild("if").addChild(randomChance);

Predicate tips

In our example for creating a party system, we ended up having lots of code repetition. In our party creation command, we had the following code:

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("createParty", new LiteralArgument("create")
	.withRequirement(sender -> {
		
		return !partyMembers.containsKey(((Player) sender).getUniqueId());
        
	}));
arguments.put("partyName", new StringArgument());

And for our party teleportation command, we had the following code:

arguments = new LinkedHashMap<>();
arguments.put("teleport", new LiteralArgument("tp")
	.withRequirement(sender -> {
		
		return partyMembers.containsKey(((Player) sender).getUniqueId());
        
	}));

We can simplify this code by declaring the predicate:

Predicate<CommandSender> testIfPlayerHasParty = sender -> {
    return partyMembers.containsKey(((Player) sender).getUniqueId());
};

Now, we can use the predicate testIfPlayerHasParty in our code for creating a party. Since we want to apply the "not" (!) operator to this predicate, we can use .negate() to invert the result of our predicate:

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
arguments.put("createParty", new LiteralArgument("create")
	.withRequirement(testIfPlayerHasParty.negate());
arguments.put("partyName", new StringArgument());

And we can use it again for our code for teleporting to party members:

arguments = new LinkedHashMap<>();
arguments.put("teleport", new LiteralArgument("tp")
	.withRequirement(testIfPlayerHasParty));

Upgrading guide

From version 3.x to 4.0

The maven repository url has changed:

Instead of being:

https://raw.githubusercontent.com/JorelAli/1.13-Command-API/mvn-repo/1.13CommandAPI/

You must now use:

https://raw.githubusercontent.com/JorelAli/CommandAPI/mvn-repo/

This information can be viewed in section 3. Setting up your development environment. (Don't worry if you forget, it should work as normal nonetheless!)

From version 2.3 to 3.0

The CommandAPI's upgrade from version 2.3 to 3.0 is very intense and various refactoring operations took place, which means that plugins that implement the CommandAPI version 2.3 or will not to work with the CommandAPI version 3.0. This page outlines the few major changes and points you to the various pages in the documentation that covers how to use version 3.0.

Imports & Renaming

The default package name has been changed. Instead of being registered under the io.github.jorelali package, the CommandAPI has been moved to the dev.jorel package:

\[\texttt{io.github.jorelali.commandapi.api}\rightarrow\texttt{dev.jorel.commandapi}\]

To organise classes with other classes of similar functions, new packages have been introduced. These can be fully explored using the new JavaDocs

Removed classes & Alternatives

To reduce redundancies, the CommandAPI removed a few classes:

Command registration

The way that commands are registered has been completely changed. It is highly recommended to switch to the new system, which is described here.

The following methods have been removed:

CommandAPI.getInstance().register(String, LinkedHashMap, CommandExecutor);
CommandAPI.getInstance().register(String, String[], LinkedHashMap, CommandExecutor);
CommandAPI.getInstance().register(String, CommandPermission, LinkedHashMap, CommandExecutor);
CommandAPI.getInstance().register(String, CommandPermission, String[], LinkedHashMap, CommandExecutor);

CommandAPI.getInstance().register(String, LinkedHashMap, ResultingCommandExecutor);
CommandAPI.getInstance().register(String, String[], LinkedHashMap, ResultingCommandExecutor);
CommandAPI.getInstance().register(String, CommandPermission, LinkedHashMap, ResultingCommandExecutor);
CommandAPI.getInstance().register(String, CommandPermission, String[], LinkedHashMap, ResultingCommandExecutor);

Additionally, the CommandAPI is no longer accessed by using CommandAPI.getInstance(). This has been replaced with static methods that can be accessed without an instance of the CommandAPI, so you can use the following:

CommandAPI.fail(String command);
CommandAPI.canRegister();
CommandAPI.unregister(String command);
CommandAPI.unregister(String command, boolean force);

Incompatible version information

There are a few arguments that are incompatible with various versions of Minecraft. This page outlines the full list of incompatibilities that the CommandAPI has with what versions of Minecraft.

Argument changes with respect to Minecraft version

BiomeArgument

Incompatible with Minecraft versions less than 1.16 (1.13.x, 1.14.x, 1.15.x)

ChatArgument

Incompatible with Minecraft version 1.16.1 (Works on 1.16.2)

EnvironmentArgument

Incompatible with Minecraft version 1.13 (Works on 1.13.1 and 1.13.2)

LocationArgument2D

If you're using LocationArgument2D with LocationType.PRECISE_POSITION, then it is incompatible with Minecraft version 1.13 (Works on 1.13.1 and 1.13.2)

RecipeArgument

If you use Minecraft versions less than 1.15, this argument will return a Recipe. If you are using Minecraft version 1.15 or greater, this argument will return a ComplexRecipe (which is a subclass of Recipe).

TimeArgument

Incompatible with Minecraft versions less than 1.14 (1.13.x)

UUIDArgument

Incompatible with Minecraft versions less than 1.16 (1.13.x, 1.14.x, 1.15.x)

CommandAPI behavior with respect to Minecraft version

Minecraft version 1.16 and beyond

In Minecraft version 1.16, the way datapacks were loaded changed in such a way that the CommandAPI had to put in additional countermeasures to provide full support to it. To illustrate this, this was the previous loading sequence for Bukkit servers in Minecraft 1.15:

\[\texttt{Server loads}\rightarrow\texttt{Plugins load}\rightarrow\texttt{Datapacks load}\rightarrow\texttt{Server finishes loading}\]

Instead however, Minecraft 1.16 changed the loading sequence to the following:

\[\texttt{Server loads}\rightarrow\texttt{Datapacks load}\rightarrow\texttt{Plugins load}\rightarrow\texttt{Server finishes loading}\]

Because the CommandAPI used to register vanilla Minecraft commands before datapacks (and thus, custom Minecraft functions), it was possible to register custom commands that can be used in functions. With this new loading sequence change in Minecraft 1.16, this meant that datapacks load first before the CommandAPI does, so custom commands are not registered and functions with custom commands would fail to load.

To resolve this, the CommandAPI reloads datapacks and recipes at the end:

\begin{align} &\quad\texttt{Server loads} \\ \rightarrow&\quad\texttt{Datapacks load} \\ \rightarrow&\quad\texttt{Plugins load} \\ \rightarrow&\quad\texttt{Server finishes loading} \\ \rightarrow&\quad\texttt{Datapacks are reloaded} && \texttt{(by the CommandAPI)} \\ \rightarrow&\quad\texttt{Recipes are reloaded} && \texttt{(by the CommandAPI)} \end{align}

By doing this, this means:

• Custom functions from datapacks are loaded twice
• Recipes are reloaded twice, including recipes defined by other plugins

Although this sounds pretty bad (since reloading these things twice can be time consuming, thus contributing to the server start-up time), it is the only way to make custom functions work in Minecraft 1.16 and beyond.

Troubleshooting

This section basically summarizes the list of things that could go wrong with the CommandAPI and how to mitigate these circumstances.

I encounter a NullPointerException when using Bukkit's scoreboard

Shove the scoreboard access inside a lambda, so it is evaluated when commands are executed rather than when the server loads. For example, use:

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
            	
arguments.put("team", new TeamArgument().safeOverrideSuggestions(s ->
    Bukkit.getScoreboardManager().getMainScoreboard().getTeams().toArray(new Team[0]))
);

as opposed to:

LinkedHashMap<String, Argument> arguments = new LinkedHashMap<>();
            	
arguments.put("team", new TeamArgument().safeOverrideSuggestions(
    Bukkit.getScoreboardManager().getMainScoreboard().getTeams().toArray(new Team[0]))
);

Server errors when loading datapacks in 1.16+

If you get an error at the very start of the server's startup sequence along the lines of:

[15:57:29] [Worker-Main-5/ERROR]: Failed to load function mycustomnamespace:test
java.util.concurrent.CompletionException: java.lang.IllegalArgumentException: Whilst parsing command on line 2: Unknown or incomplete command, see below for error at position 0: <--[HERE]
    at java.util.concurrent.CompletableFuture.encodeThrowable(Unknown Source) ~[?:1.8.0_261]
    at java.util.concurrent.CompletableFuture.completeThrowable(Unknown Source) [?:1.8.0_261]
    at java.util.concurrent.CompletableFuture$AsyncSupply.run(Unknown Source) [?:1.8.0_261]
    at java.util.concurrent.CompletableFuture$AsyncSupply.exec(Unknown Source) [?:1.8.0_261]
    at java.util.concurrent.ForkJoinTask.doExec(Unknown Source) [?:1.8.0_261]
    at java.util.concurrent.ForkJoinPool$WorkQueue.runTask(Unknown Source) [?:1.8.0_261]
    at java.util.concurrent.ForkJoinPool.runWorker(Unknown Source) [?:1.8.0_261]
    at java.util.concurrent.ForkJoinWorkerThread.run(Unknown Source) [?:1.8.0_261]
Caused by: java.lang.IllegalArgumentException: Whilst parsing command on line 2: Unknown or incomplete command, see below for error at position 0: <--[HERE]
    at net.minecraft.server.v1_16_R1.CustomFunction.a(SourceFile:62) ~[spigot-1.16.1.jar:git-Spigot-758abbe-8dc1da1]
    at net.minecraft.server.v1_16_R1.CustomFunctionManager.a(SourceFile:84) ~[spigot-1.16.1.jar:git-Spigot-758abbe-8dc1da1]
    ... 6 more

You can safely ignore it - the CommandAPI fixes this later. This is described in more detail here.

Server/Plugin reloading

Due to the implementation of the CommandAPI, the CommandAPI does not support plugin reloading for plugins that use the CommandAPI. This includes, but is not limited to:

• The /reload command which reloads all plugins on the server
• Plugin reloading plugins, such as PlugMan
• Any form of plugin enabling/disabling process for plugins which register commands via the CommandAPI

Developer's Note:

Plugin reloading gets very complicated with respect to the CommandAPI. Since the loading sequence of Minecraft commands is so picky, reloading the CommandAPI or a plugin which registers commands can cause commands to be re-registered. This can lead to very odd effects, such as command collisions (commands just don't work), to duplicate commands being registered under different namespaces (e.g. plugins are registered under Bukkit as well as Minecraft). These effects are not "100% guaranteed" and have only been seen during dodgy tests. In short, do not enable or reload plugins, and absolutely do not reload the server with /reload

Players cannot connect/timeout when joining

If players cannot connect, this could be due to the size of the command data packet. To see the resultant packet being sent to players when they log in, enable the create-dispatcher-json: true setting and view the file size of the resultant file. If the file size is abnormally large (Over 2MB is considered very large), consider reducing the number of LiteralArguments which your plugin uses.

Command conversion throws a NullPointerException

This is likely caused by the fact that the plugin you want to convert hasn't been loaded yet. Ensure that it loads before your plugin by adding the following to the target plugin's plugin.yml file:

loadbefore: [YourPlugin, CommandAPI]

My issue isn't on here, what do I do?!

If you've found a bug that isn't solved here, submit a bug report on the CommandAPI's issues page and I'll try my best to resolve the issue!

Afterword

A message from the CommandAPI's author

Congratulations on making it to the end of the documentation! It's really long, but I did my best to make it the best (Bukkit/Spigot plugin) documentation in existence.

My name is Jorel, commonly known by my Minecraft username Skepter. I started the CommandAPI in the summer holidays between my first and second year at university. On the 19th August, 2018 I made my first commit to the CommandAPI project - just a month and a day after Minecraft 1.13 was released.

At the time, I just decided to call it "The 1.13 Command API" - it wasn't the catchiest name out there, but it sort of said what I wanted it to - it's a Command API for Minecraft 1.13, which was the update when the big overhaul to the command system was introduced.

It all started as a simple idea that can be summarized in 3 bullet points:

• Create an API to use the new command UI that was introduced in Minecraft 1.13
• Make it so the developers don't have to understand/use Mojang's brigadier
• Make it similar to Bukkit's existing API

After the release of version 1.2, two days after the initial release, I received my first GitHub issue. This was quite a shock to me - version 1.2 only had 11 total downloads so it seemed odd that someone managed to stumble upon it despite the fact that I did nothing to promote the CommandAPI. Little did I know that that one issue was the main motivation to keep this API alive after its initial release.

I would never have possible imagined in my wildest dreams that 2 years later, I would still be in contact with them and know that if I had not chosen to create this API, their server would not have survived beyond Minecraft 1.13, let alone Minecraft 1.15, two major Minecraft versions later.

This project has been insane. Absolutely, utterly insane. At over 570 commits and over 450,000 additions (that includes things such as lines of code, lines of generated HTML documentation etc.), I can say without a doubt that this is indeed my biggest project ever.

Anyway, I digress. I'd like to give credit to all of the people that have opened issues on the CommandAPI GitHub, for without these people, the CommandAPI would have only remained a shadow of what it is now. I'd also like to give credit to the people that have starred the CommandAPI on its GitHub page.

I would like to personally give thanks to the following people - these are people that have made a significant contribution to the project in terms of ideas or support:

• Combustible, who kickstarted the project by creating the CommandAPI's first issue. From this issue, this allowed the CommandAPI to have interoperability with Minecraft commands and functions which is by far the CommandAPI's most admirable feature. Additionally, Combustible helped raise awareness of the CommandAPI via the Spigot forums and Spigot issue tracker.
• Draycia, who suggested implementing lazy evaluation for argument suggestions. This has been extended to provide the CommandAPI's context-aware system for argument suggestions based on previously filled arguments.
• HielkeMinecraft, who made three outstanding contributions to the CommandAPI. They created the suggestion of setting the result and success values of commands which improves the interoperability between commands registered with the CommandAPI and vanilla Minecraft commands. They also influenced the implementation of the requirements system to have more powerful command constraints and helped start the CommandAPI Discord server.
• Minenash, who was the driving force for the CommandAPI's 3.0 release, which added a plethora of new arguments to the CommandAPI. Minenash's research, code prototypes, documentation examples, bug testing and code review was a tremendous help to make the 3.0 release such a feature-rich version.
• Michael-Ziluck, who created an amazing pull request that helped greatly improve the performance of the CommandAPI as well as structure the entire CommandAPI project into a multi-module Maven project which significantly improved the maintainability of the CommandAPI for the future.

I'd also like to give a special mention to the following people that have helped find bugs or have supported the project in some way: aianlinb, Baka-Mitai, Checkium, Comeza, DerpNerb, DogeBogey, endrdragon, EnragedRabisu, i509VCB, KieranGateley, lifespan, Loapu, Marvmallow, MatrixTunnel, portlek, Ricky12Awesome, SHsuperCM, SpaceCheetah, The_Gavster, Tinkot, vladfrangu, zedwick

I never really expected more than 5 or so people to use this API, so it was truly a pleasure to see everyone's responses, issues and suggestions that has made the CommandAPI what it is today.

Thank you so much for using the CommandAPI!