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 should not be declared in the plugin.yml file.
  • Commands are automatically registered under the minecraft namespace. For example, if you register a command /hello, you can also run it using /minecraft:hello.
  • 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 palette 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 9.2.0 \(\rightarrow\) 9.3.0

  • Updates Incompatible version information page and FunctionArgument pages that functions made with the FunctionArgument will always return 1 when running on 1.20.3 and 1.20.4.
  • Updates Kotlin DSL page to mention every possible executor method.

Documentation changes 9.1.0 \(\rightarrow\) 9.2.0

  • Updates Location arguments page to mention the new centerPosition argument to center the position of integer values for location arguments.
  • Added Delegated properties page to mention the added support of delegations.

Documentation changes 9.0.3 \(\rightarrow\) 9.1.0

Documentation changes 9.0.2 \(\rightarrow\) 9.0.3

Documentation changes 9.0.1 \(\rightarrow\) 9.0.2

Documentation changes 9.0.0 \(\rightarrow\) 9.0.1

Documentation changes 8.8.0 \(\rightarrow\) 9.0.0

Developer's Note:

9.0.0 is a giant update that is incompatible with 8.8.x and prior versions. A lot of the documentation's code examples and explanations have been changed for the various changes made in this version. Please read the Upgrading guide for information on how to upgrade to 9.0.0.

  • Adds the new Optional arguments section
  • Adds Kotlin DSL code examples to all code examples

Documentation changes 8.7.0 \(\rightarrow\) 8.8.0

  • Changed the version number from 8.7.0 to 8.8.0. That's it.

Documentation changes 8.6.0 \(\rightarrow\) 8.7.0

Developer's Note:

SoundArguments written for 8.6.0 are incompatible with this update! Other significant changes to ScoreHolderArgument and EntitySelectorArgument were made in this update. I highly recommend reading the Upgrading guide section which covers the changes in more detail and how to update your plugin for this version.

Documentation changes 8.5.1 \(\rightarrow\) 8.6.0

Documentation changes 8.5.0 \(\rightarrow\) 8.5.1

Documentation changes 8.4.0 \(\rightarrow\) 8.5.0

Documentation changes 8.3.0 \(\rightarrow\) 8.4.0

Documentation changes 8.2.0 \(\rightarrow\) 8.2.1

Documentation changes 8.0.0 \(\rightarrow\) 8.2.0

Documentation changes 7.0.0 \(\rightarrow\) 8.0.0

Documentation changes 6.5.4 \(\rightarrow\) 7.0.0

Documentation changes 6.4.0 \(\rightarrow\) 6.5.4

  • Update the Maven and Gradle pages to say to use CommandAPI version 6.5.4 because this kept confusing everyone.

Documentation changes 6.3.1 \(\rightarrow\) 6.4.0

  • Adds a section Help for the new help feature.
  • Update Annotations section to include new @Help annotation.

Documentation changes 6.3.0 \(\rightarrow\) 6.3.1

Documentation changes 6.2.0 \(\rightarrow\) 6.3.0

  • Update Custom arguments page with new custom argument constructor information
  • Adds upgrade info to the Upgrading guide to help upgrade any existing custom arguments which you may have.

Documentation changes 6.0.0 \(\rightarrow\) 6.2.0

  • Update Configuration for server owners page with new config options missing-executor-implementation and use-latest-nms-version
  • Update instructions for shading the CommandAPI with maven in Shading the CommandAPI in your plugins to support Java 16.
  • Mention that commands registered with the CommandAPI appear in the minecraft: namespace (see above under "How the CommandAPI works")

Documentation changes 5.12 \(\rightarrow\) 6.0.0

  • Adds entry for Upgrading guide to help update from 5.12 to 6.0.0.
  • Adds new silent-logs config entry to Configuration for server owners
  • Update syntax for onLoad(CommandAPIConfig) for Shading the CommandAPI in your plugins
  • Update Argument suggestions including new replaceSuggestions method
  • Adds documentation for OfflinePlayerArgument
  • Adds a new section CommandAPI Contribution which gives a bit of insight into the project structure of the CommandAPI (Still in progress, not complete yet)
  • Fix old documentation typos
  • Fix spacing issues in some existing code blocks
  • Adds syntax highlighting for Minecraft commands in code blocks
  • Fix old code examples which didn't work anymore

Documentation changes 5.11 \(\rightarrow\) 5.12

Developer's Note

The Maven/Gradle repository URL has changed! See 5. Setting up your development environment for more information. For older versions of the CommandAPI (versions 5.11 and below), please consult the older documentation which can be found on the homepage here.

Documentation changes 5.10 \(\rightarrow\) 5.11

Documentation changes 5.6 \(\rightarrow\) 5.10

Documentation changes 5.3 \(\rightarrow\) 5.6

Documentation changes 5.2 \(\rightarrow\) 5.3

Documentation changes 5.1 \(\rightarrow\) 5.2

Documentation changes 5.0 \(\rightarrow\) 5.1

Documentation changes 4.3 \(\rightarrow\) 5.0

Developer's Note:

Lots and lots and lots of changes occurred in version 5.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.

Every page has been rewritten in this update and checked for errors. In general, this is the list of new additions:

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

Documentation changes 4.0 \(\rightarrow\) 4.1

Documentation changes 3.4 \(\rightarrow\) 4.0

Documentation changes 3.3 \(\rightarrow\) 3.4

Documentation changes 3.1 \(\rightarrow\) 3.3

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.