Fabric Wiki

User Tools

Site Tools

Trace:
tutorial:commands

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
tutorial:commands [2023/08/17 00:27] – Added newlines in ServerCommandSource usage treeway7tutorial:commands [2025/03/20 23:37] (current) – added a missing "be" dfnkt
Line 3: Line 3:
 ====== Creating Commands ====== ====== Creating Commands ======
  
-Creating commands can allow a mod developer to add functionality that can used through a command. This tutorial will teach you how to register commands, and the general command structure of Brigadier. +Creating commands can allow a mod developer to add functionality that can be used through a command. This tutorial will teach you how to register commands, and the general command structure of Brigadier.
- +
-Note: All code written here was written for 1.19.2. For old versions, some versions and mappings may differ.+
  
 ===== What is Brigadier? ===== ===== What is Brigadier? =====
Line 15: Line 13:
 ===== The ''Command'' interface ===== ===== The ''Command'' interface =====
  
-In Minecraft, ''Command'' (''com.mojang.brigadier.Command'') is an ''functional interface'' that run some specific things, and throw a ''CommandSyntaxException'' in some cases. It has a generic type ''S'', which defines the type of the ''command source''. The command source provides some context in which a command was ran. In Minecraft, the command source is typically a ''ServerCommandSource'' which can represent a server, a command block, rcon connection, a player or an entity. In some cases, it can also be a ''ClientCommandSource''.+In Minecraft, ''com.mojang.brigadier.Command'' is a functional interface, which runs some specific things, and throw a ''CommandSyntaxException'' in some cases. It has a generic type ''S'', which defines the type of the //command source//. The command source provides some context in which a command was ran. In Minecraft, the command source is typically a ''<yarn class_2168>'' which can represent a server, a command block, rcon connection, a player or an entity. In some cases, it can also be a ''<yarn class_637>''.
  
 The single method in ''Command'', ''run(CommandContext<S>)'' takes a ''CommandContext<S>'' as the sole parameter and returns an integer. The command context holds your command source of ''S'' and allows you to obtain arguments, look at the parsed command nodes and see the input used in this command. The single method in ''Command'', ''run(CommandContext<S>)'' takes a ''CommandContext<S>'' as the sole parameter and returns an integer. The command context holds your command source of ''S'' and allows you to obtain arguments, look at the parsed command nodes and see the input used in this command.
Line 27: Line 25:
 </code> </code>
  
-In vanilla Minecraft, they are usually used as method references, such as static methods named ''register'' under classes named ''XXXCommand''. +The integer can be considered the result of the command. Typically negative values mean a command has failed and will do nothing. A result of ''0'' means the command has passed. Positive values mean the command was successful and did something.
- +
-The integer can be considered the result of the command. In Minecraft, the result can correspond to the power of a redstone comparator feeding from a command block or the value that will be passed the chain command block the command block is facing. Typically negative values mean a command has failed and will do nothing. A result of ''0'' means the command has passed. Positive values mean the command was successful and did something.+
  
  
Line 40: Line 36:
 final ServerCommandSource source = ctx.getSource();  final ServerCommandSource source = ctx.getSource(); 
  
-// Unchecked, may be null if the sender was the console. +// Unchecked, may be null if the sender was the console or the command block. 
-final Entity sender = source.getEntity(); +final @Nullable Entity sender = source.getEntity(); 
  
-// Will end the command if the source of the command was not an Entity. +// Will throw an exception if the executor of the command was not an Entity. 
 // The result of this could contain a player. Also will send feedback telling the sender of the command that they must be an entity.  // The result of this could contain a player. Also will send feedback telling the sender of the command that they must be an entity. 
 // This method will require your methods to throw a CommandSyntaxException.  // This method will require your methods to throw a CommandSyntaxException. 
 // The entity options in ServerCommandSource could return a CommandBlock entity, any living entity or a player. // The entity options in ServerCommandSource could return a CommandBlock entity, any living entity or a player.
-final Entity sender2 = source.getEntityOrThrow(); +final @NotNull Entity sender2 = source.getEntityOrThrow(); 
  
