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
. However, you can change this defaultminecraft
namespace. More about this on the command registration page. - 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.4.0 \(\rightarrow\) 9.4.1
- Updates Configuration for server owners page with new
skip-initial-datapack-reload
option.
Documentation changes 9.3.0 \(\rightarrow\) 9.4.0
- Updates Shading the CommandAPI in your plugins page with spigot-mapped and mojang-mapped dependencies
- Adds Velocity page to outline how to setup the CommandAPI for Velocity
- Updates CommandArguments to document new additions for safe arguments
- Updates Potion effect arguments to include examples for the newly added
NamespacedKey
variant for thePotionEffectArgument
- Updates Arguments to list the newly added
PotionEffectArgument.NamespacedKey
argument - Updates Particles page to include both old particle information and new particle information
Documentation changes 9.2.0 \(\rightarrow\) 9.3.0
- Updates Incompatible version information page and
FunctionArgument
pages that functions made with theFunctionArgument
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
- Updates Multi literal arguments page to mention new
MultiLiteralArgument
constructor. - Adds CommandArguments page to explain the
CommandArguments
class introduced in 9.0.0 - Adds Adventure chat color argument to the adventure chat arguments page.
- Adds new Command unregistration page.
Documentation changes 9.0.2 \(\rightarrow\) 9.0.3
- Updates Map arguments page with new syntax
Documentation changes 9.0.1 \(\rightarrow\) 9.0.2
- Updates Multi literal arguments page to add the node name information
- Updates Help page so it contains
withUsage()
information
Documentation changes 9.0.0 \(\rightarrow\) 9.0.1
- Updates Optional arguments page to update the method list for avoiding
null
values - Updates Normal command executors page to now mention the existence of the
ExecutionInfo
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:
SoundArgument
s written for 8.6.0 are incompatible with this update! Other significant changes toScoreHolderArgument
andEntitySelectorArgument
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.
- Updated Biome arguments to allow for
NamespacedKey
objects - Updated Sound arguments with the new
NamespacedKey
constructor - Updated Scoreboard arguments with the new
Single
andMultiple
constructors - Updated Entity & player arguments to include the new
OneEntity
,ManyEntities
,OnePlayer
andManyPlayers
constructors
Documentation changes 8.5.1 \(\rightarrow\) 8.6.0
- Greatly improved the format and documentation for Configuration for server owners
- Adds a Kotlin tab to all Java code blocks which displays the equivalent code, but in Kotlin
- Adds the new Command arguments section
- Adds the new World arguments section
- Mentions the new
LiteralArgument.of()
andLiteralArgument.literal()
methods in Literal arguments - Adds a really cool new example to the Brigadier Suggestions page
- Updated various sections (a summary of this can be found in the Upgrading guide):
- Update List arguments to include the new
buildGreedy()
andbuildText()
methods - Update Handling command failures with new methods
- Update Argument suggestions with tooltips with new tooltip methods for formatting text
- Update Sound arguments with support for namespaced keys
- Update List arguments to include the new
- Adds documentation for Kotlin-based commands using the Kotlin DSL
- Update the Afterword, giving special credits to some very special contributors!
Documentation changes 8.5.0 \(\rightarrow\) 8.5.1
- Update Brigadier + CommandAPI with function parameter changes. See Upgrading for more info.
Documentation changes 8.4.0 \(\rightarrow\) 8.5.0
- Adds Chat preview section
- Adds Kotlin-DSL
build.gradle.kts
instructions for using the CommandAPI - Adds
CommandAPI.onDisable()
method to Shading the CommandAPI in your plugins
Documentation changes 8.3.0 \(\rightarrow\) 8.4.0
- Updated Shading with Maven with updated
maven-shade-plugin
version - Adds NamespacedKey arguments section
- Update Argument Casting section with new arguments and types
- Update NBT arguments page with new NBT arguments information
- Update Custom arguments page with new custom arguments information
- Adds Getting a list of registered commands section to the Internal CommandAPI page
- Update Upgrading guide for 8.4.0 changes
Documentation changes 8.2.0 \(\rightarrow\) 8.2.1
- Adds
withSubcommands
method to Subcommands section.
Documentation changes 8.0.0 \(\rightarrow\) 8.2.0
- Adds List arguments section.
- Fix bug with Multiple command executors with the same implementation example.
Documentation changes 7.0.0 \(\rightarrow\) 8.0.0
- Updated particle arguments in the Particle arguments section.
- Update the Upgrading guide for the new changes in 8.0.0.
Documentation changes 6.5.4 \(\rightarrow\) 7.0.0
- Changed the repo that the CommandAPI is served from JitPack to Maven Central.
- Remove direct link to
CommandAPI.jar
file from Installation for server owners, in favor of pointing to the latest release page (to allow version numbers to appear in the file name). - Rewrite the Argument suggestions section to cover the new argument suggestions API.
- Update the Upgrading guide for the new changes in 7.0.0.
- Update repository information in the Shading the CommandAPI in your plugins page.
- Update the Brigadier + CommandAPI page with updated methods.
- Adds an example of using Brgiader's
SuggestionsBuilder
in the Brigadier Suggestions section. - Updated the colors of links, example blocks and warning blocks to meet accessibility contrast guidelines better.
- Adds Command trees section.
- Update Handling command failures to fit new
throw
requirement for command failures. - Updated Normal command executors with the new multiple command executors with the same implementation feature.
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
- Adds Java 16 error to Troubleshooting.
- Update FAQ.
- Adds some useful tools to Command conversion to get plugin info and check
config.yml
validity. - Adds Plugin reloading page which describes how to add minimal support for
/reload
.
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
anduse-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.
- Change the repository URL for the CommandAPI in 5. Setting up your development environment
- Update the Afterword
Documentation changes 5.10 \(\rightarrow\) 5.11
- Adds a section Arbitrary command conversion on how to convert arbitrary commands
- Adds a section 3.3. Entity selectors describing how to convert entity selector commands with the CommandAPI's command conversion system
- Updated the list of all suppoprted argument types for command conversion
Documentation changes 5.6 \(\rightarrow\) 5.10
- Splits chat argument sections into two: 11.5.1. Spigot chat arguments and 11.5.2. Adventure chat arguments
- Adds a FAQ page
- Adds a warning about shading in 6. Shading the CommandAPI in your plugins
Documentation changes 5.3 \(\rightarrow\) 5.6
- Adds a section 4. Skipping proxy senders which describes how to use the
skip-sender-proxy
configuration option.
Documentation changes 5.2 \(\rightarrow\) 5.3
- Adds a section 6. Using the annotation system on setting up your development environment to use the annotation system
- Adds a whole massive section on using annotations (16. Annotation-based commands, 17. Annotations, 18. Registering annotation-based commands)
- Adds a section on argument suggestion deferral in section 9.1. Argument suggestions
- Improve warning for
LiteralArgument
- instead of it being "obsolete" compared to theMultiLiteralArgument
, it is now "more complex" thanMultiLiteralArgument
s - Fix issue in the section for custom arguments which should have been updated but wasn't
Documentation changes 5.1 \(\rightarrow\) 5.2
- Adds brief documentation for the CommandAPI's
reloadDatapacks
method in 16. Internal CommandAPI
Documentation changes 5.0 \(\rightarrow\) 5.1
- Adds a section 10.2. The SimpleFunctionWrapper class which outlines the new
SimpleFunctionWrapper
class - Updates the documentation for 10.3. The FunctionWrapper class
- Update the name of the package from
dev.jorel.commandapi.CommandAPIHandler.Brigadier
todev.jorel.commandapi.Brigadier
in section 17. Brigadier + CommandAPI - Update the documentation for 11. Permissions stating that you can use
withPermission(String)
instead ofwithPermission(CommandPermission)
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:
- New section 3. Command conversion dedicated to command conversion via the
config.yml
- New section 8.4. Listed arguments
- New section 9.8.1. Angle arguments
- New section 14. Subcommands
- New section 16. Internal CommandAPI now lists all arguments and their respective Minecraft argument IDs
- Mentions listed arguments in section 9.11.1. Literal arguments
- Section 15. Command conversion has been rewritten
- Executes native is now present in the command registration page
- Section 8.3. Argument suggestions with tooltips now mentions the
IStringTooltip
class
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
andcompileOnly
- 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 argumentsBlockPredicateArgument
: 7.9.1. Block predicate argumentsItemStackPredicateArgument
: 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 nowcommandapi-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