Skip to content

Commands System

Jump to bottom
Traqueur edited this page Jul 27, 2024 · 6 revisions

Registering Command

To create a subcommand, extend the Command<T extends JavaPlugin> or SimpleCommand class and implement the execute method.

The Command<T extends JavaPlugin> class is a generic class that provides a more powerful and flexible framework for creating commands. By extending this class, you gain access to a variety of features of your own plugin's main class.

The SimpleCommand class is a straightforward, easy-to-use base class for creating commands. It is designed to be simple. It's optimal for developers doesb' understend generic type or for simple plugin.

Then use registerCommand from CommandManager.

Example:

public class HelloCommand extends Command<JavaPlugin> {

    public HelloCommand(JavaPlugin plugin) {
        super(plugin, "hello");
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        sender.sendMessage("Hello World !");
    }
}
public class MyPlugin extends JavaPlugin {

    private CommandManager commandManager;

    @Override
    public void onEnable() {
        commandManager = new CommandManager(this);
        commandManager.registerCommand(new HelloCommand(this));
    }
}

Command Class Methods Explained

The Command<T extends JavaPlugin> class in CommandsAPI provides several methods to customize and define the behavior of your commands. This section explains the methods setUsage, setPermission, addAlias, setGameOnly, and setDescription.

setUsage

The setUsage method sets the usage message for the command. This message is typically displayed when a user provides incorrect arguments or asks for help with the command.

Syntax:

public final void setUsage(String usage)

Parameters:

  • usage - A String representing the correct usage of the command.

Example:

public class MyCommand extends Command<MyPlugin> {

    public MyCommand(MyPlugin plugin) {
        super(plugin, "mycommand");
        setUsage("/mycommand <args>");
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        sender.sendMessage("Executing my custom command!");
    }
}

setPermission

The setPermission method sets the permission required to execute the command. This allows you to control who can use the command based on their permissions. CommandsAPI check for you if sender has the permission.

Syntax:

public final void setPermission(String permission)

Parameters:

  • permission - A String representing the required permission node for the command.

Example:

public class MyCommand extends Command<MyPlugin> {

    public MyCommand(MyPlugin plugin) {
        super(plugin, "mycommand");
        setPermission("myplugin.mycommand.use");
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        sender.sendMessage("Executing my custom command!");
    }
}

addAlias

The addAlias method adds aliases for the command. Aliases are alternative names that can be used to execute the command.

Syntax:

public final void addAlias(String... aliases)

Parameters:

  • aliases - One or more String values representing the aliases for the command.

Example:

public class MyCommand extends Command<MyPlugin> {

    public MyCommand(MyPlugin plugin) {
        super(plugin, "mycommand");
        addAlias("mc", "mycmd");
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        sender.sendMessage("Executing my custom command with alias support!");
    }
}

You can run /mycommand, /mc, /mycmd

setGameOnly

The setGameOnly method specifies whether the command can only be used in-game. If set to true, the command will not be executable from the console. CommandsAPI check for you this condition and handle error message if console use the command.

Syntax:

public final void setGameOnly(boolean gameOnly)

Parameters:

  • gameOnly - A boolean value where true means the command can only be used in-game, and false means it can be used both in-game and from the console.

Example:

public class MyCommand extends Command<MyPlugin> {

    public MyCommand(MyPlugin plugin) {
        super(plugin, "mycommand");
        setGameOnly(true);
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        sender.sendMessage("Executing my in-game only command!");
    }
}

setDescription

The setDescription method sets the description of the command. This description is typically displayed in help menus or when a user requests information about the command.

Syntax:

public final void setDescription(String description)

Parameters:

  • description - A String representing the description of the command.

Example:

public class MyCommand extends Command<MyPlugin> {

    public MyCommand(MyPlugin plugin) {
        super(plugin, "mycommand");
        setDescription("A custom command for demonstration purposes.");
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        sender.sendMessage("Executing my custom command with a description!");
    }
}

