Skip to content

Types

mcproto.types.abc

mcproto.types.abc.MCType

Bases: Serializable, ABC

Base class for a minecraft type structure.

mcproto.types.chat

mcproto.types.chat.ChatMessage

Bases: MCType

Minecraft chat message representation.

mcproto.types.chat.ChatMessage.__eq__ 

__eq__(other: object) -> bool

Check equality between two chat messages.

Warning

This is purely using the raw field, which means it's possible that a chat message that appears the same, but was representing in a different way will fail this equality check.

mcproto.types.chat.ChatMessage.as_dict 

as_dict() -> RawChatMessageDict

Convert received raw into a standard dict form.

mcproto.types.chat.RawChatMessageDict

Bases: TypedDict

Dictionary structure of JSON chat messages when serialized.

mcproto.types.nbt

mcproto.types.nbt.FromObjectSchema module-attribute 

FromObjectSchema: TypeAlias = Union['type[NBTag]', 'type[NBTagConvertible]', 'Sequence[FromObjectSchema]', 'Mapping[str, FromObjectSchema]']

Represents the type of a schema, used to define how an object should be converted to an NBT tag(s).

mcproto.types.nbt.FromObjectType module-attribute 

FromObjectType: TypeAlias = Union[int, float, bytes, str, 'NBTagConvertible', 'Sequence[FromObjectType]', 'Mapping[str, FromObjectType]']

Represents any object holding some data that can be converted to an NBT tag(s).

mcproto.types.nbt.PayloadType module-attribute 

PayloadType: TypeAlias = Union[int, float, bytes, str, 'NBTag', 'Sequence[PayloadType]', 'Mapping[str, PayloadType]']

Represents the type of a payload that can be stored in an NBT tag.

mcproto.types.nbt.__all__ module-attribute 

__all__ = ['ByteArrayNBT', 'ByteNBT', 'CompoundNBT', 'DoubleNBT', 'EndNBT', 'FloatNBT', 'IntArrayNBT', 'IntNBT', 'ListNBT', 'LongArrayNBT', 'LongNBT', 'NBTag', 'NBTagConvertible', 'NBTagType', 'ShortNBT', 'StringNBT']

Implementation of the NBT (Named Binary Tag) format used in Minecraft as described in the NBT specification

Source: Minecraft NBT Spec Named Binary Tag specification

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.

A Named Tag has the following format:

byte tagType
TAG_String name
\[payload\]
  • The tagType is a single byte defining the contents of the payload of the tag.
  • The name is a descriptive name, and can be anything (eg "cat", "banana", "Hello World!"). The purpose for this name is to name tags so parsing is easier and can be made to only look for certain recognized tag names. Exception: If tagType is TAG_End, the name is skipped and assumed to be "".
  • The [payload] varies by tagType.

Note that ONLY Named Tags carry the name and tagType data. Explicitly identified Tags (such as TAG_String) only contains the payload.

mcproto.types.nbt.ByteArrayNBT

Bases: NBTag

NBT tag representing an array of bytes. The length of the array is stored as a signed 32-bit integer.

mcproto.types.nbt.ByteArrayNBT.__bytes__ 

__bytes__() -> bytes

Get the bytes value of the ByteArrayNBT tag.

mcproto.types.nbt.ByteNBT

Bases: _NumberNBTag

NBT tag representing a single byte value, represented as a signed 8-bit integer.

mcproto.types.nbt.CompoundNBT

Bases: NBTag

NBT tag representing a compound of named tags.

mcproto.types.nbt.CompoundNBT.__eq__ 

__eq__(other: object) -> bool

Check equality between two CompoundNBT tags.

Parameters:

Name Type Description Default
other
object

The other CompoundNBT tag to compare to.

 required

Returns:

Type Description
bool

True if the tags are equal, False otherwise.
Note

The order of the tags is not guaranteed, but the names of the tags must match. This function assumes that there are no duplicate tags in the compound.

mcproto.types.nbt.CompoundNBT.__iter__ 

