Pocket Minecraft Protocol

From wiki.vg
Revision as of 06:13, 25 November 2012 by Shoghicp (talk | contribs) (typos)
Jump to navigation Jump to 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.).

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