Python-NBT

A python library for reading and writing NBT files. Compatible with json.

Based on NBT Version: 19133 (Current version used by Minecraft)

What is 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. An NBT file consists of a single GZIPped Named Tag of type TAG_Compound.

From official Minecraft Wiki.

Installation

pip install Python-NBT

Usage

Read an NBT file

>>> import python_nbt.nbt as nbt
>>> file = nbt.read_from_nbt_file("file.nbt")

This function returns an instance of NBTTagCompound, or by the name on Minecraft Wiki, an instance of TAG_Compound. It only accept 1 argument, which can be either a file path string or an opened file stream.

The TAG_Compound acts like a dict in Python. More accurately, it is a subclass of dict in Python with some restrictions put on its keys and values. So you can get, and set its items as shown below:

>>> file['drop_loot_crates']
{'type_id': 1, 'value': 0}
>>> file['drop_loot_crates'] = nbt.TAG_Byte(1)
>>> file['drop_loot_crates']
{'type_id': 1, 'value': 1}

In the dict shown as above, the key 'type_id' represents the type id of an NBT. In our example, its 'type_id' is 1, which indicates this NBT is a TAG_Byte. And 'value' indicates its actual value.

Write an NBT file

Once you've completed editing an NBT, you can store it into an NBT file with the function below:

write_to_nbt_file(file, tag)

The first argument file should be a path string or a file stream to the file you want to create/write. The second argument tag is the NBT you want to write.

Compat with Json

If you want to export NBT in json, you can use NBTTagBase.json_obj(full_json=True) to get an json style dict that contains all the NBT information. After that, you can use json module in Python to do whatever you want. If you want a simpler version, which omits type id of an NBT and NBTs inside it, set full_json to False. Note: Changing full_json to False will also turn json dict of nested tags into simple version.

If you want to import NBT from a json object, you can use nbt.from_json(json_obj) to do so. This function will return an NBT object. And its argument must be as same format as what NBTTagBase.json_obj(full_json=True) exports.

Future features

Ticked entries are finished.

TowardtheStars/Python-NBT