-// Will end the command if the source of the command was not explicitly a Player.+// null if the executor of the command is not a player. 
 +final @Nullable ServerPlayerEntity player = source.getPlayer(): 
 + 
 +// Will throw an exception if the executor of the command was not explicitly a Player.
 // Also will send feedback telling the sender of the command that they must be a player. // Also will send feedback telling the sender of the command that they must be a player.
 // This method will require your methods to throw a CommandSyntaxException. // This method will require your methods to throw a CommandSyntaxException.
-final ServerPlayerEntity player = source.getPlayer(); +final @NotNull ServerPlayerEntity player = source.getPlayerOrThrow(); 
  
-// Get's the sender's position as a Vec3 when the command was sent.+// Gets the sender's position as a Vec3d when the command was sent.
 // This could be the location of the entity/command block or in the case of the console, the world's spawn point. // This could be the location of the entity/command block or in the case of the console, the world's spawn point.
-source.getPosition(); +final Vec3d position = source.getPosition(); 
  
-// Get's the world the sender is within. The console's world is the same as the default spawn world. +// Gets the world the sender is within. The console's world is the same as the default spawn world. 
-source.getWorld(); +final ServerWorld world = source.getWorld(); 
  
-// Get's the sender's rotation as a Vec2f. +// Gets the sender's rotation as a Vec2f. 
-source.getRotation(); +final Vec2f rotation = source.getRotation(); 
  
 // Access to the instance of the MinecraftServer this command was ran on. // Access to the instance of the MinecraftServer this command was ran on.
-source.getServer(); +final MinecraftServer server = source.getServer(); 
  
 // The name of the command source. This could be the name of the entity, player, // The name of the command source. This could be the name of the entity, player,
 // the name of a CommandBlock that has been renamed before being placed down, or in the case of the Console, "Console". // the name of a CommandBlock that has been renamed before being placed down, or in the case of the Console, "Console".
-source.getName(); +final String name = source.getName(); 
  
 // Returns true if the source of the command has a certain permission level. // Returns true if the source of the command has a certain permission level.
 // This is based on the operator status of the sender. // This is based on the operator status of the sender.
 // (On an integrated server, the player must have cheats enabled to execute these commands.) // (On an integrated server, the player must have cheats enabled to execute these commands.)
-source.hasPermissionLevel(int level); +final boolean b = source.hasPermissionLevel(int level); 
 </code> </code>
  
