Differences

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

--- tutorial:command_exceptions [2022/08/08 02:16] – created (migrated from [[tutorial:commands]]) solidblock
+++ tutorial:command_exceptions [2024/04/15 06:43] (current) – solidblock
@@ Line 1: / Line 1: @@
-======= Exceptions =======
+======= Command Exceptions =======
 Brigadier supports command exceptions which can be used to end a command such as if an argument didn't parse properly or the command failed to execute, as well as including richer details of the failure.
-All the exceptions from Brigadier are based on the ''CommandSyntaxException''. The two main types of exceptions Brigadier provides are Dynamic and Simple exception types, of which you must ''create()'' the exception to throw it. These exceptions also allow you to specify the context in which the exception was thrown using ''createWithContext(ImmutableStringReader)'', which builds the error message to point to where on the inputted command line the error occured.
+There are two type of command exceptions:
+  * **''CommandSyntaxException''**: provided by Brigadier. It should have an exception type, and created through ''create(...)'' or ''createWithContext(...)''. It does not belong to ''RuntimeException'', so when thrown, it must be caught properly, or added in the method signature.
+  * **''<yarn class_2164>'' (removed since 1.20.3)**: provided in Minecraft, and used in less cases. It belongs to ''RuntimeException''. You can directly create it with a ''Text'' as parameter.
+The two main types of ''CommandSyntaxException'' are dynamic and simple exception types, of which you can call ''create()'' to create the exception to throw it. These exceptions also allow you to specify the context in which the exception was thrown using ''createWithContext(ImmutableStringReader)'', which builds the error message to point to where on the inputted command line the error occured.
 Below is a coin flip command to show an example of exceptions in use.
+===== Using CommandException =====
 <code java [enable_line_numbers="true"]>
 dispatcher.register(literal("coinflip")
     .executes(ctx -> {
-        Random random = new Random();
+        Random random = ctx.getSource().getWorld().getRandom();
         if(random.nextBoolean()) { // If heads succeed.
-            ctx.getSource().sendMessage(Text.translatable("coin.flip.heads"))
+            ctx.getSource().sendFeedback(() -> Text.translatable("coin.flip.heads"), true);
             return Command.SINGLE_SUCCESS;
         }
-        throw new SimpleCommandExceptionType(Text.translatable("coin.flip.tails")).create(); // Oh no tails, you lose.
+        throw new CommandException(Text.translatable("coin.flip.tails"));
     }));
 </code>
+:!: ''CommandException'' is removed since 1.20.3.
-Though you are not just limited to a single type of exception as Brigadier also supplies Dynamic exceptions which take additional parameters for context.
+===== Using CommandSyntaxException =====
-<code java [enable_line_numbers="true"]>
+If you use ''CommandSyntaxException'', you should add a ''SimpleCommandExceptionType'' first. It is usually stored as fields, so this example presents the whole class.
-DynamicCommandExceptionType used_name = new DynamicCommandExceptionType(name -> {
-    return Text.literal("The name: " + (String) name + " has been used");
+<code java>
-});
+public class ExampleMod implements ModInitializer {
+  public static final SimpleCommandExceptionType COIN_FLIP_TAILS = new SimpleCommandExceptionType(Text.translatable("coin.flip.tails"));
+  @Override
+  public void onInitialize() {
+    CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) -> dispatcher.register(literal("coinflip")
+        .executes(ctx -> {
+          Random random = ctx.getSource().getWorld().getRandom();
+          if (random.nextBoolean()) { // If heads succeed.
+            ctx.getSource().sendFeedback(() -> Text.translatable("coin.flip.heads"), true);
+            return Command.SINGLE_SUCCESS;
+          }
+          throw COIN_FLIP_TAILS.create();
+        })));
+  }
+}
 </code>
-There are more Dynamic exception types which each take a different amount of arguments into account (''Dynamic2CommandExceptionType'', ''Dynamic3CommandExceptionType'', ''Dynamic4CommandExceptionType'', ''DynamicNCommandExceptionType''). You should remember that the Dynamic exceptions takes an object as an argument so you may have to cast the argument for your use.
+Sometimes you may use ''DynamicCommandExceptionType'' to accept complex exceptions. For example:
+<code java>
+public class ExampleMod implements ModInitializer {
+  public static final DynamicCommandExceptionType COIN_FLIP_TAILS = new DynamicCommandExceptionType(o -> Text.translatable("coin.flip.tails", o));
+  @Override
+  public void onInitialize() {
+    CommandRegistrationCallback.EVENT.register((dispatcher, registryAccess, environment) -> dispatcher.register(literal("coinflip")
+        .executes(ctx -> {
+          Random random = ctx.getSource().getWorld().getRandom();
+          if (random.nextBoolean()) { // If heads succeed.
+            ctx.getSource().sendFeedback(() -> Text.translatable("coin.flip.heads"), true);
+            return Command.SINGLE_SUCCESS;
+          }
+          throw COIN_FLIP_TAILS.create(ctx.getSource().getDisplayName());
+        })));
+  }
+}
+</code>
+There are more Dynamic exception types which each take a different amount of arguments into account (''Dynamic2CommandExceptionType'', ''Dynamic3CommandExceptionType'', ''Dynamic4CommandExceptionType'', ''DynamicNCommandExceptionType''). You should remember that the Dynamic exceptions takes an object as an argument so you may have to cast the argument for your use.
+There are some vanilla exceptions. Some can be found in ''CommandSyntaxException.BUILT_IN_EXCEPTIONS.//<exception type>//()''.