Pocket Minecraft Protocol
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.
Contents
- 1 Terminology
- 2 Types
- 3 Packets
- 3.1 ID_UNCONNECTED_PING_OPEN_CONNECTIONS (0x02)
- 3.2 ID_OPEN_CONNECTION_REQUEST_1 (0x05)
- 3.3 ID_OPEN_CONNECTION_REPLY_1 (0x06)
- 3.4 ID_OPEN_CONNECTION_REQUEST_2 (0x07)
- 3.5 ID_OPEN_CONNECTION_REPLY_2 (0x08)
- 3.6 ID_INCOMPATIBLE_PROTOCOL_VERSION (0x1A)
- 3.7 ID_UNCONNECTED_PING_OPEN_CONNECTIONS (0x1C)
- 3.8 ID_ADVERTISE_SYSTEM (0x1D)
- 3.9 Packet (0x84)
- 3.10 Unknown (0x8C)
- 3.11 Unknown (0xA0)
- 3.12 ACK (0xC0)
- 4 Packet Encapsulation format
- 5 Data Packets
- 5.1 Data ID List
- 5.2 LoginPacket (0x82)
- 5.3 LoginStatusPacket (0x83)
- 5.4 ReadyPacket (0x84)
- 5.5 SetTimePacket (0x86)
- 5.6 AddEntityPacket (0x8c)
- 5.7 AddItemEntityPacket (0x8e)
- 5.8 TakeItemEntityPacket (0x8f)
- 5.9 MoveEntityPacket_PosRot (0x93)
- 5.10 MovePlayerPacket (0x94)
- 5.11 PlaceBlockPacket (0x95)
- 5.12 RemoveBlockPacket (0x96)
- 5.13 TileEventPacket (0x9b)
- 5.14 EntityEventPacket (0x9c)
- 5.15 RequestChunkPacket (0x9d)
- 5.16 ChunkDataPacket (0x9e)
- 5.17 SetEntityMotionPacket (0xa3)
- 5.18 SetHealthPacket (0xa5)
- 6 Packet Dumps
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
|
|
| 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?).
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
|
||
| Integer | integer | |||
| Short | short | |||
| Byte | byte | |||
| Short | short | |||
| Float | float | |||
| Float | float | |||
| Float | float | |||
| Byte | byte | |||
| Byte | byte | |||
| Byte | byte | |||
| Total Size: | 25 Bytes | |||
TakeItemEntityPacket (0x8f)
| Field Name | Field Type | Example | Notes | |
| Minecraft ID | byte | 0x8f
|
||
| Int | int32 | |||
| Int | 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
|
||
| Int | 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
|
||
| Int | int32 | Maybe Entity ID? | ||
| Short | short | Maybe X motion? | ||
| Short | short | Maybe Y motion? | ||
| Short | short | Maybe Z motion? | ||
| 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
