Fabric Wiki

User Tools

Site Tools

Trace: • 添加游戏规则 • 自定义按键绑定 • 使用 Minotaur 在 Modrinth 上发布模组 • Adding Structure Features [1.16.3]
tutorial:codec

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:codec [2024/06/30 13:20] – solidblocktutorial:codec [2024/06/30 14:16] (current) – solidblock
Line 1: Line 1:
-====== Codec (DRAFT) ======+====== Codecs ======
  
 ===== What is a codec ===== ===== 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 ===== ===== Using a codec =====
Line 25: Line 25:
 </code> </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> <code java>
-    // get the result when succeed+    // get the result when succeeded
     final NbtList nbtList = new NbtList();     final NbtList nbtList = new NbtList();
     nbtList.add(NbtInt.of(1));     nbtList.add(NbtInt.of(1));
Line 41: Line 41:
 </code> </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.
  
 ===== Writing a codec ===== ===== Writing a codec =====
Line 57: Line 57:
   * ''LootTable.CODEC'' is a codec for ''LootTable''.   * ''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.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.   * ''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. > **Tips:** You can learn more about how to write codecs by seeing how vanilla codecs are written.
 +
 ==== Mapping existing codec ==== ==== Mapping existing codec ====
  
Line 101: Line 102:
 ==== Record codec ==== ==== Record codec ====
 === Required fields === === 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> <code java>
 public record Student(String name, int id, Vec3d pos) { public record Student(String name, int id, Vec3d pos) {
Line 167: Line 168:
 } }
 </code> </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 ==== ==== 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. 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.
Line 243: Line 244:
  
 ===== Packet codec ===== ===== 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//. We can also use ''PacketCodec.of'' to directly specify encoding and decoding. For example:+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> <code java>
 public record Student(String name, int id, Vec3d pos) { public record Student(String name, int id, Vec3d pos) {
Line 259: Line 260:
 </code> </code>
  
 +> **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.
tutorial/codec.1719753632.txt.gz · Last modified: 2024/06/30 13:20 by solidblock