Differences

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

--- tutorial:codec [2024/06/30 12:18] – [Dispatching codec] solidblock
+++ tutorial:codec [2024/06/30 14:16] (current) – solidblock
@@ Line 1: / Line 1: @@
-====== Codec (DRAFT) ======
+====== Codecs ======
 ===== What is a codec =====
-A **codec**, introduced in Java Edition 1.16, is a specification of conversion between any type of object (such as ''LootTable'', ''Advancement'' or ''BlockPos'') and any type serialized form (nbt, json, etc.). A codec is a combination of encoder and decoder. An **encoder** encodes an object to serialized form, and a **decoder** decodes the serialized from into objects.
+A **codec**, introduced in Java Edition 1.16, is a specification of conversion between any type of object (such as ''LootTable'', ''Advancement'' or ''BlockPos'') and any serialized form (nbt, json, etc.). A codec is a combination of encoder and decoder. An **encoder** encodes an object to serialized form, and a **decoder** decodes the serialized from into objects.
-For example, loot tables are written in json forms in data packs, and are loaded as ''LootTable'' objects in the server. To load loot tables from the jsons in the data pack, the codec is used, to decode from json files to ''LootTable'' objects. There are many pre-written codecs in Minecraft, each of which, is used for a specific type of object, but can serialize or deserialize between it and different types of serialized from. For example, ''LootTable.CODEC'' can convert ''LootTable'' objects into jsons and nbts, and can also convert jsons or nbts into ''LootTable'' objects.
+For example, loot tables are written in json forms in data packs, and are loaded as ''LootTable'' objects in the server. To load loot tables from the jsons in the data pack, the codec is used, to decode from json files to ''LootTable'' objects. There are many pre-written codecs in Minecraft, each of which, is used for a specific type of object, but can serialize or deserialize between it and different types of serialized form. For example, ''LootTable.CODEC'' can convert ''LootTable'' objects into jsons and nbts, and can also convert jsons or nbts into ''LootTable'' objects.
-Codec was introduced in 1.16, but has mainly been increasingly widely used in Minecraft since 1.20. For example, ''LootTable'', ''Advancements'' and ''Text'', are previously serialized or deserialized in other manners in older versions, but now using codecs. Item components, introduced in 1.20.5, also use codecs to serialize.
+Codec was introduced in 1.16, but has mainly been increasingly widely used in Minecraft since 1.20. For example, ''LootTable'', ''Advancements'' and ''Text'', are previously serialized or deserialized in other manners in older versions, but now using codecs. Item components, introduced in 1.20.5, also use codecs to serialize and deserialize.
 ===== Using a codec =====
@@ Line 25: / Line 25: @@
 </code>
-As seen in the code, the result is not directly ''NbtElement'' or ''BlockPos'', but a ''DataResult'' wrapping them. That's because errors are common in serialization, and instead of exceptions, errors in the data results often happens. You can fetch the result with ''result()'' (which may be empty when error happens), or fecth the error message with ''error()'' (which may be empty when error does not happen). You can also directly fetch the result with ''getOrThrow()'' (or ''Util.getResult'' in older versions).
+As seen in the code, the result is not directly ''NbtElement'' or ''BlockPos'', but a ''DataResult'' wrapping them. That's because errors are common in serialization, and instead of exceptions, errors in the data results often happens. You can fetch the result with ''result()'' (which may be empty when error happens), or fetch the error message with ''error()'' (which may be empty when error does not happen). You can also directly fetch the result with ''getOrThrow()'' (or ''Util.getResult'' in older versions).
 <code java>
-    // get the result when succeed
+    // get the result when succeeded
     final NbtList nbtList = new NbtList();
     nbtList.add(NbtInt.of(1));
@@ Line 41: / Line 41: @@
 </code>
-There is a special type of ''DynamicOps'', named ''RegistryOps'', which is usually created with ''RegistryWrapper.getOps''. It is a wrapper of other ops, which means, when encoding or decoding, it behaves basically identical to the wrapped ops, but have some differences: when encoding or decoding some registry entries, it will use the specified ''RegistryWrapper'' to get objects or entries, while other ops may directly use the registry or even throw an error.
+There is a special type of ''DynamicOps'', named ''RegistryOps'', which is usually created with ''RegistryWrapper.getOps''. It is a wrapper of other ops, which, when encoding or decoding, behaves basically identical to the wrapped ops, but has some differences: when encoding or decoding some registry entries, it will use the specified ''RegistryWrapper'' to get objects or entries, while other ops may directly use the registry or even throw an error.
-===== How to write a codec =====
+===== Writing a codec =====
 ==== Vanilla existing codecs ====
 Mojang has already written many codecs for you. You can directly use them in some cases, and in complex codecs, they may be also useful.
@@ Line 57: / Line 57: @@
   * ''LootTable.CODEC'' is a codec for ''LootTable''.
-Besides, ''Codecs'' privdes from utilities for codecs. For example:
+Besides, ''Codecs'' provdes from utilities for codecs. For example:
   * ''Codecs.JSON_ELEMENT'' is a codec for ''JsonElement''.
   * ''Codecs.NOT_EMPTY_STRING'' is a codec for ''String''. Similar to ''Codec.STRING'', but throws an error when the string is empty.
@@ Line 63: / Line 63: @@
 > **Tips:** You can learn more about how to write codecs by seeing how vanilla codecs are written.
 ==== Mapping existing codec ====
@@ Line 101: / Line 102: @@
 ==== Record codec ====
 === Required fields ===
