Pocket Minecraft Protocol

From wiki.vg
Jump to: navigation, search

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.).

As of 0.9.0, clients appear to search for servers on only 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.


The login sequence is not covered by this page.


Contents

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{|}~

Login Packets

All packets start with a single byte that identifies the packet type, the rest of the packet follows it. Please note that packets 0x09 through 0x13 are not documented (yet).


ID_CONNECTED_PING_OPEN_CONNECTIONS (0x01)

Client to Broadcast


RakNet Packet

Packet ID Field Name Field Type Example Notes
0x01 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_UNCONNECTED_PING_OPEN_CONNECTIONS (0x02)

Client to Broadcast

NOTE: THIS PACKET APPEARS TO BE UNUSED. Use a 0x01 packet instead

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

Same as ID_CONNECTED_PING_OPEN_CONNECTIONS (0x01), but with the Packet ID changed.


ID_OPEN_CONNECTION_REQUEST_1 (0x05)

Client to Server


RakNet Packet

Packet ID Field Name Field Type Example Notes
0x05 MAGIC MAGIC
RakNet Protocol Version byte 5 Check the Data Packet section for the current version
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 the client after the player taps on the server in the world list 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, not constant value*, but usually similar to 0x043f57fefd
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.

  • Instances have been observed where the value 0x043f57fefd is not always present, but similar values are sent.

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

Sent when the server doesn't support the RakNet protocol specified in 0x05.


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 "MCPE;Steve;2 7;0.11.0;0;20" Used to send the username, format: MCPE;<Server name>;<Protocol version>;<MCPE Version>;<Players>;<Max Players>
Total Size: 35 Bytes + Server name length

Server sends this packet in response to a 0x01 packet. If the Server is invisible, this packet will be sent without username

In order for the server to show up in the world list, the server name must have "MCCPP;MINECON;" in front of it. Since MCPE 0.11.0, the server name has a different format.


ID_ADVERTISE_SYSTEM (0x1D)

Server to Client


RakNet Packet

THIS PACKET IS UNUSED, Use a 0x1c packet instead.

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 MCPE;Steve;2 7;0.11.0;0;20 Used to send the username, format: MCPE;<Server name>;<Protocol version>;<MCPE Version>;<Players>;<Max Players>
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

Custom Packet (0x80-0x8F)

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
0x80-0x8F Count 3 bytes 0 Increments once every packet.
Data payload 0x40009000000009... Uses Packet Encapsulation format
Total Size: 4 Bytes + payload

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


NAK (0xA0)

Two-Way

RakNet Packet

Packet ID Field Name Field Type Example Notes
0xA0 Count short 1
MinEqualsMax boolean true true if the following range contains only one number
Packet Number (Min) 3 bytes 0x000000 Range of packet to resend
Packet Number (Max) 3 bytes 0x000004 Range of packet to resend (only if false)
Total Size: 7 or 10 Bytes

Send these when a packet was lost, or reply to this resending the lost packet.

ACK (0xC0)

Two-Way

RakNet Packet

Packet ID Field Name Field Type Example Notes
0xC0 Count short 1
MinEqualsMax boolean true true if the following range contains only one number
Packet Number (Min) 3 bytes 0x000000 Received packet number from field Count in 0x84 and 0x8C
Packet Number (Max) 3 bytes 0x000004 Received Packet Number (only when false)
Total Size: 7 or 10 Bytes

Sent after a 0x8X. 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 0x80-0x8F packets is encoded 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 first byte of the payload.

Multiple Data Encapsulation packets could be present in one packet. If you want to send data, use 0x00.

Length field is in bits, not bytes. To get the length in bytes, use length_in_bytes = length / 8. The length field is excluding the header -- both the 0x8X packet header, as well as the encapsulated packet header.


0x00

Encapsulation ID Field Name Field Type Example Notes
0x00 length short 0x0090 Length of Packet in bits
Packet Data Packet 0x09d92145...
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
Count 3 bytes 0x000000 Unknown use
Packet Data Packet 0x09d92145...
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
Count 3 bytes 0x000000 Unknown use
Unknown 4 bytes 0x00000000 Only sent on first iteration
Packet Data Packet 0x09d92145...
Total Size: 12 Bytes + Packet Data length


Encapsulated Login packets

After packets 0x05 through 0x08 are sent, the client will send the first encapsulated packets (0x09 through 0x13). After 0x13 the game begins. You can check the login sequence here.

