[TUT] Using sk89q's command framework

When looking through GitHub some time ago, I stumbled upon @sk89q's command framework. I have used it in a lot of my plugins now and I can say that it is a awesome system. Here is how to use it!

Step 1: Installing the framework
Option 1: Depending on WorldEdit. This is probably the easiest way to include the framework, but the downside is that the server owner needs WorldEdit installed.
Option 2: Copy all the files from OvercastNetwork/sk89q-command-framework to your project. A way to do it, but not recommended (by me).
Option 3: Add it as a maven dependency and shade it:

pom.xml (open) pom.xml (close)

Code:

//Add the oc.tc (Overcast Network) repo
 
<repository>
    <id>repo.oc.tc</id>
    <url>http://repo.oc.tc/content/repositories/releases/</url>
</repository>
 
 
//Add the dependency
 
<dependency>
    <groupId>com.sk89q</groupId>
    <artifactId>sk89q-command-framework</artifactId>
    <version>0.5</version>
</dependency>
 

Step 2: Adding the onCommand handler
Start by defining a variable in your main class:

Code:java

private CommandsManager<CommandSender> commands;

After that, add this method to initiate your manager

Code:java

private void setupCommands() {
        this.commands = new CommandsManager<CommandSender>() {
            @Override
            public boolean hasPermission(CommandSender sender, String perm) {
                return sender instanceof ConsoleCommandSender || sender.hasPermission(perm);
            }
        };
        CommandsManagerRegistration cmdRegister = new CommandsManagerRegistration(this, this.commands);
        //Register your commands here
} 

Almost done! Now you need one more thing. The onCommand:

Code:java

    @Override
    public boolean onCommand(CommandSender sender, Command cmd, String commandLabel, String[] args) {
        try {
            this.commands.execute(cmd.getName(), args, sender, sender);
        } catch (CommandPermissionsException e) {
            sender.sendMessage(ChatColor.RED + "You don't have permission.");
        } catch (MissingNestedCommandException e) {
            sender.sendMessage(ChatColor.RED + e.getUsage());
        } catch (CommandUsageException e) {
            sender.sendMessage(ChatColor.RED + e.getMessage());
            sender.sendMessage(ChatColor.RED + e.getUsage());
        } catch (WrappedCommandException e) {
            if (e.getCause() instanceof NumberFormatException) {
                sender.sendMessage(ChatColor.RED + "Number expected, string received instead.");
            } else {
                sender.sendMessage(ChatColor.RED + "An error has occurred. See console.");
                e.printStackTrace();
            }
        } catch (CommandException e) {
            sender.sendMessage(ChatColor.RED + e.getMessage());
        }
 
        return true;
    }

That's all the code you'll need in your main class, lets go on and make some commands!

Step 3: The Commands
First, create a new class. You can name it whatever you want.
The Command Structure
Every command method has a @Command annotation, which defines certain aspects of the command. Have a look at this example:

Code:

@Command(aliases = { "hello", "hey" }, desc = "Says hello", usage = "[player] - The player to say hello to", min = 1, max = 1)

This will create a command that can be called with either hello or hey, has the description of "Says hello" in the help list, has a min of 1 arguments and a max of 1 arguments (set to -1 for infinite) and prints the usage ("Usage: /hello [player] - The player to say hello to") on incorrect usage.

After the @Command, you'll need a method like this

Code:java

