Commands

Commands are the main focus of the SimpleCord framework.

Our goal is to make it as simple as possible to quickly make and register token-based commands while easily providing parameters, so that you, the developer, don't have to rewrite or create new code.

Let's get you started on how to create commands.

---

There are two places you can register a command, on a class and on a method. We will go into detail on how we define the command later, but for now, know that you can slap an @Command annotation onto a class or method, and it will automatically be detected and registered.

Creating A Command

Creating a command through a method is the simplest way to create a command. We will later talk about how to create a command through a Class, but the overriding principles are the same.

First thing, create a class, name it whatever you like. Note: The CommandManager automatically makes the object for you, but the one thing you have to make sure is that you either have no constructors or a constructor with no parameters.

After we create the class, create a method. The main part here is that we must pay attention to what parameters we set for the method, as SimpleCord automatically splits up the user's tokens and passes it when executing the method.

Parameters:

The first parameter should always be a MessageCreateEvent. This should be followed with the rest of your String parameters (for the number of tokens you want to accept).

Let's say we want to have three parameters.

@Command
public void doSomething(MessageCreateEvent e, String argumentOne, String argumentTwo, String argumentThree)

Now, if we execute the command !dosomething one two three, the MessageCreateEvent and the arguments (one, two, three) will automatically be passed to the method, and the code will be executed.

If you want to have the same command accept a different amount of parameters and execute a different bit of code, you can just create another command with the same method name or annotation name.

Let's say, we want to accept any token the user provides (an infinite amount of tokens). This is simple, all we have to do is change the parameters we provide. The first argument must be a String[], and the next is a MessageCreateEvent. Ex. public void doSomething(String[] args, MessageCreateEvent event)

Now let's say that we don't even want to token the user's message. We just want the raw complete String (minus the command). For that, the first argument must be a String, and the next a MessageCreateEvent.

Return Messages:

You can easily reply back using DUtils.sendMessage(e, title, message), but let's say we are even lazy to do that, and we want to return a String or Message and let the system send it for you. Well, you can!

There are two values you can return. You can return a String, and that will be sent back to the channel as plain text, or you can use an EmbedMessage, which contains either a title and text, or your own EmbedBuilder.

Here is a short and sweet example.

@Command
public String ping() { 
   return "pong";
}

Using a class:

Let's say you want to use a class instead of a method. This is generally useful when you have a lot of different parameter amounts and you want to group them.

The difference here is that you put the @Command annotation on the class instead of on the inside methods, and for any command code, you name the method run.

The @Command Annotation

This is the main way you will register a command. The @Command Annotation provides a variety of parameters you can use to define a command. Let's go through them. Note for all examples here, I use the default command prefix !, but remember you can set it to whatever you want.

Note: If you have two of the same command with different parameters, you don't have to have the same parameters on both annotations. You can just put your parameters on one annotation, or even mix it up (they will be merged).

String

• Name | This is the name of the command and how you execute your code. For example, if you set the name to ping, you can use your command by sending a message with !ping. By default, the command name will be set to the class/method name if you don't provide a value.
• Desc | Shorthand for description, it is helpful when telling users what a command does. You can see it in action with the default provided command, !help. It is normally required unless you have disabled default commands.
• Usage + Example | These are also additional parameters that can be used to easily provide your users with knowledge on how to use a command. Try setting the values and testing it out using !help.

Boolean

• Hidden | A parameter to say if the command should be listed on the help page, or hidden.
• ServerOnly | Use if you want to restrict the command to only be used on servers.
• Async | Run the command on a new thread to prevent slowing down detection for other incoming messages. (Use if whatever programming you are executing may take a while to complete)

Arrays

• Aliases (String) | Other aliases you want the command to be executed by. Note: When trying to get a command by name (in code), using its alias won't work.
• Roles (String) | Roles that the user who sends the command must have on the server to execute the command.
• Permissions (PermissionType) | Permissions that the user who sends the command must have on the server to execute the command.

Additionally, if you want to make a command only be able to run by the ServerOwner or the BotOwner, just set that string to the value of roles. This overrides all the roles you have (as it limits the command to one person).

Note: If you have the Roles or Permissions value set to something, you don't need to set serveronly to true. It will be checked regardless.

---

Here is an example of everything you learned combined in one class. Feel free to test it out and experiment with the code.

@Command(desc = "A command for testing purposes", usage = "!test {...}", aliases = {"t", "testing"}, serverOnly = true, roles = "tester")
public class Test {
    public String run(MessageCreateEvent e, String argumentOne) {
        return "One argument test";
    }
    public void run(MessageCreateEvent e, String argumentOne, String argumentTwo) {
        DUtils.sendMessage(e,"Two Argument Test","This is a two argument Test");
    }
    public EmbedMessage run(String[] args, MessageCreateEvent e) {
        return new EmbedMessage("All argument Test","This is an all argument test"); //(Title,Message)
    }
}

For more examples, you can visit the commands section of the main page.