Fabric Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Создание команды ======

Создание команд позволяет разработчику наращивать функционал и способ воздействия с пользователем через, собственно, команды.
Это руководство расскажет как регистрировать команды и общую информацию о структуре Brigadier.

Примечание: Весь код, описанный здесь, написан для 1.14.4. Что-то может быть изменено в yarn, но большая часть кода всё ещё применима и там.

===== Что такое Brigadier? =====

Brigadier - исполнитель и обработчик команд, написаный Mojang для Minecraft. Brigadier это древоподобная библиотека, с помощью которой вы можете создавать дерево из команд и аргументов.

С исходным кодом Brigadier вы можете ознакомиться тут: https://github.com/Mojang/brigadier

===== Что такое "команда"? =====

Brigadier требует описание ''команды'' чтобы её исполнять. На самом деле, "команда" это довольно неточный термин, если мы говорим о Brigadier, но обычно он означает конечную точку для команды, т.е. то место, где исполняется ваш код.
''Command'' - это функциональный интерфейс. Команда имеет подтип ''S'', где ''S'' - это источник команды. Источник команды может предоставить некий "контекст" для неё. В Minecraft обычно используется ''ServerCommandSource'', что представляет сервер, командный блок, соединение RCON, игрока или сущность.

Единственный метод в ''Command'' - ''run(CommandContext<S>)'' принимает один параметр ''CommandContext<S>'' и возвращает целое число. Контекст команды (CommandContext) типа ''S'' содержит в себе ''S'', позволяет увидеть используемые аргументы, работать с обработанными аргументами и посмотреть на непосредственный ввод пользователя.

Вы можете создать команду несколькими образами, которые написаны ниже:

**__Как лямбда-выражение__**
<code java [enable_line_numbers="true"]>
Command<Object> command = context -> {
    return 0;
};
</code>

**__Как анонимный класс__**
<code java [enable_line_numbers="true"]>
Command<Object> command = new Command<Object>() {
    @Override
    public int run(CommandContext<Object> context) {
        return 0;
    }
}
</code>

**__Как часть класса__**
<code java [enable_line_numbers="true"]>
final class XYZCommand implements Command<Object> {
    @Override
    public int run(CommandContext<Object> context) {
        return 0;
    }
}
</code>

**__Как обращение к методу__**
<code java [enable_line_numbers="true"]>
void registerCommand() {
    // Не обращайте внимание, мы объясним про это далее.
    dispatcher.register(CommandManager.literal("foo"))
        .executes(this::execute); // Это относится к приведённому ниже методу "выполнить".
}

private int execute(CommandContext<Object> context) {
    return 0;
}
</code>


Метод ''run(CommandContext)'' может произвести исключение ''CommandSyntaxException'', это будет объяснено далее в руководстве. 

Возвращаемое число можно понимать как результат команды. В Minecraft результатом может являться силой сигнала красного камня, который выдаёт командный блок или число, которое будет передано в следующий цепной командный блок. Обычно отрицательное число значит что команда не выполнена и что-то пошло не по плану, ''0'' что команда прошла, положительные числа - что выполнена и что-то произошло.  

===== Простейшая команда =====

Ниже вы можете увидеть команду, без аргументов:

<code java [enable_line_numbers="true"]>
dispatcher.register(CommandManager.literal("foo").executes(context -> { 
    System.out.println("Called foo with no arguments");

    return 1;
}));
</code>

''CommandManager.literal("foo")'' даёт brigadier'у понять, что у команды только одна ветвь, это **буквальный ввод** foo. Чтобы команда была выполнена, нужно ввести ''/foo''. Если введено ''/Foo'', ''/FoO'', ''/FOO'', ''/fOO'' или ''/fooo'', команда не будет считаться верной.

===== Статические импорты =====
Вы можете вводить ''CommandManager.literal("foo")'' каждый раз, когда хотите создать литерал. Это работает, но вы можете статически импортировать аргументы и сократить оператор до ''literal("foo")''. Это также работает для получения значения аргумента. Это сокращает ''StringArgumentType.getString(ctx, "string")'' до ''getString(ctx, "string")''.
Это также работает для собственных типов аргументов Minecraft.

