CommandAPI

CommandAPI - это библиотека-плагин для серверов Майнкрафт на базе Bukkit, Spigot, Paper, Folia и Velocity, которая открывает разработчикам полный доступ к новому интерфейсу команд, появившемуся в Minecraft 1.13. Если вы когда-нибудь писали плагины и мучились с ручным парсингом аргументов, проверкой типов и регистрацией команд в plugin.yml - этот инструмент снимает почти всю боль.

Что такое CommandAPI и зачем он нужен

Начиная с версии 1.13, Mojang полностью переработали систему команд в Minecraft: появилось автодополнение по Tab, подсветка ошибок прямо в строке ввода, подсказки по аргументам и древовидная структура команд на базе библиотеки Brigadier. Проблема в том, что Bukkit и его форки по умолчанию всё это не используют - старый добрый onCommand с массивом строк никуда не делся, и разработчику приходится вручную проверять каждый аргумент, ловить NumberFormatException и объяснять игроку, что он ввёл что-то не так.

CommandAPI решает именно эту проблему. Плагин позволяет создавать команды, которые ведут себя как ванильные: с автодополнением, валидацией на лету и понятными сообщениями об ошибках. Игрок физически не сможет запустить команду с неправильными аргументами - клиент просто подсветит ошибку до отправки. Для администраторов серверов это означает меньше мусора в консоли, а для разработчиков - меньше boilerplate-кода.

Проект распространяется под лицензией MIT, работает на Bukkit, Spigot, Paper, Folia и Velocity, поддерживает версии от 1.13 до актуальных 1.21.x и выше. Актуальный релиз - CommandAPI 12.0.0. Скачать CommandAPI можно бесплатно, и никаких внешних зависимостей вроде ручного импорта Brigadier не потребуется.

Краткий обзор возможностей

• Умные команды - игроки не смогут выполнить команду с невалидными аргументами, клиент заранее покажет ошибку
• Умные аргументы - автоматический парсинг с встроенной валидацией, больше никаких try-catch на каждый чих
• Поддержка проксированных отправителей - запускайте команды от имени других сущностей через /execute as ... run command
• Полная поддержка /execute - ваши команды можно вызывать через встроенный /execute со всеми его модификаторами
• Поддержка функций Minecraft - команды можно вызывать из датапаков, функций и тегов
• Без регистрации в plugin.yml - команды больше не нужно прописывать в конфиге плагина
• Без лишних зависимостей - не нужно вручную подключать Brigadier в проект
• Без слежки - CommandAPI не собирает никакой статистики, что видите, то и получаете

Приведение типов аргументов

Вспомните, как выглядит классическая проверка аргумента в старом стиле:

onCommand(CommandSender sender, Command command, String label, String[] args) {
    try {
        int i = Integer.parseInt(args[0]);
        // Делаем что-то с этим числом
    } catch (NumberFormatException e) {
        // Обрабатываем факт, что это не число...
    }
}

С CommandAPI весь этот цирк уходит в прошлое. Библиотека сама выводит нужный тип, и вы сразу работаете с готовым значением:

new CommandAPICommand("mycommand")
    .withArguments(new IntegerArgument("myint"))
    .executes((sender, args) -> {
        int i = (int) args.get("myint");
        // Делаем что-то с этим числом
    })
    .register();

В арсенале CommandAPI больше 40 типов аргументов под любые задачи. Автоматическое приведение к Enchantments, EntityTypes, Locations, ItemStacks, PotionEffects и многому другому. Хотите принимать зачарование в качестве аргумента? Просто укажите соответствующий тип - и получите готовый объект с автодополнением всех зачарований в игре.

Проверка типа отправителя команды

Больше никогда не придётся писать if (sender instanceof Player). CommandAPI предоставляет автоматические проверки для всех видов отправителей:

new CommandAPICommand("mycommand")
    .withArguments(arguments)
    .executesPlayer((player, args) -> {
        player.sendMessage("Привет, " + player.getDisplayName());
    })
    .register();

Есть отдельные методы executesPlayer, executesConsole, executesCommandBlock, executesEntity и так далее. Если команду попытается выполнить не тот отправитель - CommandAPI сам вернёт корректную ошибку, а не свалит ваш сервер в ClassCastException.

Встроенный конвертер команд других плагинов

Отдельная киллер-фича, о которой многие забывают. Допустим, на вашем сервере стоит плагин, чьи команды не работают с /execute и датапаками, а исходников у вас нет и писать код вы не умеете. CommandAPI закрывает и этот сценарий: встроенная система конвертации команд позволяет сделать любую команду любого плагина совместимой с /execute и функциями датапаков. Для владельцев серверов это прямо спасение, когда нужно скрестить старые плагины с современными механиками.

Что ещё умеет CommandAPI

Если вас всё ещё не убедили, вот неполный список того, что библиотека делает из коробки:

• Парсинг целых чисел с диапазонами - можно принудительно ограничить команду значениями в заданном интервале
• Работа с целочисленными и дробными координатами, включая относительные координаты через символ ~
• Парсинг сырого JSON с прямым преобразованием в BaseComponent[]
• Парсинг онлайн-игроков с подсказками на основе того, кто сейчас на сервере
• Создание собственных кастомных аргументов, преобразующих строки в любые ваши объекты
• Права доступа на уровне отдельных аргументов - без пермишена игрок даже не увидит подсказку, не говоря уже о выполнении
• Совместимость команд чужих плагинов с /execute, даже если они написаны без CommandAPI
• Обработка результатов и успехов команд так же, как это делают командные блоки
• Контекстно-зависимые подсказки, которые учитывают, что пользователь уже ввёл в строку команды

Практические нюансы

Важный момент: CommandAPI - это инструмент для разработчиков плагинов, а не самостоятельный плагин, который что-то добавляет в игру. Обычному игроку он нужен только как зависимость, если какой-то из установленных на сервере плагинов требует его для работы. Ставится он как обычный плагин в папку plugins, никакой дополнительной настройки не требует.

Для разработчиков же это, пожалуй, лучший способ писать команды под современные версии Майнкрафт. Документация у проекта действительно отличная - с примерами на Java и Kotlin, интерактивной документацией и разбором типовых сценариев. Если вы только начинаете писать плагины, начинать сразу с CommandAPI куда разумнее, чем мучиться с ванильным API Bukkit.

Ещё один плюс для серверов с датапаками: команды, созданные через CommandAPI, можно вызывать из функций датапаков напрямую. Это открывает дорогу к гибридным механикам, где логика размазана между плагином и датапаком - например, кастомные ивенты, квесты или мини-игры.

Если вы собираете сервер на Paper или Folia и планируете писать собственные плагины - CommandAPI это must-have в вашем инструментарии. Скачайте CommandAPI и забудьте про ручной парсинг аргументов раз и навсегда.