Codecs - Revision history

Blabliblubpaul: /* Lists */

2024-01-10T18:45:29Z

Lists

TheSilkMiner: Keep the only change made by Blabliblubpaul that made sense

2024-01-10T18:20:14Z

Keep the only change made by Blabliblubpaul that made sense

ChampionAsh5357: Reverted edits by Blabliblubpaul (talk) to last revision by Commoble

2024-01-10T12:57:27Z

Reverted edits by Blabliblubpaul (talk) to last revision by Commoble

Blabliblubpaul: /* Using Codecs */

2024-01-10T09:43:24Z

Using Codecs

Commoble: /* Registry Dispatch */

2023-11-23T17:22:38Z

Registry Dispatch

Commoble: Fix incorrect name in pair codec example

2021-08-06T20:41:34Z

Fix incorrect name in pair codec example

ChampionAsh5357: Update to 1.17

2021-08-02T19:42:13Z

Update to 1.17

Commoble: Add note that listOf codecs produce immutable Lists

2021-01-09T21:19:51Z

Add note that listOf codecs produce immutable Lists

Commoble: Remove incorrect statement re: pairs and strings from Maps section, clarify relationship between map keys and object fields

2021-01-06T00:41:46Z

Remove incorrect statement re: pairs and strings from Maps section, clarify relationship between map keys and object fields

Commoble: Add boxing/fieldOf link to Pair section, add warning for unbounded maps, add Pair example

2021-01-06T00:38:37Z

Add boxing/fieldOf link to Pair section, add warning for unbounded maps, add Pair example

@@ Line 92: / Line 92: @@
 As previously mentioned, we can use <code>Codec.INT</code> for the integer codec, and <code>Registry.ITEM</code> for the Item codec. We don't have a builtin codec for list-of-blockpos, but we can use BlockPos.CODEC to create one.
-== Lists ==
+==Lists==
 The <code>Codec#listOf</code> instance method can be used to generate a codec for a List from an existing codec:
 <syntaxhighlight lang="java">
 // BlockPos.CODEC is a Codec<BlockPos>
-Codec<List<BlockPos>> = BlockPos.CODEC.listOf();
+Codec<List<BlockPos>> blockPosListCodec = BlockPos.CODEC.listOf();
 </syntaxhighlight>

@@ Line 5: / Line 5: @@
 == Serialization and Deserialization ==
-The primary use for Codecs is to serialize java objects to some serialized type, such as a JsonElement or a Tag, 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 a Tag, and to deserialize a 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]] instance and an instance of the object we are serializing or deserializing, and returns a DataResult:
@@ Line 18: / Line 18: @@
 // deserialize some Tag instance back to a proper java object
-DataResult<SomeJavaType> result = someCodec.parse(NBTOps.INSTANCE, someTag );
+DataResult<SomeJavaType> result = someCodec.parse(NBTOps.INSTANCE, someTag);
 // serialize some java object to a JsonElement

@@ Line 1: / Line 1: @@
 Codecs are a serialization tool from mojang's DataFixerUpper library. Codecs are used alongside [[DynamicOps|DynamicOps]] to allow objects to be serialized to different formats and back, such as JSON or [[Using_NBT|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 =
 ==Serialization and Deserialization==
-The primary use for Codecs is to serialize java objects to some serialized type, such as a JsonElement or a Tag, and to deserialize a 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.
+== Serialization and Deserialization ==
 Each of these methods take a [[DynamicOps]] instance and an instance of the object we are serializing or deserializing, and returns a DataResult:
@@ Line 34: / Line 36: @@
 </syntaxhighlight>
-</someserializedtype></somejavatype>
+== Builtin Codecs ==
-==Builtin Codecs==
+=== Primitive Codecs ===
-===Primitive Codecs===
+The Codec class itself contains static instances of codecs for all supported primitive types, e.g. <code>Codec.STRING</code> is the canonical <code>Codec<String></code> implementation. Primitive codecs include:
 * BOOL, which serializes to a boolean value
 * BYTE, SHORT, INT, LONG, FLOAT, and DOUBLE, which serialize to numeric values
@@ Line 44: / Line 45: @@
 * EMPTY, which represents null objects
