Fabric Wiki

User Tools

Site Tools

Trace: • 创建命令
zh_cn: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
zh_cn:tutorial:commands [2023/11/18 09:57] – [ServerCommandSource 是做什么的？] solidblockzh_cn:tutorial:commands [2025/07/06 07:10] (current) – [静态导入] solidblock
Line 1: Line 1:
- 
 条款：本文中的代码适用于“Creative Commons Zero v1.0 Universial”条款，允许您将文中的代码示例用于自己的模组中。 条款：本文中的代码适用于“Creative Commons Zero v1.0 Universial”条款，允许您将文中的代码示例用于自己的模组中。
  
Line 6: Line 5:
 ====== 创建命令 ====== ====== 创建命令 ======
  
-创建命令允许模组开发者添加可以使用命令实现的功能。本教程将会教你如何注册命令，以及Brigadier的基本命令结构。 +创建命令允许模组开发者添加可以使用命令实现的功能。本教程将会教你如何注册命令，以及 Brigadier 的基本命令结构。
- +
-注意：本文的所有代码都是用于 1.19.2 的。对于旧的版本，一些版本和映射可能不同。+
  
 ===== Brigadier 是什么？ ===== ===== Brigadier 是什么？ =====
Line 29: Line 26:
 }; };
 </code> </code>
- 
-在原版 Minecraft 中，命令通常用作方法引用，例如原版的 ''XXXCommand'' 类中名叫 ''register'' 的静态方法。 
  
 这个整数相当于命令的结果。在 Minecraft 中。通常来说，负值表示命令执行失败，什么也不做，''0'' 表示命令被略过，正数则表示命令执行成功并做了一些事情。 这个整数相当于命令的结果。在 Minecraft 中。通常来说，负值表示命令执行失败，什么也不做，''0'' 表示命令被略过，正数则表示命令执行成功并做了一些事情。
Line 36: Line 31:
 ==== ServerCommandSource 是做什么的？ ==== ==== ServerCommandSource 是做什么的？ ====
  
-''ServerCommandSource'' 提供了命令运行时的一些特外的环境，这些环境拥有特定的实现，包括获取运行这个命令的实体、命令执行时所在的世界以及服务器。+''ServerCommandSource'' 提供了命令运行时的一些额外环境，这些环境拥有特定的实现，包括获取运行这个命令的实体、命令执行时所在的世界以及服务器。
  
 <code java [enable_line_numbers="true"]> <code java [enable_line_numbers="true"]>
