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.

• More json compat
  • Convert json into NBT
  • Better and configurable json output (omitting NBT types)
• Convenient classes for reading and writing Minecraft saves files
  • World
  • Region
  • Chunk
  • ItemStack
  • TileEntity
  • Entity
  • Player
• Utilities for mods
  • FTB Quests (CurseForge Link)
  • GameStages (CurseForge Link)
  • Recognize blocks and items form mods in World according to NEI exports
• A detailed ~~doc/~~wiki
• More convenient interfaces for NBT (try to fully abandon value property, and makes everthing just it should be)
  • Operators for numeric tags
    • +, -, *, /
    • **, //
    • >, <
  • List interfaces for array-like NBT
  • Dict interfaces for dict-like NBT