Difference between revisions of "Pocket Minecraft Protocol"

Revision as of 06:44, 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.).

Also check #mcpedevs on irc.freenode.net

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 hex bytes `0x00ffff00fefefefefdfdfdfd12345678`, 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
	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

Packet (0x84)

Two-Way

This packet is part of the real Minecraft PE implementation. The structure can change anytime.

This packet has a partial unknown structure

Packet ID	Field Name	Field Type	Example	Notes
0x84	Count	3 bytes	`0`	Increments once every packet.
	Data payload		`0x40009000000009d9214556220cb5c90000000000000c9800`	Uses Packet Encapsulation format
	Total Size:	6 Bytes + payload

Sent after 0x08. The receiver will use the Packet number in the 0xC0 packet and send it back.

Unknown (0x8C)

Server -> Client

This packet is part of the real Minecraft PE implementation. The structure can change anytime.

This packet has a partial unknown structure, but it seems to complement the packet 0x84. Packet Order count continues from the last value of 0x84. Could be Chunk Data or AddEntityPacket.

It seems that it has a start field of unknown length that suggests that this packet is used as an multi-purpouse packet. The same happens with 0x84

Packet ID	Field Name	Field Type	Example	Notes
0x8C	Packet Order ID	byte?	`57`	Could be used to reorder packets
	Unknown	variable
	Total Size:	1 + ? Bytes

Sent after 0x84 by client.

Unknown (0xA0)

Two-Way

This packet is part of the real Minecraft PE implementation. The structure can change anytime.

Packet ID	Field Name	Field Type	Example	Notes
0xA0	Data	6 bytes	`0x000101000000`
0xA0	Total Size:	7 Bytes

Sent after an invalid Packet Order ID.

ACK (0xC0)

Two-Way

This packet is part of the real Minecraft PE implementation. The structure can change anytime.

Packet ID	Field Name	Field Type	Example	Notes
0xC0	Unknown	short	`1`
	Additional Packet	boolean	`true`	true when there is only one packet received
	Packet Number	3 bytes	`0x000000`	Received packet number from field Count in 0x84 and 0x8C
	Packet Number #2	3 bytes	`0x000004`	Last received packet number (only when false)
Total Size:	7 or 10 Bytes

Sent after a 0x84 or 0x8C. It's used to ACK recieval of packets. The second packet number is optional and only there when bool is false.

Packet Encapsulation format

The payload in 0x84 (and more) packets is incoded using different schemes. To decode them, you've to use the Encapsulation ID to check wich type you should use. The Encapsulation ID is the firsth byte of the payload.

Multiple Data Encapsulation packets could be present in one packet

0x00

Encapsulation ID	Field Name	Field Type	Example	Notes
0x00	length	short	`0x0090`	length of Packet in bits (real length = length / 8)
	Packet	Data Packet	`0x09d9214556220cb5c90000000000000c9800`
	Total Size:	3 Bytes + Packet Data length

0x40

Encapsulation ID	Field Name	Field Type	Example	Notes
0x40	length	short	`0x0090`	length of Packet in bits (real length = length / 8)
	Count	3 bytes	`0x000000`	Unknown use
	Packet	Data Packet	`0x09d9214556220cb5c90000000000000c9800`
	Total Size:	6 Bytes + Packet Data length

0x60

Encapsulation ID	Field Name	Field Type	Example	Notes
0x60	length	short	`0x0090`	length of Packet in bits (real length = length / 8)
	Count	3 bytes	`0x000000`	Unknown use
	Unknown	4 bytes	`0x00000000`	Only sent on first iteration
	Packet	Data Packet	`0x09d9214556220cb5c90000000000000c9800`
	Total Size:	6 Bytes + ? + Packet Data length

Data Packets

Data ID List

All the information in this list is based on the RakNet and Minecraft ID for each packet. The RakNet ID is the first byte in each packet, while the Minecraft ID is the first byte after each RakNet header. All names for each packet are based on the Android assembly code. Each packet is in the format of RakNet ID first, Minecraft ID second, Name third. All packets are found by using the tutorial posted by Jocopa3 found here.

