Support and Project Discussion:

• Discord
• Spigot page

Downloads & Documentation:

• All downloads
• Documentation (includes usage for server owners!)

Announcements:

Compatible Minecraft versions:

The list of what version of the CommandAPI you'll need to run on a specific version of Minecraft is as follows:

• Minecraft 1.13.x: CommandAPI v1.0 to 5.12
• Minecraft 1.14.1, 1.14.2: CommandAPI v2.0 to 5.12
• Minecraft 1.14.3, 1.14.4: CommandAPI v2.1 to 5.12
• Minecraft 1.15.x: CommandAPI v2.3a to 5.12
• Minecraft 1.16.1: CommandAPI v3.0 to 5.12
• Minecraft 1.16.2: CommandAPI v4.0 to 5.12
• Minecraft 1.16.3: CommandAPI v4.2 to 5.12
• Minecraft 1.16.4: CommandAPI v5.2 to 5.12
• Minecraft 1.16.5: CommandAPI v5.7 to 7.0.0 or 8.2.0 (Java 17)
• For Minecraft 1.17 or higher, you'll need Java 16 or higher
  • Minecraft 1.17: CommandAPI 6.0.x to 6.4.x (Java 16) or 7.0.0 to 8.1.0 (Java 17)
  • Minecraft 1.17.1: CommandAPI 6.1.x to 6.4.x (Java 16) or 7.0.0 to 8.1.0 (Java 17)
• For Minecraft 1.18 or higher, you'll need Java 17 or higher
  • Minecraft 1.18, 1.18.1: CommandAPI 6.5.2 to 8.1.0
  • Minecraft 1.18.2: CommandAPI 6.5.4 to 8.1.0

This project provides an API to help Bukkit/Spigot developers use the Minecraft 1.13 command UI, which includes:

• Better commands - Prevent players from running invalid commands, making it easier for developers

  

• Better arguments - Easily switch from Location arguments to raw JSON, fully supported with built-in error checking

  

• Support for proxied command senders - Run your command as other entities using /execute as ... run command

  

• Argument tooltips - Let your users know exactly what their command will do

  

• Support for the /execute command - Let your command to be executed by the built in /execute command

• Support for Minecraft's functions - Allow your command to be executed from Minecraft's functions and tags

• No plugin.yml registration - Commands don't need to be registered in the plugin.yml file anymore

• You don't need Brigadier - You don't need to import Brigadier in your projects to use the CommandAPI

• No tracking - The CommandAPI don't collect any stats about its plugin; what you see is what you get!

In addition to all of the above:

• Built-in command converter - Convert regular plugin commands into /execute-compatible ones - no coding experience required!
• Optional compile-time annotation-based framework - Don't like writing lots of code with builders? You don't have to if you don't want to!
• Insanely detailed documentation - Trust me, you've never seen a plugin documentation look so good.

