Module net.minestom.server

Package net.minestom.server.codec

Interface Codec<T extends @UnknownNullability Object>

Type Parameters:

T - The type to be represented by this codec, nullable T will provide nullable results.

All Superinterfaces:

Decoder<T>, Encoder<T>

All Known Subinterfaces:

DataComponent<T>, StructCodec<R>

public interface Codec<T extends @UnknownNullability Object>
extends Encoder<T>, Decoder<T>

A Codec represents a combined Encoder and Decoder for a value. Enabling easy encoding and decoding of values to and from a between formats, making serialization simple, reusable and type safe. Going between formats is handled by Transcoder.

Most of the primitive or commonly used codecs are provided as static fields in this interface. For example, INT is a codec for integers, and STRING is a codec for strings. You can even use Enum(Class) for enums, which will convert the enum to a string representation and back.

Codecs are immutable, you must chain methods to create a codec that you want. For example

         Codec<@Nullable String> codec = Codec.STRING.optional()
         Codec<Set<@Nullable String>> setCodec = codec.set();
     
 

Heavily inspired by Mojang/DataFixerUpper, licensed under the MIT license.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Codec.RawValue	A raw value wrapper for entry is an object combined with its current decoder.

Field Summary

Fields

Modifier and Type	Field	Description
static final Codec<Point>	BLOCK_POSITION
static final Codec<Boolean>	BOOLEAN
static final Codec<Byte>	BYTE
static final Codec<byte[]>	BYTE_ARRAY
static final Codec<Component>	COMPONENT
static final Codec<Style>	COMPONENT_STYLE
static final Codec<Double>	DOUBLE
static final Codec<Float>	FLOAT
static final Codec<Integer>	INT
static final Codec<int[]>	INT_ARRAY
static final Codec<Key>	KEY
static final Codec<Long>	LONG
static final Codec<long[]>	LONG_ARRAY
static final Codec<BinaryTag>	NBT
static final Codec<CompoundBinaryTag>	NBT_COMPOUND
static final Codec<Codec.RawValue>	RAW_VALUE
static final Codec<Short>	SHORT
static final Codec<String>	STRING
static final Codec<Unit>	UNIT
static final Codec<UUID>	UUID
static final Codec<UUID>	UUID_COERCED
static final Codec<UUID>	UUID_STRING
static final Codec<Point>	VECTOR3D

Method Summary

