3. Creating Commands

The command library would be nothing if there wasn't commands. Below is a very basic, barebones command, which will be broken down bit by bit.

public class BasicCommand extends Command<Object, Object>
{

	public BasicCommand()
	{
		this.setName("greet");

		this.addArgument(new RequiredArgument("name", ParamType.STRING));
	}

	@Override
	public Object onExecute(Object obj, Arguments args)
	{
		String name = args.getString();
                System.out.println("Hello, " + name + "!");

                return obj;
	}
}

The first and most important thing to notice is that this BasicCommand class extends Command. Command is a fundamental class that is provided by Armada for you to begin creating commands. Also notice that Command has generic arguments, both of type Object.

It is important that these type arguments be the EXACT SAME as the command manager you are registering this command with. Otherwise, the command may break during execution.

When extending Command, your class will be forced to implement the onExecute method. This is the most important method of the entire command, as it is where you will execute code based on the given arguments to the command.

Note: The return type of the method takes on the second type argument passed into the Command extension, and the first parameter of the onExecute method takes on the first type argument that is passed in.

Analyze the constructor of the class above:

public BasicCommand()
{
	this.setName("greet");

	this.addArgument(new RequiredArgument("name", ParamType.STRING));
}

Notice that this constructor sets a name for the command. This is a must. If the name of the command is not set, then the command may not execute properly.

This command has a single argument, which is a name. Since the command must take that parameter, it is a RequiredArgument, of a ParamType String.

A command doesn't need an argument; you could very well have a command with no expected arguments, and it will execute all the same.

Analyze the onExecute method:

@Override
public Object onExecute(Object obj, Arguments args)
{
	String name = args.getString();
        System.out.println("Hello, " + name + "!");

        return obj;
}

The most important aspect of this method is the second parameter args. It's type is Arguments, which is a class that is used in containing the arguments a user has passed in.

There are two important things to remember about Arguments. Firstly, it is read only. Data can not be put into the object, only fetched from. Secondly, it works much like an iterator. You retrieve the next value through any of its various get methods, and you can not go back.

Recall how the above class accepts only one argument? If we try to fetch another argument like so:

@Override
public Object onExecute(Object obj, Arguments args)
{
	String name = args.getString();
	String anotherName = args.getString(); // THROWS AN EXCEPTION
        System.out.println("Hello, " + name + "!");

        return obj;
}

By trying to access another argument that is not even there, an Exception occurs. Therefore, it is important that you do not try to read more arguments than what is required. Also note that you must retrieve the arguments in the order that you specified within the constructor. This is only with required arguments, keep in mind. OptionalArgument types are an exception to these rules.

Aliases

Sometimes you may want a command that has multiple names. Instead of registering the same command under multiple names, Armada provides a way for you to assign multiple names to the same command object. These extra names are known as aliases.

With aliases, you can set as many extra names as you want, and the command will function all the same with any of those other names after the prefix.

For the greet command above, we could set multiple aliases like so:

public BasicCommand()
{
	this.setName("greet");
        this.setAliases(new String[] { "hello", "hi", "sup", "greeting", "greetings" });

	this.addArgument(new RequiredArgument("name", ParamType.STRING));
}

Any of these aliases are fine for this command.

Help

Commands come with a help string that can be set. Why would one want to set this? Because the library also comes with a HelpBuilder class, which can take a command and return a formatted string with extreme detail about the command and its usage.

In the constructor, you can call this.setHelp("A helpful string about the command's usage."); to set the help for the command.

Cooldowns

You can set a cooldown for commands in the constructor. For example, you can call this.setGlobalCooldown(3); This sets the cooldown of the command to 3 seconds.

Delays

Commands can also have a delay set for their execution. The delay can be set in the constructor like so: this.setDelay(3); This sets the delay for the command's execution to 3 seconds.

Max Usage

Commands can also be set to have a max usage. Suppose you only want a command to be executed a maximum of 3 times. In the constructor of the command, you can call this.setMaxUsage(3);. Once the command is used 3 times globally, it will no longer execute.