RakNet ID	Minecraft ID	Packet Name
0x84	0x82	LoginPacket
0x84	0x83	LoginStatusPacket
0x84	0x84	ReadyPacket
0x84	0x85	MessagePacket
0x84	0x86	SetTimePacket
0x84	0x87	StartGamePacket
0x84	0x88	AddMobPacket
0x84	0x89	AddPlayerPacket
0x84	0x8A	RemovePlayerPacket
0x84	0x8C	AddEntityPacket
0x84	0x8D	RemoveEntityPacket
0x84	0x8E	AddItemEntityPacket
0x84	0x8F	TakeItemEntityPacket
0x84	0x90	MoveEntityPacket
0x84	0x93	MoveEntityPacket_PosRot
0x84	0x94	MovePlayerPacket
0x84	0x95	PlaceBlockPacket
0x84	0x96	RemoveBlockPacket
0x84	0x97	UpdateBlockPacket
0x84	0x98	AddPaintingPacket
0x84	0x99	ExplodePacket
0x84	0x9A	LevelEventPacket
0x84	0x9B	TileEventPacket
0x84	0x9C	EntityEventPacket
0x84	0x9D	RequestChunkPacket
0x84	0x9E	ChunkDataPacket
0x84	0x9F	PlayerEquipmentPacket
0x84	0xA0	Interactpacket
0x84	0xA1	UseItemPacket
0x84	0xA2	PlayerActionPacket
0x84	0xA3	SetEntityDataPacket
0x84	0xA4	SetEntityMotionPacket
0x84	0xA5	SetHealthPacket
0x84	0xA6	SetSpawnPositionPacket
0x84	0xA7	AnimatePacket
0x84	0xA8	RespawnPacket
0x84	0xA9	Packet::Packet(void) †
0x84	0xAA	DropItemPacket
0x84	0xAB	ContainerOpenPacket
0x84	0xAC	ContainerClosePacket
0x84	0xAD	ContainerSetSlotPacket
0x84	0xAE	ContainerSetDataPacket
0x84	0xAF	ContainerSetContentPacket
0x84	0xB0	ContainerAckPacket
0x84	0xB1	ChatPacket
0x84	0xB2	SignUpdatePacket
0x84	0xB3	AdventureSettingsPacket
Total: 47 Packets

† Packet exists but the Assembly shows no further code for it (Blank Packet?).

ClientConnect (0x09)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x09`
Client ID	8 bytes	`0xffffffffb287d2a5`
Unknown	5 bytes	`0x0000000000`
Session	4 bytes	`0x000002fc`
Total Size:	18 Bytes

ClientDisconnect (0x15)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x15`
Total Size:	1 byte

LoginPacket (0x82)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x82`
Name length	short	`0x0006`
Name	string	Stevie
Int	int32	`0x00000007`
Int	int32	`0x00000007`
Total Size:	11 Bytes + Name length

LoginStatusPacket (0x83)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x83`
Unknown	int32
Total Size:	5 Bytes

ReadyPacket (0x84)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x84`
Byte	byte	`0x01`
Total Size:	2 Bytes

SetTimePacket (0x86)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x86`
Short	short	`0x0000`
Short	short	`0x0100`
Total Size:	5 Bytes

AddEntityPacket (0x8c)

Field Name	Field Type	Example	Notes
Bytes	byte
Integer	integer
Bytes	byte
X	float
Y	float
Z	float
Integer	integer		World?
Short	short		Motion?
Short	short		Motion?
Short	short		Motion?
Total Size:	? Bytes

AddItemEntityPacket (0x8e)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x8e`
Entity ID?	integer
Item ID	short
Stack Size	byte
Item Data	short
X	float
Y	float
Z	float
Yaw	byte
Pitch	byte
Roll	byte
Total Size:	25 Bytes

TakeItemEntityPacket (0x8f)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x8f`
Collector Entity ID?	int32
Item Entity ID?	int32
Total Size:	9 Bytes

MoveEntityPacket_PosRot (0x93)

Field Name	Field Type	Example	Notes
ID?	3 bytes	`0x4000c8`
Number	3 bytes	`0x010000`
Minecraft ID	byte	`0x93`
Entity ID?	3 bytes	`0x0000`
X	float
Y	float
Z	float
Short	short
Short	short
Int	int32
Total Size:	30 Bytes

MovePlayerPacket (0x94)

Field Name	Field Type	Example	Notes
ID?	3 bytes	`0x4000c8`
Number	3 bytes	`0x010000`
Minecraft ID	byte	`0x94`
Int	int32
X	float
Y	float
Z	float
Yaw	float
Pitch	float
Total Size:	31 Bytes

PlaceBlockPacket (0x95)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x95`
Int	int32
Int	int32
Int	int32
Byte	byte
Byte	byte
Byte	byte
Byte	byte
Byte	byte
Total Size:	18 Bytes

RemoveBlockPacket (0x96)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x96`
Int	int32
Int	int32
Int	int32
Byte	byte
Total Size:	14 Bytes

TileEventPacket (0x9b)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x9b`
Int	int32
Int	int32
Int	int32
Int	int32
Int	int32
Total Size:	21 Bytes

EntityEventPacket (0x9c)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x9c`
Int	int32
Int	int32
Total Size:	9 Bytes

