Changes

Codecs are a serialization tool from mojang's DataFixerUpper library. Codecs are used alongside [[DynamicOps|DynamicOps/1.16]] to allow objects to be serialized to different formats and back, such as JSON or [[Using_NBT|NBT/1.16]]. While the DynamicOps describes the format the object is to be serialized to, the Codec describes the manner in which the object is to be serialized; a single Codec can be used to serialize an object to any format for which a DynamicOps exists. Codecs and DynamicOps jointly form an abstraction layer over data serialization, simplifying the effort needed to serialize or deserialize data.

Codecs are a serialization tool from mojang's DataFixerUpper library. Codecs are used alongside [[DynamicOps/1.16|DynamicOps]] to allow objects to be serialized to different formats and back, such as JSON or [[Using NBT/1.16|NBT]]. While the DynamicOps describes the format the object is to be serialized to, the Codec describes the manner in which the object is to be serialized; a single Codec can be used to serialize an object to any format for which a DynamicOps exists. Codecs and DynamicOps jointly form an abstraction layer over data serialization, simplifying the effort needed to serialize or deserialize data.

= Using Codecs =

= Using Codecs =

The primary use for Codecs is to serialize java objects to some serialized type, such as a JsonElement or an INBT, and to deserialize an serialized object back to its proper java type. This is accomplished with <code>Codec#encodeStart</code> and <code>Codec#parse</code>, respectively. Given a Codec<SomeJavaType> and a DynamicOps<SomeSerializedType>, we can convert instances of SomeJavaType to instances of SomeSerializedType and back.

The primary use for Codecs is to serialize java objects to some serialized type, such as a JsonElement or an INBT, and to deserialize an serialized object back to its proper java type. This is accomplished with <code>Codec#encodeStart</code> and <code>Codec#parse</code>, respectively. Given a Codec<SomeJavaType> and a DynamicOps<SomeSerializedType>, we can convert instances of SomeJavaType to instances of SomeSerializedType and back.

Each of these methods take a [[DynamicOps/1.16]] instance and an instance of the object we are serializing or deserializing, and returns a DataResult:

Each of these methods take a [[DynamicOps/1.16|DynamicOps]] instance and an instance of the object we are serializing or deserializing, and returns a DataResult:

<syntaxhighlight lang="java">

<syntaxhighlight lang="java">

Codecs created via listOf() serialize things to listlike objects, such as [] json arrays or ListNBTs.

Codecs created via listOf() serialize things to listlike objects, such as [] json arrays or ListNBTs.

Deserializing a list in this manner produces an ''immutable'' list. If a mutable list is needed, [[Codecs#Equivalent_Types_and_xmap|xmap/1.16]] can be used to convert the list after deserializing.

Deserializing a list in this manner produces an ''immutable'' list. If a mutable list is needed, [[Codecs#Equivalent Types and xmap/1.16|xmap]] can be used to convert the list after deserializing.

== Records ==

== Records ==

The <code>Codec.pair(codecA, codecB)</code> static method takes two codecs and generates a Codec<Pair<A,B>> from them.

The <code>Codec.pair(codecA, codecB)</code> static method takes two codecs and generates a Codec<Pair<A,B>> from them.

The only valid arguments for this method are codecs that serialize to objects with explicit fields, such as codecs created using [[Codecs#Records|RecordCodecBuilder/1.16]] or [[Codecs#Boxing_values_as_objects|fieldOf/1.16]]. Codecs that serialize nothing (such as [[Codecs#Unit|unit codecs/1.16]]) are also valid as they act as objects-with-no-fields.

The only valid arguments for this method are codecs that serialize to objects with explicit fields, such as codecs created using [[Codecs#Records/1.16|RecordCodecBuilder]] or [[Codecs#Boxing values as objects/1.16|fieldOf]]. Codecs that serialize nothing (such as [[Codecs#Unit/1.16|unit codecs]]) are also valid as they act as objects-with-no-fields.

The resulting Pair codec will serialize a single object that has all of the fields of the two original codecs. For example:

The resulting Pair codec will serialize a single object that has all of the fields of the two original codecs. For example:

</syntaxhighlight>

</syntaxhighlight>

Codecs that serialize to objects with undefined fields such as [[Codecs#Maps|unboundedMap/1.16]] may cause strange and unpredictable behaviour when used here; these objects should be boxed via fieldOf when used in a pair codec.

Codecs that serialize to objects with undefined fields such as [[Codecs#Maps/1.16|unboundedMap]] may cause strange and unpredictable behaviour when used here; these objects should be boxed via fieldOf when used in a pair codec.

==Either==

==Either==