Modifier and Type	Method	Description
static <L, R> Codec<Either<L,R>>	Either(Codec<L> leftCodec, Codec<R> rightCodec)	Creates an Either Codec, depending on the value of Either decides which codec to use.
static <E extends Enum<E>> Codec<E>	Enum(Class<E> enumClass)	Creates an enum codec from a given class Converts the Enum.name() into lowercase when encoding and uppercase into decoding then passing it to Enum.valueOf(Class, String)
static <T> Codec<T>	ForwardRef(Supplier<Codec<T>> supplier)	Lazily gets the reference of a codec; considered immutably lazy.
default Codec<@Unmodifiable List<T>>	list()	Creates an unmodifiable unbounded list codec.
default Codec<@Unmodifiable List<T>>	list(int maxSize)	Creates an unmodifiable list codec of Codec where its size is no larger than maxSize.
default Codec<@Unmodifiable @Nullable List<T>>	listOrSingle()	Returns an unmodifiable unbounded list or the first element or null if no such element exists.
default Codec<@Unmodifiable @Nullable List<T>>	listOrSingle(int maxSize)	Returns an unmodifiable list or the first element or null if no such element exists.
default <V> Codec<@Unmodifiable Map<T,V>>	mapValue(Codec<V> valueCodec)	Creates an unmodifiable map of key Codec and value of Codec.
default <V> Codec<@Unmodifiable Map<T,V>>	mapValue(Codec<V> valueCodec, int maxSize)	Creates an unmodifiable map of key Codec and value of Codec
default Codec<@Nullable T>	optional()	Creates an optional codec, where null is encodable into Transcoder.createNull().
default Codec<@UnknownNullability T>	optional(T defaultValue)	Creates an optional codec, where null is encodable and is encoded when value equals defaultValue or null through Transcoder.createNull().
default Codec<T>	orElse(Codec<T> other)	Creates a or else codec where it will attempt to use the first codec then use the second one if it fails.
static <T> Codec<T>	Recursive(Function<Codec<T>,Codec<T>> func)	Create a recursive codec from the parent codec Useful when you want to keep encoding/decoding until there is nothing left.
static <T> StructCodec<T>	RegistryTaggedUnion(String key, Registries.Selector<StructCodec<? extends T>> registrySelector, Function<T,StructCodec<? extends T>> serializerGetter)	Creates a StructCodec to bidirectionally map values of Codec to their encoded values Registry selectors will be used to lookup values of codecs of Codec.
static <T> StructCodec<T>	RegistryTaggedUnion(String key, Registry<StructCodec<? extends T>> registry, Function<T,StructCodec<? extends T>> serializerGetter)	Shortcut for RegistryTaggedUnion(String, Registries.Selector, Function) where selector will be registry
static <T> StructCodec<T>	RegistryTaggedUnion(Registries.Selector<StructCodec<? extends T>> registrySelector, Function<T,StructCodec<? extends T>> serializerGetter)	Shortcut for RegistryTaggedUnion(String, Registries.Selector, Function) where key will be "type"
static <T> StructCodec<T>	RegistryTaggedUnion(Registries.Selector<StructCodec<? extends T>> registrySelector, Function<T,StructCodec<? extends T>> serializerGetter, String key)	Deprecated. Use RegistryTaggedUnion(String, Registries.Selector, Function) instead.
static <T> StructCodec<T>	RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry, Function<T,StructCodec<? extends T>> serializerGetter)	Shortcut for RegistryTaggedUnion(String, Registry, Function) where key will be "type"
static <T> StructCodec<T>	RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry, Function<T,StructCodec<? extends T>> serializerGetter, String key)	Deprecated. Use RegistryTaggedUnion(String, Registry, Function) instead.
default Codec<@Unmodifiable Set<T>>	set()	Creates an unmodifiable unbounded set.
default Codec<@Unmodifiable Set<T>>	set(int maxSize)	Creates an unmodifiable set where its max is no larger than maxSize
default <S extends @UnknownNullability Object> Codec<S>	transform(ThrowingFunction<T,S> to, ThrowingFunction<S,T> from)	Transforms an object from Codec to another Codec and from Codec back to Codec
default <R> StructCodec<R>	unionType(String keyField, Function<T,StructCodec<? extends R>> serializers, Function<R,? extends T> keyFunc)	Creates a union type of type Codec Useful when you have an interface of Codec and want a codec subclasses of Codec
default <R> StructCodec<R>	unionType(Function<T,StructCodec<? extends R>> serializers, Function<R,? extends T> keyFunc)	Creates a union type of type Codec.

Methods inherited from interface net.minestom.server.codec.Decoder

decode

Methods inherited from interface net.minestom.server.codec.Encoder

encode

Field Details

RAW_VALUE

static final Codec<Codec.RawValue> RAW_VALUE

UNIT

static final Codec<Unit> UNIT

BOOLEAN

static final Codec<Boolean> BOOLEAN

BYTE

static final Codec<Byte> BYTE

SHORT

static final Codec<Short> SHORT

INT

static final Codec<Integer> INT

LONG

static final Codec<Long> LONG

FLOAT

static final Codec<Float> FLOAT

DOUBLE

static final Codec<Double> DOUBLE

STRING

static final Codec<String> STRING

KEY

static final Codec<Key> KEY

BYTE_ARRAY

static final Codec<byte[]> BYTE_ARRAY

INT_ARRAY

static final Codec<int[]> INT_ARRAY

LONG_ARRAY

static final Codec<long[]> LONG_ARRAY

UUID

static final Codec<UUID> UUID

UUID_STRING

static final Codec<UUID> UUID_STRING

UUID_COERCED

static final Codec<UUID> UUID_COERCED

COMPONENT

static final Codec<Component> COMPONENT

COMPONENT_STYLE

static final Codec<Style> COMPONENT_STYLE

BLOCK_POSITION

static final Codec<Point> BLOCK_POSITION

VECTOR3D

static final Codec<Point> VECTOR3D

NBT

static final Codec<BinaryTag> NBT

NBT_COMPOUND

static final Codec<CompoundBinaryTag> NBT_COMPOUND

Method Details

Enum

@Contract(pure=true,
          value="_ -> new")
static <E extends Enum<E>> Codec<E> Enum(Class<E> enumClass)

Creates an enum codec from a given class
Converts the Enum.name() into lowercase when encoding and uppercase into decoding then passing it to Enum.valueOf(Class, String)

Type Parameters:

E - Enum type, E must be an enum

Parameters:

enumClass - the enum class

Returns:

the codec enum

Recursive

@Contract(pure=true,
          value="_ -> new")
static <T> Codec<T> Recursive(Function<Codec<T>,Codec<T>> func)

Create a recursive codec from the parent codec
Useful when you want to keep encoding/decoding until there is nothing left.

Type Parameters:

T - The codec Type

Parameters:

