How to work with Commands

Welcome to BearCommands Wiki!
BearCommands offers a new way to work with Commands and SubCommands that helps to maintain and keep organized your code. In this section we will look into all the opportunities the plugin offers. It is highly advised to read carefully and understand how easily it becomes to create commands with these classes.

Contents
Commands
SubCommands
HelpSubCommand

Commands

The BearCommands classes offered are basically wrappers for the original respective Command classes. Although there are different classes for different platforms, they all share the same structure, constructor and methods:

public BearCommand(Plugin plugin, String name, BearPermission permission, String description, String usageMessage, String... aliases);

As you can see, many parameters are required:

• Plugin plugin, an instance of your plugin main class;
• String name, the name of your command;
• BearPermission permission, the permission of the command (does not accept String);
• String description, the description of your command (later used in HelpSubCommands);
• String usageMessage, the usage of the command (for example /testcommand player name);
• String... aliases, all the other aliases of the command (optional).

We will look into each platform separately, but you can already tell how easier things become by having the same base for multiple systems.

Platforms
Bukkit
BungeeCord
Velocity

Bukkit

If you are working on Bukkit, you will be interested in the BearCommand class. This class directly extends Command and offers an easy way to load and unload commands conveniently.
Here is an example of implementation:

package it.fulminazzo.testplugin.Commands;

import it.angrybear.Bukkit.Commands.BearCommand;
import it.fulminazzo.testplugin.Enums.TestPermission;
import it.fulminazzo.testplugin.TestPlugin;
import org.bukkit.command.CommandSender;
import org.jetbrains.annotations.NotNull;

public class BukkitCommand extends BearCommand<TestPlugin> {

    public BukkitCommand(TestPlugin plugin) {
        super(plugin, "bukkitcommand", TestPermission.PERMISSION, "Description of the command", "/bukkitcommand", "bk");
    }

    @Override
    public boolean execute(@NotNull CommandSender sender, @NotNull String label, @NotNull String[] args) {
        sender.sendMessage("It works!");
        return true;
    }
}

Then, in order to load it, you could create a loadCommands() method in your plugin main class:

/* ... */
@Override
public void loadAll() throws Exception {
    super.loadAll();
    loadCommands();
}

public void loadCommands() {
    new BukkitCommand(this).loadCommand();
}
/* ... */

If your plugin supports dynamic reload (reloading the plugin without shutting down the server) you might also consider the unloadCommand() method that should be called on unload.

BearCommandExecutor

Many of you might be wondering:
"I have been working a lot with the Bukkit/Spigot API, but I have never created commands like this. I always used an implementation of CommandExecutor or TabExecutor, which is much simpler than all this."
Well, BearCommands offers also a way to work with the old executors: BearCommandExecutor. Its functioning is similar to the BearCommand counter part, but, since this is only an executor, less arguments are required:

package it.fulminazzo.testplugin.Commands;

import it.angrybear.Bukkit.Commands.BearCommandExecutor;
import it.fulminazzo.testplugin.Enums.TestPermission;
import it.fulminazzo.testplugin.TestPlugin;
import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.ArrayList;
import java.util.List;

public class BukkitCommandExecutor extends BearCommandExecutor<TestPlugin> {
    
    public BukkitCommandExecutor(TestPlugin plugin) {
        super(plugin, "bukkitcommand", TestPermission.PERMISSION);
    }

    @Override
    public boolean onCommand(@NotNull CommandSender sender, @NotNull Command cmd, @NotNull String label, @NotNull String[] args) {
        sender.sendMessage("It works!");
        return true;
    }

    @Nullable
    @Override
    public List<String> onTabComplete(@NotNull CommandSender sender, @NotNull Command cmd, @NotNull String label, @NotNull String[] args) {
        return new ArrayList<>();
    }
}

Since BearCommandExecutor extends TabExecutor, you can load your executor as you normally would:

/* ... */
@Override
public void onEnable() {
    super.onEnable();
    getCommand("bukkitcommand").setExecutor(new BukkitCommandExecutor(this));
}
/* ... */

BungeeCord

If you are working on BungeeCord, you might check out the BungeeBearCommand class. This class extends the BungeeCord Command class and allows to work on commands how you would usually do with BungeeCord.
Here is an example of implementation:

package it.fulminazzo.testplugin.Commands;

import it.angrybear.Bungeecord.Commands.BungeeBearCommand;
import it.fulminazzo.testplugin.Enums.TestPermission;
import it.fulminazzo.testplugin.TestPluginBungeeCord;
import net.md_5.bungee.api.CommandSender;
import net.md_5.bungee.api.chat.TextComponent;

