⌨️Commands

Since 1.0.0

This is one of the most powerful yet easy to use features MCUtils has to offer, as now you can register commands that support sub commands, have argument conversion methods, can filter between players or the console and don't require to be added on your plugin.yml (You can still add them optionally). Now let's see how to actually use them.

Creating an MCCommand

As the title suggests, the class used for commands is called MCCommand. MCCommands are linked to and MCPlugin, which is generally the one that will register the command. Let's assume we have an MCPlugin called ClanPlugin for this example.

import net.codersky.mcutils.general.MCCommand;
import net.codersky.clans.ClanPlugin;

public class MainClanCommand extends MCPlugin<ClanPlugin> {

    public MainClanCommand(ClanPlugin plugin) {
        // "awesome" will be the name of the command, "c" will be an alias.
        super(plugin, "clan", "c");
        // Makes this command player only, so the console can't execute it.
        setSenderClass(Player.class);
    }

    @Override
    public boolean onCommand(CommandSender sender, String[] args) {
        // We get the MessagesFileHolder from our plugin and send the
        // message under the "clan.noArgs" path of it to the sender.
        getPlugin().getMessages().send(sender, "clan.noArgs");
    }

    @Override
    public List<String> onTab(CommandSender sender, String[] args) {
        // We just return null as no suggestions will be made by this
        // specific command at this point to the sender.
        return null;
    }
}

About setSenderClass

While this method is useful to restrict players or the console from executing our commands in just one line, you may wonder what message will be displayed to the senders if they aren't allowed to use it. Well, if your MCPlugin has a registered MessagesFileHolder so MCPlugin#getMessages doesn't return null, it will send the message on the path "commands.noPlayer" for players and "commands.noConsole" for the console. If the holder is null, MCUtils will just send "[!] This command cannot be executed by <sender>", where "<sender>" can be either "players" or "the console". You can of course override this behavior with your own by overriding the MCCommand#sendInvalidSenderMsg(CommandSender), where you can send a message to the sender.

Registering commands

Registering commands is very easy and can be done in one line with multiple commands, this is generally done on the onEnable method of your MCPlugin, so that is what we are going to do.

import net.codersky.mcutils.MCPlugin;
import net.codersky.clans.cmd.MainClanCommand;

public class ClanPlugin extends MCPlugin {

    @Override
    public void onEnable() {
        registerCommand(new MainClanCommand(this));
        // You can register multiple commands with #registerCommands.
    }
}

You might have noticed that the plugin.yml file wasn't modified to register this command. That is because with MCUtils this step is not required, but optional, which means that you can still define your commands on your plugin.yml to add a description, aliases or whatever you want to add, but this is no longer required as MCUtils will detect that the command you are trying to register is not present on your plugin.yml and will register it directly to the Bukkit command map by using a bit of reflection.

Limiting access

One important thing we can do to make sure that all playes that execute our MainClanCommand command actually have a clan is to override the hasAccess method as follows, this will NOT break the sender class restrictions.

// MainClanCommand code should go here...

@Override
public boolean hasAccess(CommandSender sender, boolean message) {
    Player receiver = (Player) sender;
    boolean access = getPlugin().getClanManager().getClan(receiver) != null;
    // We send the player a message indicating that they are not on
    // a clan if that is the case and message is set to true.
    if (!access && message)
        getPlugin().getMessages().send(receiver, "clan.noClan");
    return access;
}

The message boolean basically tells you whether you should inform the sender about not having access to the command, this will be false if the method is being called via onTab and true if the method is being called via onCommand, as expected. However, this is not the most optimal way to create conditions for a group of commands, that should be done by creating a generic class for clan commands. Which is what will be explained on the "Custom command class" page.