Skip to content
This repository has been archived by the owner on Sep 10, 2020. It is now read-only.

elgbar/BukkitCommandAPI

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

BukkitCommandAPI

About

This is a CommandAPI that is developed to avoid having to statically register any command whether using reflection and a CommandExecutor, or simply putting the commands into my plugin.yml. This is a purely annotation based API.

Features

  • Easy registration and management of commands
  • Advanced automated help screen (see pictures below)
  • Automated tab completer (for now only first argument, to be improved)
  • Support to use flags
  • Maven support
  • See attribute values explained for more

Maven/Install

Add my repo

<dependency>
    <groupId>com.not2excel.api</groupId>
    <artifactId>BukkitCommandAPI</artifactId>
    <version>3.1.4</version>
</dependency>

To use CommandAPI you also need to shade it into your project to do so add the following to your pom.xml

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.0.0</version>
            <executions>
                <execution>
                    <id>shade</id>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <minimizeJar>true</minimizeJar> <!-- Only include packages that you are using. Note: Requires Java 1.5 or higher. -->
                <artifactSet>
                    <includes>
                        <include>com.not2excel.api:BukkitCommandAPI</include>
                    </includes>
                </artifactSet>
            </configuration>
        </plugin>
    </plugins>
</build>       

How to use

Using this CommandAPI is super simple, and requires minimum 3 lines to register the commands, and obviously the commands themselves.

First in either your onEnable() you need to setup the CommandManager:

final CommandManager commandManager = new CommandManager(plugin); //where `plugin` is a plugin instance
// Automatically finds all classes that implements the CommandListener.class and registers their commands
commandManager.registerCommands();
//registers a generated help topic to bukkit
//so the /help PluginName displays our plugin's registered commands
commandManager.registerHelp();

Attribute values of CommandHandler explained

command: (String) This is the name of the command. eg command /test will have command = "test"

aliases: (String[], default: {}) A list of aliases for the command

permission: (String, default: "") The permission needed to execute the command

noPermission: (String, default: "You don't have permission to do that.") The string displayed when the player doesn't have the permission for the command

usage: (String, default: "") The arbitrary arguments of the command

description: (String, default: "") A description of what the command does

min: (int, default: 0) The minimum number of arguments the command can have

max: (int, default: -1) The maximum number og arguments the command can have

playerOnly: (boolean, default: false) If only players can execute the command

flags: (Flag, default: {}) The flags of the command (see flags example below)

strictArgs: (boolean, default: false) If only known subcommand are allowed as arguments (see first example below)

flagDesc: (String[], default: {}) The description of what each flag does (see flags example below)

Attribute values of Flag explained

flags: (char) The character to use for the flag. If the char is '*' (asterisk) then this character will be used as a select everything flag.

usage: (String) An explanation of what the flag does.

permission: (String, default: "") The permission a players need to execute the flag

noPermission: (String, default: "You don't have permission use this flag.") The string displayed when the player doesn't have the permission to use the flag

Example commands

Example commands to be registered: Here are some test commands to display how commands should be written to allow registration. CommandListener is a required interface for any class you wish commands to be registered from. This is to allow shrinkage of classes searched for commands, and increase registration time. A real example can be found here

import com.not2excel.api.command.CommandHandler;
import com.not2excel.api.command.CommandListener;
import com.not2excel.api.command.objects.CommandInfo;

public class TestCommand implements CommandListener //CommandListener is required
{
    /*
     * command is the only required field for the annotation
     *
     * The base command is required (bug in 2.0). If you want the base command to display the
     * help screen when called without any arguments add the attribute values "strictArgs = true" and "max = 0"
     *
     * Do NOT register the command in plugin.yml as it is all handled by this API!
     */
    @CommandHandler(command = "test")
    public static void testingCommand(final CommandInfo info) {
        info.getSender().sendMessage("Test worked");
    }

    /*
     * A dot in the command string marks this as a sub command. It can go infinitely deep.
     * Do not have the command and/or subcommand in the usage, that is built in.
     * 
     */
    @CommandHandler(command = "test.test2",
                    permission = "test.test2",
                    noPermission = "No access!",
                    aliases = {"2", "testing", "test.2"},
                    usage = "<player>",
                    description = "Testing out (almost) all of the CommandHandler's attribute values")
    public static void testingCommand2(final CommandInfo info) {
        info.getSender().sendMessage("Test2 worked");
    }

    /*
     * A flag is a single character such as {@code -f} that will alter the behaviour of the command. flags can only
     * be any english character (a-z and A-Z) including * as a catch all.
     * 
     * Both the flag and usage option is required.
     *
     * Only valid flags will be passed you your method. If you specify the permission to be anything other than an empty string
     * then this will also be checked. In other words you do not need to check if the flags are valid or if the player has
     * permission, only if the flags are there.
     *
     * It is suggested that this is set `strictArgs` true if you only want flags as arguments. As this will then show the
     * detailed usage of the flags. 
          */
     @CommandHandler(command = COMMAND + ".reset",
        flags = {@Flag(flag = 'k', usage = "Resets kingdoms", permission = "kingdom.reset", noPermission = "Nice try punk"), 
                 @Flag(flag = 'r', usage = "Resets reficules")},
        strictArgs = true,
        description = "resets stuff!")
    public static void testingCommand3(final CommandInfo info) {
        //user gave the argument -f or -*
        if (info.hasFlag('k') ) {
            // Do some resetting
        }
        //returns true if one of the chars in the input string matches one of the flags the user gave
        if (info.hasOneOfFlags("kr")) {
            // reload or something
        }
    }
}

Pictures

Here are some pictures on how the automated help screen looks.

image

image

Finally: Please leave any comments, suggestions, and/or bugs you may find while using this CommandAPI.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages