Packets

Pending rewrite of this page

This page will be rewritten in the near future and split it into multiple pages for the individual game states, with the play state possibly being subdivided into even more pages. Currently, this page shows all implemented packets in mcproto. This split will happen once play state packets are introduced.

Base classes and interaction functions

mcproto.packets.ClientBoundPacket

Bases: Packet, ABC

Packet bound to a client (Server -> Client).

mcproto.packets.GameState

Bases: IntEnum

All possible game states in minecraft.

mcproto.packets.Packet

Bases: Serializable, RequiredParamsABCMixin, ABC

Base class for all packets.

mcproto.packets.PacketDirection

Bases: IntEnum

Represents whether a packet targets (is bound to) a client or server.

mcproto.packets.ServerBoundPacket

Bases: Packet, ABC

Packet bound to a server (Client -> Server).

mcproto.packets.async_read_packet async

async_read_packet(reader: BaseAsyncReader, packet_map: Mapping[int, type[T_Packet]], *, compression_threshold: int = -1) -> T_Packet

Read a packet.

Parameters:

Name	Type	Description	Default
reader	BaseAsyncReader	The connection/reader to receive this packet from.	required
packet_map	Mapping[int, type[T_Packet]]	A mapping of packet id (number) -> Packet (class). This mapping should contain all of the packets for the current gamestate and direction. See generate_packet_map	required
compression_threshold	int	A threshold packet length, which if crossed compression should be enabled. You can get this number from LoginSetCompression packet. If this packet wasn't sent by the server, set this to -1 (default). Note that during reading, we don't actually need to know the specific threshold, just whether or not is is non-negative (whether compression is enabled), as the packet format fundamentally changes when it is. That means you can pass any positive number here to enable compression, regardless of what it actually is.	-1

mcproto.packets.async_write_packet async

async_write_packet(writer: BaseAsyncWriter, packet: Packet, *, compression_threshold: int = -1) -> None

Write given packet.

Parameters:

Name	Type	Description	Default
writer	BaseAsyncWriter	The connection/writer to send this packet to.	required
packet	Packet	The packet to be sent.	required
compression_threshold	int	A threshold packet length, which if crossed compression should be enabled. You can get this number from LoginSetCompression packet. If this packet wasn't sent by the server, set this to -1 (default).	-1

mcproto.packets.generate_packet_map cached

generate_packet_map(direction: Literal[SERVERBOUND], state: GameState) -> Mapping[int, type[ServerBoundPacket]]

generate_packet_map(direction: Literal[CLIENTBOUND], state: GameState) -> Mapping[int, type[ClientBoundPacket]]

generate_packet_map(direction: PacketDirection, state: GameState) -> Mapping[int, type[Packet]]

Dynamically generated a packet map for given direction and state.

This generation is done by dynamically importing all of the modules containing these packets, filtering them to only contain those packets with the specified parameters, and storing those into a dictionary, using the packet id as key, and the packet class itself being the value.

As this function is likely to be called quite often, and it uses dynamic importing to obtain the packet classes, this function is cached, which means the logic only actually runs once, after which, for the same arguments, the same dict will be returned.

mcproto.packets.sync_read_packet

sync_read_packet(reader: BaseSyncReader, packet_map: Mapping[int, type[T_Packet]], *, compression_threshold: int = -1) -> T_Packet

Read a packet.

Parameters:

Name	Type	Description	Default
reader	BaseSyncReader	The connection/reader to receive this packet from.	required
packet_map	Mapping[int, type[T_Packet]]	A mapping of packet id (number) -> Packet (class). This mapping should contain all of the packets for the current gamestate and direction. See generate_packet_map	required
compression_threshold	int	A threshold packet length, which if crossed compression should be enabled. You can get this number from LoginSetCompression packet. If this packet wasn't sent by the server, set this to -1 (default). Note that during reading, we don't actually need to know the specific threshold, just whether or not is is non-negative (whether compression is enabled), as the packet format fundamentally changes when it is. That means you can pass any positive number here to enable compression, regardless of what it actually is.	-1

mcproto.packets.sync_write_packet

sync_write_packet(writer: BaseSyncWriter, packet: Packet, *, compression_threshold: int = -1) -> None

Write given packet.

Parameters:

Name	Type	Description	Default
writer	BaseSyncWriter	The connection/writer to send this packet to.	required
packet	Packet	The packet to be sent.	required
compression_threshold	int	A threshold packet length, which if crossed compression should be enabled. You can get this number from LoginSetCompression packet. If this packet wasn't sent by the server, set this to -1 (default).	-1

Handshaking gamestate

mcproto.packets.handshaking.handshake.Handshake

Bases: ServerBoundPacket

Initializes connection between server and client. (Client -> Server).

Initialize the Handshake packet.

Parameters:

Name	Type	Description	Default
protocol_version		Protocol version number to be used.	required
server_address		The host/address the client is connecting to.	required
server_port		The port the client is connecting to.	required
next_state		The next state for the server to move into.	required

