This component simplifies the management of commands with sub-commands and aliases.

Loader class (for loadComponents)

Writing commands๐Ÿ”—

Each sub-command of a command is a class extending Command, with a @CommandInfo annotation to describe the command (name, parameters help, aliases). A zero-arguments constructor is required.

In the Command sub-class, you have to override the run() (and optionally complete()) methods, respectively to execute the command and to auto-complete it.

package fr.zcraft.ztoaster.commands;

import fr.zcraft.zlib.components.commands.Command;
import fr.zcraft.zlib.components.commands.CommandException;
import fr.zcraft.zlib.components.commands.CommandInfo;

@CommandInfo(name = "awesomeness")
public class AwesomeCommand extends Command
    protected void run() throws CommandException
        // Your awesome command here
        sender.sendMessage(ChatColor.GOLD + "Such awesomeness");
        sender.sendMessage(ChatColor.GREEN + "Very grassy");
        sender.sendMessage(ChatColor.GRAY + "Wow.");

Alongside, a few methods are available to easily retrieve and parse parameters, or to send answers. All the attributes (like sender in the example code above) and methods are described in the documentation of the Command class.

Errors are managed with exceptions: if something bad happens, throw a CommandException with the good reason. Methods are here to do that for you, too.

error(String message)To be called if something bad happens.
throwInvalidArgument(String reason)To be called if an argument is invalid (explain why with reason).
playerSender()Returns the sender casted to Player or throws a CommandException with the reason COMMANDSENDER_EXPECTED_PLAYER.
getBooleanParameter(int i)
getDoubleParameter(int i)
getFloatParameter(int i)
getIntegerParameter(int i)
getLongParameter(int i)
getEnumParameter(int i, Class<T> type)
Returns the parameter at the given index casted to the required type, and throws a CommandException with the reason INVALID_PARAMETERS if it's not possible.

Registering commands๐Ÿ”—

When the subcommands are ready, you'll have to register them like this.

// "toaster" is the name of the root command: /toaster ...
Commands.register("toaster", AwesomeCommand.class, AnotherCommand.class);

You can also register shortcut to some subcommands through a simple command; as example, this will execute /toaster awesomeness while executing /awesome or /aw:

Commands.registerShortcut("toaster", AwesomeCommand.class, "awesome", "aw");

Warning! All the main commands must be registered in the plugin.yml file, or an IllegalStateException will be thrown. Here, /toaster and /awesome have to be explicitely registered, as /aw is registered as an alias. ย 

Writing documentation๐Ÿ”—

This component auto-generates the user documentation of the commands, through a description when the command is executed without subcommand and an auto-generated help subcommand.


These preview comes from a real plugin (SpectatorPlus).

Help files๐Ÿ”—

This said, the documentation does not comes from no-where: the help texts are wrote in a help subdirectory of your resources directory (next to the plugin.yml file). You can use ยง-based formatting codes in these files, and new lines are kept.


File locationContent
โ€”The message displayed when the command is called without arguments is auto-generated based on:
  • the subcommands (for the ยซ Usage ยป line in red);
  • the description field in the plugin.yml file (for the other lines).

/command help๐Ÿ”—

File locationContent
help/command.txtContains the main help of a command.
  • The first lines contains the introduction, displayed above the commands list.
  • The other lines contains the help for each subcommand, following this format.
    subcommand:Help of this subcommand
    The order of the subcommands is the one in the Commands.register method.

/command help subcommand๐Ÿ”—

File locationContent
help/command/subcommand.txtContains the blue-prefixed help of a subcommand, displayed below the command usage summary.
The lines are not automatically truncated to fit well in the chat, so avoid lines above 55-60 characters if you don't want to break the blue line.