public class BungeeCordCommand extends BungeeBearCommand<TestPluginBungeeCord> {

    public BungeeCordCommand(TestPluginBungeeCord plugin) {
        super(plugin, "bungeecordcommand", TestPermission.PERMISSION,
                "Description of the command", "/bungeecordcommand", "bg");
    }

    @Override
    public void execute(CommandSender sender, String[] args) {
        sender.sendMessage(new TextComponent("It works!"));
    }
}

Then to load it, you proceed as you would with a BungeeCord normal command:

/* ... */
@Override
public void onEnable() {
    super.onEnable();
    getProxy().getPluginManager().registerCommand(this, new BungeeCordCommand(this));
}
/* ... */

Velocity

If you are working on Velocity, BearCommands provides a Bukkit/BungeeCord way of doing things: you are not required to implement the SimpleCommand class or use the execute(Invocation invocation) method, but you can work with a similar execute function as seen previously.
Example:

package it.fulminazzo.testplugin.Commands;

import com.velocitypowered.api.command.CommandSource;
import it.angrybear.Velocity.Commands.VelocityBearCommand;
import it.angrybear.Velocity.Utils.MessageUtils;
import it.fulminazzo.testplugin.Enums.TestPermission;
import it.fulminazzo.testplugin.TestPluginVelocity;

import java.util.ArrayList;
import java.util.List;

public class VelocityCommand extends VelocityBearCommand<TestPluginVelocity> {
    
    public VelocityCommand(TestPluginVelocity plugin) {
        super(plugin, "velocitycommand", TestPermission.PERMISSION,
                "Description of the command", "/velocitycommand", "vc");
    }

    @Override
    public void execute(CommandSource sender, String label, String[] args) {
        sender.sendMessage(MessageUtils.messageToComponent("It works!"));
    }

    @Override
    public List<String> onTabComplete(CommandSource sender, String label, String[] args) {
        return new ArrayList<>();
    }
}

As you can see, this implementation is very similar to the Bukkit or BungeeCord ones. Note how we used the MessageUtils class to easily create a TextComponent message to send to the player.
As always, to load it you proceed as if you are working with normal Velocity:

/* ... */
@Override
public void onEnable() {
    super.onEnable();
    CommandManager commandManager = proxyServer.getCommandManager();
    commandManager.register(commandManager.metaBuilder("velocitycommand").plugin(this).build(), new VelocityCommand(this));
}
/* ... */

SubCommands

BearCommands offers an easy and elegant way to implement any SubCommands for your plugin. For SubCommands we mean commands that are linked to a "main command", as for example would be in a clan plugin with /clan invite, /clan disband and more. We will take as example the Bukkit version of the plugin, but do keep in mind that all the following features are compatible in BungeeCord and Velocity as well.

BearSubCommand

To start things off, you will need to access the BearSubCommand class (BungeeCord: BungeeBearSubCommand, Velocity: VelocityBearSubCommand).

public BearSubCommand(Plugin plugin, SubCommandable<Plugin> command, String name, BearPermission permission, String description,
        String usage, boolean playerOnly, String... aliases);

We will go through every parameter and describe it:

• Plugin plugin, an instance of your plugin main class;
• SubCommandable<Plugin> command, the command from which the subcommand comes from (do keep in mind that nested SubCommands are allowed);
• String name, the name of your subcommand;
• BearPermission permission, the permission of the subcommand (does not accept String);
• String description, the description of your subcommand (later used in HelpSubCommands);
• String usage, the usage of the subcommand (for example /testcommand testsubcommand player);
• boolean playerOnly, whether or not the subcommand is player only allowed;
• String... aliases, all the other aliases of the subcommand (optional).

You can also omit the ```boolean playerOnly``` parameter, which will set it to false (always allowed).
Let's see an example of use of this class: ```java package it.fulminazzo.testplugin.Commands.SubCommands;

import it.angrybear.Bukkit.Commands.BearSubCommand; import it.angrybear.Bukkit.Interfaces.SubCommandable; import it.angrybear.Enums.BearPermission; import it.fulminazzo.testplugin.Enums.TestPermission; import it.fulminazzo.testplugin.TestPlugin; import org.bukkit.command.Command; import org.bukkit.command.CommandSender;

import java.util.ArrayList; import java.util.List;

public class TestSubCommand extends BearSubCommand {

public TestSubCommand(TestPlugin plugin, SubCommandable<TestPlugin> command) {
    super(plugin, command, "testsubcommand", TestPermission.PERMISSION, "Description of the command",
            "testsubcommand <player>", // No need to specify the command or the /. 
            false, "tsc");
}

@Override
public void execute(CommandSender sender, Command cmd, String[] args) {
    sender.sendMessage("It works!");
}

@Override
public List<String> onTabComplete(CommandSender sender, Command cmd, String[] args) {
    return new ArrayList<>();
}

@Override
public int getMinArguments() {
    return 0;
}

}