-===Other Builtin Codecs===
+=== Other Builtin Codecs ===
-Vanilla minecraft has many builtin codecs for objects that it frequently serializes. These codecs are typically static instances in the class the codec is serializing; e.g. <code>ResourceLocation.CODEC</code> is the canonical <code>Codec<resourcelocation></resourcelocation></code>, while <code>BlockPos.CODEC</code> is the codec used for serializing a BlockPos.
+Vanilla minecraft has many builtin codecs for objects that it frequently serializes. These codecs are typically static instances in the class the codec is serializing; e.g. <code>ResourceLocation.CODEC</code> is the canonical <code>Codec<ResourceLocation></code>, while <code>BlockPos.CODEC</code> is the codec used for serializing a BlockPos.
-Each vanilla <code>Registry</code> acts as the Codec for the type of object the registry contains; e.g. <code>Registry.BLOCK</code> is itself a <code>Codec<block></block></code>. Forge Registries, however, do not currently implement Codec and cannot yet be used in this way; custom codecs must be created for forge-specific registries that are not tied to specific vanilla registries.
+Each vanilla <code>Registry</code> acts as the Codec for the type of object the registry contains; e.g. <code>Registry.BLOCK</code> is itself a <code>Codec<Block></code>. Forge Registries, however, do not currently implement Codec and cannot yet be used in this way; custom codecs must be created for forge-specific registries that are not tied to specific vanilla registries.
 Of particular note here is the CompoundTag.CODEC, which can be used to e.g. serialize a CompoundTag into a json file. This has a notable limitation in that CompoundTag.CODEC *cannot* safely deserialize lists of numbers from json, due to the strong typing of ListTag and the way that the NBTOps deserializer reads numeric values.

@@ Line 1: / Line 1: @@
 Codecs are a serialization tool from mojang's DataFixerUpper library. Codecs are used alongside [[DynamicOps|DynamicOps]] to allow objects to be serialized to different formats and back, such as JSON or [[Using_NBT|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=
 ==Serialization and Deserialization==
-== Serialization and Deserialization ==
+The primary use for Codecs is to serialize java objects to some serialized type, such as a JsonElement or a Tag, and to deserialize a 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]] instance and an instance of the object we are serializing or deserializing, and returns a DataResult:
@@ Line 36: / Line 34: @@
 </syntaxhighlight>
-== Builtin Codecs ==
+</someserializedtype></somejavatype>
-=== Primitive Codecs ===
+==Builtin Codecs==
-The Codec class itself contains static instances of codecs for all supported primitive types, e.g. <code>Codec.STRING</code> is the canonical <code>Codec<String></code> implementation. Primitive codecs include:
+===Primitive Codecs===
 * BOOL, which serializes to a boolean value
 * BYTE, SHORT, INT, LONG, FLOAT, and DOUBLE, which serialize to numeric values
@@ Line 45: / Line 44: @@
 * EMPTY, which represents null objects
-=== Other Builtin Codecs ===
+===Other Builtin Codecs===
-Vanilla minecraft has many builtin codecs for objects that it frequently serializes. These codecs are typically static instances in the class the codec is serializing; e.g. <code>ResourceLocation.CODEC</code> is the canonical <code>Codec<ResourceLocation></code>, while <code>BlockPos.CODEC</code> is the codec used for serializing a BlockPos.
+Vanilla minecraft has many builtin codecs for objects that it frequently serializes. These codecs are typically static instances in the class the codec is serializing; e.g. <code>ResourceLocation.CODEC</code> is the canonical <code>Codec<resourcelocation></resourcelocation></code>, while <code>BlockPos.CODEC</code> is the codec used for serializing a BlockPos.
-Each vanilla <code>Registry</code> acts as the Codec for the type of object the registry contains; e.g. <code>Registry.BLOCK</code> is itself a <code>Codec<Block></code>. Forge Registries, however, do not currently implement Codec and cannot yet be used in this way; custom codecs must be created for forge-specific registries that are not tied to specific vanilla registries.
+Each vanilla <code>Registry</code> acts as the Codec for the type of object the registry contains; e.g. <code>Registry.BLOCK</code> is itself a <code>Codec<block></block></code>. Forge Registries, however, do not currently implement Codec and cannot yet be used in this way; custom codecs must be created for forge-specific registries that are not tied to specific vanilla registries.
 Of particular note here is the CompoundTag.CODEC, which can be used to e.g. serialize a CompoundTag into a json file. This has a notable limitation in that CompoundTag.CODEC *cannot* safely deserialize lists of numbers from json, due to the strong typing of ListTag and the way that the NBTOps deserializer reads numeric values.