Line 97: Line 96:
         .executes(context -> {         .executes(context -> {
       // For versions below 1.19, replace "Text.literal" with "new LiteralText".       // For versions below 1.19, replace "Text.literal" with "new LiteralText".
-      context.getSource().sendMessage(Text.literal("Called /foo with no arguments")); +      // For versions below 1.20, remode "() ->" directly. 
-      // For versions since 1.20, please use the following, which is intended to avoid creating Text objects if no feedback is needed. +      context.getSource().sendFeedback(() -> Text.literal("Called /foo with no arguments"), false);
-      context.getSource().sendMessage(() -> Text.literal("Called /foo with no arguments"));+
  
       return 1;       return 1;
Line 107: Line 105:
 </code> </code>
  
-''CommandManager.literal("foo")'' tells brigadier this command has one node, a **literal** called ''foo''.+**Please ensure you import the correct static method.** The method ''literal'' is ''CommandManager.literal''. You can also alternatively explicitly write ''CommandManager.literal'' instead of using static imports. ''CommandManager.literal("foo")'' tells brigadier this command has one node, a **literal** called ''foo''. 
 + 
 +In the ''sendFeedback'' method, the first parameter is the text to be sent, which is a ''Text'' in versions below 1.20, or a ''Supplier<Text>'' in 1.20 and above (this is used to avoid instantiating ''Text'' objects when not needed, so please do not use ''Suppliers.ofInstance'' or smiliar methods). The second parameter determines whether to broadcast the feedback to other operators. If the command is to //query// something without actually affecting the world, such as query the current time or some player's score, it should be ''false''. If the command actually //does// something, such as changing the time or modifying someone's score, it should be ''true''. If game rule ''sendCommandFeedback'' is false, you will not accept any feedback. If the sender is modifed through ''/execute as ...'', the feedback is sent to the original sender. 
 + 
 +If the command fails, instead of calling ''sendFeedback'', you may directly throw a ''CommandSyntaxException'' or ''<yarn class_2164>''. See [[command_exceptions]] for details.
  
 To execute this command, you must type ''/foo'', which is case-sensitive. If ''/Foo'', ''/FoO'', ''/FOO'', ''/fOO'' or ''/fooo'' is typed instead, the command will not run. To execute this command, you must type ''/foo'', which is case-sensitive. If ''/Foo'', ''/FoO'', ''/FOO'', ''/fOO'' or ''/fooo'' is typed instead, the command will not run.
  
 +===== Registration environment =====
 If desired, you can also make sure a command is only registered under some specific circumstances, for example, only in the dedicated environment: If desired, you can also make sure a command is only registered under some specific circumstances, for example, only in the dedicated environment:
  
-<code java [enable_line_numbers="true", highlight_lines_extra="5,6,7"]>+<yarncode java [enable_line_numbers="true", highlight_lines_extra="5,6,7"]>
 public class ExampleCommandMod implements ModInitializer { public class ExampleCommandMod implements ModInitializer {
     @Override     @Override
     public void onInitialize() {     public void onInitialize() {
         CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) -> {         CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) -> {
-            if (environment.dedicated) {+            if (environment.field_25423) {
                 ...;                 ...;
             }             }
Line 124: Line 127:
     }     }
 } }
-</code>+</yarncode>
  
 ===== Static Imports ===== ===== Static Imports =====
Line 149: Line 152:
 Minecraft's arguments are in ''net.minecraft.command.arguments''. CommandManager is in the package ''net.minecraft.server.command''. Minecraft's arguments are in ''net.minecraft.command.arguments''. CommandManager is in the package ''net.minecraft.server.command''.
  
-===== Requirements =====+===== Add Requirements =====
  
 Let's say you have a command that you only want operators to be able to execute. This is where the ''requires'' method comes into play. The ''requires'' method has one argument of a ''Predicate<ServerCommandSource>'' which will supply a ''ServerCommandSource'' to test with and determine if the ''CommandSource'' can execute the command. Let's say you have a command that you only want operators to be able to execute. This is where the ''requires'' method comes into play. The ''requires'' method has one argument of a ''Predicate<ServerCommandSource>'' which will supply a ''ServerCommandSource'' to test with and determine if the ''CommandSource'' can execute the command.
Line 157: Line 160:
 <code java [enable_line_numbers="true"]> <code java [enable_line_numbers="true"]>
 dispatcher.register(literal("foo") dispatcher.register(literal("foo")
- .requires(source -> source.hasPermissionLevel(4))+  .requires(source -> source.hasPermissionLevel(2))
   .executes(ctx -> {   .executes(ctx -> {
-    ctx.getSource().sendFeedback(Text.literal("You are an operator"), false);+    ctx.getSource().sendFeedback(() -> Text.literal("You are an operator"), false);
     return 1;     return 1;
   });   });
 </code> </code>
  
-This command will only execute if the source of the command is a level 4 operator at minimum. Otherwise, the command is not registered. Also this has the side effect of not showing this command in tab completion to anyone who is not a level 4 operator. This is also why you cannot tab-complete most commands when you did not enable cheating.+This command will only execute if the source of the command is a level 2 operator at minimum, //including// command blocks. Otherwise, the command is not registered. Also this has the side effect of not showing this command in tab completion to anyone who is not a level 2 operator. This is also why you cannot tab-complete most commands when you did not enable cheating. 
 + 
 +To create commands that only level 4 operators (//not including// command blocks) can execute, use ''source.hasPermissionLevel(4)''.
  
 ===== Arguments ===== ===== Arguments =====
  
-Arguments in Brigadier both parse and error check any inputted arguments. +Arguments are used in most of commands. Sometimes they can be optional, which means if you do not provide that argument, the command will also run. One node may have multiple argument types, but be aware that there is possibility of ambiguity, which should be avoided.
-Minecraft creates some special argument types for it's own use such as the ''EntityArgumentType'' which represents the in-game entity selectors ''@a, @r, @p, @e[type=!player, limit=1, distance=..2]'', or an ''NbtTagArgumentType'' that parses stringified nbt (snbt) and verifies that the input is the correct syntax.+
  
-**TODO:** Go into more detail on how to use arguments+In this case, we add one integer argument, and calculate the square of the integer.
  
-===== A sub command =====+<code java> 
 +    dispatcher.register(literal("mul") 
 +        .then(argument("value", IntegerArgumentType.integer()) 
 +            .executes(context -> { 
 +              final int value = IntegerArgumentType.getInteger(context, "value"); 
 +              final int result = value * value; 
 +              context.getSource().sendFeedback(() -> Text.literal("%s × %s = %s".formatted(value, value, result)), false); 
 +              return result; 
 +            }))); 
 +</code>
  
-To add a sub command, you register the first literal node of the command normally.+In this case, after the word ''/mul'', you should type an integer. For example, if you run ''/mul 3'', you will get the feedback message "3 × 3 = 9". If you type ''/mul'' without arguments, the command cannot be correctly parsed.
  
-<code java [enable_line_numbers="true"]> +Note: for simplicity, ''IntegerArgumentType.integer'' and ''IntegerArgumentType.getInteger'' can be replaced with ''integer'' and ''getInteger'' with static import. This example does not use static imports, in order to be more explicit. 
-dispatcher.register(literal("foo"))+ 
 +Then we add an optional second argument: 
 +<code java> 
 +    dispatcher.register(literal("mul") 
 +        .then(argument("value", IntegerArgumentType.integer()) 
 +            .executes(context -> { 
 +              final int value = IntegerArgumentType.getInteger(context, "value"); 
 +              final int result = value * value; 
 +              context.getSource().sendFeedback(() -> Text.literal("%s × %s = %s".formatted(value, value, result)), false); 
 +              return result; 
 +            }) 
 +            .then(argument("value2", IntegerArgumentType.integer()) 
 +                .executes(context -> { 
 +                  final int value = IntegerArgumentType.getInteger(context, "value"); 
 +                  final int value2 = IntegerArgumentType.getInteger(context, "value2"); 
 +                  final int result = value * value2; 
 +                  context.getSource().sendFeedback(() -> Text.literal("%s × %s = %s".formatted(value, value2, result)), false); 
 +                  return result; 
 +                }))));
 </code> </code>
  
-In order to have a sub command, one needs to append the next node to the existing node. This is done use the ''then(ArgumentBuilder)'' method which takes in an ''ArgumentBuilder''.+Now you can type one or two integers. If you give one integer, that square of integer will be calculated. If you provide two integers, their product will be calculated. You may find it unnecessary to specify similar executions twice. Therefore, we can create a method that will be used in both executions.
  
-This creates the command ''foo <bar>'' as shown below.+<code java> 
 +public class ExampleMod implements ModInitializer { 
 +  @Override 
 +  public void onInitialize() { 
 +    CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) -> dispatcher.register(literal("mul") 
 +        .then(argument("value", IntegerArgumentType.integer()) 
 +            .executes(context -> executeMultiply(IntegerArgumentType.getInteger(context, "value"), IntegerArgumentType.getInteger(context, "value"), context)) 
 +            .then(argument("value2", IntegerArgumentType.integer()) 
 +                .executes(context -> executeMultiply(IntegerArgumentType.getInteger(context, "value"), IntegerArgumentType.getInteger(context, "value2"), context)))))); 
 +  }
  
-<code java [enable_line_numbers="true", highlight_lines_extra="2"]> +  private static int executeMultiply(int value, int value2, CommandContext<ServerCommandSource> context) { 
-dispatcher.register(literal("foo") +    final int result = value * value2; 
-    .then(literal("bar")) +    context.getSource().sendFeedback(() -> Text.literal("%s × %s = %s".formatted(value, value2, result)), false); 
-);+    return result; 
 +  } 
 +}
 </code> </code>
 +===== A sub command =====
  
-It is advised to indent your code as you add nodes to the command. Usually the indentation corresponds to how many nodes deep one is on the command tree. The new line also makes it visible that another node is being added. There are alternative styles to formatting the tree command that are shown later on in this tutorial.+To add a sub command, you register the first literal node of the command normally.
  
-**So let's try running the command**+<code> 
 +dispatcher.register(literal("foo")) 
 +</code>
  
-Most likely if you typed ''/foo bar'' in game, the command will fail to run. This is because there is no code for the game to execute when all the required arguments have been met. To fix this, you need to tell the game what to run when the command is being executed using the ''executes(Command)'' method. Below is how the command should look as an example.+In order to have a sub command, one needs to append the next node to the existing node. 
  
-<code java [enable_line_numbers="true", highlight_lines_extra="3,4,5,6,7"]>+This creates the command ''foo <bar>'' as shown below. 
 + 
 +<code java [enable_line_numbers="true"]>
 dispatcher.register(literal("foo") dispatcher.register(literal("foo")
     .then(literal("bar")     .then(literal("bar")
         .executes(context -> {         .executes(context -> {
             // For versions below 1.19, use ''new LiteralText''.             // For versions below 1.19, use ''new LiteralText''.
-            context.getSource().sendMessage(Text.literal("Called foo with bar"));+            // For versions below 1.20, use directly the ''Text'' object instead of supplier. 
 +            context.getSource().sendFeedback(() -> Text.literal("Called foo with bar"), false);
  
             return 1;             return 1;
Line 210: Line 258:
 </code> </code>
  
 +Similar to arguments, sub command nodes can also be set optional. In the following case, both ''/foo'' and ''/foo bar'' will be valid. 
 +<code java [enable_line_numbers="true"]> 
 +dispatcher.register(literal("foo") 
 +    .executes(context -> { 
 +        context.getSource().sendFeedback(() -> Text.literal("Called foo without bar"), false); 
 +        return 1; 
 +    }) 
 +    .then(literal("bar") 
 +        .executes(context -> { 
 +            context.getSource().sendFeedback(() -> Text.literal("Called foo with bar"), false); 
 +            return 1; 
 +        }) 
 +    ) 
 +); 
 +</code>
 ====== Advanced concepts ====== ====== Advanced concepts ======
  
Line 224: Line 286:
 ====== FAQ ====== ====== FAQ ======
  
-===== Why does my command not compile =====+===== Why does my code not compile =====
  
-There are two immediate possibilities for why this could occur.+There are several immediate possibilities for why this could occur.
  
-==== Catch or throw a CommandSyntaxException ==== +  * **Catch or throw a CommandSyntaxException:** ''CommandSyntaxException'' is not a ''RuntimeException''. If you throw it, where it is throwed should be in methods that throws ''CommandSyntaxException'' in method signatures, or be caught. Brigadier will handle the checked exceptions and forward the proper error message in game for you. 
- +  * **Issues with generics:** You may have an issue with generics once in a while. If you are registering server command (which is most of the case), make sure you are using ''CommandManager.literal(...)'' or ''CommandManager.argument(...)'' instead of ''LiteralArgumentBuilder.literal'' or ''RequiredArgumentBuilder.argument'' in your static imports. 
-The solution to this issue is to make the ''run'' or ''suggest'' methods throw a ''CommandSyntaxException''. Brigadier will handle the checked exceptions and forward the proper error message in game for you. +  * **Check ''sendFeedback'' method:** You may have forgotten to provide a boolean as the second argument. Also remember that, since 1.20, the first parameter is ''Supplier<Text>'' instead of ''Text''. 
- +  * **''Command'' should return an integer:** When registering commands, the ''executes'' method accepts a ''Command'' object, which is usually a lambda. The lambda should return an integer, instead of other types.
-==== Issues with generics ==== +
- +
-You may have an issue with generic types once in a while. Verify you are using ''CommandManager.literal(...)'' or ''CommandManager.argument(...)'' instead ''LiteralArgumentBuilder'' or ''RequiredArgumentBuilder'' in your static imports.+
  
 ===== Can I register client side commands? ===== ===== Can I register client side commands? =====
  
-Fabric has a ClientCommandManager that can be used to register client side commands.+Fabric has a ''ClientCommandManager'' that can be used to register client side commands. The code should exist only in client-side codes. Example:
  
-===== Dark Arts =====+<code java> 
 +    ClientCommandRegistrationCallback.EVENT.register((dispatcher, registryAccess) -> dispatcher.register(ClientCommandManager.literal("foo_client") 
 +        .executes(context -> { 
 +              context.getSource().sendFeedback(Text.literal("The command is executed in the client!")); 
 +              return 1; 
 +            } 
 +        ))); 
 +</code>
  
-A few things we don't recommend, but are possible.+If you need to open a screen in the client command execution, instead of directly calling ''client.setScreen(...)'', you should call ''%%client.execute(() -> client.setScreen(...))%%''. The variable ''client'' can be obtained with ''context.getSource().getClient()''.
  
-==== Can I register commands in runtime? ====+===== Can I register commands in runtime? =====
  
 You can do this but it is not recommended. You would get the ''CommandManager'' from the server and add anything commands you wish to it's ''CommandDispatcher''. You can do this but it is not recommended. You would get the ''CommandManager'' from the server and add anything commands you wish to it's ''CommandDispatcher''.
Line 250: Line 316:
 After that you need to send the command tree to every player again using ''CommandManager.sendCommandTree(ServerPlayerEntity)''. This is required because the client locally caches the command tree it receives during login (or when operator packets are sent) for local completions rich error messages. After that you need to send the command tree to every player again using ''CommandManager.sendCommandTree(ServerPlayerEntity)''. This is required because the client locally caches the command tree it receives during login (or when operator packets are sent) for local completions rich error messages.
  
-==== Can I unregister commands in runtime? ====+===== Can I unregister commands in runtime? =====
  
 You can also do this, however it is much less stable than registering commands and could cause unwanted side effects. To keep things simple, you need to use reflection on brigadier and remove the nodes. After this, you need to send the command tree to every player again using ''sendCommandTree(ServerPlayerEntity)''. If you don't send the updated command tree, the client may think a command still exists, even though the server will fail execution. You can also do this, however it is much less stable than registering commands and could cause unwanted side effects. To keep things simple, you need to use reflection on brigadier and remove the nodes. After this, you need to send the command tree to every player again using ''sendCommandTree(ServerPlayerEntity)''. If you don't send the updated command tree, the client may think a command still exists, even though the server will fail execution.
  
 +===== Can I execute command without typing in game? =====
 +Yes! You can. Before trying the next code, take note it works on Fabric 0.91.6+1.20.2 and it was not tested in other versions.
 +
 +Here is the code example
 +
 +<code java>
 +    private void vanillaCommandByPlayer(World world, BlockPos pos, String command) {
 +        PlayerEntity player = world.getClosestPlayer(pos.getX(), pos.getY(), pos.getZ(), 5, false);
 +        if (player != null) {
 +            CommandManager commandManager = Objects.requireNonNull(player.getServer()).getCommandManager();
 +            ServerCommandSource commandSource = player.getServer().getCommandSource();
 +            commandManager.executeWithPrefix(commandSource, command);
 +        }
 +    }
 +</code>
 +
 +First, you need a CommandManager<ServerCommandSource>.
 +Second, you need the ServerCommandSource.
 +Then, u can call some CommandManager public methods like commandeManader.execute. (.execute need ParseResults<ServerCommandSource>)
 +But commandeManader.executeWithPrefix allow you to use String. You can also put the slash (/).
 +
 +So... have fun!
tutorial/commands.1692232077.txt.gz · Last modified: 2023/08/17 00:27 by treeway7