As you can see, three methods are required:
- **execute**, which is called when executing the command;
- **onTabComplete**, called when tab completing the command;
- **getMinArguments**, that returns the minimum amount of arguments required by the command.
<br>
You can then add your **SubCommand** to its **main Command/SubCommand** by using the provided method:
```java
/* ... */
public BukkitCommand(TestPlugin plugin) {
    super(plugin, "bukkitcommand", TestPermission.PERMISSION, 
        "Description of the command", "/bukkitcommand", "bk");
    addSubCommands(new TestSubCommand(plugin, this));
}
/* ... */

As of writing this guide, BearCommands does not yet support an automatic system to intercept and interpret any called SubCommand, but it does provide some methods to work with:

• getSubCommand(CommandSender sender, String arg): returns the subcommand specified in "arg" if its name or alias is equal to "arg" and the sender has the permission to execute it;
• getExecutableSubCommands(CommandSender sender): returns a list of subcommands executable by the sender;
• getInternalSubCommands(): returns a list of all added subcommands;
• getExecutableSubCommandsStrings(CommandSender sender): returns a list of names and aliases of subcommands executable by the sender (useful for tab completition).

It is up to the developer to use them conveniently according her/his needs.

HelpSubCommand

Along with Commands and SubCommands, BearCommands also offers a default SubCommand: the HelpSubCommand. This command is thought to be used as a guide for every other subcommand the main command has to offer. Do keep in mind that versions for other platform do exist (BungeeCord: BungeeHelpSubCommand, Velocity: VelocityHelpSubCommand), but we will focus on the Bukkit part.

public HelpSubCommand(Plugin plugin, SubCommandable<Plugin> command,
                    BearPermission permission, String description, String usage,
                    String[] topMessages, String[] subMessages,
                    String noPermission, String subcommandNotFound, 
                    String helpMessage, String... aliases)

The constructor is very similar to a BearSubCommand one, but with some differences:

• Plugin plugin, an instance of your plugin main class;
• SubCommandable<Plugin> command, the command from which the subcommand comes from (do keep in mind that nested SubCommands are allowed);
• BearPermission permission, the permission of the subcommand (does not accept String);
• String description, the description of your subcommand (later used in HelpSubCommands);
• String usage, the usage of the subcommand (for example /testcommand help command);
• String[] topMessages, an array of messages to be sent before sending the list of subcommands with their respective help;
• String[] subMessages, an array of messages to be sent after sending the list of subcommands;
• String noPermission, a message to be sent to the user if she/he tries to lookup information for a denied command;
• String subcommandNotFound, a message to be sent to the user if she/he tries to lookup information for a subcommand that does not exist (supports the placeholder %subcommand% to be replaced with the name of the command);
• String helpMessage, the help format used to send the list of subcommands; it supports various placeholders:
  • %name%: the name of the subcommand;
  • %alias%: the aliases of the subcommand;
  • %permission%: the permission of the subcommand;
  • %min-arguments%: the minimum amount of arguments required from the subcommand;
  • %help%: the description of the subcommand (specified in the constructor);
  • %usage%: the usage of the subcommand (specified in the constructor);
  • %command%: the name of the main command;
  • %subcommands%: the amount of available subcommands;
• String... aliases, all the other aliases of the subcommand (optional).
  Its functioning is basic: the user can either specify no arguments or certain arguments. If some arguments are specified, the plugin will look for all other executable SubCommands that have a name or an alias that equals to one of the given arguments, meaning that the list will only be made of the results of this research. If the user has no permission to execute any command, then the noPermission message is shown. If after the previous search no subcommand is found (meaning the user passed invalid arguments), the subcommandNotFound message is shown. Otherwise, if topMessages it will be shown, then a list of subcommands formatted using helpMessage, and finally subMessages if it is not null or empty.

You can add your **HelpSubCommand** to your **main command** as you would with any other subcommand: ```java /* ... */ public BukkitCommand(TestPlugin plugin) { super(plugin, "bukkitcommand", TestPermission.PERMISSION, "Description of the command", "/bukkitcommand", "bk"); addSubCommands(new TestSubCommand(plugin, this), new HelpSubCommand<>(plugin, this, TestPermission.HELP_PERMISSION, "Description of help command", "help ", new String[]{"Here is the help page:"}, null, "You don't have enough permissions", "Subcommand %subcommand% not found", "- /%usage% : %help% (%aliases%)", "?") ); } /* ... */ ```