-Most objects are complicated, which cannot simply represented in primitive type. It may be in a form of a map-like object with multiple fields, such as ''NbtCompound'' or ''JsonObject''. In this case, you need to specify the fields, including name and codecs of the fields. For example, we create a record type:
+Most objects are complicated, which cannot simply be represented in primitive type. It may be in a form of a map-like object with multiple fields, such as ''NbtCompound'' or ''JsonObject''. In this case, you need to specify the fields, including name and codecs of the fields. For example, we create a record type:
 <code java>
 public record Student(String name, int id, Vec3d pos) {
@@ Line 167: / Line 168: @@
 }
 </code>
-Writing like this may be simpler. You need to specify the method to convert fields to an objects at first (''Student::new'' in the example), and then write field codecs following it, with IDEs able to properly provide suggestions. Remember the method name (''apply3'' in the example) should contain the number of fields in this situation. For example, sometimes you may also use ''apply4'', ''apply5'', etc. If your record codec contains only one field, use ''ap''.
+Writing like this may be simpler. You need to specify the method to convert fields to an objects at first (''Student::new'' in this example), and then write field codecs following it, with IDEs able to properly provide suggestions. Remember the method name (''apply3'' in this example) should contain the number of fields in this situation. For example, sometimes you may also use ''apply4'', ''apply5'', etc. If your record codec contains only one field, use ''ap''.
 ==== Dispatching codec ====
-Some objects may not be in fixed structures, but have variant types, each of which, is in a unique structure. Therefore, dispatching codecs are used. When encoding, the codec gets the type from the object, and encode it according to a codec corresponding to the "type". Then the type itself is also added into the result. When decoding, the type is obtained from a map-like object, and then decode it according to the codec corresponding to the "type".
+Some objects may not be in fixed structures, but have variant types, each of which, is in a unique structure. Therefore, dispatching codecs are used.
+When encoding, the codec gets the type from the object, encode it according to a codec corresponding to the "type", then encode the type, and finally add the type as a field ''type'' of the serialized map-like object. When decoding, obtains and decodes the type from the ''type'' field of the map-like object, and then decode it according to the codec corresponding to the type.
 Let's take this example: ''SchoolMember'' has three types: ''Student'', ''Teacher'' and ''Staff'', each of which has a unique structure.
@@ Line 180: / Line 183: @@
 </code>
-It's easy to know that each type can be created a specific codec:
+It's easy to know that each type can be created a specific codec (note that it is ''MapCodec'', not ''Codec''):
 <code java>
 public interface SchoolMember {
   record Student(String name, int id) implements SchoolMember {
-    public static final Codec<Student> CODEC = RecordCodecBuilder.create(i -> i.group(Codec.STRING.fieldOf("name").forGetter(Student::name), Codec.INT.fieldOf("id").forGetter(Student::id)).apply(i, Student::new));
+    public static final MapCodec<Student> CODEC = RecordCodecBuilder.mapCodec(i -> i.group(Codec.STRING.fieldOf("name").forGetter(Student::name), Codec.INT.fieldOf("id").forGetter(Student::id)).apply(i, Student::new));
   }
-  // other types similar
+  // Codecs of other two types are omitted here.
 }
 </code>
@@ Line 219: / Line 222: @@
   }
-  // other two types similar.
+  // The other two types are omitted here.
-  // ...
+}
+</code>
+Now we specified how to get the type from the object. However, it is also required to specify how to get the codec from the type. It can be achieved in many ways, such as storing fields in the type object, or using a map. But in this example, for simplicity, we just use a simple "switch" statements. Then, to create a dispatching codec, invoke method ''**dispatch**'' to the codec of the type:
+<code java>
+  Codec<SchoolMember> CODEC = Type.CODEC.dispatch(SchoolMember::getType, type -> switch (type) {
+    case STAFF -> Staff.CODEC;
+    case STUDENT -> Student.CODEC;
+    case TEACHER -> Teacher.CODEC;
+  });
+</code>
+If you need to specify another name of the field, add a string as a first parameter of ''dispatch'' method.
+Let's see the effect our example:
+  * ''%%new SchoolMember.Student("Steve", 15)%%'' will be encoded as ''{type: student, name: Steve, id: 15}''.
+  * ''{type: teacher, name: Alex, department: chemistry, id: 18}'' will be decoded as ''%%new SchoolMember.Teacher("Alex", "chemistry", 18)%%''.
+> **Note:** Actually, in practice, the types can be more complicated. Therefore, you may use registry for types, such as vanilla ''LootFunctionType'', which has a specific registry ''Registries.LOOT_FUNCTION_TYPE''. It is more flexible and extendable.
+===== Packet codec =====
+A **packet codec**, different from codec, converts between objects and binery packets. It is sometimes similar to codec, and also used in many cases such as item components, but for complex objects, it uses //tuples// instead of //maps//. Packet codecs for primitive types are stored in ''PacketCodecs''. We can also use ''PacketCodec.of'' to directly specify encoding and decoding. For example:
+<code java>
+public record Student(String name, int id, Vec3d pos) {
+  public static final PacketCodec<PacketByteBuf, Student> PACKET_CODEC = PacketCodec.tuple(
+      PacketCodecs.STRING, Student::name,
+      PacketCodecs.INTEGER, Student::id,
+      PacketCodec.of(
+          // encoder: writing to the packet
+          (value, buf) -> buf.writeDouble(value.x).writeDouble(value.y).writeDouble(value.z),
+          // decoder: reading the packet
+          buf -> new Vec3d(buf.readDouble(), buf.readDouble(), buf.readDouble())
+      ), Student::pos,
+      Student::new);
 }
 </code>
-Now we specified how to get the type from the object.
+> **Note:** Besides ''PacketByteBuf'', you may also sometimes see ''RegistryByteBuf''. Similar to ''RegistryOps'' explained before, it works the same as ''PacketByteBuf'', but also provides a ''registryManager'' so as to obtain some registry elements.