TypeNBT is a idiomatic, type safe NBT library for Scala. TypeNBT allows you to focus on the data in the code, not the NBT as most other libraries requires.
Add TypeNBT to your project by including this line in build.sbt
libraryDependencies += "net.katsstuff" %% "typenbt" % "0.5.1" //Or this if you use Scala.js libraryDependencies += "net.katsstuff" %%% "typenbt" % "0.5.1"
Why did I decide to write TypeNBT and not just use something that already existed.
- You can find TypeNBT on maven
- Everything in TypeNBT is immutable, this includes the collections
- TypeNBT is type safe. There are no surprises when running the code and getting an exception back because you expected the wrong data type. Even the list is type safe
- It includes the type information at runtime. How do serialize an empty list in other libraries, you can't really, but here you can do that
- Convert anything to NBT. TypeNBT defines typeclasses for encoding and decoding a value to NBT. This aspect of the library isn't hidden away either. Instead it's a core part of how it works
- Create a NBTCompound easily. TypeNBT easily allows you to create your entire NBTCompound in a single line using a HList like this
NBTCompound.fromHList("first" -> "hi" :: "second" -> 5 :: "third" -> false :: HNil). NOTE: Requires the use of the
- Easy conversion to and from common types not represented by raw NBT. Notice the boolean in the above line
- Full support for Mojangson parsing. NOTE: Requires the
- TypeNBT works for Scala.js
Here is some information about how to use TypeNBT in practice. For all of these, make sure you import
Creating NBTTag, and the typeclasses that TypeNBT uses
Converting a value to nbt can be done like this:
import net.katsstuff.typenbt._ 5.nbt //Int, return NBTInt "hi".nbt //String, returns NBTString false.nbt //Boolean, returns NBTByte IndexedSeq(2, 5).nbt //IndexedSeq[Int], returns NBTIntArray NBTInt(1) //You can also create the NBTTag more explicitly
This uses the typeclass
NBTSerializer[Repr, NBT] which takes to types, the type to convert from, and the type to convert to. This is analogous to the type
Repr => NBT.
There is also
NBTDeserializer[Repr, NBT] which goes the other way around, except that it returns an
Option as the data might not be valid for a given type. This is analogous to the type
NBT => Option[Repr].
For cases where a value can always be safely converted from an nbt value, there exists
SafeNBTDeserializer. This is analogous to the type
NBT => Repr.
Next there is
NBTView which combines
There is also
SafeNBTView which uses
SafeNBTDeserializer instead of
Then there is
SafeNBTViewCaseLike. Which adds apply and unapply methods to the view to make certain types behave like they are normal nbt types. For example, you can do
NBTBoolean(false) which will then convert the boolean to an nbt byte.
Lastly there is
NBTType which corresponds to the base nbt types. This also contains the byte id for the type.
On multiple type parameter lists
For some methods like
NBTCompount#getValue, TypeNBT uses multiple parameter lists in the form of anonymous classes. Unless you really want to, you generally only have to fill in one of them.
If you want more fanciness, then there is also the module
typenbt-extra, which contains some more operations which uses shapeless under the hood.
First add the dependency to your build.
libraryDependencies += "net.katsstuff" %% "typenbt-extra" % "0.5.1" //Or this if you use Scala.js libraryDependencies += "net.katsstuff" %%% "typenbt-extra" % "0.5.1"
Now you can convert a
HList into a
NBTCompound or add a
HList to an existing
NBTCompound. First make sure you have your HList. The HList must consist of tuples from string to values that an NBTSerializer exists for. Then import
net.katsstuff.typenbt.extra._ and call
NBTCompound.fromHList(hList) or do
compound ++ hList. TypeNBT takes care of the rest.
TypeNBT also has another module for both parsing and creating mojangson.
libraryDependencies += "net.katsstuff" %% "typenbt-mojangson" % "0.5.1" //Or this if you use Scala.js libraryDependencies += "net.katsstuff" %%% "typenbt-mojangson" % "0.5.1"
You can then use
There exists more examples on how to use TypeNBT in the examples directory.