[LIB/TUT] MondoCommand - Handle sub-commands with ease!

One of the most irking things about developing bukkit plugins is handling commands, especially when you want to do the more common approach these days of having a single outer command with multiple sub-actions nested inside it (and don't get me started on sub-sub-actions).

You've probably tried it, and very soon entire function blocks start to look like a huge if-elseif-else scenario. Well worry not, there's a new library in town, and it's going to make the headache about dealing with sub-commands go away.

MondoCommand:

• Lets you register many sub-commands and let you separate the code how you like (multiple methods, classes, whatever) with minimal headache.
• Enforces permissions on individual sub-commands
• Generates a colorful help screen automatically
• Handles gracefully player-only commands vs commands for consoles
• Lets you do pretty formatted color output without having to bang your head against the ChatColor class.

Resources

• NEW user manual
• How to setup with Maven
• JavaDocs
• Example Plugin Source

Brief Intro Tutorial
Note There is now an even better tutorial as part of the official documentation

Code:java

// Basic setup and registration
MondoCommand base = new MondoCommand();
base.autoRegisterFrom(this);
getCommand("housebuilder").setExecutor(base);

Yep, that's all there is to register the base command. MondoCommand is a CommandExecutor, nothing terribly fancy.

Now you're going to write your first command:

Code:java

@Sub(description="Build a House", minArgs=2, usage="<owner> <name>")
public void build(CallInfo call) {
    String owner = call.getArg(0);
    String name = call.getArg(1);
    if (houseMap.containsKey(name)) {
        call.reply("House with name %s already exists", name);
    } else {
        // TODO add code to actually make a house
        call.reply("House %s made!", name);
    }
}

Whoa whoa, what just happened there? Well, MondoCommand lets you register commands automatically from any class's attributes by decorating methods with @Sub. The method must take an argument of CallInfo (more on this later) and return void.

Let's show another example command:

Code:java

@Sub(permission="housebuilder.destroy", description="Destroy a House",
     minArgs=1, usage="<name>", allowConsole=false)
public void destroy(CallInfo Call) {
    // We don't need to check number of args, becaus we registered the
    // command with minArgs = 1.
    String name = call.getArg(0);
    if (houseMap.containsKey(name)) {
        houseMap.remove(name);
        call.reply("{GREEN}House {GOLD}%s{GREEN} removed", name);
    } else {
        call.reply("{RED}House %s not found", name);
    }
}

This shows off a few more of MondoCommand's features, like the ability to control whether individual commands can be used at the console or not, and to gate individual sub-commands with permissions. Also, automatic color interpolation, which we'll explain more soon.

Besides handling the sub-command registration, you also get auto-generated help screens that look like this:


On top of all that, MondoCommand wraps much of the ugliness of command handling into much easier convenience accessors:

• call.getPlayer() gets a Player object (no more casting from CommandSender) and commands can be registered as allowing console or player-only.
• call.reply(template, [...]) - This is the gem of MondoCommand, it will send a message back to the user that interprets color codes embedded in the string, and lets you also interpolate variables into the string without having to do string concatenation. Ever write something like:
  Code:java

  player.sendMessage(ChatColor.BLUE.toString() + "Added user "
          + ChatColor.RED.toString() + targetPlayer.getName()
          + ChatColor.BLUE.toString() + "with role"
          + ChatColor.GREEN.toString() + role);

  Well with MondoCommand, that looks like:
  Code:java

  call.reply("{BLUE}Added user {RED}%s {BLUE}with role {GREEN}%s",
             targetPlayer.getName(), role);

  You can put any of the Bukkit color codes in braces and also take advantage of string formatting as provided by String.format to let you smartly interpolate variables.
• call.getArg(index) - To get a single argument, where the 0th index is the first index which comes after the sub command name (no more argument math!) and furthermore, you don't need to check the length of the args if you registered the subcommand with setMinArgs(), it will show the player a usage message and stop them from running your command.
• call.getIntArg(index) - Convenient way to get an argument coerced into an integer.
• call.getJoinedArgsAfter(index) - If you need to get a bunch of arguments after a certain index (like say you're accepting a text entry or chat message) this convenience method does that for you.
• call.numArgs() - Show number of arguments.

Do it with static registration (advanced mode)

If you don't want to use dynamic command registration with @Sub, don't worry, there's an API for you which uses no reflection and is completely predictable and type-safe. Actually, dynamic @Sub registration is implemented by building a bunch of anonymous handler classes for the API, so it works out roughly the same.

This tutorial section has now moved into the official documentation

 

Wowwww this is really cool.

 

Glad you dig it. Have you had a chance to use it? any comments?

By the way, I just released version 0.2, and the API has stabilized somewhat, I don't anticipate breaking it for the moment (but if you follow a -SNAPSHOT release, you never know )

 

No, not yet! Haven't had the chance/time to build a plugin with this. I'll let you know when I do!

 

This is a very sexy command system. I foresee myself using it.

 

I have released MondoCommand 0.3, and with it comes even cooler dynamic registration via annotations (optional, you can still register sub-commands manually too). It's also now on DevBukkit, though my recommendation is to use maven so you can shade the code easily.

 

For a small Plugin i use ure Command Lib and it works well.

Thanks for your work.

 

I had a problem... I can't find the getCommand() method that you used in the example... Where do I get that?

 

DJ8X
You register your command in the main class... Otherwise, use plugin.getCommand(...)...

 

You know how I make subcommands? I use a crap ton of nested if statements. But you know what? This is so much nicer. Thanks OP, bookmarking this.

 

I've now added a much better manual on all the various awesomeness you can do with MondoCommand here: http://mondocommand.rtfd.org/