Skip to content
This repository was archived by the owner on Nov 30, 2024. It is now read-only.

Your first Command

xRa1ny edited this page May 23, 2023 · 2 revisions

Creating Commands has always been a struggle with the normal SpigotAPI since you always have to check the length and validity of the parsed command arguments on execution
To create your own Command, you need to create a new class which extends from the RCommand class, lets call it 'MyCommand'

@CommandInfo(name = "mycommand", permission = "permission.command.mycommand", requiresPlayer = false, args = {"arg1", "arg1 %PLAYER%", "arg1 %PLAYER% arg2"})
public class MyCommand extends RCommand {
    @Override
    protected @NotNull CommandReturnState executeBaseCommand(@NotNull CommandSender sender) { // <- Called when only the base command has been executed (/mycommand)
        return RCommandReturnState.SUCCESS; // <- There are currently 3 valid return states, that represent an execution of the command (SUCCESS, INVALID_ARGS, ERROR)
    }

    @Override
    protected @NotNull CommandReturnState executeWithArgs(@NotNull CommandSender sender, @NotNull String args, @NotNull String[] values) {
        return RCommandReturnState.SUCCESS;
    }

    @Override
    protected @NotNull @Unmodifiable List<String> help(@NotNull CommandSender sender) {
        return List.of();
    }
}

As you can see here, we also use an annotation to parse our meta information to our command
Whats interesting about this though, is that we also have an option to specify the arguments of our command...
This field is responsible for specifying all valid arguments on this command in form of a string array

To properly use this, you have to understand how the arguments are being parsed to you...
Whenever you execute a command with arguments, the executeWithArgs() Method will be called...
Lets assume we run the command like so: /mycommand arg1 xRa1ny
Since we defined in our CommandInfo that the arguments arg1 %PLAYER% are valid, we can expect the following inside the executeWithArgs() Method:
Our args parameter will look like this: "arg1 ?" and our values string array like this: xRa1ny

Running a command with an argument that has not been specified in the CommandInfo, it will always be replaced with a ? inside the args parameter
The arguments only know what YOU define, not what a user types in the chat when executing a command
When you run a command with an 'unknown' argument, it will always be put inside the values string array

For instance, lets say we run this command like so: /mycommand test1 test2
What would be the value of args and values?
args: ? ?
values: "test1", "test2"

Now that you know how the command interprets arguments, you only need to know what the help() Method is used for...
This Method defines what to display when running a command with the help argument
For instance /mycommand help
This argument is hard coded into every command and will always be available

And last but not least, TabCompletion!
We all want it but are sick of coding it up...
With the API you dont have to worry about anything TabCompletion related, it gets handled automatically!
Every argument you define in the CommandInfo, gets handled automatically in TabCompletion, removing the step of coding it up yourself!

But now you might ask yourself, what if I want some other user input in my arguments, not only %PLAYER%
Good Question!
The API handles custom arguments very well, you can always make up your own pattern and use it within your arguments
For instance, there is no pattern coded up for %USER% or %TEST% or %123% but we can still use them in our code!
If we use %TEST% our TabComplete will look like this: <TEST>

Oookay, now that we have command creation out of the way, we want to register this command...
So again, we head on over back to our main class and register the command within our onPluginEnable():

public class MyPlugin extends RPlugin {
    @Override
    public void onPluginEnable() {
        getCommandManager().register(new MyCommand());                            // <- Singular command registration
        getCommandManager().registerAll("PACKAGE NAME OF MULTIPLE COMMANDS");     // <- Multiple command registration
    }

    @Override
    public void onPluginDisable() {
        ...
    }
}

Now, after registering the command inside our main class, we also need to add it to our plugin.yml

name: MyPlugin
version: 1.0
main: PACKAGE.TO.YOUR.MAIN.CLASS.MyPlugin
api-version: 1.16
commands:
  mycommand: # <- THIS IS THE COMMAND NAME WE SPECIFIED IN OUR COMMAND INFO ANNOTATION!

DONE!
Thats all we need to create and register a fully functioning command!

Clone this wiki locally