И ваш импорт будет выглядеть примерно так:
<code java [enable_line_numbers="true"]>
// getString(ctx, "string")
import static com.mojang.brigadier.arguments.StringArgumentType.getString;
// word()
import static com.mojang.brigadier.arguments.StringArgumentType.word;
 // literal("foo")
import static net.minecraft.server.command.CommandManager.literal;
 // argument("bar", word())
import static net.minecraft.server.command.CommandManager.argument;
// Импортировать всё
import static net.minecraft.server.command.CommandManager.*;
</code>

Примечание: Пожалуйста, убедитесь, что вы используете ''literal'' и ''argument'' из CommandManager, иначе у вас могут возникнуть проблемы с дженериками при попытке компиляции.

Аргументы Brigadier по умолчанию находятся в ''com.mojang.brigadier.arguments''

Аргументы Minecraft находятся в разделе ''net.minecraft.command.arguments''.
CommandManager находится в ''net.minecraft.server.command''

===== Подкоманда =====

Чтобы добавить команде подкоманду, сначала необходимо зарегистрировать ветвь с буквальным вводом.

<code java [enable_line_numbers="true"]>
dispatcher.register(CommandManager.literal("foo")
</code>

В целом, чтобы получить подкоманду, нужно расширить текущую ветвь следующей, уже существующей ветвью. Это можно сделать с помощью метода ''then(ArgumentBuilder)'' который принимает в себя ''ArgumentBuilder''.

То, что показано ниже, создаёт команду ''foo <bar>'':

<code java [enable_line_numbers="true", highlight_lines_extra="2"]>
dispatcher.register(CommandManager.literal("foo")
    .then(CommandManager.literal("bar"))
);
</code>

Рекомендуется делать отступы в вашем коде при добавлении узлов в команду. Обычно отступ соответствует количеству глубоких узлов в дереве команд. Новая строка также делает видимым, что добавляется еще один узел. Существуют альтернативные стили для форматирования команды дерева, которые будут показаны позже в этом руководстве.

**Итак, давайте попробуем выполнить команду**

Скорее всего, если вы наберете ''/foo bar'' в игре, команда не будет выполнена. Это происходит потому, что нет кода для игры, который выполнялся бы после выполнения всех требуемых аргументов. Чтобы исправить это, вам нужно указать игре, что запускать, когда выполняется команда, используя метод ''executes(Command)''. Ниже в качестве примера показано, как должна выглядеть команда:

<code java [enable_line_numbers="true", highlight_lines_extra="3,4,5,6,7"]>
dispatcher.register(CommandManager.literal("foo")
    .then(CommandManager.literal("bar")
        .executes(context -> {
            System.out.println("Called foo with bar");

            return 1;
        })
    )
);
</code>

===== Регистрация команд =====

Регистрация команд выполняется путем регистрации обратного вызова с помощью ''CommandRegistrationCallback''. Для получения информации о регистрации обратных вызовов, ознакомьтесь с [[ru:tutorial:callbacks|статьёй об обратных вызовах]].

Событие должно быть зарегистрировано в инициализаторе вашего мода. Обратный вызов имеет два параметра. ''CommmandDispatcher<S>'' используется для регистрации, анализа и выполнения команд. ''S'' i- это тип источника команд, который поддерживает диспетчер команд. Второй параметр - это логическое значение, которое определяет тип сервера, на котором регистрируются команды. Это может быть ''dedicated'' (выделенный) или ''integrated''(интегрированный) (false) сервер:


<code java [enable_line_numbers="true"]>
public class ExampleCommandMod implements ModInitializer {
    @Override
    public void onInitialize() {
        CommandRegistrationCallback.EVENT.register((dispatcher, dedicated) -> {
            ...
        });
    }
}
</code>

Внутри вашего лямбда-выражения, ссылки на метод или чего бы вы ни выбрали, зарегистрируете свои команды:

<code java [enable_line_numbers="true", highlight_lines_extra="5,6,7,8"]>
public class ExampleCommandMod implements ModInitializer {
    @Override
    public void onInitialize() {
        CommandRegistrationCallback.EVENT.register((dispatcher, dedicated) -> {
            dispatcher.register(CommandManager.literal("foo").executes(context -> {
                System.out.println("foo");
                return 1;
            }));
        });
    }
}
</code>

При желании вы можете убедиться, что команда зарегистрирована только на выделенном сервере, установив флажок ''dedicated''(выделенный):


<code java [enable_line_numbers="true", highlight_lines_extra="5,6,7"]>
public class ExampleCommandMod implements ModInitializer {
    @Override
    public void onInitialize() {
        CommandRegistrationCallback.EVENT.register((dispatcher, dedicated) -> {
            if (dedicated) {
                TestDedicatedCommand.register(dispatcher);
            }
        });
    }
}
</code>

И наоборот:

<code java [enable_line_numbers="true", highlight_lines_extra="5,6,7"]>
public class ExampleCommandMod implements ModInitializer {
    @Override
    public void onInitialize() {
        CommandRegistrationCallback.EVENT.register((dispatcher, dedicated) -> {
            if (!dedicated) {
                TestIntegratedCommand.register(dispatcher);
            }
        });
    }
}
</code>

===== Аргументы =====

Аргументы в Brigadier как анализируют, так и проверяют на ошибки любые введенные аргументы.
Minecraft создает некоторые специальные типы аргументов для собственного использования, такие как ''EntityArgumentType'', который представляет внутриигровые селекторы сущностей ''@a, @r, @p, @e[type=!player, limit=1, distance=..2]'', или ''NbtTagArgumentType'', который анализирует строковый nbt (snbt) и проверяет правильность ввода синтаксиса.

**Будет сделано позже:** Подробнее о том, как использовать аргументы.

====== Дополнительные концепции ======

Ниже приведены ссылки на статьи о более сложных концепциях, используемых в Brigadier.

^ Страница                                                           ^ Описание                                                                     ^
| [[ru:tutorial:commands:requirements|Условия]]| Разрешать пользователям выполнять команды только в определенных сценариях.|
| [[ru:tutorial:commands:exceptions|Исключения]]| Сбой выполнения команды с описательным сообщением и в определенных контекстах.|                                                                  
| [[ru:tutorial:commands:suggestions|Предложения]]| Предложение входных данных для отправки клиенту.|
| [[ru:tutorial:commands:redirects_aliases|Редиректы (Разные вариации)]]| Разрешить использование разновидностей команд.|
| [[ru:tutorial:commands:redirects_chaining|Редиректы (Цепочки)]]| Разрешить командам иметь повторяющиеся элементы и флаги.|
| [[ru:tutorial:commands:argument_types|Свои типы аргументов]]| Анализируйте свои аргументы и возвращайте свои типы.|

====== Часто задаваемые вопросы ======

===== Почему моя команда не компилируется? =====

Есть две непосредственные возможности того, почему это могло произойти.

==== Поймать или вызвать исключение CommandSyntaxException ====

Решение этой проблемы состоит в том, чтобы заставить методы run или suggest вызывать исключение CommandSyntaxException. Не волнуйтесь, Brigadier обработает исключения и выдаст соответствующее сообщение об ошибке.

==== Проблемы с дженериками ====

Время от времени у вас могут возникать проблемы с типами дженерика. Убедитесь, что вы используете ''CommandManager.literal(...)'' или ''CommandManager.argument(...)'' вместо ''LiteralArgumentBuilder'' или ''RequiredArgumentBuilder''.

===== Могу ли я зарегистрировать команды на стороне клиента? =====

Fabric в настоящее время не поддерживает команды на стороне клиента. Существует [[https://github.com/CottonMC/ClientCommands|сторонний мод]] от команды Cotton, которая добавляет эту функциональность.

===== "Темные искусства" =====

Несколько вещей, которые мы не рекомендуем, но которые возможны.

==== Могу ли я регистрировать команды во время выполнения? ====

Вы можете это сделать, но это не рекомендуется. Вы получите ''CommandManager'' с сервера и добавите любые команды, которые пожелаете, в его ''CommandDispatcher''.

После этого вам нужно снова отправить дерево команд каждому игроку, используя ''sendCommandTree(ServerPlayerEntity)''. Это необходимо, поскольку клиент локально кэширует дерево команд, которое он получает во время входа в систему (или при отправке пакетов оператора) для локальных завершений и сообщений об ошибках.

==== Могу ли я отменить регистрацию команд во время выполнения? ====

Вы также можете сделать это, однако это гораздо менее стабильно, чем регистрация команд, и может вызвать нежелательные побочные эффекты. Чтобы все было просто, вам нужно использовать отражение для бригадира и удалить узлы. После этого вам нужно снова отправить дерево команд каждому игроку, используя ''sendCommandTree(ServerPlayerEntity)''. Если вы не отправите обновленное дерево команд, клиент может подумать, что команда все еще существует, даже если сервер завершит выполнение с ошибкой.

----

====== Со временем будет перенесено ======

===== Что может сделать ServerCommandSource? =====

''ServerCommandSource'' предоставляет некоторый дополнительный контекст, специфичный для конкретной реализации, при выполнении команды. Это включает в себя возможность получить объект, который выполнил команду, мир, в котором была запущена команда, или сервер, на котором была запущена команда:

<code java [enable_line_numbers="true"]>
final ServerCommandSource source = ctx.getSource(); 
// Находка источника. Это всегда будет работать.

final Entity sender = source.getEntity(); 
// Непроверенный, может быть нулевым, если отправителем была консоль.

final Entity sender2 = source.getEntityOrThrow(); 
// Завершит выполнение команды, если источником команды не была не сущность. 
// В результате этого может появиться игрок. Также будет отправлена обратная связь, сообщающая отправителю команды, что он должен быть сущностью. 
// Этот метод потребует, чтобы ваши методы вызывали исключение CommandSyntaxException. 
// Параметры сущности в ServerCommandSource могут возвращать сущность CommandBlock, любое живое существо или игрока.

final ServerPlayerEntity player = source.getPlayer(); 
// Завершит выполнение команды, если источником команды явно не был игрок. Также будет отправлен отзыв, сообщающий отправителю команды, что он должен быть игроком.
// Этот метод потребует, чтобы ваши методы вызывали исключение CommandSyntaxException

source.getPosition(); 
// Позиция отправителя в качестве Vec3, когда была отправлена команда. Это может быть местоположение сущности/командного блока или, в случае консоли, точка появления в мире.

source.getWorld(); 
// Мир, в котором находится отправитель. Мир консоли такой же, как и мир создания по умолчанию.

source.getRotation(); 
// Вращение отправителя как Vec2f.

source.getMinecraftServer(); 
// Доступ к экземпляру MinecraftServer, на котором была запущена эта команда.

source.getName(); 
// Имя источника команды. Это может быть имя сущности, игрока, имя командного блока, который был переименован перед размещением, или, в случае консоли, "Console".

source.hasPermissionLevel(int level); 
// Возвращает значение true, если источник команды имеет определенный уровень разрешений. Это зависит от статуса оператора отправителя. (На интегрированном сервере у игрока должны быть включены читы для выполнения этих команд)
</code>

===== Некоторые примеры команд =====

=== Транслировать сообщение ===

<code java [enable_line_numbers="true"]> 
public static void register(CommandDispatcher<ServerCommandSource> dispatcher){
    dispatcher.register(literal("broadcast")
        .requires(source -> source.hasPermissionLevel(2)) // Должен быть мастером игры, чтобы использовать эту команду. Команда не будет отображаться при перебора через Tab или выполняться не для операторов или любого оператора, имеющего уровень разрешений 1.
            .then(argument("color", ColorArgumentType.color())
                .then(argument("message", greedyString())
                    .executes(ctx -> broadcast(ctx.getSource(), getColor(ctx, "color"), getString(ctx, "message")))))); // Вы можете разобраться с приведенными здесь аргументами и передать их в команду.
}

public static int broadcast(ServerCommandSource source, Formatting formatting, String message) {
    final Text text = new LiteralText(message).formatting(formatting);

    source.getMinecraftServer().getPlayerManager().broadcastChatMessage(text, false);
    return Command.SINGLE_SUCCESS; // Успех
}
</code>

==== /giveMeDiamond ====

Сначала базовый код, в котором мы регистрируем ''giveMeDiamond'' как литерал, а затем вызываем блок, чтобы сообщить диспетчеру, какой метод запускать:

<code java [enable_line_numbers="true"]>
public static LiteralCommandNode register(CommandDispatcher<ServerCommandSource> dispatcher) { // Вы также можете вернуть LiteralCommandNode для использования с возможными редиректорами.
    return dispatcher.register(literal("giveMeDiamond")
        .executes(ctx -> giveDiamond(ctx)));
}
</code>

Затем, поскольку мы хотим передавать только игрокам, мы проверяем, является ли CommandSource игроком. Но мы можем использовать ''getPlayer'' и сделать и то, и другое одновременно, и выдать ошибку, если источник не является игроком:

<code java [enable_line_numbers="true"]>
public static int giveDiamond(CommandContext<ServerCommandSource> ctx) throws CommandSyntaxException {
    final ServerCommandSource source = ctx.getSource();
		
    final PlayerEntity self = source.getPlayer(); // Если это не игрок, то команда заканчивается
</code>

Затем мы добавляем в инвентарь игрока, проверяя, заполнен ли инвентарь:

<code java [enable_line_numbers="true"]>
    if(!player.inventory.insertStack(new ItemStack(Items.DIAMOND))){
        throw new SimpleCommandExceptionType(new TranslatableText("inventory.isfull")).create();
    }

    return 1;
}
</code>

==== Граната Антиоха ====
...брось ты свою Святую Ручную Гранату из Антиохии своему врагу.
который, будучи непослушным в моих глазах, погубит его. 
(Иностранный прикол)

Помимо шутки, эта команда вызывает заряженный TNT в указанное местоположение или местоположение курсора отправителя.

Сначала создайте запись в CommandDispatcher, которая принимает литерал antioch с необязательным аргументом местоположения для вызова сущности.

<code java [enable_line_numbers="true"]>
public static void register(CommandDispatcher<ServerCommandSource> dispatcher) {
    dispatcher.register(literal("antioch")
        .then(required("location", BlockPosArgumentType.blockPos()
            .executes(ctx -> antioch(ctx.getSource(), BlockPosArgument.getBlockPos(ctx, "location")))))
        .executes(ctx -> antioch(ctx.getSource(), null)));
}
</code>

Затем создайте сообщения, стоящие за шуткой:

<code java [enable_line_numbers="true"]>
public static int antioch(ServerCommandSource source, BlockPos blockPos) throws CommandSyntaxException {
    if(blockPos == null) {
        // В случае отсутствия введенного аргумента мы вычисляем положение курсора игрока или выдаем ошибку, если ближайшая позиция находится слишком далеко или находится за пределами мира.
        // Этот класс используется в качестве примера и на самом деле еще не существует.
        blockPos = LocationUtil.calculateCursorOrThrow(source, source.getRotation());
    }

    final TntEntity tnt = new TntEntity(source.getWorld(), blockPos.getX(), blockPos.getY(), blockPos.getZ(), null);
    tnt.setFuse(3);
        
    source.getMinecraftServer().getPlayerManager().broadcastChatMessage(new LiteralText("...брось ты свою Святую Ручную Гранату из Антиохии своему врагу").formatting(Formatting.RED), false);
    source.getMinecraftServer().getPlayerManager().broadcastChatMessage(new LiteralText("который, будучи непослушным в моих глазах, погубит его.").formatting(Formatting.RED), false);
    source.getWorld().spawnEntity(tnt);
    return 1;
}
</code>

==== Скоро появятся новые примеры ====