__iter__()

Iterate over the tags in the compound.

mcproto.types.nbt.DoubleNBT

Bases: _FloatingNBTag

NBT tag representing a double-precision floating-point value, represented as a 64-bit IEEE 754-2008 binary64.

mcproto.types.nbt.EndNBT

Bases: NBTag

Sentinel tag used to mark the end of a TAG_Compound.

mcproto.types.nbt.FloatNBT

Bases: _FloatingNBTag

NBT tag representing a floating-point value, represented as a 32-bit IEEE 754-2008 binary32 value.

mcproto.types.nbt.IntArrayNBT

Bases: _NumberArrayNBTag

NBT tag representing an array of integers. The length of the array is stored as a signed 32-bit integer.

mcproto.types.nbt.IntNBT

Bases: _NumberNBTag

NBT tag representing an integer value, represented as a signed 32-bit integer.

mcproto.types.nbt.ListNBT

Bases: NBTag

NBT tag representing a list of tags. All tags in the list must be of the same type.

mcproto.types.nbt.ListNBT.__iter__ 

__iter__() -> Iterator[NBTag]

Iterate over the tags in the list.

mcproto.types.nbt.LongArrayNBT

Bases: _NumberArrayNBTag

NBT tag representing an array of longs. The length of the array is stored as a signed 32-bit integer.

mcproto.types.nbt.LongNBT

Bases: _NumberNBTag

NBT tag representing a long value, represented as a signed 64-bit integer.

mcproto.types.nbt.NBTag

Bases: MCType, NBTagConvertible, ABC

Base class for NBT tags.

In MC v1.20.2+ the type and name of the root tag is not written to the buffer, and unless specified, the type of the tag is assumed to be TAG_Compound.

mcproto.types.nbt.NBTag.value abstractmethod property 

value: PayloadType

Get the payload of the NBT tag in a python-friendly format.

mcproto.types.nbt.NBTag._read_header classmethod 

_read_header(buf: Buffer, read_type: bool = True, with_name: bool = True) -> tuple[str, NBTagType]

Read the header of the NBT tag.

Parameters:

Name Type Description Default
buf
Buffer

The buffer to read from.

 required
read_type
bool

Whether to read the type of the tag from the buffer.

  • If True, the tag type will be read from the buffer
  • If False and called from a subclass, the tag type will be inferred from the subclass.
  • If False and called from the base class, the tag type will be TAG_Compound.
 True
with_name
bool

Whether to read the name of the tag. If set to False, the tag will have the name "".

 True

Returns:

Type Description
tuple[str, NBTagType]

A tuple containing the name and the tag type.
Note

It is possible that this function reads nothing from the buffer if both with_name and read_type are set to False.

mcproto.types.nbt.NBTag._write_header 

_write_header(buf: Buffer, with_type: bool = True, with_name: bool = True) -> None

Write the header of the NBT tag to the buffer.

Parameters:

Name Type Description Default
buf
Buffer

The buffer to write to.

 required
with_type
bool

Whether to include the type of the tag in the serialization.

 True
with_name
bool

Whether to include the name of the tag in the serialization.

 True

mcproto.types.nbt.NBTag.deserialize classmethod 

deserialize(buf: Buffer, with_name: bool = True, with_type: bool = True) -> NBTag

Deserialize the NBT tag.

Parameters:

Name Type Description Default
buf
Buffer

The buffer to read from.

 required
with_name
bool

Whether to read the name of the tag. (Passed to _read_header)

 True
with_type
bool

Whether to read the type of the tag. (Passed to _read_header)

 True

Returns:

Type Description
NBTag

The deserialized NBT tag.
NBTag

This tag will be an instance of the class, that is associated with the tag type
NBTag

obtained from _read_header (see: [ASSOCIATED_TYPES][mcproto.types.nbt.ASSOCIATED_TYPES]).

mcproto.types.nbt.NBTag.from_object staticmethod 

from_object(data: FromObjectType, schema: FromObjectSchema, name: str = '') -> NBTag