Line 95: Line 90:
     CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) -> dispatcher.register(literal("foo")     CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) -> dispatcher.register(literal("foo")
         .executes(context -> {         .executes(context -> {
-      // 对于 1.19 以下的版本，把“Text.literal”替换为“new LiteralText”。 +      // 对于 1.19 之前的版本，把“Text.literal”替换为“new LiteralText”。 
-      context.getSource().sendMessage(Text.literal("调用 /foo，不带参数。"));+      // 对于 1.20 之前的版本，请移除“() ->”。 
 +      context.getSource().sendFeedback(() -> Text.literal("调用 /foo，不带参数"), false);
  
       return 1;       return 1;
Line 104: Line 100:
 </code> </code>
  
-''CommandManager.literal("foo")'' 会告诉 brigadier，命令有一个节点，''foo''这个**字面的**节点。+**请确保你导入了正确的静态方法。**方法 ''literal'' 是 ''CommandManager.literal''。你也可以清楚地写 ''CommandManager.literal'' 而不是使用静态导入。''%%CommandManager.literal("foo")%%'' 会告诉 brigadier，命令有一个节点，''foo'' 这个**字面的**节点。 
 + 
 +在 ''sendFeedback'' 方法中，第一个参数是需要发送的文本，在 1.20 之前的版本中是 ''Text''，在 1.20 以及之后的版本是 ''Supplier<Text>''（这是为了避免在不需要的时候实例化了 ''Text'' 对象，因此请不要使用 ''Suppliers.ofInstance'' 或类似方法）。第二个参数决定了命令是否要将反馈的内容发送给其他的管理员。如果命令是//查询//一些内容，比如查询当前的时间或者某玩家的分数，则应该是 ''false''。如果命令实际上//做了些//事情，例如修改时间或者分数，那么则应该是 ''true''。如果游戏规则 ''sendCommandFeedback'' 是 false，那么你不会收到反馈。如果命令执行者被通过 ''/execute as ...'' 修改，反馈则会发送给原始的执行者。 
 + 
 +如果命令失败，可以不必调用 ''sendFeedback''，而是直接抛出 ''CommandSyntaxException'' 或 ''<yarn class_2164>''。具体请参见 [[command_exceptions]]。
  
 要执行命令，必须输入 ''/foo''，这是大小写敏感的。如果输入 ''/Foo''、''/FoO''、''/FOO''、''/fOO'' 或者 ''/fooo''，命令不会运行。 要执行命令，必须输入 ''/foo''，这是大小写敏感的。如果输入 ''/Foo''、''/FoO''、''/FOO''、''/fOO'' 或者 ''/fooo''，命令不会运行。
  
 +===== 注册环境 =====
 如有需要，你可以确保命令仅在一些特定情形下注册，例如仅在专用服务器上： 如有需要，你可以确保命令仅在一些特定情形下注册，例如仅在专用服务器上：
  
-<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 121: Line 122:
     }     }
 } }
-</code>+</yarncode>
  
 ===== 静态导入 ===== ===== 静态导入 =====
-在上面的例子中，使用了静态导入以简化代码。对于字面值，语句会简化为 ''literal("foo")''，这也适用于获取参数的值，把 ''StringArgumentType.getString(ctx, "string")'' 简化为 ''getString(ctx, "string")''。这也适用于 Minecraft 自己的参数类型。+在上面的例子中，使用了静态导入以简化代码。对于字面值，语句会简化为 ''%%literal("foo")%%''，这也适用于获取参数的值，把 ''%%StringArgumentType.getString(ctx, "string")%%'' 简化为 ''%%getString(ctx, "string")%%''。这也适用于 Minecraft 自己的参数类型。
  
-Below is an example of some static imports:+以下是一些静态导入的例子。
 <code java [enable_line_numbers="true"]> <code java [enable_line_numbers="true"]>
 // getString(ctx, "string") // getString(ctx, "string")
Line 140: Line 141:
 </code> </code>
  
-注意：请确保使用了 ''CommandManager'' 中的 ''literall'' 和 ''argument''，而非其他类中的，否则编译时存在泛型擦除问题，因为类型参数 ''S'' 应该是 ''ServerCommandSource''。（对于客户端的命令，请使用 ''ClientCommandManager''。）+注意：请确保使用了 ''CommandManager'' 中的 ''literal'' 和 ''argument''，而非其他类中的，否则编译时存在泛型擦除问题，因为类型参数 ''S'' 应该是 ''ServerCommandSource''。（对于客户端的命令，请使用 ''ClientCommandManager''。）
  
 Brigadier 的默认参数位于 ''com.mojang.brigadier.arguments''。 Brigadier 的默认参数位于 ''com.mojang.brigadier.arguments''。
Line 146: Line 147:
 Minecraft 的参数位于 ''net.minecraft.command.arguments''。CommandManager 位于包 ''net.minecraft.server.command'' 内。 Minecraft 的参数位于 ''net.minecraft.command.arguments''。CommandManager 位于包 ''net.minecraft.server.command'' 内。
  
-===== 条件 =====+===== 添加条件 =====
  
 有时你希望命令只有管理员（OP）可以执行，这时就要用到 ''requires'' 方法。''requires'' 方法有一个参数 ''Predicate<ServerCommandSource>''，提供一个 ''ServerCommandSource'' 以检测 ''CommandSource'' 能否执行命令。 有时你希望命令只有管理员（OP）可以执行，这时就要用到 ''requires'' 方法。''requires'' 方法有一个参数 ''Predicate<ServerCommandSource>''，提供一个 ''ServerCommandSource'' 以检测 ''CommandSource'' 能否执行命令。
Line 154: Line 155:
 <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("你是 OP"), false);+    ctx.getSource().sendFeedback(() -> Text.literal("你是 OP"), false);
     return 1;     return 1;
   });   });
 </code> </code>
-此时命令只会在命令源为 4 级以上时运行，否则命令不会被注册。这样做的副作用就是，非 4 级管理员会看到命令不会被 tab 补全，这也就是为什么没有启用作弊时不能够 tab 补全大多数命令。+此时命令只会在命令源为 2 级以上（包括命令方块）时运行，否则命令不会被注册。这样做的副作用就是，非 2 级管理员会看到命令不会被 tab 补全，这也就是为什么没有启用作弊时不能够 tab 补全大多数命令。 
 + 
 +要创建只有 4 级管理员（不包括命令方块）可以执行的命令，请使用 ''source.hasPermissionLevel(4)''。
  
 ===== 参数 ===== ===== 参数 =====
  
-Brigadier 中的参数会解析任何输入的参数，并检查错误。Minecraft 创建了一些特殊的参数类型以用于自己使用，例如 ''EntityArgumentType''，表示游戏内的实体选择器 ''@a, @r, @p, @e[type=!player, limit=1, distance=..2]''，又如 ''NbtTagArgumentType''，解析字符串化的 nbt（snbt）并验证输入的语法是否正确。+大多数命令都使用了参数。一些参数是可选的，也就是说如果你不提供此参数，命令仍能运行。一个节点可以有多个参数类型，但是注意有可能出现二义性，这是需要避免的。
  
