NBT

NBT

alias of NbtCompound

class NbtCompound(dict=None, /, **kwargs)

The definitive class for parsing and manipulating NBT-format data. It can be used like a python dict with the exception that its keys must be strings. It can also be passed a dict at initialization which will be automatically converted (see convertion rules below).

Alias NBT of NbtCompound.

from mcpq import Minecraft, Vec3, NBT
mc = Minecraft()
nbt = NBT()  # create new NBT dictionary, called a compound in NBT format
# its keys must always be strings
nbt["bool_key"] = True  # will be converted to byte 1 (=`true`)
nbt["int_key"] = 1  # will be converted to int (or long if number is too large)
nbt["double_key"] = 1.4  # will be converted to double
nbt["string_key"] = "not a number text"  # will stay a string (see number conversion below)
# for lists and dicts: all internal values will be recursively converted
nbt["list_key"] = [1,2,3]  # will be converted to nbt-list of int
nbt["compound_key"] = {"waterlogged": True}  # will be converted to compound
# compounds and lists can also be created/got and directly returned like so:
inner_compound = nbt.get_or_create_nbt("compound_key")  # get compound set above
inner_compound["waterlogged"] = False  # overwrite nbt["compound_key"]["waterlogged"]
nbt.get_or_create_list("list_key").extend([4,5,6])  # append to upper list

# to easier convert to different number types, string-numbers will be parsed like so:
nbt["bool_key"] = "true"  # will be converted to byte 1 (=`true`)
nbt["byte_key"] = "1b"  # will be converted to byte 1
nbt["short_key"] = "1s"  # will be converted to short 1
nbt["int_key"] = "1"  # will be converted to int 1
nbt["long_key"] = "1l"  # will be converted to long 1
nbt["float_key"] = "1.4f"  # will be converted to float 1.4
nbt["double_key"] = "1.4"  # will be converted to double 1.4

# to enforce a certain type during conversion use the corresponding property:
nbt.string["string_key"] = "1b"  # will STAY a string `"1b"` and not be converted
nbt.string["key"] = {"text": "hi"}  # will be converted to string, not compound
nbt.byte_array["key"] = [1,2,3]  # will be converted to byte-array instead of nbt-list of int
nbt.short["short_key"] = 1  # will be converted to short, not int

# types are also checked on equality checks of compounds and lists:
NBT({"check": True}) == NBT({"check": "1b"})  # true (true == 1b)
NBT({"check": True}) == NBT({"check": "true"})  # true (true == true)
NBT({"check": 1}) == NBT({"check": "1s"})  # false
NBT({"check": "1.4d"}) == NBT({"check": "1.4f"})  # false
# but NOT for primitive type checks, there the base type comparison is used:
NBT({"check": True})["check"] == NBT({"check": "1b"})["check"]  # true (int compare)
NBT({"check": True})["check"] == NBT({"check": "true"})["check"]  # true (int compare)
NBT({"check": 1})["check"] == NBT({"check": "1s"})["check"]  # true (int compare)
NBT({"check": "1.4d"})["check"] == NBT({"check": "1.4f"})["check"]  # true (float compare)

snbt = str(nbt)  # convert to snbt (string NBT)
print(str(NBT({"key1": "value1", "key 2": 2})))
# >>> '{key1:"value1","key 2":2}'

# this can then be used for commands or other operations, for example:
# to remove the AI and remove sound from a cow spawned at 0 0
nbt = NBT({"NoAI": "1b", "Silent": "1b"})
cow = mc.spawnEntity("cow", mc.getHeighestPos(0, 0).up())
cow.runCommand(f"data merge entity @s {nbt}")
classmethod parse(string: str) → NbtCompound

Parse string of a compound in SNBT-format to NBT.

from mcpq import Minecraft, Vec3, NBT
nbt = NBT.parse('{key1:"value1",key2:2}')
same_nbt = NBT.parse(str(nbt))
Parameters:

string (str) – the string of a compound in SNBT-format

Returns:

the parsed compound

Return type:

NbtCompound

asComponentData() → ComponentData

Convert self of type NbtCompound to ComponentData. Note, keys must not contain characters that would have to be quoted.

deepcopy() → NbtCompound
get_or_create_nbt(key: str) → NbtCompound

