Dispatchers

Dispatchers, as mentioned on the concepts page, contain a list of registered commands.

Currently, Intake only provides one dispatcher, SimpleDispatcher. It can be created easily:

Dispatcher dispatcher = new SimpleDispatcher();

Registering

To register a command, first, implement your command as a CommandCallable (or see Parametric builder to use the annotation method) and then you use the registerCommand() method on a dispatcher. The register method takes a callable and a vararg list of command aliases, where the first alias is the name of the command.

registerCommand(new TeleportCommand(), "teleport", "tp");

The list of command aliases is a String[], but here we use Java's varags and enter "teleport", "tp".

Warning: Currently, you cannot replace existing commands in SimpleDispatcher. This is not a result of some major limitation -- rather, it simply has not been implemented yet. Attempting to re-register a command will result in an IllegalArgumentException exception.

Calling

Since every dispatcher is also a callable command, we can use the call() method to execute commands that have been registered in a dispatcher.

Let's see an example of how the command /tp bob would be dispatched below.

dispatcher.call("tp bob", locals, new String[0]);

The first parameter is the arguments as a string and without the command prefix (/, !, ., or whatever it may be). The reason for this is because the prefix may vary, and because this design allows you to register this dispatcher itself as a sub-command, as seen below.

Dispatcher dispatcher2 = new SimpleDispatcher();
dispatcher2.registerCommand(dispatcher, "admin");

That results in the registered command of /admin tp bob.

The second argument, locals, is an instance of CommandLocals (see the command locals page).

Lastly, the third argument is a list of parent commands. In this case, because /tp is a root command, we pass an empty String[0]. The teleport command will actually get ["tp"] for the parent commands array, and if you have deeper sub-commands, such as a theoretical /admin tp player, it would receive ["admin", "tp"] for the array of parent commands.

More information about handling exceptions, errors, and so on is described in the Handling exceptions. In addition, Implementing help may be of interest.

Sub-commands

As mentioned previously, to make a sub-command, simply register one dispatcher under another, like you would any other command.

SimpleDispatcher behavior

If you choose to use SimpleDispatcher, be aware of the following behavior:

• If there is no sub-command found, then a InvalidUsageException exception is thrown with some message along the lines of "can't find that sub-command" and it provides itself as the command.
• If no sub-commands are even registered, then a InvalidUsageException exception is thrown with some message along the lines of "there are no sub-commands" and it provides itself as the command.
• getSuggestions() will return sub-commands for tab completion.
• testPermission() (of CommandCallable) will return true if there is at least one command that also returns true. Otherwise, false is returned. This means that if the dispatcher is put under another one, it will "disappear" from help lists (if you implement your help lists so they check permissions) if there is no usable sub-command.