Registering Subcommands

To create a subcommand, extend the Command or SimpleCommand class and implement the execute method. Then, add the subcommand to the parent command using the addSubcommand method. The framework will automatically handle the subcommand routing for you.

Example: The name of the subcommand is "sub" and the parent command is "hello".

Creating a Subcommand

First, create the subcommand by extending the Command class and implementing the execute method:

public class SubCommand extends Command<JavaPlugin> {

    public SubCommand(JavaPlugin plugin) {
        super(plugin, "sub");
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        sender.sendMessage("This is a subcommand!");
    }
}

Next, add the subcommand to the parent command:

public class HelloCommand extends Command<JavaPlugin> {

    public HelloCommand(JavaPlugin plugin) {
        super(plugin, "hello");
        addSubcommand(new SubCommand(plugin));
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        sender.sendMessage("This is the parent command!");
    }
}

With this example, you can run /hello or /hello sub and it will display the corresponding message.

Registering Only the Subcommand

If you only want the /hello sub command and not the /hello command, you can register the subcommand using a dotted notation:

public class SubWithDotCommand extends Command<JavaPlugin> {

    public SubWithDotCommand(JavaPlugin plugin) {
        super(plugin, "hello.sub");
        setDescription("A subcommand");
        setUsage("/hello sub");
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        sender.sendMessage("This is a subcommand!");
    }
}

The framework will automatically parse the dots in the command name and create the subcommand for you. You only need to register the parent command, and the framework will automatically register the subcommands.

Registering Commands

To register your commands, use the CommandManager in your plugin's onEnable method:

public class MyPlugin extends JavaPlugin {

    private CommandManager commandManager;

    @Override
    public void onEnable() {
        commandManager = new CommandManager(this);
        commandManager.registerCommands(new HelloCommand(this));
    }
}

or, if you're using the dotted notation:

public class MyPlugin extends JavaPlugin {

    private CommandManager commandManager;

    @Override
    public void onEnable() {
        commandManager = new CommandManager(this);
        commandManager.registerCommands(new SubWithDotCommand(this));
    }
}

With these examples, you can easily create and manage both parent and subcommands in your plugin.

Keep in mind, the permission is for a specific node of a permission, so if subcommand have a permission and the player have not the permission, the subcommand doesn't run. Aliases work for subcommand if the main command have aliases you can run /alias subcommand.

Command Unregistration

You can unregister commands using either the command name or its instance. Additionally, you have the option to unregister only the main command or include all its subcommands. This flexibility helps in maintaining a clean and organized command structure.

To unregister a command, use the CommandManager methods:

unregisterCommand(String label, boolean subcommands) or unregisterCommand(Command<?> command, boolean subcommands)

Or their overloaded versions:

unregisterCommand(String label) or unregisterCommand(Command<?> command)

Alternatively, you can directly call the methods in the Command class:

unregister(boolean subcommands) or unregister()

Exemple:

public class HelloCommand extends Command<MyPlugin> {

    public HelloCommand(MyPlugin plugin) {
        super(plugin, "hello");
    }

    @Override
    public void execute(CommandSender sender, Arguments args) {
        sender.sendMessage("Hello World!");
    }
}
public class MyPlugin extends JavaPlugin {

    private CommandManager commandManager;
    private HelloCommand helloCommand;

    @Override
    public void onEnable() {
        commandManager = new CommandManager(this);
        
        // Registering the "hello" command
        helloCommand = new HelloCommand(this);
        commandManager.registerCommand(helloCommand);

       commandManager.unregisterCommand("hello");
       //or
       commandManager.unregisterCommand(helloCommand);
      //or
      helloCommand.unregister();
    }
}

It's important to note that unregisterCommand(String label) does not unregister all aliases of the command, whereas unregisterCommand(Command<?> command) does unregister all aliases.

Clone this wiki locally