-**TODO：**详细介绍如何使用参数+在这个例子中。我们添加一个整数参数。并计算整数的平方。
  
-===== 子命令 =====+<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>
  
-要添加子命令，你需要先照常注册注册第一个字面节点。+在这个例子中，在 ''/mul'' 之后，你需要输入一个整数。例如，如果你输入 ''/mul 3''，会收到消息“3 × 3 = 9”。如果你输入 ''/mul'' 不带参数，命令无法正确解析。
  
-<code java [enable_line_numbers="true"]> +注意：为了简便，''IntegerArgumentType.integer'' 和 ''IntegerArgumentType.getInteger'' 可以替换为 ''integer'' 和 ''getInteger'' 同时使用静态导入。为了显得更加清楚，这个例子不使用静态导入。 
-dispatcher.register(literal("foo"))+ 
 +然后我们添加可选的第二个参数： 
 +<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>
  
-为拥有子命令，需要把下一个节点追加到已经存在的节点后面，这是利用 ''then(ArgumentBuilder)'' 实现的，该方法接收一个 ''ArgumentBuilder''。+现在你可以输入一个或者两个整数了。如果给一个整数，会计算这个整数的平方。如果提供两个整数，会计算这两个整数的积。你可能发现，两次指定类似的执行内容有些不太必要。因此，我们可以创建一个在两个执行中都使用的方法。
  
-如下所示，创建命令 ''foo <bar>''。+<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>
  
-建议给命令添加节点时缩进你的代码，通常来说缩进对应了命令树中有多少节点的深度，每一次换行也可以看出添加了一个节点。本教程后面会展示格式化树状命令的几种可选样式。+===== 子命令 =====
  
-**那就开始尝试运行命令**+要添加子命令，你需要先照常注册第一个字面节点。
  
-通常如果你在游戏内输入了 ''/foo bar''，命令不会运行，这是因为当所有条件都满足时，游戏没有可执行的代码。要解决这个问题，你需要告诉游戏如何执行这个命令，方法就是使用 ''executes(Command)'' 方法。因此一个命令看起来应该像下面这样：+<code> 
 +dispatcher.register(literal("foo")) 
 +</code> 
 + 
 +为拥有子命令，需要把下一个节点追加到已经存在的节点后面。 
 + 
 +如下所示，创建命令 ''foo <bar>''。
  
 <code java [enable_line_numbers="true", highlight_lines_extra="3,4,5,6,7"]> <code java [enable_line_numbers="true", highlight_lines_extra="3,4,5,6,7"]>
