Differences

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

--- tutorial:command_argument_types [2023/11/18 12:44] – solidblock
+++ tutorial:command_argument_types [2024/04/15 07:21] (current) – [Custom argument serializer] solidblock
@@ Line 80: / Line 80: @@
         // Brigadier has support to show examples for what the argument should look like,
         // this should contain a Collection of only the argument this type will return.
-        // This is mainly used to calculate ambiguous commands which share the exact same.
+        // This is mainly used to detect ambiguity, which means an argument of this type may be parsed as another type.
         return EXAMPLES;
     }
@@ Line 90: / Line 90: @@
 <code java [enable_line_numbers="true"]>
-ArgumentTypeRegistry.registerArgumentType(new Identifier("tutorial", "uuid"), UuidArgumentType.class, ConstantArgumentSerializer.of(UuidArgumentType::uuid));
+ArgumentTypeRegistry.registerArgumentType(
+  new Identifier("tutorial", "uuid"),
+  UuidArgumentType.class, ConstantArgumentSerializer.of(UuidArgumentType::uuid));
 // The argument should be what will create the ArgumentType.
 </code>
@@ Line 166: / Line 168: @@
         // Brigadier has support to show examples for what the argument should look like,
         // this should contain a Collection of only the argument this type will return.
-        // This is mainly used to calculate ambiguous commands which share the exact same.
+        // This is mainly used to detect ambiguity, which means an argument of this type may be parsed as another type.
         return EXAMPLES;
     }
@@ Line 200: / Line 202: @@
 </code>
+===== Custom argument serializer ======
+In the example above, the UUID is simple. If the argument is complex, how to make it correctly send to and understood by the client? This is where ''ArgumentSerializer'' come into use.
+''ArgumentSerializer'' has generic with two type parameters:
+  * The ''ArgumentType''.
+  * The ''ArgumentSerializer.ArgumentTypeProperties<A>'', where ''A'' is the first type parameter. It is usally an immutable object (can be records) containing the basic information (not including ''CommandRegistryAccess'') of the argument type. In some cases, when the ''ArgumentType'' is immutable and does not contain ''CommandRegistryAccess'', it itself can extend ''ArgumentSerializer.ArgumentTypeProperties<A>''.
+In this example, we create a new complicated argument type, which contains a boolean value and an integer value. ''CommandRegistryAccess'' is required in this case.
+<code java>
+public record ExampleArgumentType(CommandRegistryAccess commandRegistryAccess, boolean booleanValue, int intValue) implements ArgumentType<String> {
+  @Override
+  public String parse(StringReader reader) throws CommandSyntaxException {
+    ...
+  }
+  public static class Serializer implements ArgumentSerializer<ExampleArgumentType, Serializer.Properties> {
+    @Override
+    public void writePacket(Properties properties, PacketByteBuf buf) {
+      // Writes the basic properties to a packet. You should ensure all properties
+      // can be in some ways stored in the packet.
+      buf.writeBoolean(properties.booleanValue).writeInt(properties.intValue);
+    }
+    @Override
+    public Properties fromPacket(PacketByteBuf buf) {
+      // Reads the information in the packet. It returns the ''ArgumentSerializer.ArgumentTypeProperties'' instead of ''ArgumentType''.
+      return new Properties(buf.readBoolean(), buf.readInt());
+    }
+    @Override
+    public void writeJson(Properties properties, JsonObject json) {
+      // Present the argument type in the format of JSON.
+      json.addProperty("booleanValue", properties.booleanValue);
+      json.addProperty("intValue", properties.intValue);
+    }
+    @Override
+    public Properties getArgumentTypeProperties(ExampleArgumentType argumentType) {
+      return new Properties(argumentType.booleanValue, argumentType.intValue);
+    }
+    public record Properties(boolean booleanValue, int intValue) implements ArgumentTypeProperties<ExampleArgumentType> {
+      @Override
+      public ExampleArgumentType createType(CommandRegistryAccess commandRegistryAccess) {
+        // Only in this method, ''CommandRegistryAccess'' is provided,
+        // and the argument type that require ''CommandRegistryAccess'' can be created.
+        return new ExampleArgumentType(commandRegistryAccess, booleanValue, intValue);
+      }
+      @Override
+      public ArgumentSerializer<ExampleArgumentType, Serializer.Properties> getSerializer() {
+        // Do not create a new ''Serializer'' object here.
+        return Serializer.this;
+      }
+    }
+  }
+}
+</code>
+And now you can register it like this:
+<code java>
+ArgumentTypeRegistry.registerArgumentType(new Identifier("tutorial", "example"), ExampleArgumentType.class, new ExampleArgumentType.Serializer());
+</code>
+==== Another possible way to define serializer ====
+If the argument does not require ''CommandRegistryAccess'', it itself may extend ''ArgumentSerializer.ArgumentTypeProperties'':
+<code java>
+public record ExampleArgumentType(boolean booleanValue, int intValue) implements ArgumentType<String>, ArgumentSerializer.ArgumentTypeProperties<ExampleArgumentType> {
+  @Override
+  public String parse(StringReader reader) throws CommandSyntaxException {
+    ...
+  }
+  @Override
+  public ExampleArgumentType createType(CommandRegistryAccess commandRegistryAccess) {
+    return this;
+  }
+  @Override
+  public ArgumentSerializer<ExampleArgumentType, ?> getSerializer() {
+    // always return a same object here to avoid failing to serialize.
+    return Serializer.INSTANCE;
+  }
+  public static class Serializer implements ArgumentSerializer<ExampleArgumentType, ExampleArgumentType> {
+    public static final Serializer INSTANCE = new Serializer();
+    private Serializer() {}
+    @Override
+    public void writePacket(ExampleArgumentType properties, PacketByteBuf buf) {
+      buf.writeBoolean(properties.booleanValue).writeInt(properties.intValue);
+    }
+    @Override
+    public ExampleArgumentType fromPacket(PacketByteBuf buf) {
+      return new ExampleArgumentType(buf.readBoolean(), buf.readInt());
+    }
+    @Override
+    public void writeJson(ExampleArgumentType properties, JsonObject json) {
+      json.addProperty("booleanValue", properties.booleanValue);
+      json.addProperty("intValue", properties.intValue);
+    }
+    @Override
+    public ExampleArgumentType getArgumentTypeProperties(ExampleArgumentType argumentType) {
+      return argumentType;
+    }
+  }
+}
+</code>
+And now you can register it like this:
+<code java>
+ArgumentTypeRegistry.registerArgumentType(new Identifier("tutorial", "example"), ExampleArgumentType.class, ExampleArgumentType.Serializer.INSTANCE);
+</code>