(I always like to see code examples on GitHub repos, so here's what CommandAPI code looks like):

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

List<Argument> arguments = new ArrayList<>();
arguments.add(new EntitySelectorArgument("target", EntitySelector.ONE_PLAYER));
arguments.add(new PotionEffectArgument("potioneffect").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();

new CommandAPICommand("perm")
    .withSubcommand(new CommandAPICommand("group")
        .withSubcommand(new CommandAPICommand("add")
            .withArguments(new StringArgument("permission"))
            .withArguments(new StringArgument("groupName"))
            .executes((sender, args) -> {
                //perm group add code
            })
        )
        .withSubcommand(new CommandAPICommand("remove")
            .withArguments(new StringArgument("permission"))
            .withArguments(new StringArgument("groupName"))
            .executes((sender, args) -> {
                //perm group remove code
            })
        )
    )
    .withSubcommand(new CommandAPICommand("user")
        .withSubcommand(new CommandAPICommand("add")
            .withArguments(new StringArgument("permission"))
            .withArguments(new StringArgument("userName"))
            .executes((sender, args) -> {
                //perm user add code
            })
        )
        .withSubcommand(new CommandAPICommand("remove")
            .withArguments(new StringArgument("permission"))
            .withArguments(new StringArgument("userName"))
            .executes((sender, args) -> {
                //perm user remove code
            })
        )
    )
    .register();

@Command("warp")
public class WarpCommand {
    
    // List of warp names and their locations
    static Map<String, Location> warps = new HashMap<>();
    
    @Default
    public static void warp(CommandSender sender) {
        sender.sendMessage("--- Warp help ---");
        sender.sendMessage("/warp - Show this help");
        sender.sendMessage("/warp <warp> - Teleport to <warp>");
        sender.sendMessage("/warp create <warpname> - Creates a warp at your current location");
    }
    
    @Default
    public static void warp(Player player, @AStringArgument String warpName) {
        player.teleport(warps.get(warpName));
    }
    
    @Subcommand("create")
    @Permission("warps.create")
    public static void createWarp(Player player, @AStringArgument String warpName) {
        warps.put(warpName, player.getLocation());
    }
    
}

plugins-to-convert:
  - Essentials:
    - speed <speed>[0..10]
    - speed <target>[minecraft:game_profile]
    - speed (walk|fly) <speed>[0..10]
    - speed (walk|fly) <speed>[0..10] <target>[minecraft:game_profile]

The CommandAPI can be built easily, but requires copies of the Spigot server jars to be present locally on your machine in order to be compatible with any Minecraft version. The CommandAPI is built using the Maven build tool - if you don't have it, you can download it here.

• Clone the repository using your preferred method, or with the command below:

  git clone https://github.com/JorelAli/CommandAPI.git

• Run mvn

The resulting plugin .jar is found in commandapi-plugin/target/CommandAPI-X.X.X_DATE.jar

The CommandAPI's documentation is built using a custom version of mdBook, a command line tool to create "books" with Markdown. This custom version can be found in my mdBook fork.

• (Optional): Build the CommandAPI first, using the instructions above. The documentation pulls information directly from tests in the source code, so it assumes that those tests compile correctly!

• Get a copy of mdbook fork executable.

  • On Windows, download mdbook-fa5.exe from the mdBook FA5 support release
  • On Linux:

    • Clone my mdBook fork using your preferred method, or with the command below:

      git clone https://github.com/JorelAli/mdBook.git

    • Use git to checkout to the fa5 branch, using the following command:

      git checkout fa5

    • Build the executable with cargo (can be installed using sudo apt-get install cargo on Ubuntu distros), using the following command:

      cargo build

    • Grab the executable mdbook from mdBook/target/debug/

• Navigate to the docssrc folder

• Run mdbook-fa5.exe build (or mdbook build on Linux)

The resulting compiled documentation is found in docs/X.X.X, where X.X.X is specified in the book.toml file's build-dir in the docssrc folder.

This is the current roadmap for the CommandAPI (as of 13th April 2022):

• Future:

  Annotation improvements

  The CommandAPI's annotation system has always been a bit limited and was primarily introduced as a proof-of-concept. In this update, the CommandAPI's annotation system will be improved to be (ideally) as powerful as the non-annotation system and have slightly better type safety, support for non-static methods and better checks to prevent invalid command generation.

  CustomArgument improvements

  The CustomArgument class is fairly flexible, but nowhere near flexible enough. In this update, more attention will be focused on the CustomArgument class to provide it the ability to extend from all other argument types as a base.

  Argument conflict detection

  The CommandAPI simply uses the Brigadier system under the hood. This system is prone to argument conflicts, which is where certain arguments are given priority over other arguments. (For example "hello" and "123" are both valid string arguments, but if you have a command that has a string argument or an integer argument, Brigadier may ignore the integer argument). In this update, the CommandAPI will try to spot potential conflicts and add a warning in the console. The research required for this is also required in order to implement optional arguments (which is not coming out in this release).

  'True' custom arguments and server-side argument implementations

  Through some brief testing of the regex-mod branch and my MinecraftRegexArgumentMod repository, it was discovered that 'true' custom arguments (arguments with a custom implementation of the returned type and parser) are possible with the aid of a client-sided mod. Additionally, this functionality also works without a client-sided mod, assuming this is only used server-side. This can be useful for server-only datapacks, functions and tags, as well as command blocks.