mcproto.packets.handshaking.handshake.Handshake.serialize_to

serialize_to(buf: Buffer) -> None

Serialize the packet.

mcproto.packets.handshaking.handshake.NextState

Bases: IntEnum

Enum of all possible next game states we can transition to from the Handshake packet.

Status gamestate

mcproto.packets.status.ping.PingPong

Bases: ClientBoundPacket, ServerBoundPacket

Ping request/Pong response (Server <-> Client).

Initialize the PingPong packet.

Parameters:

Name	Type	Description	Default
payload		Random number to test out the connection. Ideally, this number should be quite big, however it does need to fit within the limit of a signed long long (-2 ** 63 to 2 ** 63 - 1).	required

mcproto.packets.status.status.StatusRequest

Bases: ServerBoundPacket

Request from the client to get information on the server. (Client -> Server).

mcproto.packets.status.status.StatusResponse

Bases: ClientBoundPacket

Response from the server to requesting client with status data information. (Server -> Client).

Initialize the StatusResponse packet.

Parameters:

Name	Type	Description	Default
data		JSON response data sent back to the client.	required

Login gamestate

mcproto.packets.login.login.LoginAcknowledged

Bases: ServerBoundPacket

Sent by client to acknowledge LoginSuccess from server. (Client -> Server).

This packet has no fields - it's just an empty acknowledgment.

mcproto.packets.login.login.LoginAcknowledged._deserialize classmethod

_deserialize(buf: Buffer) -> Self

Deserialize the packet (no data to deserialize).

mcproto.packets.login.login.LoginAcknowledged.serialize_to

serialize_to(buf: Buffer) -> None

Serialize the packet (no data to serialize).

mcproto.packets.login.login.LoginDisconnect

Bases: ClientBoundPacket

Sent by the server to kick a player while in the login state. (Server -> Client).

Initialize the LoginDisconnect packet.

Parameters:

Name	Type	Description	Default
reason		The reason for disconnection (kick).	required

mcproto.packets.login.login.LoginEncryptionRequest

Bases: ClientBoundPacket

Used by the server to ask the client to encrypt the login process. (Server -> Client).

Initialize the LoginEncryptionRequest packet.

Parameters:

Name	Type	Description	Default
public_key		Server's public key.	required
verify_token		Sequence of random bytes generated by server for verification.	required
server_id		Empty on minecraft versions 1.7.X and higher (20 random chars pre 1.7).	required

mcproto.packets.login.login.LoginEncryptionResponse

Bases: ServerBoundPacket

Response from the client to LoginEncryptionRequest packet. (Client -> Server).

Initialize the LoginEncryptionResponse packet.

Parameters:

Name	Type	Description	Default
shared_secret		Shared secret value, encrypted with server's public key.	required
verify_token		Verify token value, encrypted with same public key.	required

mcproto.packets.login.login.LoginEncryptionResponse.serialize_to

serialize_to(buf: Buffer) -> None

Serialize the packet.

mcproto.packets.login.login.LoginPluginRequest

Bases: ClientBoundPacket

Sent by the server to implement a custom handshaking flow. (Server -> Client).

Initialize the LoginPluginRequest.

Parameters:

Name	Type	Description	Default
message_id		Message id, generated by the server, should be unique to the connection.	required
channel		Channel identifier, name of the plugin channel used to send data.	required
data		Data that is to be sent.	required

mcproto.packets.login.login.LoginPluginResponse

Bases: ServerBoundPacket

Response to LoginPluginRequest from client. (Client -> Server).

Initialize the LoginPluginRequest packet.

Parameters:

Name	Type	Description	Default
message_id		Message id, generated by the server, should be unique to the connection.	required
data		Optional response data, present if client understood request.	required

mcproto.packets.login.login.LoginSetCompression

Bases: ClientBoundPacket

Sent by the server to specify whether to use compression on future packets or not (Server -> Client).

Initialize the LoginSetCompression packet.

Parameters:

Name	Type	Description	Default
threshold		Maximum size of a packet before it is compressed. All packets smaller than this will remain uncompressed. To disable compression completely, threshold can be set to -1.	required

Note

This packet is optional, and if not set, the compression will not be enabled at all.

mcproto.packets.login.login.LoginStart

Bases: ServerBoundPacket

Packet from client asking to start login process. (Client -> Server).

Initialize the LoginStart packet.

Parameters:

Name	Type	Description	Default
username		Username of the client who sent the request.	required
uuid		UUID of the player logging in (if the player doesn't have a UUID, this can be None)	required

mcproto.packets.login.login.LoginSuccess

Bases: ClientBoundPacket

Sent by the server to denote a successful login. (Server -> Client).

Initialize the LoginSuccess packet.

Parameters:

Name	Type	Description	Default
uuid		The UUID of the connecting player/client.	required
username		The username of the connecting player/client.	required

Play gamestate

Work In Progress

Packets for the Play gamestate aren't yet implemented.