Commands

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

Documentation: Javadoc
Loader class (for loadComponents): fr.zcraft.quartzlib.components.commands.Commands

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
{
    @Override
    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.

Method	Description
`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.

Preview🔗

These preview comes from a real plugin (SpectatorPlus).

Command executed without sub-command (/command)
Sub-commands global help (/command help)
Detailed help of a sub-command (/command help subcommand)

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.

`/command`🔗

File location	Content
—	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 location	Content
`help/command.txt`	Contains 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 location	Content
`help/command/subcommand.txt`	Contains 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.