Skip navigation links

Package com.mojang.serialization

Contains types used for serializing and deserializing data structures.

See: Description

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:

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

Skip navigation links