Line 197: Line 244:
         .executes(context -> {         .executes(context -> {
             // 对于 1.19 以下的版本，使用 ''new LiteralText''。             // 对于 1.19 以下的版本，使用 ''new LiteralText''。
-            context.getSource().sendMessage(Text.literal("调用 foo 和 bar"));+            // 对于 1.20 以下的版本，直接使用 ''Text'' 对象而非 supplier。 
 +            context.getSource().sendFeedback(() -> Text.literal("调用 foo 和 bar"), false);
  
             return 1;             return 1;
Line 205: Line 253:
 </code> </code>
  
 +建议给命令添加节点时缩进你的代码，通常来说缩进对应了命令树中有多少节点的深度，每一次换行也可以看出添加了一个节点。本教程后面会展示格式化树状命令的几种可选样式。
 +
 +类似于参数，子命令节点也可以设置为可选的。在下面这个例子中，''/foo'' 和 ''/foo bar'' 都是有效的。
 +<code java [enable_line_numbers="true"]>
 +dispatcher.register(literal("foo")
 +    .executes(context -> {
 +        context.getSource().sendFeedback(() -> Text.literal("调用 foo 不带 bar"), false);
 +        return 1;
 +    })
 +    .then(literal("bar")
 +        .executes(context -> {
 +            context.getSource().sendFeedback(() -> Text.literal("调用 foo 带有 bar"), false);
 +            return 1;
 +        })
 +    )
 +);
 +</code>
  
 ====== 高级概念 ====== ====== 高级概念 ======
Line 219: Line 284:
 ====== 常见问题 ====== ====== 常见问题 ======
  
-===== 命令为什么不编译 =====+===== 代码为什么不编译 ===== 
 +此问题可能有一些常见的原因。
  
-有两种可能的原因。 +  * **捕获或抛出 CommandSyntaxException：**''CommandSyntaxException'' 不是 ''RuntimeException''，如果抛出，则抛出的地方所在方法必须在方法签名中也抛出 ''CommandSyntaxException''，或者捕获。Brigadier 可以处理此异常，并在游戏内为你提供适当的错误消息。 
- +  * **泛型问题：**你可能遇到了泛型问题。如果你在注册服务器命令（大多数情况都是如此），确保你在静态导入中使用 ''CommandManager.literal(...)'' 或 ''CommandManager.argument(...)'' 而不是''LiteralArgumentBuilder.literal'' 或 ''RequiredArgumentBuilder.argument''。 
-==== 捕获或抛出 CommandSyntaxException ==== +  * **检查 ''sendFeedback'' 方法：**你可能忘记了提供第二个参数（一个布尔值）。还需要注意，从 1.20 开始，第一个参数是 ''Supplier<Text>'' 而不是 ''Text''。 
- +  * **''Command'' 应该返回整数：**注册命令时，''executes'' 方法接受一个 ''Command'' 对象，通常是 lambda。这个 lambda 应该返回整数，而不是其他的类型。
-这个问题的解决方法就是让 ''run'' 或者 ''suggest'' 方法抛出 ''CommandSyntaxException''。Brigadier 会处理已检查的异常，并在游戏内向你提供适当的错误消息。 +
- +
-==== 泛型问题 ==== +
- +
-你可能有时出现了泛型问题，请检查你的静态导入里面用的是不是 ''CommandManager.literal(...)'' 或 ''CommandManager.argument(...)'' 而非 ''LiteralArgumentBuilder'' 或 ''RequiredArgumentBuilder''。+
  
 ===== 可以注册客户端命令吗？ ===== ===== 可以注册客户端命令吗？ =====
  
-Fabric 有个 ClientCommandManager，可以注册客户端命令。+Fabric API 有个 ''ClientCommandManager''，可以注册客户端命令。代码应该仅存在于客户端的代码中。例子：
  
-===== 黑科技 =====+<code java> 
 +    ClientCommandRegistrationCallback.EVENT.register((dispatcher, registryAccess) -> dispatcher.register(ClientCommandManager.literal("foo_client") 
 +        .executes(context -> { 
 +              context.getSource().sendFeedback(Text.literal("此命令是客户端执行的！")); 
 +              return 1; 
 +            } 
 +        ))); 
 +</code>
  
-一些可行但是不推荐的做法：+如果你需要在客户端命令执行过程中打开屏幕，不要直接调用 ''client.setScreen(...)''，你应该调用 ''%%client.execute(() -> client.setScreen(...))%%''，其中变量 ''client'' 可以通过 ''context.getSource().getClient()'' 获得。
  
-==== 可以运行时注册命令吗？ ====+===== 可以运行时注册命令吗？ =====
  
 可以这么做但是不推荐，你可以从服务器中获取 ''CommandManager'' 并向里面添加你希望添加到 ''CommandDispatcher'' 中的任何内容。 可以这么做但是不推荐，你可以从服务器中获取 ''CommandManager'' 并向里面添加你希望添加到 ''CommandDispatcher'' 中的任何内容。
Line 245: Line 313:
 然后你需要通过 ''CommandManager.sendCommandTree(ServerPlayerEntity)'' 向每个玩家再次发送命令树，之所以要这么做，是因为客户端已经缓存了命令树并在登录过程中（或发出管理员封包时）使用，以用于本地的补全和错误消息。 然后你需要通过 ''CommandManager.sendCommandTree(ServerPlayerEntity)'' 向每个玩家再次发送命令树，之所以要这么做，是因为客户端已经缓存了命令树并在登录过程中（或发出管理员封包时）使用，以用于本地的补全和错误消息。
  
-==== 可以在运行时取消注册命令吗？ ====+===== 可以在运行时取消注册命令吗？ =====
  
 可以这么做，但是这更不稳定，并且可能造成未预料的副作用。为简化事情，你需要在 brigadier 中使用反射并移除这个节点，然后还需要再次使用 ''sendCommandTree(ServerPlayerEntity)'' 向每个玩家发送命令树。如果不发送更新的命令树，客户端可能还是会认为命令依然存在，即使服务器已经无法执行。 可以这么做，但是这更不稳定，并且可能造成未预料的副作用。为简化事情，你需要在 brigadier 中使用反射并移除这个节点，然后还需要再次使用 ''sendCommandTree(ServerPlayerEntity)'' 向每个玩家发送命令树。如果不发送更新的命令树，客户端可能还是会认为命令依然存在，即使服务器已经无法执行。
  
zh_cn/tutorial/commands.1700301435.txt.gz · Last modified: 2023/11/18 09:57 by solidblock