func - the function to get the codec from.

Returns:

the recursive codec

ForwardRef

@Contract(pure=true,
          value="_ -> new")
static <T> Codec<T> ForwardRef(Supplier<Codec<T>> supplier)

Lazily gets the reference of a codec; considered immutably lazy.
Useful for breaking possible cyclic loading of recursive codecs. This may become a stable value in the future; don't rely on supplier getting called multiple times.

Type Parameters:

T - the codec type

Parameters:

supplier - the supplier to load the codec from.

Returns:

the supplier

RegistryTaggedUnion

@Deprecated
@Contract(pure=true,
          value="_, _, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry,
 Function<T,StructCodec<? extends T>> serializerGetter,
 String key)

Deprecated.

Use RegistryTaggedUnion(String, Registry, Function) instead. Shortcut for RegistryTaggedUnion(Registries.Selector, Function, String)

Type Parameters:

T - the struct codec type.

Parameters:

registry - the codec registry

serializerGetter - the codec getter

key - the map key

Returns:

a StructCodec

RegistryTaggedUnion

@Deprecated
@Contract(pure=true,
          value="_, _, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(Registries.Selector<StructCodec<? extends T>> registrySelector,
 Function<T,StructCodec<? extends T>> serializerGetter,
 String key)

Deprecated.

Use RegistryTaggedUnion(String, Registries.Selector, Function) instead. Creates a StructCodec to bidirectionally map values of Codec to their encoded values
Registry selectors will be used to lookup values of codecs of Codec. Then will be used to map to object Codec from key

Type Parameters:

T - the codec type

Parameters:

registrySelector - the registry selector used during lookup.

serializerGetter - the serializer for each value of Codec

key - the map key for Codec

Returns:

a StructCodec bidirectionally mapping values of Codec

RegistryTaggedUnion

@Contract(pure=true,
          value="_, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(Registry<StructCodec<? extends T>> registry,
 Function<T,StructCodec<? extends T>> serializerGetter)

Shortcut for RegistryTaggedUnion(String, Registry, Function) where key will be "type"

Type Parameters:

T - the struct codec type.

Parameters:

registry - the codec registry

serializerGetter - the codec getter

Returns:

a StructCodec

RegistryTaggedUnion

@Contract(pure=true,
          value="_, _, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(String key,
 Registry<StructCodec<? extends T>> registry,
 Function<T,StructCodec<? extends T>> serializerGetter)

Shortcut for RegistryTaggedUnion(String, Registries.Selector, Function) where selector will be registry

Type Parameters:

T - the struct codec type.

Parameters:

key - the map key

registry - the codec registry

serializerGetter - the codec getter

Returns:

a StructCodec

RegistryTaggedUnion

@Contract(pure=true,
          value="_, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(Registries.Selector<StructCodec<? extends T>> registrySelector,
 Function<T,StructCodec<? extends T>> serializerGetter)

Shortcut for RegistryTaggedUnion(String, Registries.Selector, Function) where key will be "type"

Type Parameters:

T - the codec type

Parameters:

registrySelector - the registry selector used during lookup.

serializerGetter - the serializer for each value of Codec

Returns:

a StructCodec bidirectionally mapping values of Codec

RegistryTaggedUnion

@Contract(pure=true,
          value="_, _, _ -> new")
static <T> StructCodec<T> RegistryTaggedUnion(String key,
 Registries.Selector<StructCodec<? extends T>> registrySelector,
 Function<T,StructCodec<? extends T>> serializerGetter)

Creates a StructCodec to bidirectionally map values of Codec to their encoded values
Registry selectors will be used to lookup values of codecs of Codec. Then will be used to map to object Codec from key

Type Parameters:

T - the codec type

Parameters:

key - the map key for Codec

registrySelector - the registry selector used during lookup.

serializerGetter - the serializer for each value of Codec

Returns:

a StructCodec bidirectionally mapping values of Codec

Either

@Contract(pure=true,
          value="_, _ -> new")
static <L,
R> Codec<Either<L,R>> Either(Codec<L> leftCodec,
 Codec<R> rightCodec)

Creates an Either Codec, depending on the value of Either decides which codec to use.

Type Parameters:

L - the left type

R - the right type

Parameters:

leftCodec - the left codec

rightCodec - the right codec

Returns:

a Codec with Either of Codec and Codec

optional

@Contract(pure=true,
          value="-> new")
default Codec<@Nullable T> optional()

Creates an optional codec, where null is encodable into Transcoder.createNull().

Returns:

the optional codec of type Codec

optional

@Contract(pure=true,
          value="_ -> new")
default Codec<@UnknownNullability T> optional(T defaultValue)