Client Connect (0x09)

Client to Server

This is a Data Packet. It is encoded using packet encapsulation format.

Packet ID Field Name Field Type Example Notes
0x09 clientID int64 The mojang client's clientID.
session int64 A long that is sent back to the client in 0x10.
unknown byte Unknown use. Constant value.
Total Size: 18 Bytes

Server Handshake (0x10)

Server to Client

This is a Data Packet. It is encoded using packet encapsulation format..

Packet ID Field Name Field Type Example Notes
0x10 Cookie 4 bytes 043f57fe Unknown use, constant value.
Security flags 1 byte 0xcd Unknown use, constant value.
Server port short 19132 Unknown use.
Data Array 70 bytes Unknown use, constant value (see below).
Unknown 2 bytes 0x00 0x00 Unknown use, constant value.
Session int64 Session long recieved in 0x09.
Unknown 8 bytes 0x00, 0x00, 0x00, 0x00, 0x04, 0x44, 0x0b, 0xa9 Unknown use, constant value.
Total Size: 96 Bytes

Data Array

The data array section is unknown, but we do know how to get it right. Below is some code on how to create the array (C#). 

  public void putDataArray()
       {
           byte[] unknown1 = new byte[] { 0xf5, 0xff, 0xff, 0xf5 };
           byte[] unknown2 = new byte[] { 0xff, 0xff, 0xff, 0xff };
           this.putTriad(unknown1.Length);
           this.putBytes(unknown1);
           for (int i = 0; i < 9; i++)
           {
               this.putTriad(unknown2.Length);
               this.putBytes(unknown2);
           }
       }

A triad is a 3 byte integer.

Credit goes to InusualZ (https://github.com/InusualZ/CraftMine/blob/master/src/Network/Packets/Minecraft/ServerHandshake.cs).

Client Handshake (0x13)

Client to Server

This is a Data Packet. It is encoded using packet encapsulation format..

Packet ID Field Name Field Type Example Notes
0x13 cookie int32 0x43f57fe Unknown use, same cookie as in 0x10.
Security flags 1 byte 0xcd Unknown use, constant value.
Server port short 19132 Unknown use.
Data Array 1 Length + Data Array 1 1 + ? bytes Unknown use (see below).
Data Array 2  ? bytes Unknown use, constant value (see below).
Timestamp short Unknown use.
session int64 Unknown use.
session2 int64 Unknown use.
Total Size: 94 Bytes

Data Arrays

Array 1

The first array is just a series of bytes, starting with the first byte which has the length of the rest of the array. This can be decoded as follows (Java): 

  buffer.get(new byte[(int) buffer.get()]);

The buffer variable is really a ByteBuffer object found in the package java.nio.

Array 2

The second array is a little more complicated. The first section is a triad (3 bytes) which specifies how many bytes to read next. This is repeated 9 times. An example is below (Java):

for(int i = 0; i < 9; i++){

int l = NetworkUtils.getTriad(buf);

buf.get(new byte[l]);

}

Again, the buf object is a ByteBuffer object.


Client Cancel Connect (0x15)

Client to Server

This is a Data Packet. It is encoded using packet encapsulation format.

Packet ID Notes
0x15 Only the packet ID is sent.
Total Size: 1 Byte

This appears to be sent whenever the user clicks the "cancel" button when connecting.

Ping/Pong

The client will repeatedly send ping packets to the server each containing an identifier (long). The server then must reply with a pong packet containing the identifier found in the ping. This is observed to happen sometime during the encapsulation login.

Ping Packet (0x00)

Client to Server

This is a Data Packet. It is encoded using packet encapsulation.

Packet ID Field Name Field Type Example Notes
0x00 identifier int64 0000000000000b3d An identifer sent back by a Pong packet (0x03).
Total Size: 9 Bytes

Pong Packet (0x03)

Server to Client

This is a Data Packet. It is encoded using packet encapsulation.

Packet ID Field Name Field Type Example Notes
0x03 identifier int64 0000000000000b3d The identifier found in the ping packet (0x00).
Total Size: 9 Bytes


Data Packets

This information has been generated using PocketBurger, then edited manually.

This information was generated based on:

Minecraft: Pocket Edition v0.7.3, protocol #11

RakNet Protocol version #5

However, these packets seem to be unchanged since then, and will (most likely) work with the current version.

Current Version:

Minecraft: Pocket Edition v0.10.4, protocol #20

RakNet Protocol version #5

LoginPacket (0x82)

Client to Server


Packet ID Field Name Field Type Notes
0x82 Username string8
Protocol #1 int
Protocol #2 int
ClientID int
Realms Data string8

LoginStatusPacket (0x83)

Server to Client


Packet ID Field Name Field Type Notes
0x83 Status int

The three type of status are:

0: Everything is good.

1: If the server is outdated.

2. If the game is outdated.

If everything is good you need to send StartGamePacket.

ReadyPacket (0x84)

Client to Server


Packet ID Field Name Field Type Notes
0x84 bits[8] Status byte

MessagePacket (0x85)

Two-Way


Packet ID Field Name Field Type Notes
0x85 Message string8

SetTimePacket (0x86)

Client to Server


Packet ID Field Name Field Type Notes
0x86 Time int

StartGamePacket (0x87)

Client to Server


Packet ID Field Name Field Type Notes
0x87 level seed int
Unknown int
Gamemode int
Entity ID int
X float
Y float
Z float

AddMobPacket (0x88)

Client to Server


Packet ID Field Name Field Type Notes
0x88 Entity ID int
Type int
X float
Y float
Z float
yaw byte
pitch byte
Metadata byte[]

AddPlayerPacket (0x89)

Client to Server


Packet ID Field Name Field Type Notes
0x89 (unsigned) Client ID long
Username string8
Entity ID int
X float
Y float
Z float
Yaw byte
Pitch byte
Unknown short
Unknown short
Metadata byte[]

RemovePlayerPacket (0x8a)

Client to Server


Packet ID Field Name Field Type Notes
0x8a entity ID int
(unsigned) Client ID long

AddEntityPacket (0x8c)

Client to Server


Packet ID Field Name Field Type Notes
0x8c Entity ID int
Type byte
X float
Y float
Z float
Did? int If this int > 0 you can send the next parameter
SpeedX short
SpeedY short
SpeedZ short

RemoveEntityPacket (0x8d)

Client to Server


Packet ID Field Name Field Type Notes
0x8d Entity ID int

AddItemEntityPacket (0x8e)

Client to Server


Packet ID Field Name Field Type Notes
0x8e Enity ID int
Block short
Stack byte
Meta short
X float
Y float
Z float
Yaw byte
Pitch byte
Roll byte

TakeItemEntityPacket (0x8f)

Client to Server


Packet ID Field Name Field Type Notes
0x8f Target int
Entity ID int

MoveEntityPacket (0x90)

Client to Server


Packet ID Field Name Field Type Notes
0x90 Entity ID int
X float
Y float
Z float

MoveEntityPacket_PosRot (0x93)

None


Packet ID Field Name Field Type Notes
0x93 Entity ID int
X float
Y float
Z float
Yaw float
Pitch float

MovePlayerPacket (0x94)

Two-Way


Packet ID Field Name Field Type Notes
0x94 Entity ID int
X float
Y float
Z float
Yaw float
Pitch float

PlaceBlockPacket (0x95)

Two-Way


Packet ID Field Name Field Type Notes
0x95 Entity iD int
X int
Z int
Y byte
Block byte
Meta byte
Face byte

RemoveBlockPacket (0x96)

Server to Client


Packet ID Field Name Field Type Notes
0x96 Entity ID int
X int
Z int
Y byte

UpdateBlockPacket (0x97)

Client to Server


Packet ID Field Name Field Type Notes
0x97 Entiy ID int
X int
Z int
Y byte
Block byte
Meta byte

AddPaintingPacket (0x98)

Client to Server


Packet ID Field Name Field Type Notes
0x98 Entity ID int
X int
Y int
Z int
Direction int
Title string8

ExplodePacket (0x99)

Client to Server


Packet ID Field Name Field Type Notes
0x99 X float
Y float
Z float
Radius float
Count int
Records byte
Counts? byte
Records? byte

LevelEventPacket (0x9a)

Client to Server


Packet ID Field Name Field Type Notes
0x9a Unknown? short
Unknown? short
Unknown? short
Unknown? short
Unknown? int

TileEventPacket (0x9b)

Client to Server


Packet ID Field Name Field Type Notes
0x9b X int
Y int
Z int
Case 1 int
Case 2 int

EntityEventPacket (0x9c)

Two-Way


Packet ID Field Name Field Type Notes
0x9c Entity ID int
Event byte

RequestChunkPacket (0x9d)

Server to Client


Packet ID Field Name Field Type Notes
0x9d X int
Z int

ChunkDataPacket (0x9e)

Client to Server


Packet ID Field Name Field Type Notes
0x9e X int
Z int
byte
Data? byte[]
Data? byte[]

PlayerEquipmentPacket (0x9f)

Two-Way


Packet ID Field Name Field Type Notes
0x9f Entity ID int
Block short
Meta short
Slot byte

PlayerArmorEquipmentPacket (0xa0)

Two-Way


Packet ID Field Name Field Type Notes
0xa0 Entity ID int
Slot 1 byte
Slot 2 byte
Slot 3 byte
Slot 4 byte

InteractPacket (0xa1)

Two-Way


Packet ID Field Name Field Type Notes
0xa1 Action byte[]
entity ID int
Target int

UseItemPacket (0xa2)

Server to Client


Packet ID Field Name Field Type Notes
0xa2 X int
Y int
Z int
Face int
Block byte[]
Meta byte
Entity ID int
Fx float
Fy float
Fz float
PosX float
PosY float
PosZ float

PlayerActionPacket (0xa3)

Server to Client


Packet ID Field Name Field Type Notes
0xa3 Action int
X int
Y int
Z int
Face int
Entity ID int

HurtArmorPacket (0xa5)

Client to Server


Packet ID Field Name Field Type Notes
0xa5 Health byte

SetEntityDataPacket (0xa6)

Client to Server


Packet ID Field Name Field Type Notes
0xa6 Entity ID int
Metadata byte[]

SetEntityMotionPacket (0xa7)

Client to Server


Packet ID Field Name Field Type Notes
0xa7 Unknown? byte
Entity ID int
X short
Y short
Z short

SetRidingPacket (0xa8)

Client to Server


Packet ID Field Name Field Type Notes
0xa8 a int
b int

SetHealthPacket (0xa9)

Two-Way


Packet ID Field Name Field Type Notes
0xa9 Health byte

SetSpawnPositionPacket (0xaa)

Client to Server


Packet ID Field Name Field Type Notes
0xaa X int
Z int
Y byte

AnimatePacket (0xab)

Two-Way


Packet ID Field Name Field Type Notes
0xab Action byte
Entity ID int

RespawnPacket (0xac)

Two-Way


Packet ID Field Name Field Type Notes
0xac Entity ID int
X float
Y float
Z float

SendInventoryPacket (0xad)

None


Packet ID Field Name Field Type Notes
0xad Entity ID int
Windows ID byte
Count short
Slots byte[]
Items byte[]

DropItemPacket (0xae)

Server to Client


Packet ID Field Name Field Type Notes
0xae Entity ID int
Unknown? byte
Block short
Stack byte
Meta short

ContainerOpenPacket (0xaf)

Client to Server


Packet ID Field Name Field Type Notes
0xaf Window ID byte
Type byte
Slot byte
Title string8

ContainerClosePacket (0xb0)

Two-Way


Packet ID Field Name Field Type Notes
0xb0 Window ID byte

ContainerSetSlotPacket (0xb1)

Two-Way


Packet ID Field Name Field Type Notes
0xb1 Window ID byte
Slot short
Block short
Stack byte
Meta short

ContainerSetDataPacket (0xb2)

Client to Server


Packet ID Field Name Field Type Notes
0xb2 Window ID byte
Property short
Value short

ContainerSetContentPacket (0xb3)

Client to Server


Packet ID Field Name Field Type Notes
0xb3 Window ID byte
Count short
Items byte[]

ContainerAckPacket (0xb4)

None


Packet ID Field Name Field Type Notes
0xb4 Window ID byte
Unknown? short

ChatPacket (0xb5)

Client to Server


Packet ID Field Name Field Type Notes
0xb5 Message string8

SignUpdatePacket (0xb6)

Two-Way


Packet ID Field Name Field Type Notes
0xb6 X short
Y byte
Z short
Lines string8

AdventureSettingsPacket (0xb7)

Client to Server


Packet ID Field Name Field Type Notes
0xb7 Flags byte[]
Retrieved from "http://wiki.vg/index.php?title=Pocket_Minecraft_Protocol&oldid=13541"