A Bukkit/Spigot API to use the command UI introduced in Minecraft 1.13

Support and Project Discussion:

• Discord
• Spigot page

Downloads & Documentation:

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

Announcements:

💰 The CommandAPI now has a donation link! Feel free to buy me a coffee here!

Compatible Minecraft versions:

1.13 versions	1.13	1.13.1	1.13.2
1.14 versions	1.14 (v2.0+)	1.14.1	1.14.2	1.14.3 (v2.1+)	1.14.4
1.15 versions	1.15 (v2.3a+)	1.15.1	1.15.2
1.16 versions		1.16.1 (v3.0+)	1.16.2 (v4.0+)	1.16.3 (v4.2+)	1.16.4 (v5.2+)	1.16.5 (v5.7+)

---

Purpose

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.

---

Code examples

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

Simple command registration

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

Potion removing, suggesting potions that a player has currently

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

Subcommands

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

Annotation-based commands

@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());
        new IntegerArgument("");
    }
    
}

Command conversion (no compilation required)

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]

---

Building the CommandAPI

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
  

• Go into the folder named CommandAPI (Not to be confused with the folder named CommandAPI, which is what is cloned). You want the folder which contains pom.xml.

• Ensure you have the required spigot server jars (see below)

• Run mvn

Spigot Libraries

To build the CommandAPI, the following versions of Spigot are required:

1.13 versions	1.13	1.13.1	1.13.2
1.14 versions	1.14	1.14.3	1.14.4
1.15 versions	1.15
1.16 versions	1.16.1	1.16.2	1.16.4

These versions of Minecraft must be installed in your local machine's Maven repository (~/.m2). The easiest way to do this is to build them manually using Spigot's BuildTools, as it automatically adds it to the .m2 local repository folder.

Building them using BuildTools + downloadSpigot file (recommended)

• Download the BuildTools.jar file from here
• Make sure you have maven installed on your machine. If not, it can be downloaded from here
• If on Windows:
  • Download the downloadSpigot.bat file (right click this link, save as...) and place it in the same folder as the BuildTools.jar
  • Double click on the downloadSpigot.bat file to run it
• If on Linux/MacOS:
  • Download the downloadSpigot.sh file (right click this link, save as...) and place it in the same folder as the BuildTools.jar
  • Open up a terminal in your folder and make the downloadSpigot.sh file executable by using chmod u+x ./downloadSpigot.sh
  • Run the downloadSpigot file using ./downloadSpigot.sh

Building them using BuildTools + manual command line

• Download the BuildTools.jar file from here and place it in a separate directory
• Use the command java -jar BuildTools.jar --rev <VERSION> to download the specific version of the Spigot.jar you need. For example, to download Spigot for 1.14.4, use java -jar BuildTools.jar --rev 1.14.4

---

Future project plans + timeline

The CommandAPI has somewhat reached a "stable" point in its lifecycle. It can basically do everything that it needs to do and has been able to keep up-to-date with the latest Minecraft versions (e.g. 1.16.5 support released within a day of 1.16.5 being released). The original goal was to release CommandAPI v6.0 sometime early 2021. As you can see, this hasn't happened yet.

So what went wrong? I over-planned v6.0. The plans for v6.0 was so excessive that it brought down motivation and has made such an update seem forever out of reach. For example, this was the list of all features planned for v6.0:

• A better (refined and rewritten) annotation system
• Optional arguments
• A way to add suggestions to existing suggestions
• Help page support
• Namespace support
• More powerful argument sanitization with earlier fail detection
• A continuous integration suite for public access to dev builds
• A testing suite to determine correctness and accuracy of the CommandAPI
• A rewrite of custom arguments
• More full plugin examples
• Conflicting argument research and documentation on how to avoid them

So where do we go from here? It's simple - we do one feature at a time and release one update for each feature. That way, we get more of the new stuff that people want and less of the "absolutely no development is going on". This is the current roadmap for the CommandAPI (as of 22nd Feb 2021):