Create an NBT tag from a python object and a schema.

Parameters:

Name Type Description Default
data
FromObjectType

The python object to create the NBT tag from.

 required
schema
FromObjectSchema

The schema used to create the NBT tags.

This is a description of the types of the data in the python object. It can be a subclass of NBTag (e.g. IntNBT, StringNBT, CompoundNBT, etc.), a dict, a list, a tuple, or any class that has a to_nbt method.

Example of schema:

```python
schema = {
    "string": StringNBT,
    "list_of_floats": [FloatNBT],
    "list_of_compounds": [{
        "key": StringNBT,
        "value": IntNBT,
    }],
    "list_of_lists": [[IntNBT], [StringNBT]],
}
```

This would be translated into a [`CompoundNBT`][mcproto.types.nbt.CompoundNBT].
required
name
str

The name of the NBT tag.

 ''

Returns:

Type Description
NBTag

The NBT tag created from the python object.

mcproto.types.nbt.NBTag.read_from abstractmethod classmethod 

read_from(buf: Buffer, with_type: bool = True, with_name: bool = True) -> NBTag

Read the NBT tag from the buffer.

Implementation shortcut used in deserialize. (Subclasses can override this, avoiding some repetition when compared to overriding deserialize directly.)

mcproto.types.nbt.NBTag.serialize 

serialize(with_type: bool = True, with_name: bool = True) -> Buffer

Serialize the NBT tag to a new buffer.

Parameters:

Name Type Description Default
with_type
bool

Whether to include the type of the tag in the serialization. (Passed to _write_header)

 True
with_name
bool

Whether to include the name of the tag in the serialization. (Passed to _write_header)

 True

Returns; The buffer containing the serialized NBT tag.

Note

The with_type and with_name parameters only control the first level of serialization.

mcproto.types.nbt.NBTag.serialize_to abstractmethod 

serialize_to(buf: Buffer, with_type: bool = True, with_name: bool = True) -> None

Serialize the NBT tag to a buffer.

Parameters:

Name Type Description Default
buf
Buffer

The buffer to write to.

 required
with_type
bool

Whether to include the type of the tag in the serialization.

 True
with_name
bool

Whether to include the name of the tag in the serialization.

 True
See Also

serialize

mcproto.types.nbt.NBTag.to_nbt 

to_nbt(name: str = '') -> NBTag

Convert the object to an NBT tag.

Warning

This is already an NBT tag, so it will modify the name of the tag and return itself.

mcproto.types.nbt.NBTag.to_object 

to_object(include_schema: bool = False, include_name: bool = False) -> PayloadType | Mapping[str, PayloadType] | tuple[PayloadType | Mapping[str, PayloadType], FromObjectSchema]

Convert the NBT tag to a python object.

Parameters:

Name Type Description Default
include_schema
bool

Whether to return a schema describing the types of the original tag.

 False
include_name
bool

Whether to include the name of the tag in the output.

If the tag has no name, the name will be set to "".

 False

Returns:

Type Description
PayloadType | Mapping[str, PayloadType] | tuple[PayloadType | Mapping[str, PayloadType], FromObjectSchema]

Either of: * A python object representing the payload of the tag. (default) * A dictionary containing the name associated with a python object representing the payload of the tag. * A tuple which includes one of the above and a schema describing the types of the original tag.

mcproto.types.nbt.NBTagConvertible

Bases: Protocol

Protocol for objects that can be converted to an NBT tag.

mcproto.types.nbt.NBTagConvertible.to_nbt 

to_nbt(name: str = '') -> NBTag

Convert the object to an NBT tag.

Parameters:

Name Type Description Default
name
str

The name of the tag.

 ''

Returns:

Type Description
NBTag

The NBT tag created from the object.

mcproto.types.nbt.NBTagType

Bases: IntEnum

Enumeration of the different types of NBT tags.

See the documentation of the individual variants for more information.

mcproto.types.nbt.NBTagType.BYTE class-attribute instance-attribute 

