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.

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.

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.

When you serialize or deserialize, you need to specify a DynamicOps, which specifies each concrete action in the serialization or deserialization. The most common used are JsonOps.INSTANCE and NbtOps.INSTANCE. The following code shows an example of converting between BlockPos and NbtElement.

    // serializing a BlockPos
    final BlockPos blockPos = new BlockPos(1, 2, 3);
    final DataResult<NbtElement> encodeResult = BlockPos.CODEC.encodeStart(NbtOps.INSTANCE, blockPos);
 
    // deserializing a BlockPos
    final NbtList nbtList = new NbtList();
    nbtList.add(NbtInt.of(1));
    nbtList.add(NbtInt.of(2));
    nbtList.add(NbtInt.of(3));
    final DataResult<Pair<BlockPos, NbtElement>> decodeResult = BlockPos.CODEC.decode(NbtOps.INSTANCE, nbtList);

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).

    // get the result when succeed
    final NbtList nbtList = new NbtList();
    nbtList.add(NbtInt.of(1));
    nbtList.add(NbtInt.of(2));
    nbtList.add(NbtInt.of(3));
    final DataResult<Pair<BlockPos, NbtElement>> result1 = BlockPos.CODEC.decode(NbtOps.INSTANCE, nbtList);
    System.out.println(result1.getOrThrow().getFirst());
 
    // get the result when error
    final NbtString nbtString = NbtString.of("can't decode me");
    final DataResult<Pair<BlockPos, NbtElement>> result2 = BlockPos.CODEC.decode(NbtOps.INSTANCE, nbtString);
    System.out.println(result2.error().get().message());

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.

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.

For primitive types, codecs are stored as fields of Codec. For example:

• Codec.BOOLEAN is a codec for boolean.
• Codec.INT is a codec for int.
• Codec.FLOAT is a codec for float.

For classes belonging to Minecraft, codecs are stored as their fields. For example:

• Identifier.CODEC is a codec for Identifier.
• BlockPos.CODEC is a codec for BlockPos.
• LootTable.CODEC is a codec for LootTable.

Besides, Codecs privdes 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.
• Codecs.rangedInt(1, 5) is a codec for Integer, but throws an error when the integer is not within range [1, 5].

Tips: You can learn more about how to write codecs by seeing how vanilla codecs are written.

For simple objects, you can directly convert it between those have existing codecs. Mojang provides codecs for all primitive types and common types. In this example, you want to create a codec for Identifier. We just know that it can be converted from and to a String, then we map through xmap:

    // replace ''Identifier.of'' with ''new Identifier'' for versions before 1.21.
    Codec<Identifier> identifierCodec = Codec.STRING.xmap(s -> Identifier.of(s), identifier -> identifier.toString());

When decoding, the serialized from is converted into string through Codec.STRING, and then converted into Identifier through the first lambda. When encoding, the Identifier is converted into string through the second lambda, and then encoded through Codec.STRING.

If the serialized from is something that cannot be converted into a string, a codec result may be DataResult.Error, and handled properly as expected. However, if you pass a string that cannot be an Identifier, such as NbtString.of(“ABC”), decoding it will directly throw InvalidIdentifierException. Therefore, to handle errors properly, we use flatXmap:

    Codec<Identifier> identifierCodec = Codec.STRING.flatXmap(s -> {
      try {
        // replace ''Identifier.of'' with ''new Identifier'' for versions before 1.21.
        return DataResult.success(Identifier.of(s));
      } catch (InvalidIdentifierException e) {
        return DataResult.error(() -> "The identifier is invalid:" + e.getMessage());
      }
    }, identifier -> DataResult.success(identifier.toString()));

Note that this time we use flatXmap instead of xmap, in which, the two lambdas returns DataResult. This is used then two lambdas may return failed results. In this case, the second lambda does not fail, so we can also use comapFlatMap:

    Codec<Identifier> identifierCodec = Codec.STRING.comapFlatMap(s -> {
      try {
        // replace ''Identifier.of'' with ''new Identifier'' for versions before 1.21.
        return DataResult.success(Identifier.of(s));
      } catch (InvalidIdentifierException e) {
        return DataResult.error(() -> "The identifier is invalid:" + e.getMessage());
      }
    }, identifier -> identifier.toString());

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:

