Package com.mojang.serialization

Contains types used for serializing and deserializing data structures.

See: Description

Interface Summary

Interface	Description
Codec<A>	A combined Decoder and Encoder.
Codec.ResultFunction<A>	A unary operator applied on the result obtained from decoding or encoding from a Codec.
Compressable	A Keyable that furthermore supports key compression.
Decoder<A>	Deserializes (decodes) objects of a given type from a serialized form.
Decoder.Boxed<A>	A simple decoder interface that decodes an object from a Dynamic.
Decoder.Simple<A>	A simple decoder interface that completely decodes an object from a Dynamic, discarding any remaining serialized data.
Decoder.Terminal<A>	A simple decoder interface that discards any serialized input that was not used to decode the object.
DynamicOps<T>	An adapter for a hierarchical serialization format.
Encoder<A>	Serializes (encodes) objects of a given type to a serialized form.
Keyable	A definer or acceptor of serialized keys.
ListBuilder<T>
MapCodec.ResultFunction<A>	A unary operator applied on the result obtained from decoding or encoding from a MapCodec.
MapDecoder<A>	Deserializes (decodes) a fixed set of record fields from a serialized form.
MapEncoder<A>	Serializes (encodes) a fixed set of record fields to a serialized form.
MapLike<T>	An unmodifiable store for serialized key-value pairs.
RecordBuilder<T>

Class Summary

Class	Description
CompressorHolder	Abstract base class for Compressable objects.
DataResult<R>	Represents either a successful operation, or a partial operation with an error message and a partial result (if available).
DataResult.Instance.Mu	A marker class representing the meta-type constructor DataResult.Instance.
DataResult.Mu	A marker interface representing the type constructor DataResult.
DataResult.PartialResult<R>	A container for a partial result in an error DataResult.
Dynamic<T>	Encapsulates the serialized form of a single value.
DynamicLike<T>	An abstract base class for objects that encapsulate a value of some serialized type.
JsonOps	A DynamicOps adapter for JSON.
KeyCompressor<T>	An immutable collection of indexed, string-convertible keys.
Lifecycle	A marker defining the stability of a given result.
Lifecycle.Deprecated	A class for deprecated lifecycles.
ListBuilder.Builder<T>
MapCodec<A>	A combined MapEncoder and MapDecoder.
MapCodec.MapCodecCodec<A>	A Codec adapter for a MapCodec.
MapDecoder.Implementation<A>	A class that implements both MapDecoder and Compressable.
MapEncoder.Implementation<A>	A class that implements both MapEncoder and Compressable.
OptionalDynamic<T>
RecordBuilder.AbstractBuilder<T,R>
RecordBuilder.AbstractStringBuilder<T,R>
RecordBuilder.AbstractUniversalBuilder<T,R>
RecordBuilder.MapBuilder<T>

Enum Summary

Enum	Description
DataResult.Instance	The applicative functor type instance for the type constructor DataResult.

Package com.mojang.serialization Description

Contains types used for serializing and deserializing data structures. This includes adapters for generating and parsing serialized forms, such as DynamicOps and Dynamic; and schemas for encoding and decoding data structures, such as Codec and MapCodec.

Serialization Adapters

Serialization adapters are low level interfaces used to marshall simple data types into a joint serialized form. Programmers should generally not use these adapters to directly serialize values, and should prefer using the Codec abstraction unless performance requires using the adapter directly.

Instances of DynamicOps allow for the extraction and insertion of simple data types to an underlying serialized form such as JSON or NBT. Low-level serialization and deserialization methods in DFU all take a DynamicOps object as an argument, through which serialization and deserialization should be delegated. The class JsonOps is a provided implementation for the JSON serialized form.

Instances of Dynamic are type-safe wrappers for serialized values which are guaranteed to be associated with a corresponding DynamicOps instance. When returning or accepting a serialized value, programmers may find it useful to use instances of Dynamic instead of manually keeping track of DynamicOps instances. However, usage of these objects is uncommon outside of low level serialization code in practice.

Encoders and Decoders

Encoders and decoders are high level APIs which can be used to construct complex serialization and deserialization routines for structurally hierarchical objects. Programmers should generally prefer using Codec to actually build these routines, since typically both encoding and decoding operations are desired.

General purpose implementations of Codec and its supporting types are provided for programmer usage, although programmers are free to provide additional implementations for most types. Note that additional implementations will not be drop-in replaceable with code that uses the provided implementation.

Building Codecs

Codecs allow the programmer to define a bidirectional transformation for a record-like object that is generic over any hierarchical serialization format. The programmer starts with one of the provided primitive codecs and chains composition methods to build arbitrarily complex structures. Commonly used codec methods include:

• Codec.listOf() builds a codec for a list from a codec for its elements.
• Codec.unboundedMap(com.mojang.serialization.Codec, com.mojang.serialization.Codec) builds a codec for an arbitrary-keyed map based on codecs for the key and value types.
• Codec.fieldOf(java.lang.String) builds a codec for a key in a record from a codec for the value of that field.
• Codec.optionalFieldOf(java.lang.String) builds a codec for an optional serialized value based on a codec for the present value.
• Codec.xmap(java.util.function.Function, java.util.function.Function) and related methods use a bidirectional transformation to produce a codec for another type.
• Codec.dispatch(java.util.function.Function, java.util.function.Function) and related methods allow for dynamically dispatching a polymorphic object/serialized form based on a type key.

To build a codec for a record-like object, the RecordCodecBuilder class is used to collect codecs for each record element. The general form for constructing a record codec is predictable and is typically as follows.

 RecordCodecBuilder.create(inst -> inst.group(
     field1Codec.fieldOf("Field1").forGetter(r -> r.field1),
     field2Codec.fieldOf("Field2").forGetter(r -> r.field2),
     ...
     fieldNCodec.fieldOf("FieldN").forGetter(r -> r.field3)
 ).apply(inst, SomeRecord::new))

Codecs are immutable and should be stored in a static location once constructed.