BYTE = 1

A single signed byte (8 bits).

mcproto.types.nbt.NBTagType.BYTE_ARRAY class-attribute instance-attribute 

BYTE_ARRAY = 7

The payload is a TAG_Int representing the length, followed by an array of bytes.

mcproto.types.nbt.NBTagType.COMPOUND class-attribute instance-attribute 

COMPOUND = 10

A sequential list of Named Tags. This array keeps going until a TAG_End is found.

  • If there's a nested TAG_Compound within this tag, that one will also have a TAG_End, so simply reading until the next TAG_End will not work.
  • The names of the named tags have to be unique within each TAG_Compound.
  • The order of the tags is not guaranteed.

mcproto.types.nbt.NBTagType.DOUBLE class-attribute instance-attribute 

DOUBLE = 6

A floating point value (64 bits, big endian, IEEE 754-2008, binary64).

mcproto.types.nbt.NBTagType.END class-attribute instance-attribute 

END = 0

This tag is used to mark the end of a list. It doesn't carry any payload, and it cannot be named!

If this type appears where a Named Tag is expected, the name is assumed to be "". (In other words, this Tag is always just a single 0x00 byte when named, and nothing in all other cases)

mcproto.types.nbt.NBTagType.FLOAT class-attribute instance-attribute 

FLOAT = 5

A floating point value (32 bits, big endian, IEEE 754-2008, binary32).

mcproto.types.nbt.NBTagType.INT class-attribute instance-attribute 

INT = 3

A signed integer (32 bits, big endian).

mcproto.types.nbt.NBTagType.INT_ARRAY class-attribute instance-attribute 

INT_ARRAY = 11

The payload is a TAG_Int representing the length, followed by an array of TAG_Int elements.

mcproto.types.nbt.NBTagType.LIST class-attribute instance-attribute 

LIST = 9

The payload is a TAG_Byte representing the type of the items in the list, followed by a TAG_Int representing the length of the list, followed by an array of NBTags.

All the tags in the list must be of the same type.

mcproto.types.nbt.NBTagType.LONG class-attribute instance-attribute 

LONG = 4

A signed long (64 bits, big endian).

mcproto.types.nbt.NBTagType.LONG_ARRAY class-attribute instance-attribute 

LONG_ARRAY = 12

The payload is a TAG_Int representing the length, followed by an array of TAG_Long elements.

mcproto.types.nbt.NBTagType.SHORT class-attribute instance-attribute 

SHORT = 2

A signed short (16 bits, big endian).

mcproto.types.nbt.NBTagType.STRING class-attribute instance-attribute 

STRING = 8

The payload is a TAG_Short representing the length, followed by an array of bytes, holding a string in UTF-8 format.

mcproto.types.nbt.ShortNBT

Bases: _NumberNBTag

NBT tag representing a short value, represented as a signed 16-bit integer.

mcproto.types.nbt.StringNBT

Bases: NBTag

NBT tag representing an UTF-8 string value. The length of the string is stored as a signed 16-bit integer.

mcproto.types.nbt._FloatingNBTag

Bases: NBTag, RequiredParamsABCMixin

Base class for NBT tags representing a floating-point number.

mcproto.types.nbt._NumberArrayNBTag

Bases: NBTag, RequiredParamsABCMixin

Base class for NBT tags representing an array of numbers.

mcproto.types.nbt._NumberNBTag

Bases: NBTag, RequiredParamsABCMixin

Base class for NBT tags representing a number.

This class is not meant to be used directly, but rather through its subclasses.

mcproto.types.nbt._get_tag_type 

_get_tag_type(tag: NBTag | type[NBTag]) -> NBTagType

Get the tag type of an NBTag object or class.

mcproto.types.uuid

mcproto.types.uuid.UUID

Bases: UUID, MCType

Minecraft UUID type.

In order to support potential future changes in protocol version, and implement MCType, this is a custom subclass, however it is currently compatible with the stdlib's UUID.