CommandAPI 9.7.0
An API for the command UI introduced in Minecraft 1.13
|
The core command dispatcher, for registering, parsing, and executing commands. More...
Public Member Functions | |
CommandDispatcher (final RootCommandNode< S > root) | |
Create a new CommandDispatcher with the specified root node. More... | |
CommandDispatcher () | |
Creates a new CommandDispatcher with an empty command tree. | |
LiteralCommandNode< S > | register (final LiteralArgumentBuilder< S > command) |
Utility method for registering new commands. More... | |
void | setConsumer (final ResultConsumer< S > consumer) |
Sets a callback to be informed of the result of every command. More... | |
int | execute (final String input, final S source) throws CommandSyntaxException |
Parses and executes a given command. More... | |
int | execute (final StringReader input, final S source) throws CommandSyntaxException |
Parses and executes a given command. More... | |
int | execute (final ParseResults< S > parse) throws CommandSyntaxException |
Executes a given pre-parsed command. More... | |
ParseResults< S > | parse (final String command, final S source) |
Parses a given command. More... | |
ParseResults< S > | parse (final StringReader command, final S source) |
Parses a given command. More... | |
String[] | getAllUsage (final CommandNode< S > node, final S source, final boolean restricted) |
Gets all possible executable commands following the given node. More... | |
Map< CommandNode< S >, String > | getSmartUsage (final CommandNode< S > node, final S source) |
Gets the possible executable commands from a specified node. More... | |
CompletableFuture< Suggestions > | getCompletionSuggestions (final ParseResults< S > parse) |
Gets suggestions for a parsed input string on what comes next. More... | |
CompletableFuture< Suggestions > | getCompletionSuggestions (final ParseResults< S > parse, int cursor) |
Gets suggestions for a parsed input string on what comes next, checking from the given cursor position. More... | |
RootCommandNode< S > | getRoot () |
Gets the root of this command tree. More... | |
Collection< String > | getPath (final CommandNode< S > target) |
Finds a valid path to a given node on the command tree. More... | |
CommandNode< S > | findNode (final Collection< String > path) |
Finds a node by its path. More... | |
void | findAmbiguities (final AmbiguityConsumer< S > consumer) |
Scans the command tree for potential ambiguous commands. More... | |
Static Public Attributes | |
static final String | ARGUMENT_SEPARATOR = " " |
The string required to separate individual arguments in an input string. More... | |
static final char | ARGUMENT_SEPARATOR_CHAR = ' ' |
The char required to separate individual arguments in an input string. More... | |
The core command dispatcher, for registering, parsing, and executing commands.
<S> | a custom "source" type, such as a user or originator of a command |
com.mojang.brigadier.CommandDispatcher< S >.CommandDispatcher | ( | final RootCommandNode< S > | root | ) |
Create a new CommandDispatcher with the specified root node.
This is often useful to copy existing or pre-defined command trees.
root | the existing RootCommandNode to use as the basis for this tree |
int com.mojang.brigadier.CommandDispatcher< S >.execute | ( | final ParseResults< S > | parse | ) | throws CommandSyntaxException |
Executes a given pre-parsed command.
If this command returns a value, then it successfully executed something. If the execution was a failure, then an exception will be thrown. Most exceptions will be of type CommandSyntaxException
, but it is possible that a RuntimeException
may bubble up from the result of a command. The meaning behind the returned result is arbitrary, and will depend entirely on what command was performed.
If the command passes through a node that is CommandNode#isFork()
then it will be 'forked'. A forked command will not bubble up any CommandSyntaxException
s, and the 'result' returned will turn into 'amount of successful commands executes'.
After each and any command is ran, a registered callback given to setConsumer(ResultConsumer)
will be notified of the result and success of the command. You can use that method to gather more meaningful results than this method will return, especially when a command forks.
parse | the result of a successful parse(StringReader, Object) |
CommandSyntaxException | if the command failed to parse or execute |
RuntimeException | if the command failed to execute and was not handled gracefully |
int com.mojang.brigadier.CommandDispatcher< S >.execute | ( | final String | input, |
final S | source | ||
) | throws CommandSyntaxException |
Parses and executes a given command.
This is a shortcut to first parse(StringReader, Object)
and then execute(ParseResults)
.
It is recommended to parse and execute as separate steps, as parsing is often the most expensive step, and easiest to cache.
If this command returns a value, then it successfully executed something. If it could not parse the command, or the execution was a failure, then an exception will be thrown. Most exceptions will be of type CommandSyntaxException
, but it is possible that a RuntimeException
may bubble up from the result of a command. The meaning behind the returned result is arbitrary, and will depend entirely on what command was performed.
If the command passes through a node that is CommandNode#isFork()
then it will be 'forked'. A forked command will not bubble up any CommandSyntaxException
s, and the 'result' returned will turn into 'amount of successful commands executes'.
After each and any command is ran, a registered callback given to setConsumer(ResultConsumer)
will be notified of the result and success of the command. You can use that method to gather more meaningful results than this method will return, especially when a command forks.
input | a command string to parse & execute |
source | a custom "source" object, usually representing the originator of this command |
CommandSyntaxException | if the command failed to parse or execute |
RuntimeException | if the command failed to execute and was not handled gracefully |
int com.mojang.brigadier.CommandDispatcher< S >.execute | ( | final StringReader | input, |
final S | source | ||
) | throws CommandSyntaxException |
Parses and executes a given command.
This is a shortcut to first parse(StringReader, Object)
and then execute(ParseResults)
.
It is recommended to parse and execute as separate steps, as parsing is often the most expensive step, and easiest to cache.
If this command returns a value, then it successfully executed something. If it could not parse the command, or the execution was a failure, then an exception will be thrown. Most exceptions will be of type CommandSyntaxException
, but it is possible that a RuntimeException
may bubble up from the result of a command. The meaning behind the returned result is arbitrary, and will depend entirely on what command was performed.
If the command passes through a node that is CommandNode#isFork()
then it will be 'forked'. A forked command will not bubble up any CommandSyntaxException
s, and the 'result' returned will turn into 'amount of successful commands executes'.
After each and any command is ran, a registered callback given to setConsumer(ResultConsumer)
will be notified of the result and success of the command. You can use that method to gather more meaningful results than this method will return, especially when a command forks.
input | a command string to parse & execute |
source | a custom "source" object, usually representing the originator of this command |
CommandSyntaxException | if the command failed to parse or execute |
RuntimeException | if the command failed to execute and was not handled gracefully |
void com.mojang.brigadier.CommandDispatcher< S >.findAmbiguities | ( | final AmbiguityConsumer< S > | consumer | ) |
Scans the command tree for potential ambiguous commands.
This is a shortcut for CommandNode#findAmbiguities(AmbiguityConsumer)
on getRoot()
.
Ambiguities are detected by testing every CommandNode#getExamples()
on one node verses every sibling node. This is not fool proof, and relies a lot on the providers of the used argument types to give good examples.
consumer | a callback to be notified of potential ambiguities |
CommandNode< S > com.mojang.brigadier.CommandDispatcher< S >.findNode | ( | final Collection< String > | path | ) |
Finds a node by its path.
Paths may be generated with getPath(CommandNode)
, and are guaranteed (for the same tree, and the same version of this library) to always produce the same valid node by this method.
If a node could not be found at the specified path, then null
will be returned.
path | a generated path to a node |
String[] com.mojang.brigadier.CommandDispatcher< S >.getAllUsage | ( | final CommandNode< S > | node, |
final S | source, | ||
final boolean | restricted | ||
) |
Gets all possible executable commands following the given node.
You may use getRoot()
as a target to get all usage data for the entire command tree.
The returned syntax will be in "simple" form: <param>
and literal
. "Optional" nodes will be listed as multiple entries: the parent node, and the child nodes. For example, a required literal "foo" followed by an optional param "int" will be two nodes:
foo
foo <int>
The path to the specified node will not be prepended to the output, as there can theoretically be many ways to reach a given node. It will only give you paths relative to the specified node, not absolute from root.
node | target node to get child usage strings for |
source | a custom "source" object, usually representing the originator of this command |
restricted | if true, commands that the source cannot access will not be mentioned |
CompletableFuture< Suggestions > com.mojang.brigadier.CommandDispatcher< S >.getCompletionSuggestions | ( | final ParseResults< S > | parse | ) |
Gets suggestions for a parsed input string on what comes next.
As it is ultimately up to custom argument types to provide suggestions, it may be an asynchronous operation, for example getting in-game data or player names, reading a file, etc. As such, this method returns a future and no guarantees are made to when or how the future completes.
The suggestions provided will be in the context of the end of the parsed input string, but may suggest new or replacement strings for earlier in the input string. For example, if the end of the string was foobar
but an argument preferred it to be minecraft:foobar
, it will suggest a replacement for that whole segment of the input.
parse | the result of a parse(StringReader, Object) |
Suggestions
object CompletableFuture< Suggestions > com.mojang.brigadier.CommandDispatcher< S >.getCompletionSuggestions | ( | final ParseResults< S > | parse, |
int | cursor | ||
) |
Gets suggestions for a parsed input string on what comes next, checking from the given cursor position.
As it is ultimately up to custom argument types to provide suggestions, it may be an asynchronous operation, for example getting in-game data or player names, reading a file, etc. As such, this method returns a future and no guarantees are made to when or how the future completes.
The suggestions provided will be in the context of the end of the parsed input string, but may suggest new or replacement strings for earlier in the input string. For example, if the end of the string was foobar
but an argument preferred it to be minecraft:foobar
, it will suggest a replacement for that whole segment of the input.
parse | the result of a parse(StringReader, Object) |
cursor | the index to fetch suggestions for |
Suggestions
object Collection< String > com.mojang.brigadier.CommandDispatcher< S >.getPath | ( | final CommandNode< S > | target | ) |
Finds a valid path to a given node on the command tree.
There may theoretically be multiple paths to a node on the tree, especially with the use of forking or redirecting. As such, this method makes no guarantees about which path it finds. It will not look at forks or redirects, and find the first instance of the target node on the tree.
The only guarantee made is that for the same command tree and the same version of this library, the result of this method will always be a valid input for findNode(Collection)
, which should return the same node as provided to this method.
target | the target node you are finding a path for |
RootCommandNode< S > com.mojang.brigadier.CommandDispatcher< S >.getRoot | ( | ) |
Gets the root of this command tree.
This is often useful as a target of a com.mojang.brigadier.builder.ArgumentBuilder#redirect(CommandNode)
, getAllUsage(CommandNode, Object, boolean)
or getSmartUsage(CommandNode, Object)
. You may also use it to clone the command tree via CommandDispatcher(RootCommandNode)
.
Map< CommandNode< S >, String > com.mojang.brigadier.CommandDispatcher< S >.getSmartUsage | ( | final CommandNode< S > | node, |
final S | source | ||
) |
Gets the possible executable commands from a specified node.
You may use getRoot()
as a target to get usage data for the entire command tree.
The returned syntax will be in "smart" form: <param>
, literal
, [optional]
and (either|or)
. These forms may be mixed and matched to provide as much information about the child nodes as it can, without being too verbose. For example, a required literal "foo" followed by an optional param "int" can be compressed into one string:
foo [<int>]
The path to the specified node will not be prepended to the output, as there can theoretically be many ways to reach a given node. It will only give you paths relative to the specified node, not absolute from root.
The returned usage will be restricted to only commands that the provided source
can use.
node | target node to get child usage strings for |
source | a custom "source" object, usually representing the originator of this command |
ParseResults< S > com.mojang.brigadier.CommandDispatcher< S >.parse | ( | final String | command, |
final S | source | ||
) |
Parses a given command.
The result of this method can be cached, and it is advised to do so where appropriate. Parsing is often the most expensive step, and this allows you to essentially "precompile" a command if it will be ran often.
If the command passes through a node that is CommandNode#isFork()
then the resulting context will be marked as 'forked'. Forked contexts may contain child contexts, which may be modified by the RedirectModifier
attached to the fork.
Parsing a command can never fail, you will always be provided with a new ParseResults
. However, that does not mean that it will always parse into a valid command. You should inspect the returned results to check for validity. If its ParseResults#getReader()
StringReader#canRead()
then it did not finish parsing successfully. You can use that position as an indicator to the user where the command stopped being valid. You may inspect ParseResults#getExceptions()
if you know the parse failed, as it will explain why it could not find any valid commands. It may contain multiple exceptions, one for each "potential node" that it could have visited, explaining why it did not go down that node.
When you eventually call execute(ParseResults)
with the result of this method, the above error checking will occur. You only need to inspect it yourself if you wish to handle that yourself.
command | a command string to parse |
source | a custom "source" object, usually representing the originator of this command |
ParseResults< S > com.mojang.brigadier.CommandDispatcher< S >.parse | ( | final StringReader | command, |
final S | source | ||
) |
Parses a given command.
The result of this method can be cached, and it is advised to do so where appropriate. Parsing is often the most expensive step, and this allows you to essentially "precompile" a command if it will be ran often.
If the command passes through a node that is CommandNode#isFork()
then the resulting context will be marked as 'forked'. Forked contexts may contain child contexts, which may be modified by the RedirectModifier
attached to the fork.
Parsing a command can never fail, you will always be provided with a new ParseResults
. However, that does not mean that it will always parse into a valid command. You should inspect the returned results to check for validity. If its ParseResults#getReader()
StringReader#canRead()
then it did not finish parsing successfully. You can use that position as an indicator to the user where the command stopped being valid. You may inspect ParseResults#getExceptions()
if you know the parse failed, as it will explain why it could not find any valid commands. It may contain multiple exceptions, one for each "potential node" that it could have visited, explaining why it did not go down that node.
When you eventually call execute(ParseResults)
with the result of this method, the above error checking will occur. You only need to inspect it yourself if you wish to handle that yourself.
command | a command string to parse |
source | a custom "source" object, usually representing the originator of this command |
LiteralCommandNode< S > com.mojang.brigadier.CommandDispatcher< S >.register | ( | final LiteralArgumentBuilder< S > | command | ) |
Utility method for registering new commands.
This is a shortcut for calling RootCommandNode#addChild(CommandNode)
after building the provided command
.
As RootCommandNode
can only hold literals, this method will only allow literal arguments.
command | a literal argument builder to add to this command tree |
void com.mojang.brigadier.CommandDispatcher< S >.setConsumer | ( | final ResultConsumer< S > | consumer | ) |
Sets a callback to be informed of the result of every command.
consumer | the new result consumer to be called |
|
static |
The string required to separate individual arguments in an input string.
|
static |
The char required to separate individual arguments in an input string.