Codecs support in API

[akarahdev]

Is your feature request related to a problem?

Let's say you want to serialize a Minecraft class to your disk or database. Maybe you're making a custom way to store a small world! (This is something I'm struggling with actually)
You go to serialize a BlockState and you realize you have to make your own format. You code a system (or use a library), you make a class to serialize and deserialize BlockState. It works, but it took some extra effort to get working when you just want to save data if you coded it yourself, or you had to get another dependency if you used a library.

Another plugin or developer comes in and wants to read that format or edit your plugin - they now have to learn how you serialized BlockState. Why go through all this trouble when it can be standardized?

This issue isn't exclusive to BlockStates - maybe you want to serialize a Component (granted, MiniMessage exists but that's to String, not json/nbt/etc.), a Location, PotionEffect etc.

Describe the solution you'd like.

Minecraft has the Codec API built-in via DFU (DataFixerUpper)!

So, instead of needing libraries, what if PaperMC added codecs to some of its' classes?
It would be in the form of

public static Codec<T> CODEC = ...

T is obviously the type it serializes / deserializes, usually in the class.
Some useful classes for this would be:

• BlockState*
• Component
• Location
• Vector
• ItemStack*
• PotionEffect
• TriState
• Entity*

*These have a lot of data, so it may be challenging to implement Codecs for them.
Note that these are just ideas, I'm not sure exactly which classes should have Codecs and which not honestly. It would most likely be better for more used ones to have Codecs though in my opinion.

To save effort, some Minecraft classes on the NMS level do have Codecs built-in to them, Paper could maybe call to those for Codecs aswell to make things easier and more standard.

This Codec API also means that mods can use DFU's DynamicOps, allowing them to serialize/deserialize to/from NBT and JSON with ones Minecraft has built-in, but also potentially other data storages such as YAML (commonly used in configuration), TOML, and .properties!

This would make DFU a dependency of PaperAPI, but it shouldn't matter much since it's already used in the vanilla server.

Fabric has a good document on Codecs here: https://docs.fabricmc.net/develop/codecs

Describe alternatives you've considered.

Using a library could work, but it adds an unnecessary dependency and means there's no serialization consistency in plugins.
You could also make your own serialization / deserialization system, but that's potentially a lot of work.
You could also just call down to NMS to do that for you, but that is not supported and there could be an API for it.

Other

Searched terms for similar requests:

• NBT
• Codec

[Machine-Maker]

I know one reason to not expose dfu to the API, is that DFU API is not stable and changes pretty frequently. That doesn't fit well in an API where lots of stuff has compatibility guarentees. That is slightly changing with the Registry Modification API however. It means there isn't as much of a difference to just doing what you suggested.

You could also just call down to NMS to do that for you, but that is not supported and there could be an API for it.

Using NMS to access the codecs if you want them comes with the implicit understanding that things change between versions. If its part of the API, its less clear.

[MiniDigger]

I think implementing stable APIs for the stuff people care about (like the (de)serializeAsBytes on item stack or soon #11235) is a much better course of action than exposing unstable internals as API, that has bitten us before.

[Machine-Maker]

I think we probably could add an interface with both serializeToBytes and serializeToJson methods. Then that interface would mark types that would have static deserializeFromBytes deserializeFromJson methods. The implementations of such methods would use the codecs and wrap each type to include the data version to upgrade data on deserialization. I know the main issue people have with human-readable serialization formats w/the data version is: Why is it human readable if I can't just make changes to it? The changes I make have to line up with the data version which might be years out of date.