NBT

from python_nbt import nbt

This is the basic module of this package. It contains everything you need to read, edit and write NBT format files such as *.mca, *.dat inside Minecraft saves folder, *.nbt, and so on. Also, it can export your NBT to json and import them json!

Classes

NBTTagBase

Also named and can be referred as "TAG_Base", which is the name on Minecraft Wiki. This is the super class for all other NBT types and as a result, DO NOT instanciate this class directly. Use its subclasses instead.

Initializer

NBTTagBase(value=None, **kwargs)

Parameter	Default Value	Description
value	None	value to initialize. If value has attribute read, it will be treated as buffer.
buffer	None	buffer of binary data to be read from

Properties

Name	Description	Get	Set
type_id	NBT type id, always an int	✔
value	Value stored in NBT	✔

Methods

json_obj(self, full_json=True)

Return an object that can be accepted by json module built in Python.

Parameter	Default Value	Description
full_json	True	When is True by default, function will return a dict containing tag type id and its values. When set as False, function will return an object that omits tag type id and can be accepted by json module containing only this tag's value.

For example, in IDLE

>>> nbt_str = nbt.NBTTagString('I\'m a string!')
>>> nbt_str.json_obj()
{'type_id': 8, 'value': "I'm a string!"}
>>> a.json_obj(False)
"I'm a string!"

Magic methods overriden

__eq__ (tag == obj)

Equals when:

• NBTTagBase or its subclasses: True for same type_id and same value, False for otherwise.
• Other types: True when value equals obj, False for otherwise

Of course != is also overriden automatically.

__str__ (str(tag))

Returns str(tag.json_obj())

__repr__ (repr(tag))

Returns repr(tag.json_obj())

Single Value NBT

Contains NBTTagByte, NBTTagShort, NBTTagInt, NBTTagLong, NBTTagFloat, NBTTagDouble, and NBTTagString. Added validator for values. Trying to input invalid values will raise a ValueError.

Extends

NBTTagBase

Initializer

Same as NBTTagBase.

Properties (Overriden)

Name	Description	Get	Set
value	Value stored in NBT	✔	✔

Classes

Class	Description	Value Requirements
NBTTagByte	Class for TAG_Byte	Integer in range(-128, 128)
NBTTagShort	Class for TAG_Short	Integer in range(-65536, 65536)
NBTTagInt	Class for TAG_Int	Integer in range(-2,147,483,648‬, 2,147,483,648‬)
NBTTagLong	Class for TAG_Long	Interger in range(-9,223,372,036,854,775,808‬, 9,223,372,036,854,775,808‬)
NBTTagFloat	Class for TAG_Float	float
NBTTagDouble	Class for TAG_Double	float
NBTTagString	Class for TAG_String	String with 65535 bytes of data or less

Array-like NBT

Contains NBTTagByteArray, NBTTagIntArray, and NBTTagLongArray. Added validator for entries. Trying to input invalid entries will raise a ValueError.

These classes are also subclasses of list, so you can add, edit, delete, get items like doing so in a list.

Extends

NBTTagBase, _util.RestrictedList

Initializer

Same as NBTTagBase, but value accepts iterable objects.

Properties (Overriden)

Name	Description	Get	Set
value	Value list stored in NBT	✔

Classes

Class	Description	Valid entries
NBTTagByteArray	Class for TAG_Byte_Array	integer in range(-128, 128)
NBTTagIntArray	Class for TAG_Int_Array	integer in range(-2,147,483,648‬, 2,147,483,648‬)
NBTTagLongArray	Class for TAG_Long_Array	interger in range(-9,223,372,036,854,775,808‬, 9,223,372,036,854,775,808‬)

NBTTagList

Added validator for elements inside, if applied invalid values, it will raise an ValueError.

This class is also a subclass of list, so feel free to use them like lists.

Extends

NBTTagBase, _util.RestrictedList

Initializer

NBTTagList(value=None, **kwargs)

Same as NBTTagBase, but must specify tag_type if not reading from buffer. tag_type should be a subclass of NBTTagBase.

Properties (Overriden)

Name	Description	Get	Set
value	Value list stored in NBT	✔
tag_type	Valid value type	✔
tag_type_id	ID of valid value type	✔

Valid Entries

Entries inside must be instances of tag_type.

NBTTagCompound

A subclass of dict, so you can add, edit, delete entries like doing so to a dict. Added validator to ensure that keys are str and values are NBTTagBase. Trying to input invalid keys or values will raise ValueError.

Extends

NBTTagBase, _util.TypeRestrictedDict

Initializer

NBTTagCompound(value=None, **kwargs)

Same as NBTTagBase. value must be an instance of dict whose keys must be instances of str and values must be instances of NBTTagBase if you want to initialize it with value, or an object with attribute read to read from binary data.

Properties (Overriden are shown)

Name	Description	Get	Set
value	Entries dict stored in NBT	✔	✔

Functions

read_from_nbt_file(file)

Read from NBT file. Returns an NBTTagBase.

file can be path to file, or an file pointer with mode 'rb'.

write_to_nbt_file(file, tag, name='')

Write an NBT tag to binary file.

file can be path to file, or an file pointer with mode 'wb'. tag must be an NBTTagCompound. name can be whatever string you want, this will be the name of root tag of this file. However, this is not used in Minecraft or mods of the game, so leave it default.

from_json(json_obj)

Return an NBT object according to json_obj. And its argument must be as same format as what NBTTagBase.json_obj(full_json=True) exports.

Constants

TAG_END         =  0
TAG_BYTE        =  1
TAG_SHORT       =  2
TAG_INT         =  3
TAG_LONG        =  4
TAG_FLOAT       =  5
TAG_DOUBLE      =  6
TAG_BYTE_ARRAY  =  7
TAG_STRING      =  8
TAG_LIST        =  9
TAG_COMPOUND    = 10
TAG_INT_ARRAY   = 11
TAG_LONG_ARRAY  = 12

TAGLIST: A dict maps ids of different types NBT to their classes.

For compatibility with names on Minecraft Wiki, just in case.

TAG            = NBTTagBase
TAG_Byte       = NBTTagByte
TAG_Short      = NBTTagShort
TAG_Int        = NBTTagInt
TAG_Long       = NBTTagLong
TAG_Float      = NBTTagFloat
TAG_Double     = NBTTagDouble
TAG_Byte_Array = NBTTagByteArray
TAG_Int_Array  = NBTTagIntArray
TAG_Long_Array = NBTTagLongArray
TAG_String     = NBTTagString
TAG_List       = NBTTagList
TAG_Compound   = NBTTagCompound
TAG_End        = NBTTagEnd