@@ Line 267: / Line 267: @@
 * BlockPlacer and BlockPlacerType
 * ConfiguredDecorator and FeatureDecorator
 =External Links=
 * [https://github.com/Mojang/DataFixerUpper/blob/master/src/main/java/com/mojang/serialization/Codec.java Codecs in Mojang's official public DataFixerUpper repository]
 * [https://kvverti.github.io/Documented-DataFixerUpper/snapshot/com/mojang/serialization/Codec.html#flatXmap-java.util.function.Function-java.util.function.Function- Unofficial Codec Javadocs]

@@ Line 166: / Line 166: @@
 	Codec.STRING.fieldOf("name").codec());
-JsonElement encodedPair = BOXED_INT_CODEC.encodeStart(JsonOps.INSTANCE, Pair.of(5, "cheese").result().get();
+JsonElement encodedPair = PAIR_CODEC.encodeStart(JsonOps.INSTANCE, Pair.of(5, "cheese").result().get();
 </syntaxhighlight>
 This codec serializes the above value to:

@@ Line 5: / Line 5: @@
 == Serialization and Deserialization ==
-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 a Tag, 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]] instance and an instance of the object we are serializing or deserializing, and returns a DataResult:
@@ Line 12: / Line 12: @@
 // let someCodec be a Codec<SomeJavaType>
 // let someJavaObject be an instance of SomeJavaType
-// let someNBT and someJsonElement be instances of INBT and JsonElement, respectively
+// let someTag and someJsonElement be instances of Tag and JsonElement, respectively
-// serialize some java object to INBT
+// serialize some java object to Tag
-DataResult<INBT> result = someCodec.encodeStart(NBTDynamicOps.INSTANCE, someJavaObject);
+DataResult<Tag> result = someCodec.encodeStart(NBTOps.INSTANCE, someJavaObject);
-// deserialize some INBT instance back to a proper java object
+// deserialize some Tag instance back to a proper java object
-DataResult<SomeJavaType> result = someCodec.parse(NBTDynamicOps.INSTANCE, someNBT);
+DataResult<SomeJavaType> result = someCodec.parse(NBTOps.INSTANCE, someTag );
 // serialize some java object to a JsonElement
@@ Line 50: / Line 50: @@
 Each vanilla <code>Registry</code> acts as the Codec for the type of object the registry contains; e.g. <code>Registry.BLOCK</code> is itself a <code>Codec<Block></code>. Forge Registries, however, do not currently implement Codec and cannot yet be used in this way; custom codecs must be created for forge-specific registries that are not tied to specific vanilla registries.
-Of particular note here is the CompoundNBT.CODEC, which can be used to e.g. serialize a CompoundNBT into a json file. This has a notable limitation in that CompoundNBT.CODEC *cannot* safely deserialize lists of numbers from json, due to the strong typing of ListNBT and the way that the NBTDynamicOps deserializer reads numeric values.
+Of particular note here is the CompoundTag.CODEC, which can be used to e.g. serialize a CompoundTag into a json file. This has a notable limitation in that CompoundTag.CODEC *cannot* safely deserialize lists of numbers from json, due to the strong typing of ListTag and the way that the NBTOps deserializer reads numeric values.
 = Creating Codecs =
@@ Line 65: / Line 65: @@
      public int getSomeInt() { return this.someInt; }
-     public Item getItem() { return this.someItem; }
+     public Item getItem() { return this.item; }
      public List<BlockPos> getBlockPositions() { return this.blockPositions; }
+}
@@ Line 88: / Line 88: @@
 * a <code>Codec<Item></code>
 * a <code>Codec<List<BlockPos>></code>
-And then we'll need to assemble these into a <code>Codec<ExampleCodecClass</code>.
+And then we'll need to assemble these into a <code>Codec<ExampleCodecClass></code>.
 As previously mentioned, we can use <code>Codec.INT</code> for the integer codec, and <code>Registry.ITEM</code> for the Item codec. We don't have a builtin codec for list-of-blockpos, but we can use BlockPos.CODEC to create one.
@@ Line 100: / Line 100: @@
 </syntaxhighlight>
