cpp-nbt

This is a C++23 header-only library for reading/writing Minecraft NBT data:

• Single header file
• Requires C++23 (GCC 13, Clang 14, MSVC 19.latest)
• Reads from istreams, writes to ostreams
• Supports pretty printing

This is mostly for me to play with bleeding edge C++ stuff. Don't expect this to compile on anything but trunk.

Quickstart

std::map doesn't work with incomplete types portably, so you need to provide your own (std::map may work depending on your platform and stdlib). By default cpp-nbt uses boost::container::map. You can do this by defining NBT_MAP_TYPE to whatever type you want to use, so long it has a vaguely std::map-ish API.

Include nbt.hpp, munch some data.

#define NBT_MAP_TYPE myFavoriteMap
#include "nbt.hpp"

nbt::NBT root {std::ifstream {"hello_world.nbt"}};
std::cout << root;

Tags

All PC-edition NBT tags are supported, Bedrock is not currently supported.

Most tags map directly to primitive types, the remainder map to STL containers.

Tag Type	Description
TagEnd	std::nullptr_t
TagByte	std::int8_t
TagShort	std::int16_t
TagInt	std::int32_t
TagLong	std::int64_t
TagFloat	float
TagDouble	double
TagByteArray	std::vector<TagByte>
TagIntArray	std::vector<TagInt>
TagLongArray	std::vector<TagLong>
TagString	std::string
TagList	std::variant<std::vectors<TagEnd>, std::vector<TagByte>, and all other tags>
Tag	std::variant<TagEnd, TagByte, and all other tags>
TagCompound	std::map<TagString, Tag>
NBTData	struct { TagString name; TagCompound tags; }
NBT	struct {std::optional<NBTData> data; }

Constructing and Destructing Tags

Java edition NBT root nodes are always either a TagEnd, or a named TagCompound. These two root nodes are encapsulated by the NBT type, which has an encode() and decode() methods to serialize and deserialize NBT. When the TagCompound is present the data field will be present, otherwise it will be absent. If absent, the NBT container will serialize to a single TagEnd.

Example Usage:

nbt::NBT root;
root.decode(std::ifstream {"hello_world.nbt"});
// Optionally, use the constructor
// nbt::NBT root {ifs};

root.encode(std::ofstream {"out.nbt"});

Manipulating Tags

Tags must exist inside a container type, and manipulating NBT containers involves standard usage of the STL.

nbt::NBT root {"LyricalNBT", {
  {"Hello", "World"},
  {"Lyrics", nbt::TagList {
      "There's", "a", "song", "that", "we're", "singing",
  }},
}};

root["LuckyNumbers"] = nbt::TagByteArray {1, 3, 7, 9, 13, 15};
std::get<nbt::TagByteArray>(root["LuckyNumbers"]).push_back(21);

std::cout << root["Hello"] << std::endl;
std::cout << root << std::endl;

Issues

Please open an issue or better yet, a pull request, for any bugs or other problems.