Buffers¶
Quarry implements Minecraft’s data types by way of the Buffer
class.
When quarry reads a packet, it stores its payload in a buffer object
and passes the buffer to a packet handler. The packet handler then unpacks
the payload, which usually made up of multiple fields of differing types. You
can read from the front of the buffer via the Buffer.read()
method or any
of the unpack_*()
methods listed below
Buffers also provide a number of static methods that pack data into
a byte string. These are named like pack_*()
.
When unpacking data you work with a buffer object, whereas when packing
data you work with a buffer type. A reference to the buffer type is available
from Protocol
objects as self.buff_type
.
-
class
quarry.types.buffer.
Buffer
(data=None)[source]¶ -
registry
= <quarry.types.registry.OpaqueRegistry object>¶ An object that encodes/decodes IDs, such as blocks and items.
-
add
(data)¶ Add some bytes to the end of the buffer.
-
discard
()¶ Discards the entire buffer contents.
-
classmethod
pack
(fmt, *fields)¶ Pack fields into a struct. The format accepted is the same as for
struct.pack()
.
-
classmethod
pack_array
(fmt, array)¶ Packs array into a struct. The format accepted is the same as for
struct.pack()
.
-
classmethod
pack_block
(block, packer=None)¶ Packs a block.
-
classmethod
pack_chat
(message)¶ Pack a Minecraft chat message.
-
classmethod
pack_chunk_section
(blocks, block_lights=None, sky_lights=None)¶ Packs a chunk section. The supplied argument should be an instance of
quarry.types.chunk.BlockArray
.
-
classmethod
pack_command_node
(node, nodes)¶ Packs a command node.
-
classmethod
pack_command_node_properties
(parser, properties)¶ Packs the properties of an
argument
command node.
-
classmethod
pack_commands
(root_node)¶ Packs a command graph.
-
classmethod
pack_direction
(direction)¶ Packs a direction.
-
classmethod
pack_entity_metadata
(metadata)¶ Packs entity metadata.
-
classmethod
pack_ingredient
(ingredient)¶ Packs a crafting recipe ingredient alternation.
-
classmethod
pack_json
(obj)¶ Serialize an object to JSON and pack it to a Minecraft string.
-
classmethod
pack_nbt
(tag=None)¶ Packs an NBT tag
-
classmethod
pack_optional
(packer, val)¶ Packs a boolean indicating whether val is None. If not,
packer(val)
is appended to the returned string.
-
classmethod
pack_optional_varint
(number)¶ Packs an optional varint.
-
classmethod
pack_packet
(data, compression_threshold=-1)¶ Unpacks a packet frame. This method handles length-prefixing and compression.
-
classmethod
pack_particle
(kind, data=None)¶ Packs a particle.
-
classmethod
pack_pose
(pose)¶ Packs a pose.
-
classmethod
pack_position
(x, y, z)¶ Packs a Position.
-
classmethod
pack_recipe
(name, type, **recipe)¶ Packs a crafting recipe.
-
classmethod
pack_rotation
(x, y, z)¶ Packs a rotation.
-
classmethod
pack_slot
(item=None, count=1, tag=None)¶ Packs a slot.
-
classmethod
pack_string
(text)¶ Pack a varint-prefixed utf8 string.
-
classmethod
pack_uuid
(uuid)¶ Packs a UUID.
-
classmethod
pack_varint
(number, max_bits=32)¶ Packs a varint.
-
classmethod
pack_villager
(kind, profession, level)¶ Packs villager data.
-
read
(length=None)¶ Read length bytes from the beginning of the buffer, or all bytes if length is
None
-
save
()¶ Saves the buffer contents.
-
unpack
(fmt)¶ Unpack a struct. The format accepted is the same as for
struct.unpack()
.
-
unpack_array
(fmt, length)¶ Unpack an array struct. The format accepted is the same as for
struct.unpack()
.
-
unpack_block
(unpacker=None)¶ Unpacks a block.
-
unpack_chat
()¶ Unpack a Minecraft chat message.
-
unpack_chunk_section
(overworld=True)¶ Unpacks a chunk section. Returns a sequence of length 4096 (16x16x16).
-
unpack_command_node
()¶ Unpacks a command node.
-
unpack_command_node_properties
(parser)¶ Unpacks the properties of an
argument
command node.
-
unpack_commands
(resolve_redirects=True)¶ Unpacks a command graph.
If resolve_redirects is
True
(the default), the returned structure may contain contain circular references, and therefore cannot be serialized to JSON (or similar). If it isFalse
, all node redirect information is stripped, resulting in a directed acyclic graph.
-
unpack_direction
()¶ Unpacks a direction.
-
unpack_entity_metadata
()¶ Unpacks entity metadata.
-
unpack_ingredient
()¶ Unpacks a crafting recipe ingredient alternation.
-
unpack_json
()¶ Unpack a Minecraft string and interpret it as JSON.
-
unpack_nbt
()¶ Unpacks NBT tag(s).
-
unpack_optional
(unpacker)¶ Unpacks a boolean. If it’s True, return the value of
unpacker()
. Otherwise return None.
-
unpack_optional_varint
()¶ Unpacks an optional varint.
-
unpack_packet
(cls, compression_threshold=-1)¶ Unpacks a packet frame. This method handles length-prefixing and compression.
-
unpack_particle
()¶ Unpacks a particle. Returns an
(kind, data)
pair.
-
unpack_pose
()¶ Unpacks a pose.
-
unpack_position
()¶ Unpacks a position.
-
unpack_recipe
()¶ Unpacks a crafting recipe.
-
unpack_rotation
()¶ Unpacks a rotation
-
unpack_slot
()¶ Unpacks a slot.
-
unpack_string
()¶ Unpack a varint-prefixed utf8 string.
-
unpack_uuid
()¶ Unpacks a UUID.
-
unpack_varint
(max_bits=32)¶ Unpacks a varint.
-
unpack_villager
()¶ Unpacks villager data.
-
Protocol Versions¶
Some data types vary between Minecraft versions. Quarry automatically sets the
buff_type
attribute of Protocol
instance to an appropriate buffer
class when the protocol version becomes known.
Minecraft 1.7¶
Support for Minecraft 1.7+ is implemented in the Buffer1_7
class.
Minecraft 1.9¶
Support for Minecraft 1.9+ is implemented in the Buffer1_9
class.
Changes from 1.7:
pack_chunk_section()
andunpack_chunk_section()
added.pack_entity_metadata()
andunpack_entity_metadata()
modified.
Minecraft 1.13¶
Support for Minecraft 1.13+ is implemented in the Buffer1_13
class.
Changes from 1.9:
pack_commands()
andunpack_commands()
added.pack_particle()
andunpack_particle()
added.pack_recipes()
andunpack_recipes()
added.pack_chunk_section_palette()
andunpack_chunk_section_palette()
modified.pack_slot()
andunpack_slot()
modified.pack_entity_metadata()
andunpack_entity_metadata()
modified.
Minecraft 1.13.2¶
Support for Minecraft 1.13.2+ is implemented in the Buffer1_13_2
class.
Changes from 1.13:
pack_slot()
andunpack_slot()
modified.
Minecraft 1.14¶
Support for Minecraft 1.14+ is implemented in the Buffer1_14
class.
Changes from 1.13.2:
pack_villager()
andunpack_villager()
added.pack_optional_varint()
andunpack_optional_varint()
added.pack_pose()
andunpack_pose()
added.pack_chunk_section()
andunpack_chunk_section()
modified.pack_position()
andunpack_position()
modified.pack_entity_metadata()
andunpack_entity_metadata()
modified.pack_particle()
andunpack_particle()
modified.pack_recipes()
andunpack_recipes()
modified.