Difference between revisions of "DynamicOps"

From Forge Community Wiki
m (Corret Link)
(Update to 1.17)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<code>DynamicOps</code> is a helper interface that's used to convert files into data types and vice versa. Their usages will probably never be explored by most modders. They are overshadowed by [[codecs]].
+
The <code>DynamicOps</code> class is part of mojang's DataFixerUpper serialization library; DynamicOps are used alongside [[codecs]] to convert java objects to a serialized format and back. While Codecs describe how a java object is to be serialized, DynamicOps describe the format the object is to be serialized to.
  
== <code>NBTDynamicOps</code> ==
+
The DataFixerUpper library includes several DynamicOps for serializing to json; vanilla minecraft also includes a DynamicOps for serializing to minecraft's [[Using_NBT|NBT]] format.
  
<code>NBTDynamicOps</code> is a handler that converts an NBT file to an <code>INBT</code> tag. They are also used to parse information from codecs to send them across networks.
+
= Builtin DynamicOps =
  
There is only one public instance of <code>NBTDynamicOps</code>: <code>INSTANCE</code>.
+
== JsonOps ==
  
== <code>JsonOps</code> ==
+
The <code>JsonOps</code> DynamicOps are used to serialize and deserialize json data. These are instances of <code>DynamicOps<JsonElement></code>, meaning that they are used to convert java objects to and from <code>JsonElement</code> instances. These can used in conjunction with codecs to serialize/deserialize objects from assets and datapacks.
  
<code>JsonOps</code> are similar in which they convert a JSON file into a <code>JsonElement</code>. These are usually used in conjunction with codecs as well to serialize/deserialize instances.
+
There are two public instances of JsonOps: <code>JsonOps.INSTANCE</code> and <code>JsonOps.COMPRESSED</code>. Compressed data is represented as a single string to read/write. However, this is never used within vanilla itself.
  
There are two public instances of <code>JsonOps</code>: <code>INSTANCE</code> and <code>COMPRESSED</code>. Compressed data is represented as a single string to read/write. However, this is never used within vanilla itself.
+
== NbtOps ==
 +
 
 +
The <code>NbtOps.INSTANCE</code> is an instance of <code>DynamicOps<Tag></code>, meaning it is used to convert java objects to and from <code>Tag</code> instances. This can be used for serializing data into packets to send across networks, as well as serializing persistent data for entities and similar objects.
 +
 
 +
There is only one public instance of NbtOps: <code>NbtOps.INSTANCE</code>.
 +
 
 +
= Using DynamicOps =
 +
 
 +
== Serializing and Deserializing ==
 +
 
 +
By combining a <code>Codec<SomeJavaType></code> with a <code>DynamicOps<SomeSerializedFormat></code>, the proper java object can be converted to the serialized form and back. See [[codecs]] for details on this subject.
 +
 
 +
== Format Conversion ==
 +
 
 +
By using the <code>DynamicOps#convertTo</code> instance method with a second DynamicOps instance, data can be converted between two different serialized formats, such as JsonElement to Tag and back.
 +
 
 +
<syntaxhighlight lang=java>
 +
// converting Tag to JsonElement
 +
JsonElement someJsonElement = NbtOps.INSTANCE.convertTo(JsonOps.INSTANCE, someTag);
 +
 
 +
// converting JsonElement to Tag
 +
Tag someTag = JsonOps.INSTANCE.convertTo(NbtOps.INSTANCE, someJsonElement);
 +
</syntaxhighlight>
 +
 
 +
Depending on the implementation of the DynamicOps used, this may throw an exception or return an empty object if the two formats are incompatible.
 +
 
 +
In particular, it is '''not''' safe to convert lists of numbers to NBT in this manner, due to the NBT format's strong typing and the way the NbtOps attempts to create lists of numbers.
 +
 
 +
= External Links =
 +
* [https://kvverti.github.io/Documented-DataFixerUpper/snapshot/com/mojang/serialization/DynamicOps.html DynamicOps unofficial javadocs]

Latest revision as of 19:32, 2 August 2021

The DynamicOps class is part of mojang's DataFixerUpper serialization library; DynamicOps are used alongside codecs to convert java objects to a serialized format and back. While Codecs describe how a java object is to be serialized, DynamicOps describe the format the object is to be serialized to.

The DataFixerUpper library includes several DynamicOps for serializing to json; vanilla minecraft also includes a DynamicOps for serializing to minecraft's NBT format.

Builtin DynamicOps

JsonOps

The JsonOps DynamicOps are used to serialize and deserialize json data. These are instances of DynamicOps<JsonElement>, meaning that they are used to convert java objects to and from JsonElement instances. These can used in conjunction with codecs to serialize/deserialize objects from assets and datapacks.

There are two public instances of JsonOps: JsonOps.INSTANCE and JsonOps.COMPRESSED. Compressed data is represented as a single string to read/write. However, this is never used within vanilla itself.

NbtOps

The NbtOps.INSTANCE is an instance of DynamicOps<Tag>, meaning it is used to convert java objects to and from Tag instances. This can be used for serializing data into packets to send across networks, as well as serializing persistent data for entities and similar objects.

There is only one public instance of NbtOps: NbtOps.INSTANCE.

Using DynamicOps

Serializing and Deserializing

By combining a Codec<SomeJavaType> with a DynamicOps<SomeSerializedFormat>, the proper java object can be converted to the serialized form and back. See codecs for details on this subject.

Format Conversion

By using the DynamicOps#convertTo instance method with a second DynamicOps instance, data can be converted between two different serialized formats, such as JsonElement to Tag and back.

// converting Tag to JsonElement
JsonElement someJsonElement = NbtOps.INSTANCE.convertTo(JsonOps.INSTANCE, someTag);

// converting JsonElement to Tag
Tag someTag = JsonOps.INSTANCE.convertTo(NbtOps.INSTANCE, someJsonElement);

Depending on the implementation of the DynamicOps used, this may throw an exception or return an empty object if the two formats are incompatible.

In particular, it is not safe to convert lists of numbers to NBT in this manner, due to the NBT format's strong typing and the way the NbtOps attempts to create lists of numbers.

External Links