CraftProtocol — Minecraft network protocol and NBT in Python 2.7.

Source code: CraftProtocol


This module provide high level interface for handling Named Binary Tags (NBT) and Minecraft network packets.

Warning

This documentation is not complete.

Named Binary Tags (NBT)

Creating in-memory NBT tags:

from CraftProtocol import NBT

tag = NBT.NBTTagCompound()
tag["example_int_list_key"] = NBT.NBTTagList(NBT.NBTTagByte)
tag["example_int_list_key"].append(NBT.NBTTagByte(0x00))
tag["example_int_list_key"].append(NBT.NBTTagByte(0x0F))
tag["example_string_key"] = NBT.NBTTagString("string")
tag["example_double_key"] = NBT.NBTTagDouble(120.1351)

Warning

You can’t assign a native python value to NBTTagCompound key. Use class that inherits from NBTBase.

Python Type NBT Type
NoneType NBTBase
str NBTTagString
unicode NBTTagString
int NBTTagInt
int NBTTagShort
int NBTTagByte
long NBTTagLong
float NBTTagFloat
float NBTTagDouble
dict NBTTagCompound
list NBTTagList
list NBTTagByteArray
list NBTTagIntArray
list NBTTagLongArray

Remember that NBT Types with “Array” suffix can store only one NBT Type which is prefixed and NBTTagList can store only one choosed by user (in constructor) NBT Type.

To serialize NBT tag to stream (file-like or socket object):

from CraftProtocol.NBT import NBTSerializer

NBTSerializer.write(stream, tag)

or deserialize from stream:

from CraftProtocol.NBT import NBTSerializer

tag = NBTSerializer.read(stream)

Note

NBTSerializer does not support compression. If you want to handle compressed NBT tags, use appropriate module for this, for example gzip.

To convert NBT Value to Python Value:

nbt_string = tag["example_string_key"]
native_string = nbt_string.get()

Packets

Documentation of Minecraft network protocol can be found at http://wiki.vg. Currently implemented versions of this protocol:

  • 1.8.x
  • 1.10.x
  • 1.12.2

Note

In described examples, we use 1.10.x protocol.

Creating packet:

from CraftProtocol.Protocol import ProtocolVersion
from CraftProtocol.Protocol import ProtocolState
from CraftProtocol.Protocol.v1_10 import Packet

packet = Packet.Handshaking.HandshakePacket(ProtocolVersion.MC_1_10, "hostname", 25565, ProtocolState.STATUS)

To know arguments for packet constructor, see http://wiki.vg.

If you want to serialize packets, use:

from CraftProtocol.Protocol import ProtocolVersion
from CraftProtocol.Protocol import Packet

serializer = CraftProtocol.Protocol.Packet.PacketSerializer(
    CraftProtocol.Protocol.ProtocolVersion.MC_1_10,
    CraftProtocol.Protocol.Packet.PacketSerializer.Mode.CLIENT
)
serializer.write(stream, packet)

To deserialize packets from stream (e.g. from socket object):

from CraftProtocol.Protocol import ProtocolVersion
from CraftProtocol.Protocol import Packet

serializer = CraftProtocol.Protocol.Packet.PacketSerializer(
    CraftProtocol.Protocol.ProtocolVersion.MC_1_10,
    CraftProtocol.Protocol.Packet.PacketSerializer.Mode.CLIENT
)
packet = serializer.read(stream)

Warning

Different protocols may have different packets. See http://wiki.vg for details.

Warning

Some packets is not implemented in CraftProtocol (only in Play protocol state). If you want to know list of implemented packets, see source code.

Warning

You must manually change serializer protocol state if necessary. Default state is Handshaking. For example, in Server List Ping after sending Handshake packet state must be switched to Status.

Note

Valid packet must inherits from CraftProtocol.Protocol.Packet.BasePacket class.

Chat

If you want to strip colors from chat (dict) object (e.g. from ChatMessageClientPacket packet) use:

from CraftProtocol.Chat import ChatSerializer

raw_text = ChatSerializer.strip_colors(chat)

To serialize chat in legacy format use:

from CraftProtocol.Chat import ChatSerializer

chat = ChatSerializer.translate_legacy(raw_text)

Note

Serializing chat in modern (JSON) format is not currently supported.

Chat Objects

class CraftProtocol.Chat.ChatMode

Note

This class is used to enum purposes only. You don’t have to create new instances.

ENABLED

This is default mode.

HIDDEN

In this mode, chat is hidden.

COMMANDS

In this mode, only commands can be send to server.

class CraftProtocol.Chat.ChatSerializer

Note

This class is static. You don’t have to create new instances.

static strip_colors(chat)

Strip colors in chat (dict) message and return it.

Parameters:chat (dict) – chat message in modern JSON format
static translate_legacy(text, code="&")

Translate colored chat message (like this &aHello &bWorld) to paragraph-prefixed legacy format.

Parameters:
  • text – text to translate
  • code – character that is replaced to paragraph
Return type:

unicode

Inventory Objects

class CraftProtocol.Inventory.Inventory(window_id, title, inventory_type, slots_number, entity_id=None)
Parameters:
  • window_id (int) – inventory window id
  • title (dict) – inventory title in chat format
  • inventory_type (basestring enum) – inventory type
  • slots_number (int) – number of items in inventory
  • entity_id (int) – only used if inventory type is EntityHorse.