• CommandAPI v5.9: "Quick" version updating

  Another proof of concept that I want to bring into fruition. Currently, the CommandAPI's version system goes along the lines of: When a new version of Minecraft comes out, you need to update your version of the CommandAPI with the latest version. This is an acceptable solution - it's not unreasonable for the CommandAPI to require a version-specific update when a new version comes out. The downside with this is the CommandAPI is always in constant development, so API changes occur (e.g. deprecation/refactoring of methods etc.) and bugs may be present in later versions. So to avoid this, releases from this point onwards which add additional support for future Minecraft versions will also release with a supported version .class file which can be shoved into your existing setup of the CommandAPI which will allow you to have support for newer versions of Minecraft without needing to update.

  (Of course, this isn't recommended, but it may benefit a few people and I think it's an interesting thing to add).

• CommandAPI v5.10: PaperSpigot support and deprecations

  PaperSpigot have recently announced that they are moving away from the BungeeCord API and it is pretty important that the CommandAPI updates in order to keep up with things. Additionally, PaperSpigot have changed their supported Java version to Java 11, from Java 8. Despite this, to ensure backwards compatibility with older Java versions, the CommandAPI will remain compiled for Java 8.

  Lastly, in this update I want to deprecate a few methods to do with argument suggestions. The CommandAPI has a number of ways of populating argument suggestions using constant values, but more often than not this causes expected issues. As such, these will be deprecated in this version in favour of the existing lambdas. (Don't worry, updating is really really easy!)

• CommandAPI v5.11: 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.

• CommandAPI v5.12: 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.

• CommandAPI v5.13: 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).

• CommandAPI v5.14+: TBD

---

Changelog

