Skip to content

Latest commit

 

History

History
102 lines (76 loc) · 3.02 KB

ReadMe.md

File metadata and controls

102 lines (76 loc) · 3.02 KB
Raw

cpp-nbt

license

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.