Difference between revisions of "Pocket Minecraft Protocol"

Revision as of 17:41, 25 November 2012

Unlike the Minecraft protocol, this protocol uses UDP with (so far observed, at least) one message per packet. This makes the protocol easier to work with when it comes to packet serialization, and might offer latency improvements, but will inevitably have the usual UDP issues (packets lost, truncated, duplicated, out-of-order, etc.).

Servers listen on UDP port 19132.

Clients don't pick any specific port to listen on.

Please note that even where packet field names are written in this page, these are still largely hypothetical and could well be incorrect guesses. Some packets are fixed to the RakNet protocol, and will be marked as "RakNet Packet", which means that these packets will not change on future versions.

It has been determined that PM uses RakNet for its networking library, some documentation that seems relevant.

Terminology

PM: Pocket Minecraft (aka Minecraft PE or Minecraft Pocket Edition)

Types

	Size	Range	Notes
byte	1	-128 to 127	Signed, two's complement
short	2	-32768 to 32767	Signed, two's complement
int32	4	-2147483648 to 2147483647	Signed, two's complement
int64	8		Maybe a double?
MAGIC	16	`0x00ffff00fefefefefdfdfdfd12345678`	always those hex bytes, corresponding to RakNet's default OFFLINE_MESSAGE_DATA_ID
string	= 1	N/A	Prefixed by a short containing the length of the string in characters. It appears that only the following ASCII characters can be displayed: !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{\|}~

Packets

All packets start with a single byte that identifies the packet type, the rest of the packet follows it.

ID_UNCONNECTED_PING_OPEN_CONNECTIONS (0x02)

Client to Broadcast

RakNet Packet

Packet ID	Field Name	Field Type	Example	Notes
0x02	Ping ID	int64	`0x00000000003c6d0d`	Time since start in Milliseconds
0x02	MAGIC	MAGIC
Total Size:	25 Bytes

Clients start out by sending this packet to the IP broadcast address on port 19132 repeatedly (approx once per second) when joining a server was chosen on the main screen, and stops when the user selects a server (or leaves the screen). The ping ID from the client increases over time, and appears to be the number of milliseconds since the client program was started (might be used to measure server response latency).

ID_OPEN_CONNECTION_REQUEST_1 (0x05)

Client to Server

RakNet Packet

Packet ID	Field Name	Field Type	Example	Notes
0x05	MAGIC	MAGIC
	Protocol Version	byte	`5`	Currently 5
	Null Payload	many 0x00 bytes	`0x00 * 1447`	MTU (Maximum Transport Unit)
Total Size:	18 Bytes + length of Null Payload

If the version is different than yours, reply with a ID_INCOMPATIBLE_PROTOCOL_VERSION (0x1A)

Sent from client after it receives packet 0x1d. The client will repeatedly send this with reducing sizes until it successfully receives a reply. Observed behaviour is that the client will send packets ~0.5s apart in the following way, until it gets a 0x06 response packet, or reaches the end of these:

4 packets of Null Payload length of 1447
4 packets of Null Payload length of 1155
5 packets of Null Payload length of 531

If the server doesnt't reply the client, the client will display a "Connect Error" window

ID_OPEN_CONNECTION_REPLY_1 (0x06)

Server to Client

RakNet Packet

Packet ID	Field Name	Field Type	Example	Notes
0x06	MAGIC	MAGIC
	Server ID	int64	`0x00000000372cdc9e`	This value seems to be constant for an installation of PM, or differs between the demo and full version.
	Server Security	byte	`0`	Always 0
	MTU Size	short	`1447`	length of 0x05. Used to determine packet loss and max UDP packet size (MTU)
Total Size:	28 Bytes

Sent from server after it receives packet 0x05.

ID_OPEN_CONNECTION_REQUEST_2 (0x07)

Client to Server

RakNet Packet

Packet ID	Field Name	Field Type	Example	Notes
0x07	MAGIC	MAGIC
	Security + Cookie	1 + 4 bytes	`0x043f57fefd`	Unused, constant value
	Server UDP Port	short	`19132`
	MTU Size	short	`1464`
	Client ID	int64	`0x00000000372cdc9e`	The Client / Server ID will be the same for a given device
Total Size:	34 Bytes

Sent from client in response to packet 0x06.

ID_OPEN_CONNECTION_REPLY_2 (0x08)

Server to Client

RakNet Packet

Packet ID	Field Name	Field Type	Example	Notes
0x08	MAGIC	MAGIC
	Server ID	int64	`0x00000000372cdc9e`
	Client UDP Port	short	`46946`
	MTU Size	short	`1464`
	Security	byte	`0`	Always 0
Total Size:	30 Bytes

Sent from server in response to packet 0x07.

ID_INCOMPATIBLE_PROTOCOL_VERSION (0x1A)

Server to Client

RakNet Packet

Packet ID	Field Name	Field Type	Example	Notes
0x1A	Protocol Version	byte	`5`
	MAGIC	MAGIC
	Server ID	int64	`0x00000000372cdc9e`
Total Size:	26 Bytes

ID_UNCONNECTED_PING_OPEN_CONNECTIONS (0x1C)

Server to Client

RakNet Packet

Packet ID	Field Name	Field Type	Example	Notes
0x1C	Ping ID	int64	`0x00000000003c6d0d`	Time since start in Milliseconds
	Server ID	int64	`0x00000000372cdc9e`
	MAGIC	MAGIC
	Identifier	string	MCCPP;Demo;
	Server name	string	`Steve`
Total Size:	46 Bytes + Server name length

Server sends this packet in response to a 0x02 packet. Depends of the version to send a 0x1D or a 0x1C If the Server is invisible, this packet will be sent without username

Minecraft Pocket Edition v0.5.0.0 introduced another identifier special for Minecon 2012 "MCCPP;MINECON;". This will show a Minecon logo in front of the server name, and the color of the name is changed to blue.

ID_ADVERTISE_SYSTEM (0x1D)

Server to Client

RakNet Packet

Packet ID	Field Name	Field Type	Example	Notes
0x1D	Ping ID	int64	`0x00000000003c6d0d`	Time since start in Milliseconds
	Server ID	int64	`0x00000000372cdc9e`
	MAGIC	MAGIC
	Data	string	`MCCPP;Demo;Steve`	Used to send the username (MCCPP;Demo; + username)
Total Size:	35 Bytes + length of string

Same as ID_UNCONNECTED_PING_OPEN_CONNECTIONS (0x1C), but with the Packet ID changed. Depends of the version to send a 0x1D or a 0x1C