Cyotek.Data.Nbt
NBT (Named Binary Tag) is a tag based binary format designed to carry large amounts of binary data with smaller amounts of additional data. This is currently the format that Minecraft uses for player and region data.
Cyotek.Data.Nbt is a library for reading and writing NBT format files used by Minecraft. However, the format is versatile enough to use for many other applications and purposes.
In addition to support for the native binary NBT format, this library also offers the ability to read and write NBT tags to and from XML... not quite as "binary", but certainly more readable!
Features
- Support for all tags in the specification
- Reads and writes binary files compatible with existing NBT libraries and tools
- Supports reading and writing to XML based files for human readable output (deprecated)
- Ability to provide custom readers/writers if required
- Extended API for working with NBT documents
- Query support
NBT Specification
See SPECIFICATION.md for the specification.
Saving a document
Similar to XmlDocument and XmlWriter, you can either
directly write NBT documents, or you can construct a document
then save it. The former approach is the fastest, the latter
approach may be simpler.
Using the BinaryTagWriter to create a document
using (TagWriter writer = new BinaryTagWriter(stream))
{
writer.WriteStartDocument();
writer.WriteStartTag("Level", TagType.Compound);
writer.WriteTag("longTest", 9223372036854775807);
writer.WriteTag("shortTest", (short)32767);
writer.WriteTag("stringTest", "HELLO WORLD THIS IS A TEST STRING ÅÄÖ!");
writer.WriteTag("floatTest", (float)0.498231471);
writer.WriteTag("intTest", 2147483647);
writer.WriteStartTag("nested compound test", TagType.Compound);
writer.WriteStartTag("ham", TagType.Compound);
writer.WriteTag("name", "Hampus");
writer.WriteTag("value", 0.75F);
writer.WriteEndTag();
writer.WriteStartTag("egg", TagType.Compound);
writer.WriteTag("name", "Eggbert");
writer.WriteTag("value", 0.5F);
writer.WriteEndTag();
writer.WriteEndTag();
writer.WriteStartTag("listTest (long)", TagType.List, TagType.Long, 5);
writer.WriteTag((long)11);
writer.WriteTag((long)12);
writer.WriteTag((long)13);
writer.WriteTag((long)14);
writer.WriteTag((long)15);
writer.WriteEndTag();
writer.WriteStartTag("listTest (compound)", TagType.List, TagType.Compound, 2);
writer.WriteStartTag(TagType.Compound);
writer.WriteTag("name", "Compound tag #0");
writer.WriteTag("created-on", 1264099775885);
writer.WriteEndTag();
writer.WriteStartTag(TagType.Compound);
writer.WriteTag("name", "Compound tag #1");
writer.WriteTag("created-on", 1264099775885);
writer.WriteEndTag();
writer.WriteEndTag();
writer.WriteTag("byteTest", (byte)127);
writer.WriteTag("byteArrayTest (the first 1000 values of (n*n*255+n*7)%100, starting with n=0 (0, 62, 34, 16, 8, ...))", SampleByteArray);
writer.WriteTag("doubleTest", 0.49312871321823148);
writer.WriteEndTag();
writer.WriteEndDocument();
}Using NbtDocument to construct and save a document
NbtDocument document;
TagCompound root;
TagCompound compound;
TagCompound child;
TagList list;
document = new NbtDocument();
root = document.DocumentRoot;
root.Name = "Level";
root.Value.Add("longTest", 9223372036854775807);
root.Value.Add("shortTest", (short)32767);
root.Value.Add("stringTest", "HELLO WORLD THIS IS A TEST STRING ÅÄÖ!");
root.Value.Add("floatTest", (float)0.498231471);
root.Value.Add("intTest", 2147483647);
compound = (TagCompound)root.Value.Add("nested compound test", TagType.Compound);
child = (TagCompound)compound.Value.Add("ham", TagType.Compound);
child.Value.Add("name", "Hampus");
child.Value.Add("value", (float)0.75);
child = (TagCompound)compound.Value.Add("egg", TagType.Compound);
child.Value.Add("name", "Eggbert");
child.Value.Add("value", (float)0.5);
list = (TagList)root.Value.Add("listTest (long)", TagType.List, TagType.Long);
list.Value.Add((long)11);
list.Value.Add((long)12);
list.Value.Add((long)13);
list.Value.Add((long)14);
list.Value.Add((long)15);
list = (TagList)root.Value.Add("listTest (compound)", TagType.List, TagType.Compound);
child = (TagCompound)list.Value.Add(TagType.Compound);
child.Value.Add("name", "Compound tag #0");
child.Value.Add("created-on", 1264099775885);
child = (TagCompound)list.Value.Add(TagType.Compound);
child.Value.Add("name", "Compound tag #1");
child.Value.Add("created-on", 1264099775885);
root.Value.Add("byteTest", (byte)127);
root.Value.Add("byteArrayTest (the first 1000 values of (n*n*255+n*7)%100, starting with n=0 (0, 62, 34, 16, 8, ...))", SampleByteArray);
root.Value.Add("doubleTest", 0.49312871321823148);Once you have a document or root TagCompound, you can either
use the NbtDocument class to save the document, or use a
TagWriter class directly.
Using a TagWriter class
using (BinaryTagWriter writer = new BinaryTagWriter(stream)) // Or XmlTagWriter
{
writer.WriteStartDocument();
writer.WriteTag(document.DocumentRoot);
writer.WriteEndDocument();
}Using NbtDocument
document.Save(stream);See the Benchmarks project, or the test suite for examples of the different ways of serializing documents.
Using Binary or XML Formats
The library supports both the use of the binary NBT format, and a variant that uses XML. While the XML version is much more readable, it is also much slower to serialize and isn't really recommended for production use.
The Load methods of NbtDocument class will automatically
detect if the source is binary or XML, allowing seamless use.
However, if you use serialization classes directly you will need
to perform your own detection and construct an XmlTagReader or
BinaryTagReader object accordingly. The static
NbtDocument.GetDocumentFormat method can help with format
detection.
The following table was generated by running the write benchmarks using BenchmarkDotNet and clearly show the difference between writing XML and writing binary.
| Method | Mean | StdErr | StdDev | Median | Gen 0 | Allocated |
|---|---|---|---|---|---|---|
| WriteBinaryDirect | 8.4448 us | 0.0836 us | 0.5733 us | 8.1153 us | 3.4424 | 6.67 kB |
| WriteBinaryDocument | 16.6214 us | 0.1641 us | 0.7337 us | 16.1428 us | 5.4867 | 10.12 kB |
| WriteBinaryDocumentViaNbtDocument | 16.8629 us | 0.1667 us | 1.2696 us | 16.0460 us | 5.6095 | 10.14 kB |
| WritePredefinedBinaryDocument | 9.3312 us | 0.0808 us | 0.3129 us | 9.1901 us | 3.6070 | 6.86 kB |
| WritePredefinedXmlDocument | 180.8340 us | 1.8036 us | 10.8217 us | 177.5857 us | 23.9909 | 50.56 kB |
| WriteXmlDirect | 172.9066 us | 1.8421 us | 10.2566 us | 167.6837 us | 24.0885 | 50.37 kB |
| WriteXmlDocument | 180.4061 us | 0.6515 us | 2.2568 us | 179.7206 us | 29.5038 | 53.8 kB |
| WriteXmlDocumentViaNbtDocument | 187.5790 us | 1.8653 us | 12.7877 us | 182.9234 us | 28.5127 | 53.82 kB |
In closing, XML support will probably be removed in the next major version of the library and is deprecated in the current.
Requirements
.NET Framework 2.0 or later.
Pre-built binaries are available via a signed NuGet package containing the following targets.
- .NET 3.5
- .NET 4.0
- .NET 4.5.2
- .NET 4.6.2
- .NET 4.7.2
- .NET 4.8
- .NET Standard 2.0
- .NET Standard 2.1
- .NET Core 2.1
- .NET Core 2.2
- .NET Core 3.1
Is there a target not on this list you'd like to see? Raise an issue, or even better, a pull request.
Acknowledgements
This library was originally based on LibNBT found on CodePlex, but I've made a lot of changes to it. The API has substantially changed, although it should be easier to use than the original.
The current WIP icon is simply the familiar Minecraft grass icon taken from the Official Minecraft Wiki.
License
As per the original library, this source is licensed under the GNU Lesser General Public License, version 2.1. For more information, see COPYING.txt