public static void hello(final CommandContext args, CommandSender sender) throws Exception {

Note that the method can be called anything, as long as it is after a @Command.

Here is an example of the hello command:

Code:java

@Command(aliases = { "hello", "hey" }, desc = "Says hello", usage = "[player] - The player to say hello to", min = 1, max = 1)
public static void hello(final CommandContext args, CommandSender sender) throws CommandException {
    Player target = Bukkit.getPlayer(args.getString(0)); //0 is the index
    if (target == null) throw new CommandException("Player "+args.getString(0)+" not found!");
    target.sendMessage("Hello!");
}

Step 4: Registering your commands
This is probably the easiest step. Remember the setupCommands method in your main class? After all the code that's already in there, call

Code:

cmdRegister.register(MYCOMMANDCLASS.class);

Step 3b: Command tricks
The CommandContext
The CommandContext is an advanced version of String[] args. It allows for some really cool usages. Here are the methods you are most likely using most:
args.getString(index) Gets the string at a certain index
args.getInt(index) Gets the int at a certain index, throws an error message (see the onCommand) if the index is not a string
args.getJoinedStrings(index) Joins all the strings after index. For example, if the player did /hello <player> I am awesome and you are not, args.getJoinedStrings(1) will return I am....
For every get<TYPE> command, you can also supply a default value. For example, if you do args.getInt(0, 10) it'll be 10 if the player did not pass an int at index 0.
For a full documentation on CommandContext, have a look here

Flags!
@Command also allows you to specify flags for the player to pass in! Just add flags="a" in your @Command to allow the player to do /hello -a <player>. You can also require a flag to have a value by adding a : in front of it. For example, flags=":ab" will allow you to pass in -b and -a <value>.
The CommandContext also has the method hasFlag('b') and getFlag('a') for getting the flags.

Nested commands
You can allow for nested commands (/myplugin <command>) by adding a @NestedCommand. An example of this is here.

Conclusion
I feel that the real power of sk89q's command framework lies in the NestedCommands, but overall it is a really powerful system for handling commands. I hope you try it out

 

I alway's wanted a better command framework I could actually understand, the other ones always confused me somewheres along the road, and never saw a tutorial on how to use this yet. Thank you.

 

This is a really good tutorial, great job molenz.

 

I hate to bump, but the Maven setup in the OP is no longer working.

 

Incomprehendable
Change the version to

Code:

0.4-SNAPSHOT

 

RainoBoy97
I do believe that has fixed the issue, but the Overcast Network is currently down. Is there some other maven repo with the standalone framework?

 

Incomprehendable
I dont think there is. I'm also waiting for Overcast's repository to go live again, can't build my plugin without it

 

RainoBoy97
Back to depending on WorldEdit, then. Let's hope it's back up soon enough. Thanks for your help!
EDIT: I asked the owner of the network on Twitter. He doesn't know of any alternatives and has no ETA.

 

For all future visitors, repo.oc.tc is up again.

 

While the Overcast Network's Maven repository is back up, the shading part of the OP is now horribly incorrect. I'm pretty sure that the new repository link is https://repo.oc.tc/content/groups/public/, and I'm still unaware of the actual artifact ID. But I'm sure that the version is now 0.5-SNAPSHOT. Any help on this would be appreciated.

 

Din't know sk89q had a framework like this, looking into using this for some of my bigger projects.

 

Incomprehendable
This is what I use, I'm not sure if this is the "correct" one to use.

Code:

<dependency>
<groupId>com.sk89q</groupId>
<artifactId>sk89q-command-framework</artifactId>
<version>0.4-SNAPSHOT</version>
</dependency>

 

RainoBoy97
That doesn't seem to be working. When you go to repo.oc.tc, click "Repositories", and then click "Releases", there's no "com" directory. There's one in the "Public" repository though, but in that one, there is no "0.4-SNAPSHOT" version, only a "0.5-SNAPSHOT" one. The artifacts in the public repository are:

• command-framework-bukkit
• command-framework-bungee
• command-framework-core
• command-framework-parent

Sorry if I'm making any nooby mistakes, I'm a bit new to Maven.

EDIT: Fixed.
I managed to solve this on my own.

For all of those who may have had this issue, here are the details you want to put in your pom.xml:
REPO ID: repo.oc.tc
REPO URL: https://repo.oc.tc/content/groups/public/
DEPENDENCY GROUP ID: com.sk89q
DEPENDENCY ARTIFACT ID: command-framework-bukkit
DEPENDENCY VERSION: 0.5-SNAPSHOT

 

I hate to double post, but I did resolve this issue. Look in my post above. ^

 

For future reference here's a POM.xml for my PVPMoney plugin and it works absolutely fine:

Code:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.frostcore</groupId>
    <artifactId>PVPMoney</artifactId>
    <version>0.7</version>
    <build>
        <defaultGoal>clean install</defaultGoal>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.1</version>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>2.3</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                        <configuration>
                            <finalName>PVPMoney</finalName>
                            <useBaseVersion>true</useBaseVersion>
                            <shadedClassifierName/>
                            <outputDirectory>${project.basedir}</outputDirectory>
                            <artifactSet>
                                <includes>
                                    <include>net.gravitydevelopment.updater:updater</include>
                                    <include>com.sk89q:command-framework-bukkit</include>
                                    <include>org.mcstats.bukkit:metrics</include>
                                </includes>
                            </artifactSet>
                            <relocations>
                                <relocation>
                                    <pattern>net.gravitydevelopment.updater</pattern>
                                    <shadedPattern>com.frostcore.pvpmoney.updater</shadedPattern>
                                </relocation>
                                <relocation>
                                    <pattern>com.sk89q:command-framework-bukkit</pattern>
                                    <shadedPattern>com.frostcore.pvpmoney.commands</shadedPattern>
                                </relocation>
                                <relocation>
                                    <pattern>org.mcstats.bukkit:metrics</pattern>
                                    <shadedPattern>com.frostcore.pvpmoney.metrics</shadedPattern>
                                </relocation>
                            </relocations>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
    <repositories>
        <repository>
            <id>bukkit-repo</id>
            <url>http://repo.bukkit.org/content/groups/public/</url>
        </repository>
        <repository>
            <id>vault-repo</id>
            <url>http://nexus.theyeticave.net/content/repositories/pub_releases/</url>
        </repository>
        <repository>
            <id>Plugin Metrics</id>
            <url>http://repo.mcstats.org/content/repositories/public</url>
        </repository>
        <repository>
            <id>repo.oc.tc</id>
            <url>http://repo.oc.tc/content/repositories/public/</url>
        </repository>
        <repository>
            <id>gravity-repo</id>
            <url>http://repo.gravitydevelopment.net</url>
        </repository>
    </repositories>
    <dependencies>
        <dependency>
            <groupId>org.bukkit</groupId>
            <artifactId>bukkit</artifactId>
            <version>LATEST</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>org.mcstats.bukkit</groupId>
            <artifactId>metrics</artifactId>
            <version>R7</version>
        </dependency>
        <dependency>
            <groupId>net.milkbowl.vault</groupId>
            <artifactId>VaultAPI</artifactId>
            <version>1.4</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>com.sk89q</groupId>
            <artifactId>command-framework-bukkit</artifactId>
            <version>0.5-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>net.gravitydevelopment.updater</groupId>
            <artifactId>updater</artifactId>
            <version>2.1</version>
        </dependency>
    </dependencies>
</project>

 

Incomprehendable
You don't need to wait for repos to come online to build, you can always build it yourself. Fetch the code from github and do a clean install with maven. You will end up with perfectly usable build in your local maven repo. It's even written in readme.

 

raGan.
"Complaining > Competence"
In seriousness, I wasn't aware of that, thanks for letting me know!

 

Is there any fancy way to differ player vs. Console command?

 

No, I don't think so. I usually do something like:

Code:

if (!(sender instanceof Player))
throw new CommandException("You must be a player to use this command.");

And if you don't put a @ Console annotation before your command method, I don't think it will be called if the command was issued by the console. I'm not sure if the method will be called by a command block or not though.