BukkitCommands to API komend dla Bukkit wyciągnięte z biblioteki Commons. API idealnie pasuje do dużych i małych projektów ze względu na jego prostotę i zwięzłość kodu. Wszystko opiera się na adnotacji @CommandInfo w której to definiuje się wszystkie parametry danej komendy. Biblioteka BukkitCommands wymaga inicjalizacji najlepiej przy włączaniu pluginu. Należy użyć abstrakcyjnej klasy Commands do zdefiniowania swojej zmiennej. Implementacją musi być BukkitCommons, który odpowiada za wstrzykiwanie komend do silnika serwera oraz tworzenia strony pomocy. W parametrze konstruktora BukkitCommands należy podać Plugin na którym mają rejestrować się komendy. W tym miejscu należy podać referencję do głównej klasy pluginu.

Przykładowa inicjalizacja:

@Override
public void onEnable() {
    Commands commands = new BukkitCommands(this);
}

Tak jak wspomniałem powyżej wszystkie komendy opierają się o adnotację. Do każdej komendy należy przypisać metodę. Metoda ta powinna być metodą void z parametrami CommandSender oraz CommandContext. CommandSender jest obiektem wykonującym komendę znanym już z API Bukkit'a. CommandSender może być to jednocześnie blokiem komend (command block), konsola lub gracz. Uważaj więc z castowaniem CommandSendera do Player!

Nazwa metody jest dowolna, aczkolwiek dla dobrej identyfikacji dla programisty powinna zawierać nazwę komendy. Każda metoda musi zostać udekorowana adnotacją @CommandInfo. Poniżej przedstawię klucze tych adnotacji, opis oraz przykładowe wartości dla komendy /teleportto.

Specyfikacja @CommandInfo (porządek alfabetyczny):

Powyższe wartości podają następującą adnotację.

@CommandInfo(
        name = {"teleportto", tpt},
        description = "Teleportuj siebie do innego gracza",
        min = 1,
        flags = "silent",
        usage = "[-silent] <player>",
        userOnly = true,
        permission = "example.teleportto",
        completer = "teleportToCompleter")
public void teleportToCommand(CommandSender sender, CommandContext context) {
    // ...
}

CommandContext odpowiada za całą komendę oraz podane w niej argumentów. Klasa ta oferuje bogaty system pobierania wartości z flag oraz parametrów różnego typu. Każdą z metod opisze poniżej w tabeli.

Specyfikacja CommandContext (porządek alfabetyczny):

Biblioteka dla prostszego wysyłania błędów posiada system wyjątków. Rzucenie wyjątkiem spowoduje zakończenie wykonywania metody oraz wysłanie błędu użytkownikowi. BukkitCommons opiera się o następujące wyjątki.

Specyfikacja wyjątków (porządek alfabetyczny):

• CommandException - prosty błąd - w parametrze należy podać powód, który zostanie wysłany wysyłającemu.
• CommandConsoleException - błędny wysyłający - true w parametrze gdy wysyłający jest graczem.
• CommandPermissionException - brak uprawnienia - opcjonalna nazwa uprawnienia w parametrze.
• CommandUsageException - zbyt mało lub złe argumenty - w parametrze należy podać powód, który zostanie wysłany wysyłającemu.
• NumberFormatException - błędny format liczby

Uwaga! Każdy inny wyjątek wyświetli naganny błąd wysyłającemu oraz log w konsoli!

BukkitCommands posiada system flag. Użycie flag opiera się na dwie możliwości; tj. użycie flagi oraz przesłanie wartości poprzez flagę. Flagę tworzy się poprzez porzedzenie jej nazwy myślnikiem - /example -flag, na przykład /tpt -silent Jeb_. Każdej fladze można nadać wartość poprzez podanie jej w znakach cytatu - /example -flag "flag value". Wartości mogą być oddzielone znakiem odstępu.

Każda flaga musi zostać podana w adnotacji w komendy. W innym przypadku nie zostanie ona sparsowana, a będzie podana jako parametr.

@CommandInfo(
        ...
        flags = {"ip", "uuid"},
        ...)
public void playerInfoCommand(CommandSender sender, CommandContext context) {
    // ...
}

Operowanie flagami poprzez pobieranie ich wartości znajduje się w klasie CommandContext podanej jako parametr każdej komendy.

Biblioteka posiada także auto-uzupełnianie argumentów komendy poprzez tabulację. Aby do komendy dodać auto-uzupełnianie wystarczy do adnotacji w completer nazwę metody, która zwróci List<String> lub null oraz za parametry weźmie CommandSender oraz CommandContext. Trzeba pamiętać o tym, że metoda auto-uzupełniania musi znaleźć się w tej samej klasie co komenda!

@CommandInfo(
        ...
        completer = "pluginInfoCompleter",
        ...
)
public void pluginInfoCommand(CommandSender sender, CommandContext context) {
    // ...
}

public List<String> pluginInfoCompleter(CommandSender sender, CommandContext context) {
    // ...
}

Aby zarejestrować komendę wystarczy w Commands użyć registerCommandObject(...), a w parametrze podać obiekt w której ta komenda się znajduje. Jeżeli komenda są statyczne należy użyć metody registerCommandClass(...), natomiast w parametrze podać klasę w której ta komenda się znajduje. Obie możliwości pobiorą wszystkie możliwe komendy i zarejestrują je w silniku.

Commands commands = new BukkitCommands(this); // inicjalizacja w onEnable()
commands.registerCommandObject(new ExampleCommands());

lub gdy komendy są statyczne

Commands commands = new BukkitCommands(this); // inicjalizacja w onEnable()
commands.registerCommandClass(ExampleCommands.class);