Creating simple commands

Commands are a big part of a SA:MP Gamemode / Filterscript, and that’s why we put a lot of time into our CommandManager to make it as easy and enjoyable as possible.

You need to add the following dependency to your pom.xml (you might have to change the version):

<dependency>
    <groupId>net.gtaun</groupId>
    <artifactId>shoebill-common</artifactId>
    <version>1.3-SNAPSHOT</version>
</dependency>

After your IDE has downloaded the dependency, you can start using the full power of shoebill-common, including the PlayerCommandManager.

Setup

First, you will have to create an instance of the PlayerCommandManager class. The constructor requires an EventManager instance as the only parameter which you can get by calling getEventManager() from your main class:

PlayerCommandManager commandManager = new PlayerCommandManager(getEventManager());

After you got your PlayerCommandManager instance, you need to install a command handler:

commandManager.installCommandHandler(HandlerPriority.NORMAL);

This will define when your command manager will take action. I recommend using a priority of „NORMAL“. After you installed your CommandHandler, you can start creating your class where your commands will be handled. I recommend choosing a name that is easy to understand and summarizes your class. I will use „PlayerCommands“ as my class name, because I will store commands in this class that are related to players, such as /pm and /givemoney.

public class PlayerCommands {
    
}

Right now, we got an empty class with no command in it. The command manager will search for methods that are annotated with the @Command annotation and generate a CommandHandler for it automatically. We will now create a simple /pm command that will send a message from player A to player B.

Requirements for a Command Handler

A Command Handler method needs to fulfill three requirements:

• The method has to be annotated with the @Command annotaton.
• The method must be returning a boolean.
• The first parameter of the method needs to be a variable of the type Player.

The method’s name will at the same time be the command’s name. So, if we want to make a command that will be invoked like this: „/pm (Player) (Message)“ we will have to call our method „pm“. Also, our method’s signature must contain two players (playerid and targetid) and one String for the message:

@Command
public boolean pm(Player player, Player target, String message) {
        
}

This is our command now. We will have to add a return at the end of the method that will determine if the command chain should be interrupted or not. We will have to check if the target player is even connected and if the message is longer or equal one character. Our method now looks like this:

@Command
public boolean pm(Player player, Player target, String message) {
    if(target == null) { //Check if the target is not online.
        player.sendMessage(Color.RED, "* The target is not connected to this server!"); //Send message that the target is offline.
        return true; //Interrupt the further execution of this command handler chain because we handled the command.
    }
    if(message.isEmpty()) { //Check if the message is empty
        player.sendMessage(Color.RED, "* The message you supplied is empty!"); //Send message that the supplied message is empty.
        return true; //Interrupt the further execution of this command handler chain because we handled the command.
    }

    return true;
}

We now have all of the needed checks in our command that will prevent the user from causing exceptions, and now we should implement the main part. The target should get a chat-message that contains the message the player added to the command. The player that issued this command should also get a similar message to see that the message got send successfully. We will use the sendClientMessage() function:

target.sendMessage(Color.LIGHTBLUE, "* Message from " + player.getName() + ": " + message); //Send message to target.
player.sendMessage(Color.LIGHTGREEN, "* " + target.getName() + " received: " + message); //Send confirmation to player.

Our class now looks like this and is ready for action:

import net.gtaun.shoebill.common.command.Command;
import net.gtaun.shoebill.data.Color;
import net.gtaun.shoebill.object.Player;


public class PlayerCommands {

    @Command
    public boolean pm(Player player, Player target, String message) {
        if(target == null) { //Check if the target is not online.
            player.sendMessage(Color.RED, "* The target is not connected to this server!"); //Send message that the target is offline.
            return true; //Interrupt the further execution of this command handler chain because we handled the command.
        }
        if(message.isEmpty()) { //Check if the message is empty
            player.sendMessage(Color.RED, "* The message you supplied is empty!"); //Send message that the supplied message is empty.
            return true; //Interrupt the further execution of this command handler chain because we handled the command.
        }
        target.sendMessage(Color.LIGHTBLUE, "* Message from " + player.getName() + ": " + message); //Send message to target.
        player.sendMessage(Color.LIGHTGREEN, "* " + target.getName() + " received: " + message); //Send confirmation to player.
        return true;
    }

}

Registering the class to the CommandManager

We now have a class, but our class is not yet registered to the CommandManager. To do this, we have to call the registerCommands() method on our PlayerCommandManager’s instance:

commandManager.registerCommands(new PlayerCommands()); //register an instance of our newly created PlayerCommands class.

That’s it! You can now use /pm to send messages directly to other players.