public record Student(String name, int id, Vec3d pos) {
}

To create a codec for this record, we should specify the fields codec, specify how to get fields from a Student object, and specify how to create a Student object from the fields:

  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),
      Vec3d.CODEC.fieldOf("pos").forGetter(Student::pos)
  ).apply(i, Student::new));

In this example, the method group takes three fields, specifying each field of the record. The parameter of fieldOf is the name of the field, which represents as keys of the encodec result. The method forGetter specifies how to get the value of the field from the object, such as student → student.name() (in lambda form) or Student::name (in method reference form). The second parameter of apply specified how to convert the field values to a complete object, such as (string, i, vec3d) → new Student(string, i, vec3d).

Let's demonstrate the effect of the codec:

• new Student("Steve", 20, Vec3d.ZERO) will be encoded as {name: Steve, id: 20, pos: [0, 0, 0]}.
• new Student("Alex", 25, new Vec3d(1d, 2d, 3d)) will be encoded as {name: Alex, id: 25, pos: [1d, 2d, 3d]}.
• {name: Steve, id: 20, pos: [0, 0, 0]} will be decoded as new Student("Steve", 20, Vec3d.ZERO).
• {name: Steve, id: 30} cannot be decoded, because it misses a required field pos.

Sometimes all fields are not required. In the previous example, if the encoded result misses some fields, error will be thrown. To make the fields optional, use optionalFieldOf. You also need to specify a default value:

  public static final Codec<Student> CODEC = RecordCodecBuilder.create(i -> i.group(
      Codec.STRING.fieldOf("name").forGetter(Student::name),
      Codec.INT.optionalFieldOf("id", 0).forGetter(Student::id),
      Vec3d.CODEC.fieldOf("pos").forGetter(Student::pos)
  ).apply(i, Student::new));

In this case, when decoding, when the field id does not exist, the default value 0 will be taken. When encoding, when the field equals to default value 0, it will be missing in the result. For example:

• new Student("Steve", 0, Vec3d.ZERO) will be encoded as {name: Steve, pos: [0, 0, 0]}.
• {name: Steve, pos: [0, 0, 0]} will be decoded as new Student("Steve", 0, Vec3d.ZERO).
• Of course, {name: Steve, id: 0, pos: [0, 0, 0]} will be also decoded as new Student("Steve", 0, Vec3d.ZERO).
• {name: Steve, id: Hello, pos: [0, 0, 0]} cannot be decoded, because the field id is invalid.

Pay attention to the last example. When decoding, when an optional field has an invalid value, error will be thrown. Howevevr, in older Minecraft versions, when an optional field has an invalid value, the default value will be directly taken.

• In older Minecraft versions, {name: Steve, id: Hello, pos: [0, 0, 0]} will be encoded as new Student("Steve", 0, Vec3d.ZERO).

Note: In current versions, you can also replace optionalFieldOf with lenientOptionalFieldOf, so as to take default values when the value is invalid.

If you do not provide a default value for optionalFieldOf or lenientOptionalFieldOf, it will be a field codec for Optional<T>. For example, if the name of a Student is optional:

public record Student(Optional<String> name, int id, Vec3d pos) {
  public static final Codec<Student> CODEC = RecordCodecBuilder.create(i -> i.group(
      Codec.STRING.optionalFieldOf("name").forGetter(Student::name),
      Codec.INT.fieldOf("id").forGetter(Student::id),
      Vec3d.CODEC.fieldOf("pos").forGetter(Student::pos)
  ).apply(i, Student::new));
}

The codec can also be written like this:

public record Student(String name, int id, Vec3d pos) {
  public static final Codec<Student> CODEC = RecordCodecBuilder.create(i -> i.apply3(
      Student::new,
      Codec.STRING.fieldOf("name").forGetter(Student::name),
      Codec.INT.fieldOf("id").forGetter(Student::id),
      Vec3d.CODEC.fieldOf("pos").forGetter(Student::pos)
  ));
}

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.

Some objects may have different types. In the serialized form, it may need a “type”, and according to the “type”, specify a codec to deserialize or serialize.