Version	Date	Features / Changes
5.8	January 2021	Removed a debug /test command which wasn't supposed to be released!
5.7	January 2021	Add support for Minecraft 1.16.5
5.6	January 2021	Fix bug where plugins that use Aikar's ACF were incompatible with the CommandAPI Add a new configuration option skip-sender-proxy which prevents certain plugins from running properly
5.5	January 2021	Fix bug with annotations where @NeedsOp didn't work if placed on a class Fix bug where entity selector arguments with @ selectors return empty values if the sender is not op
5.4	December 2020	Fix bug where the NBT-API wasn't compatible with the CommandAPI when both are shaded into a plugin
5.3	November 2020	Fix bug where permissions weren't being applied for subcommands and multi literal arguments Adds detection system for command graph conflicts Adds a way to "negate" permissions using .withoutPermission Adds an annotation-based command framework Fix minor documentation inaccuracies Fix bug where converted commands didn't apply multiple parameters The fields in CommandAPICommand can now be accessed via getters and setters
5.2	November 2020	Adds CommandAPI.reloadDatapacks() method to reload datapacks in the same way the CommandAPI does Adds support for Minecraft 1.16.4
5.1	October 2020	Fixes bug where converted commands could not be executed by players ingame Adds withPermission(String) to arguments and CommandAPICommands Adds SimpleFunctionWrapper with helper methods to get functions and tags from ingame, as well as run them without needing to parse them via commands Greatly improve the type-safety of the internal CommandAPI code Move the Brigadier class outside of the CommandAPIHandler class
5.0	October 2020	Note: This version is incompatible with any plugin that used the CommandAPI version 4.3c or below! (See documentation for more information) API improvements: The .withArguments method can now take varargs String tooltips are now much easier to implement for custom objects using IStringTooltip Removes LinkedHashMap for argument registration in favour of List Adds subcommands Adds AngleArgument Arguments can now be omitted from the Object[] args using the method .setListed(). This means Literal arguments can now be "present" in the arguments if desired. Remove lots of reflection calls, so start up should be a little faster Bug fixes: Fixes bug where verbose logging of permission linking was inaccurate Fixes bug where overriding suggestions can break when generating suggestions Fixes bug where null could appear in the suggestions list of arguments CommandAPI's non-verbose logging is now actually quiet Fixes bug where converted commands couldn't be run from the console Fixes bug where LongArgument wouldn't let you use long values as minimum or maximum Command conversion improvements: The Converter.convert() method can now take varargs for arguments Command conversion code that was specific to the CommandAPI plugin is no longer included in the shaded version of the CommandAPI Command conversion in the configuration for server owners can now let server owners apply their own command argument implementations! Documentation improvements: Documentation code examples are now guaranteed to compile The list of CommandAPI arguments to Minecraft argument IDs is now in the documentation CommandAPI-Brigadier improvements: Adds toSuggestions() to the CommandAPI-Brigadier library to convert CommandAPI suggestions into Brigadier's SuggestionProvider CommandAPI-Brigadier library methods got renamed Changed the way literal arguments are constructed in the CommandAPI-Brigadier library - they are no longer unnecessarily registered into the command graph
4.3c	October 2020	Fixes bug where function loading would break because permissions could not be properly computed
4.3b	September 2020	Fixes minor command sender related bugs from 4.3a. Fixes permissions with /execute ... as ... from converted commands
4.3a	September 2020	Fixes a bug where running converted commands via /execute ... as ... wouldn't apply the command sender correctly
4.3	September 2020	Fix bug where resulting command executors with command block senders would not work Improves the power of command conversion by letting you declare CommandAPICommand arguments for conversion Adds support for YAML's "null" for command conversion via the config.yml file, which should be way more comprehensible rather than trailing colons
4.2	September 2020	Adds support for Minecraft 1.16.3 Fixes a bug where shading the CommandAPI and the NBT-API together causes the CommandAPI to incorrectly think that the NBT-API isn't present Fixes a bug where commands with redirects (4.0+ aliases and redirects from /execute) that have two consecutive arguments with suggestions would spam the console and not provide suggestions Adds NativeProxyCommandSender which lets you access the location and world of a command sender via /execute in|positioned|at|facing|rotated
4.1	September 2020	Allows the CommandAPI to be shaded into plugins Adds a way to set hover tooltips for suggestions Adds multi-literal arguments Adds a logo! Adds a new method to the CommandAPI/Brigadier system to easily create Brigadier arguments from CommandAPI arguments Rename maven modules You can view more information about this on the public maven repository
4.0	August 2020	Suggestion overriding can now be populated by Bukkit objects instead of strings Fixes a bug with the FloatRangeArgument where it caused a casting error Adds support for 1.16.2 ChatArgument now works on Minecraft 1.16.2 (still doesn't work on 1.16.1) Adds new arguments: UUIDArgument ItemStackPredicateArgument BlockPredicateArgument Fix bug where CustomArguments break when using the namespaced key flag Adds a list of commands that FunctionWrapper executes which is now accessible Command aliases are now much more efficient Documentation changes (briefly): BlockStateArgument is now documented properly Documentation now has pictures to show you what arguments look like Documentation now has a page dedicated to what doesn't work on what Minecraft version Adds Brigadier support for developers (lets you use the CommandAPI and Brigadier code side by side!) Fixes a bug where Java 12+ had incompatibility issues Adds support for setting arbitrary requirements to arguments and commands
3.4	July 2020	Fix bug with custom recipes not registering in Minecraft 1.16+ Fix bug where command conversion didn't actually register commands Adds command conversion as a built-in feature via the CommandAPI's config.yml
3.3	July 2020	Fixes a bug where functions didn't work in Minecraft 1.16+ Fixes a bug where spigot produces a warning about api-versions
3.2	July 2020	Fixes a bug with .overrideSuggestions() from version 3.1
3.1	July 2020	Fixes bug where command senders didn't work properly, causing commands to not work properly Adds the ability to override suggestions with the information of previously declared argument
3.0	June 2020	Note: This version is incompatible with pre 3.0 versions CommandAPI plugins (See documentation for more information) Complete code refactor to make command syntax slightly more intuitive and consistent Removes lots of reflection to improve performance Adds better documentation Adds JavaDocs Adds support for 1.16.1 Adds new command executors (These let you filter commands based on what type of command executor runs the command): Player command executors Command block command executors Console command executors Entity command executors Proxied command executors Adds new arguments: Axis Argument Biome Argument ChatColor Argument Chat Argument FloatRange Argument IntegerRange Argument Location2D Argument MathOperation Argument NBT Argument (NBTAPI required) Scoreboard arguments: Objective Argument ObjectiveCriteria Argument ScoreboardSlot Argument ScoreHolder Argument Team Argument Time Argument Rotation Argument Environment Argument Removes old arguments: SuggestedStringArgument DynamicSuggestedStringArgument DefinedCustomArguments
2.3a	December 2019	Adds support for Minecraft 1.15, 1.15.1 and 1.15.2
2.3	August 2019	Fixes bug where permissions didn't work Fixes bug where functions weren't working on 1.14.3 and 1.14.4
2.2	July 2019	Adds support for Minecraft 1.13 and 1.13.1 (Funny isn't it? It's called the 1.13 CommandAPI but never supported Minecraft 1.13 until now) Improves support for different versions Adds pointless witty comments into changelog notes Adds 1.13-Command-API-SafeReflection library to greatly improve reliability of reflection calls
2.1	July 2019	Adds RecipeArgument Adds SoundArgument Adds AdvancementArgument Adds LootTableArgument Adds support for 1.14.3 and 1.14.4 Fixes bug where aliases weren't registering properly (#43) Fix documentation for tooltips Improve documentation for dependencies and repositories
2.0.1	May 2019	Fix a bug where Brigadier was required as a dependency to build plugins
2.0	May 2019	Compatibility for 1.14 Major overhaul of the CommandAPI's internals - greatly improves performance Deprecates SuggestedStringArgument, adding overrideSuggestions as an alternative for any argument type Adds CustomArguments, allowing you to create your own ... custom arguments Excludes dependencies from final jar (#40) Adds DefinedCustomArguments - CustomArguments that have been created by yours truly DynamicSuggestedArguments now have access to the CommandSender (#41) Adds Loot Table support
1.8.2	January 2019	Fix bug with PlayerArgument when player cannot be found Adds LocationArgument options for block precision or exact precision
1.8.1	December 2018	Fix permissions for argument from 1.8 Neaten up logging with verbose outputs
1.8	December 2018	Fix bugs where DynamicSuggestedArguments don't work as the last argument Fix support for latest spigot version Adds permissions for arguments Adds support to override suggestions for arguments
1.7.2	December 2018	Fix a bug where default return value was 0 instead of 1, causing issues with commandblocks
1.7.1	December 2018	Fix a bug with permission checks. Other than that, it's the same as 1.7 (in terms of documentation)
1.7	December 2018	Adds DynamicSuggestedStringArguments for dynamically updating suggestions Adds support for success and result values for /execute store Overhaul permissions system so it works properly Note: This version is incompatible with pre-1.7 version CommandAPI plugins
1.6	November 2018	Adds FunctionArguments to handle Minecraft functions Remove useless test code Fix bug with ProxiedCommandSender callee and caller Adds Converter for legacy plugin support Improved performance by caching NMS better than in version 1.5
1.5	October 2018	Adds ChatComponentArgument to handle raw JSON Adds SuggestedStringArgument to suggest strings Adds config file Fix bug where command errors weren't being thrown Improved performance by caching NMS
1.4	October 2018	Fix critical bug where arguments weren't being handled properly Adds GreedyStringArgument Adds various Exception classes
1.3	October 2018	Migrate to Maven Remove unnecessary reflection Adds EntitySelectorArgument Adds LiteralArgument Adds support for ProxiedCommandSender
1.2	August 2018	Adds TextArgument
1.1	August 2018	Adds PlayerArgument Adds ParticleArgument Adds ChatColorArgument Adds EnchantmentArgument Adds LocationArgument Adds EntityTypeArgument Adds permissions support Adds alias support
1.0	August 2018	Initial release