Creates an optional codec, where null is encodable and is encoded when value equals defaultValue or null through Transcoder.createNull().
The default value will be used if the decoding is null or fails to decode.

Parameters:

defaultValue - the default value

Returns:

the optional codec of type Codec

Throws:

NullPointerException - if defaultValue is null, use optional() instead.

transform

@Contract(pure=true,
          value="_, _ -> new")
default <S extends @UnknownNullability Object>
Codec<S> transform(ThrowingFunction<T,S> to,
 ThrowingFunction<S,T> from)

Transforms an object from Codec to another Codec and from Codec back to Codec

Type Parameters:

S - the type

Parameters:

to - the function to Codec from Codec

from - the function from Codec to Codec

Returns:

the transforming codec of Codec

list

@Contract(pure=true,
          value="_ -> new")
default Codec<@Unmodifiable List<T>> list(int maxSize)

Creates an unmodifiable list codec of Codec where its size is no larger than maxSize.

Parameters:

maxSize - the max size of the list before returning an error result.

Returns:

the list codec of type Codec

list

@Contract(pure=true,
          value="-> new")
default Codec<@Unmodifiable List<T>> list()

Creates an unmodifiable unbounded list codec. See list(int)

Returns:

the unbounded list codec of type Codec

listOrSingle

@Contract(pure=true,
          value="_ -> new")
default Codec<@Unmodifiable @Nullable List<T>> listOrSingle(int maxSize)

Returns an unmodifiable list or the first element or null if no such element exists.

Parameters:

maxSize - the max size of the list before returning an error result

Returns:

the list codec of type Codec

listOrSingle

@Contract(pure=true,
          value="-> new")
default Codec<@Unmodifiable @Nullable List<T>> listOrSingle()

Returns an unmodifiable unbounded list or the first element or null if no such element exists. See listOrSingle(int)

Returns:

the list codec of type Codec

set

@Contract(pure=true,
          value="_ -> new")
default Codec<@Unmodifiable Set<T>> set(int maxSize)

Creates an unmodifiable set where its max is no larger than maxSize

Parameters:

maxSize - the max size before returning an error result

Returns:

the set codec of type Codec

set

@Contract(pure=true,
          value="-> new")
default Codec<@Unmodifiable Set<T>> set()

Creates an unmodifiable unbounded set. See set(int)

Returns:

the set codec of type Codec

mapValue

@Contract(pure=true,
          value="_, _ -> new")
default <V> Codec<@Unmodifiable Map<T,V>> mapValue(Codec<V> valueCodec,
 int maxSize)

Creates an unmodifiable map of key Codec and value of Codec

Type Parameters:

V - the value type

Parameters:

valueCodec - the codec to use for Codec

maxSize - the max size before returning an error result.

Returns:

the map codec of type Codec and Codec

mapValue

@Contract(pure=true,
          value="_ -> new")
default <V> Codec<@Unmodifiable Map<T,V>> mapValue(Codec<V> valueCodec)

Creates an unmodifiable map of key Codec and value of Codec. See mapValue(Codec, int)

Type Parameters:

V - the value type

Parameters:

valueCodec - the codec to use for Codec

Returns:

the map codec of type Codec and Codec

unionType

@Contract(pure=true,
          value="_, _ -> new")
default <R> StructCodec<R> unionType(Function<T,StructCodec<? extends R>> serializers,
 Function<R,? extends T> keyFunc)

Creates a union type of type Codec. See unionType(String, Function, Function)
Useful when you have an interface of Codec and want a codec subclasses of Codec

Type Parameters:

R - the return type; Codec or a subclass

Parameters:

serializers - the map from Codec value to its serializer

keyFunc - to map from Codec to its value of Codec

Returns:

the struct codec union of Codec

unionType

@Contract(pure=true,
          value="_, _, _ -> new")
default <R> StructCodec<R> unionType(String keyField,
 Function<T,StructCodec<? extends R>> serializers,
 Function<R,? extends T> keyFunc)

Creates a union type of type Codec
Useful when you have an interface of Codec and want a codec subclasses of Codec

Type Parameters:

R - the return type; Codec or a subclass

Parameters:

keyField - the map key

serializers - the map from Codec value to its serializer

keyFunc - to map from Codec to its value of Codec

Returns:

the struct codec union of Codec

orElse

@Contract(pure=true,
          value="_ -> new")
default Codec<T> orElse(Codec<T> other)

Creates a or else codec where it will attempt to use the first codec then use the second one if it fails.
If both codecs fail the first error will be returned instead.

Parameters:

other - the other codec

Returns:

the or else codec of Codec