RequestChunkPacket (0x9d)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x9d`
X	int32
Z	int32
Total Size:	9 Bytes

ChunkDataPacket (0x9e)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0x9e`
Int	int32
Int	int32
Total Size:	9 Bytes

SetEntityMotionPacket (0xa3)

Field Name	Field Type	Example	Notes
ID?	3 bytes	`0x400058`
Number	3 bytes	`0x010000`
Minecraft ID	byte	`0xa3`
Entity ID?	int32
X Motion	short
Y Motion	short
Z Motion	short
Total Size:	17 Bytes

SetHealthPacket (0xa5)

Field Name	Field Type	Example	Notes
Minecraft ID	byte	`0xa5`
Health	byte	`0x14`
Total Size:	2 Bytes

Packet Dumps

Due to the lack of information about the protocol, packet dumps are welcome. You can also post here pcap files of Client <-> Server sessions

Partial Custom Client server connection
Partial Custom Server client info + connection
Full Client / Server Communication. PCAP, including server search. download

@@ Line 1,108: / Line 1,108: @@
 | class="col3 centeralign" |
 |- class="row2"
-| class="col0 centeralign" | Integer
+| class="col0 centeralign" | Entity ID?
 | class="col1 centeralign" | integer
 | class="col2 centeralign" |
 | class="col3" |
 |- class="row3"
-| class="col0 centeralign" | Short
+| class="col0 centeralign" | Item ID
 | class="col1 centeralign" | short
 | class="col2 centeralign" |
 | class="col3" |
 |- class="row4"
-| class="col0 centeralign" | Byte
+| class="col0 centeralign" | Stack Size
 | class="col1 centeralign" | byte
 | class="col2 centeralign" |
 | class="col3" |
 |- class="row5"
-| class="col0 centeralign" | Short
+| class="col0 centeralign" | Item Data
 | class="col1 centeralign" | short
 | class="col2 centeralign" |
 | class="col3" |
 |- class="row6"
-| class="col0 centeralign" | Float
+| class="col0 centeralign" | X
 | class="col1 centeralign" | float
 | class="col2 centeralign" |
 | class="col3" |
 |- class="row7"
-| class="col0 centeralign" | Float
+| class="col0 centeralign" | Y
 | class="col1 centeralign" | float
 | class="col2 centeralign" |
 | class="col3 centeralign" |
 |- class="row8"
-| class="col0 centeralign" | Float
+| class="col0 centeralign" | Z
 | class="col1 centeralign" | float
 | class="col2 centeralign" |
 | class="col3 centeralign" |
 |- class="row9"
-| class="col0 centeralign" | Byte
+| class="col0 centeralign" | Yaw
 | class="col1 centeralign" | byte
 | class="col2" |
 | class="col3 centeralign" |
 |- class="row10"
-| class="col0 centeralign" | Byte
+| class="col0 centeralign" | Pitch
 | class="col1 centeralign" | byte
 | class="col2" |
 | class="col3 centeralign" |
 |- class="row11"
-| class="col0 centeralign" | Byte
+| class="col0 centeralign" | Roll
 | class="col1 centeralign" | byte
 | class="col2" |

Difference between revisions of "Pocket Minecraft Protocol"

Revision as of 06:44, 25 November 2012

Contents

Terminology

Types

Packets

ID_UNCONNECTED_PING_OPEN_CONNECTIONS (0x02)

ID_OPEN_CONNECTION_REQUEST_1 (0x05)

ID_OPEN_CONNECTION_REPLY_1 (0x06)

ID_OPEN_CONNECTION_REQUEST_2 (0x07)

ID_OPEN_CONNECTION_REPLY_2 (0x08)

ID_INCOMPATIBLE_PROTOCOL_VERSION (0x1A)

ID_UNCONNECTED_PING_OPEN_CONNECTIONS (0x1C)

ID_ADVERTISE_SYSTEM (0x1D)

Packet (0x84)

Unknown (0x8C)

Unknown (0xA0)

ACK (0xC0)

Packet Encapsulation format

0x00

0x40

0x60

Data Packets

Data ID List

ClientConnect (0x09)

ClientDisconnect (0x15)

LoginPacket (0x82)

LoginStatusPacket (0x83)

ReadyPacket (0x84)

SetTimePacket (0x86)

AddEntityPacket (0x8c)

AddItemEntityPacket (0x8e)

TakeItemEntityPacket (0x8f)

MoveEntityPacket_PosRot (0x93)

MovePlayerPacket (0x94)

PlaceBlockPacket (0x95)

RemoveBlockPacket (0x96)

TileEventPacket (0x9b)

EntityEventPacket (0x9c)

RequestChunkPacket (0x9d)

ChunkDataPacket (0x9e)

SetEntityMotionPacket (0xa3)

SetHealthPacket (0xa5)

Packet Dumps

Navigation menu

Search