Note

Currently there is no class that has inventory type enum defined.

get_window_id()

Return inventory window id.

Return type:int
get_title()

Return inventory title.

Return type:dict

Note

Inventory title uses Chat format.

get_type()

Return inventory type.

Return type:unicode enum

Note

Currently there is no class that has this enum defined.

get_slots()

Return items in this inventory.

Return type:list (CraftProtocol.Inventory.SlotData)
get_entity_id()

Return inventory entity id.

Return type:int or None

Note

Used only when Inventory Type is EntityHorse.

__getitem__(index)

Return item at specified index.

Parameters:index (int) – index
Return type:CraftProtocol.Inventory.SlotData
__setitem__(index, value)

Set item at specified index.

Parameters:
__delitem__(index)

Set item at specified index to empty slot.

Parameters:index (int) – index
__len__()

Return number of items in this inventory.

Return type:int
__iter__()

The same as __iter__() of get_slots().

Return type:iter
copy()

Return copy of this inventory.

Return type:CraftProtocol.Inventory.Inventory
class CraftProtocol.Inventory.SlotData(item_id, count=0, damage=0, tag=None)
Parameters:
  • item_id (int) – item id
  • count (int) – item count
  • damage (int) – item variant
  • tag (CraftProtocol.NBT.NBTTagCompound or None) – item NBT tag
static empty()

Return empty slot.

Return type:CraftProtocol.Inventory.SlotData
get_id()

Return slot item id.

Return type:int
get_count()

Return number of items in this slot.

Return type:int
set_count(count)

Set number of items in this slot.

Parameters:count (int) – items count
get_damage()

Return slot item variant.

Return type:int
set_damage(damage)

Set slot item variant.

Parameters:damage (int) – item variant
get_tag()

Return NBT tag of this slot.

Return type:CraftProtocol.NBT.NBTTagCompound or None
set_tag(tag)

Set NBT tag of this slot.

Parameters:tag (CraftProtocol.NBT.NBTTagCompound or None) – NBT tag
has_tag()

Return True if slot has NBT tag.

Return type:bool

World Objects

class CraftProtocol.World.World(world_type, dimension, difficulty)
Parameters:
  • world_type (CraftProtocol.World.WorldType basestring enum) – world type
  • dimension (CraftProtocol.World.WorldDimension int enum) – world dimension
  • difficulty (CraftProtocol.World.WorldDifficulty int enum) – world difficulty
get_world_type()

Return world type.

Return type:CraftProtocol.World.WorldType unicode enum
get_dimension()

Return world dimension.

Return type:CraftProtocol.World.WorldDimension int enum
get_difficulty()

Return world difficulty.

Return type:CraftProtocol.World.WorldDifficulty int enum
class CraftProtocol.World.Location(x, y, z, yaw=0.00, pitch=0.00)
Parameters:
  • x (float) – x
  • y (float) – y
  • z (float) – z
  • yaw (float) – yaw
  • pitch (float) – pitch
get_x()

Return x.

Return type:float
set_x(x)

Set x.

Parameters:x (float) – new x
get_y()

Return y.

Return type:float
set_y(y)

Set y.

Parameters:y (float) – new y
get_z()

Return z.

Return type:float
set_z(z)

Set z.

Parameters:z (float) – new z
get_yaw()

Return yaw.

Return type:float
set_yaw(yaw)

Set yaw.

Parameters:yaw (float) – new yaw
get_pitch()

Return pitch.

Return type:float
set_pitch(pitch)

Set pitch.

Parameters:pitch – new pitch
class CraftProtocol.World.WorldDimension

Note

This class is used to enum purposes only. You don’t have to create new instances.

NETHER

Represent Nether dimension.

OVERWORLD

Represent natural dimension.

END

Represent The End dimension.

class CraftProtocol.World.WorldDifficulty

Note

This class is used to enum purposes only. You don’t have to create new instances.

PEACEFUL

Represent easiest difficulty.

EASY

Represent easy difficulty.

NORMAL

Represent normal difficulty.

HARD

Represent hard difficulty.

class CraftProtocol.World.WorldType

Note

This class is used to enum purposes only. You don’t have to create new instances.

DEFAULT

Represent default map type.

FLAT

Represent super flat map type.

LARGE_BIOMES

Represent map type with large biomes.

AMPLIFIED

Represent amplified map type.

DEFAULT_1_1

Represent legacy map type.

Protocol Objects

class CraftProtocol.Protocol.ProtocolState

Note

This class is used to enum purposes only. You don’t have to create new instances.

HANDSHAKING

Represent Handshaking protocol state.

STATUS

Represent Status (Server List Ping) protocol state.

LOGIN

Represent Login protocol state.

PLAY

Represent Play protocol state.

class CraftProtocol.Protocol.ProtocolVersion

Note

This class is used to enum purposes only. You don’t have to create new instances.

MC_1_8

Represent protocol version that is used by Minecraft 1.8.x.

MC_1_10

Represent protocol version that is used by Minecraft 1.10.x.

MC_1_12_2

Represent protocol version that is used by Minecraft 1.12.2.