Get an existing or create a NbtCompound at key key. Equivalent to self[key] if key is a NbtCompound, otherwise overwrite with new compound and return it.

Parameters:

key (str) – key to get or create compound at

Returns:

existing compound if key had one else new (overwritten) compound

Return type:

NbtCompound

get_or_create_list(key: str) → NbtList

Get an existing or create a NbtList at key key. Equivalent to self[key] if key is a NbtList, otherwise overwrite with new list and return it.

Parameters:

key (str) – key to get or create list at

Returns:

existing list if key had one else new (overwritten) list

Return type:

NbtList

property bool: TypedCompoundView[bool]
property byte: TypedCompoundView[NbtByte]
property short: TypedCompoundView[NbtShort]
property int: TypedCompoundView[NbtInt]
property long: TypedCompoundView[NbtLong]
property float: TypedCompoundView[NbtFloat]
property double: TypedCompoundView[NbtDouble]
property string: TypedCompoundView[str]
property list: TypedCompoundView[NbtList]
property compound: TypedCompoundView[NbtCompound]
property byte_array: TypedCompoundView[NbtByteArray]
property int_array: TypedCompoundView[NbtIntArray]
property long_array: TypedCompoundView[NbtLongArray]
class TypedCompoundView(compound: NbtCompound, dtype: type[bool | NbtByte | NbtShort | NbtInt | NbtLong | NbtFloat | NbtDouble | str | NbtList | NbtCompound | NbtByteArray | NbtIntArray | NbtLongArray])

A generic view of NbtCompound that enforces values to be of a specific type and subclass of dict.

class ComponentData(dict=None, /, **kwargs)

ComponentData subclasses and behaves exactly like NBT with the only difference being its string representation: Instead of {key1:value1,key2:value2} it is represented as [key1=value1,key2=value2], allowing it to represent the component-format on item, item stacks and block entities. Additionally, the keys of ComponentData may not contain characters that have to be quoted in NBT format and must be strings.

Checkout Block for an explanation and example on how to parse and write component data directly.

classmethod parse(string: str) → ComponentData

Parse string of a component-data block to ComponentData.

asCompound() → NbtCompound

Convert self of type ComponentData to NbtCompound

class NbtList(iterable=None)

NbtList behaves like a python list with the exception that all its elements must have the same nbt type. When the list is empty any nbt type can be added but once an element was added the list (and conversions) are defined by the first element’s type.

property dtype: type[bool | NbtByte | NbtShort | NbtInt | NbtLong | NbtFloat | NbtDouble | str | NbtList | NbtCompound | NbtByteArray | NbtIntArray | NbtLongArray] | None
property bool: TypedListView[bool]
property byte: TypedListView[NbtByte]
property short: TypedListView[NbtShort]
property int: TypedListView[NbtInt]
property long: TypedListView[NbtLong]
property float: TypedListView[NbtFloat]
property double: TypedListView[NbtDouble]
property string: TypedListView[str]
property list: TypedListView[NbtList]
property compound: TypedListView[NbtCompound]
property byte_array: TypedListView[NbtByteArray]
property int_array: TypedListView[NbtIntArray]
property long_array: TypedListView[NbtLongArray]
class TypedListView(data: NbtList, dtype: type[bool | NbtByte | NbtShort | NbtInt | NbtLong | NbtFloat | NbtDouble | str | NbtList | NbtCompound | NbtByteArray | NbtIntArray | NbtLongArray])

A generic view of NbtList that enforces values to be of a specific type and subclass of list.

class NbtByte(value, base=None)

Signed 8-bit integer and subclass of int. Both 1b == True and 0b == False are true as booleans just represent 0 and 1 byte.

class NbtShort(value, base=None)

Signed 16-bit integer and subclass of int

class NbtInt(value, base=None)

Signed 32-bit integer and subclass of int

class NbtLong(value, base=None)

Signed 64-bit integer and subclass of int

class NbtFloat(value)

Signed float with limit ±3.4e+38 and subclass of float

class NbtDouble(value)

Subclass of float

class NbtByteArray(iterable=None)

Subclass of NbtList.

class NbtIntArray(iterable=None)

Subclass of NbtList.

class NbtLongArray(iterable=None)

Subclass of NbtList.