-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 ListTags.
 Deserializing a list in this manner produces an ''immutable'' list. If a mutable list is needed, [[Codecs#Equivalent_Types_and_xmap|xmap]] can be used to convert the list after deserializing.
 == Records ==
-RecordCodecBuilder is used to generate codecs that serialize instances of classes with explicitly named fields, like our example above. Codecs created via RecordCodecBuilder serialize things to maplike objects, such as {} json objects or CompoundNBTs.
+RecordCodecBuilder is used to generate codecs that serialize instances of classes with explicitly named fields, like our example above. Codecs created via RecordCodecBuilder serialize things to maplike objects, such as {} json objects or CompoundTags.
 RecordCodecBuilder can be used in several ways, but the simplest form is as follows:
@@ Line 130: / Line 130: @@
 ===Optional and Default Values in Record Fields===
-When RecordCodecBuilder is used as shown above, all of the fields are *required* to be in the serialized object (the JsonObject/CompoundNBT/etc), or the entire thing will fail to parse when the codec tries to deserialize it. If we wish to have optional or default values, we have several alternatives of fieldOf() we can use.
+When RecordCodecBuilder is used as shown above, all of the fields are *required* to be in the serialized object (the JsonObject/CompoundTag/etc), or the entire thing will fail to parse when the codec tries to deserialize it. If we wish to have optional or default values, we have several alternatives of fieldOf() we can use.
 * <code>someCodec.optionalFieldOf("field_name")</code> creates a field for an Optional. If the field in the json/nbt is not present or invalid, it will deserialize as an empty optional. Empty optionals will not be serialized; the field will be omitted from the json or nbt.
@@ Line 195: / Line 195: @@
 </syntaxhighlight>
-The serialized form of maps serialized by this codec will be a JsonObject or CompoundNBT, whose fields are the key-value pairs in the map; the map's keys will be used as the field names, and the map's values will be the values of those fields
+The serialized form of maps serialized by this codec will be a JsonObject or CompoundTag, whose fields are the key-value pairs in the map; the map's keys will be used as the field names, and the map's values will be the values of those fields
 A limitation of using unboundedMap is that it only supports key codecs that serialize to Strings (including codecs for things like ResourceLocation that aren't Strings themselves but still serialize to strings). To create a codec for a Map whose keys are not fundamentally strings, the Map must be serialized as a list of key-value pairs instead of using unboundedMap.
@@ Line 264: / Line 264: @@
 Several examples of vanilla classes that use dispatch codecs:
-* RuleTest and IRuleTestType
+* RuleTest and RuleTestType
-* IParticleData and ParticleType
+* BlockPlacer and BlockPlacerType
-* ConfiguredPlacement and Placement
+* ConfiguredDecorator and FeatureDecorator
 =External Links=
 * [https://github.com/Mojang/DataFixerUpper/blob/master/src/main/java/com/mojang/serialization/Codec.java Codecs in Mojang's official public DataFixerUpper repository]
 * [https://kvverti.github.io/Documented-DataFixerUpper/snapshot/com/mojang/serialization/Codec.html#flatXmap-java.util.function.Function-java.util.function.Function- Unofficial Codec Javadocs]

← Older revision		Revision as of 21:19, 9 January 2021
Line 101:		Line 101:

	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]] can be used to convert the list after deserializing.

	== Records ==		== Records ==

@@ Line 193: / Line 193: @@
 </syntaxhighlight>
-The serialized form of maps serialized by this codec will be a JsonObject or CompoundNBT, whose fields are the key-value pairs in the map.
+The serialized form of maps serialized by this codec will be a JsonObject or CompoundNBT, whose fields are the key-value pairs in the map; the map's keys will be used as the field names, and the map's values will be the values of those fields
-A limitation of using unboundedMap is that it only supports key codecs that serialize to Strings (including codecs for things like ResourceLocation that aren't Strings themselves but still serialize to strings). To create a codec for a Map whose keys are not fundamentally strings, the Map must be serialized as a list of key-value entries instead of using unboundedMap. As Codec.pair() also requires that the first codec serialize to a string, the pair function cannot be used for this purpose either.
+A limitation of using unboundedMap is that it only supports key codecs that serialize to Strings (including codecs for things like ResourceLocation that aren't Strings themselves but still serialize to strings). To create a codec for a Map whose keys are not fundamentally strings, the Map must be serialized as a list of key-value pairs instead of using unboundedMap.
 ==Equivalent Types and xmap==

@@ Line 156: / Line 156: @@
 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, such as codecs created using [[Codecs#Records|RecordCodecBuilder]], [[Codecs#Maps|unboundedMap]], or fieldOf. Codecs that serialize nothing (such as [[Codecs#Unit|unit codecs]]) 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|RecordCodecBuilder]] or [[Codecs#Boxing_values_as_objects|fieldOf]]. Codecs that serialize nothing (such as [[Codecs#Unit|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.
+The resulting Pair codec will serialize a single object that has all of the fields of the two original codecs. For example:
 ==Either==