Pre-release protocol
This page documents the changes from the last stable Minecraft release (currently 1.2.5) to the current pre-release (or weekly release).
Contents
- 1 New packets
- 2 Changed Data Type
- 3 Changed packets
- 3.1 Login Request (0x01)
- 3.2 Handshake (0x02)
- 3.3 Entity Equipment (0x05)
- 3.4 Respawn (0x09)
- 3.5 Player Block Placement (0x0F)
- 3.6 Spawn Named Entity (0x14)
- 3.7 Spawn Object/Vehicle (0x17)
- 3.8 Spawn Mob (0x18)
- 3.9 Destroy Entity (0x1D)
- 3.10 Chunk Data (0x33)
- 3.11 Block Change (0x35)
- 3.12 Block Action (0x36)
- 3.13 Update Tile Entity (0x84)
- 3.14 Explosion (0x3C)
- 3.15 Player Abilities (0xCA)
- 4 Removed packets
- 5 Protocol History
New packets
Map Chunk Bulk (0x38)
To reduce the number of bytes this packet is used to send chunk columns together for better compression results. The packet contains up to 100 chunk columns (later this might be reduced to 50).
The data part is a zlib compressed byte array containing the chunk data. The meta data part specifies which chunks in which order the data part exists of.
To split this packet into chunks you need to uncompress the data array. Then you can iterate through the data part. Each part is 10240 * n + 256 bytes. n is the number of chunks in the current chunk column(this is the number of flags set in the primary bitmap). 10240 is the amount of bytes for each chunk without add bitmap, 256 bytes are used for biomes. The second short in the meta data part is not yet in use. It could specify if the chunk uses the add bitmap part, because it has very high block ids, but not in the current snapshot.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x38 | Chunk Column Count | short | The number of chunk columns in this packet | |
Chunk data size | int | the size of the data field | ||
Data | byte array | compressed chunk data | ||
meta information | chunk bulk meta information | Chunk column count times the Meta information structure (See notes for details) | ||
Total Size: | 7 + (Chunk data size) + 12 * (Chunk Column Count) bytes |
Chunk Bulk Meta Information Structure
Field Name | Field Type | Example | Notes |
---|---|---|---|
Chunk Column X | int | 10 | The X coordinate of the specific chunk column |
Chunk Column Z | int | 10 | The Z coordinate of the specific chunk column |
Chunk Primary bitmap | short | 15 | A bitmap which specifies which chunk is not empty in this chunk column |
Chunk Add bitmap? | short | 0 | A bitmap which specifies which chunk need add information because of very high block ids. not yet used. needs verification |
Total Size: | 12 bytes |
Tab-complete (0xCB)
Two-way
Sent C->S when the user presses [tab] while writing text. The payload contains all text behind the cursor.
The server responds with an auto-completion of the last word sent to it. In the case of regular chat, this is a player username. Command names and parameters are also supported.
In the event of more than one possible completion, the server responds with the options packed into the single string field, separated by a null character. Note that as strings are UTF-16, this is two bytes wide.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0xCB | Text | string | ||
Total Size: | 3 bytes + length of string |
Locale and View Distance (0xCC)
Client to server
Sent when the player connects, or when settings are changed.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0xCC | Locale | string | en_GB | |
View distance | byte | 0 | 0-3 for 'far', 'normal', 'short', 'tiny'. | |
Chat flags | byte | 8 | Chat settings. See notes below. | |
Difficulty | byte | 0 | Client-side difficulty from options.txt | |
Total Size: | 8 bytes + length of string |
Chat flags has several values packed into one byte.
Chat Enabled: Bits 0-1. 00: Enabled. 01: Commands only. 10: Hidden.
Colors Enabled: Bit 3. 0: Disabled. 1: Enabled.
Client Statuses (0xCD)
Client to server
Sent when the client is ready to complete login and when the client is ready to respawn after death.
Packet ID | Field Name | Field Type | Example | Notes | |
---|---|---|---|---|---|
0xCD | Payload | byte | 0 | Bit field. 0: Initial spawn, 1: Respawn after death | |
Total Size: | 2 bytes |
Encryption Key Response (0xFC)
Two-Way
See Protocol Encryption for information on this packet.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0xFC | Shared secret length | short | ||
Shared secret | byte array | |||
Verify token length | short | |||
Verify token response | byte array | |||
Total Size: | 5 bytes + length of shared secret + length of token |
Encryption Key Request (0xFD)
Server to client
See Protocol Encryption for information on this packet.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0xFD | Server id | string | ||
Public key length | short | |||
Public key | byte array | |||
Verify token length | short | |||
Verify token | byte array | |||
Total Size: | 7 bytes + length of string + length of key + length of token |
Named Sound Effect (0x3E)
Server to client
Used to play a sound effect on the client.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x3E | Sound name | string | step.grass | 250 |
Effect position X | int | 250 | effect X multiplied by 8 | |
Effect position Y | int | 250 | effect Y multiplied with 8 | |
Effect position Z | int | 250 | effect Z multiplied with 8 | |
Volume | float | 9 | 1 is 100%, can be more | |
Pitch | byte | 1 | 63 is 100%, can be more | |
Total Size: | 20 bytes + length of string |
Block Break Animation (0x37)
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x37 | EID? | int | Entity breaking the block? | |
X | int | Block position | ||
Y | int | |||
Z | int | |||
Destroy Stage | byte | 1 | How far destroyed this block is. | |
Total Size: | 18 bytes |
Changed Data Type
Slot Data
Parsing or encoding of Slot Data no longer requires a list of all enchantable item IDs. Every slot transmitted now includes a short that indicates the length of the NBT data. As before, a length of -1 means there is no NBT data.
This change affects any packets with Slot Data, including:
- 0x0F (Player Block Placement)
- 0x10 (Held Item Change)
- 0x66 (Click Window)
- 0x67 (Set Slot)
- 0x68 (Set Window Items)
- 0x6B (Creative Inventory Action)
- 0x05 (Entity Equipment)
Changed packets
Login Request (0x01)
Server to Client
See Protocol Encryption for information on logging in.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x01 | Entity ID | int | 1298
|
The Players Entity ID |
Level Type | string | default | default or SUPERFLAT; level-type in server.properties | |
Server mode | byte | 0
|
0 for survival, 1 for creative | |
Dimension | byte | 0
|
-1 : The Nether, 0 : The Overworld, 1 : The End
| |
Difficulty | byte | 1
|
0 thru 3 for Peaceful, Easy, Normal, Hard
| |
Not used | unsigned byte | 0
|
Only 0 observed from vanilla server, was previously world height | |
Max players | unsigned byte | 8
|
Used by the client to draw the player list | |
Total Size: | 12 bytes + length of strings |
Handshake (0x02)
Client to server
See Protocol Encryption for information on logging in.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x02 | Protocol Version | byte | 38
|
|
Username | string | TkTech
|
The username of the player attempting to connect | |
Server Host | string | localhost
|
||
Server Port | int | 25565
|
||
Total Size: | 10 bytes + length of strings |
Entity Equipment (0x05)
Server to Client
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x05 | Entity ID | int | 0x00010643 | Named Entity ID |
Slot | short | 4 | Equipment slot: 0=held, 1-4=armor slot | |
Item | slot | Item in slot format | ||
Total Size: | 11 bytes |
Respawn (0x09)
Server to Client
To change the player's dimension (overworld/nether/end), send them a respawn packet with the appropriate dimension, followed by prechunks/chunks for the new dimension, and finally a position and look packet. You do not need to unload chunks, the client will do it automatically.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x09 | Dimension | int | 1
|
-1 : The Nether, 0 : The Overworld, 1 : The End
|
Difficulty | byte | 1
|
0 thru 3 for Peaceful, Easy, Normal, Hard. 1 is always sent c->s
| |
Creative mode | byte | 1
|
0 for survival, 1 for creative.
| |
World height | short | 256
|
Defaults to 256
| |
Level Type | string | default | See 0x01 login | |
Total Size: | 11 bytes + length of string |
Player Block Placement (0x0F)
Client to Server
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x0F | X | int | 32
|
Block position |
Y | unsigned byte | 64
|
Block position | |
Z | int | 32
|
Block position | |
Direction | byte | 3
|
The offset to use for block/item placement (see below) | |
Held item | slot | |||
Cursor position X | byte | 0 - 16 | The position of the crosshair on the block | |
Cursor position Y | byte | 0 - 16 | ||
Cursor position Z | byte | 0 - 16 | ||
Total Size: | 11 bytes + slot data |
Spawn Named Entity (0x14)
Server to Client
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x14 | EID | int | 94453
|
Player ID |
Player Name | string | Twdtwd
|
Max length of 16 | |
X | int | 784
|
Player X as Absolute Integer | |
Y | int | 2131
|
Player Y as Absolute Integer | |
Z | int | -752
|
Player Z as Absolute Integer | |
Yaw | byte | 0
|
Player rotation as a packed byte | |
Pitch | byte | 0
|
Player rotation as a packed byte | |
Current Item | short | 0
|
The item the player is currently holding. Note that this should be 0 for "no item", unlike -1 used in other packets. A negative value crashes clients. | |
Metadata | Metadata | 127
|
||
Total Size: | 22 bytes + length of strings + metadata (at least 1) |
Spawn Object/Vehicle (0x17)
Server to Client
Sent by the server when an Object/Vehicle is created. The throwers entity id is now used for fishing floats too.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x17 | EID | int | 62
|
Entity ID of the Object |
Type | byte | 11
|
The type of object (see Entities#Objects) | |
X | int | 16080
|
The Absolute Integer X Position of the object | |
Y | int | 2299
|
The Absolute Integer Y Position of the object | |
Z | int | 592
|
The Absolute Integer Z Position of the object | |
thrower's entity ID | int | 0
|
If this is bigger than 0, this is a entity trown by a other entity and the next 3 fields are sent. | |
Speed X | short | 0
|
Not sent if the thrower entity ID is 0. The speed of this entity along the X axis. | |
Speed Y | short | 0
|
Not sent if the thrower entity ID is 0. The speed of this entity along the Y axis. | |
Speed Z | short | 0
|
Not sent if the thrower entity ID is 0. The speed of this entity along the Z axis. | |
Total Size: | 22 or 28 bytes |
Spawn Mob (0x18)
Server to Client
Sent by the server when a Mob Entity is Spawned
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x18 | EID | int | 446
|
Entity ID |
Type | byte | 91
|
The type of mob. See Entities#Mobs | |
X | int | 13366
|
The Absolute Integer X Position of the object | |
Y | int | 2176
|
The Absolute Integer Y Position of the object | |
Z | int | 1680
|
The Absolute Integer Z Position of the object | |
Yaw | byte | -27
|
The yaw in steps of 2p/256 | |
Pitch | byte | 0
|
The pitch in steps of 2p/256 | |
Head Yaw | byte | Head yaw in steps of 2p/256 | ||
Velocity Z | short | 0
|
||
Velocity X | short | 0
|
||
Velocity Y | short | 0
|
||
Metadata | Metadata | 127
|
Varies by mob, see Entities | |
Total Size: | 27 bytes + Metadata (at least 1) |
Destroy Entity (0x1D)
Server to Client
Sent by the server when an list of Entities is to be destroyed on the client.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x1D | Entity Count | byte | 3
|
The amount of entities which should be destroyed |
Entity IDs | array of int | 452, 546, 123
|
The list of entity ids which should be destroyed | |
Total Size: | 2 + (entity count * 4) bytes |
Chunk Data (0x33)
Server to Client
See also: Map Format
Chunks are sent a column at a time, with some sections optionally missing from each packet (those consisting only of air).
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x33 | X | int | Chunk X Coordinate (*16 to get true X) | |
Z | int | Chunk Z Coordinate (*16 to get true Z) | ||
Ground-up continuous | boolean | This is True if the packet represents all sections in this vertical column, where the primary bit map specifies exactly which sections are included, and which are air. | ||
Primary bit map | unsigned short | 15 | Bitmask with 1 for every 16x16x16 section which data follows in the compressed data. | |
Add bit map | unsigned short | 0 | Same as above, but this is used exclusively for the 'add' portion of the payload | |
Compressed size | int | Size of compressed chunk data. | ||
Compressed data | unsigned byte array | …
|
The chunk data is compressed using ZLib Deflate function. | |
Total Size: | 22 bytes + Compressed chunk size |
Block Change (0x35)
Server to Client
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x35 | X | int | 502
|
Block X Coordinate |
Y | byte | 71
|
Block Y Coordinate | |
Z | int | 18
|
Block Z Coordinate | |
Block Type | short | 78
|
The new block type for the block | |
Block Metadata | byte | 0
|
The new Metadata for the block | |
Total Size: | 13 bytes |
Block Action (0x36)
Server to Client
This packet is used for a number of things:
- Chests opening and closing
- Pistons pushing and pulling
- Note blocks playing
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x36 | X | int | 502
|
Block X Coordinate |
Y | short | 71
|
Block Y Coordinate | |
Z | int | 18
|
Block Z Coordinate | |
Byte 1 | byte | 3
|
Varies depending on block - see below | |
Byte 2 | byte | 17
|
Varies depending on block - see below | |
Block ID | short | 29
|
The block id this action is set for | |
Total Size: | 14 bytes |
See Also: Block Actions
Update Tile Entity (0x84)
Server to Client
Essentially a block update on a tile entity.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x84 | X | int | ||
Y | short | |||
Z | int | |||
Action | byte | The type of update to perform | ||
Data length | Short | Varies | ||
NBT Data | Byte Array - Present if data length > 0 | Varies | ||
Total Size: | 12 + itemstack bytes |
Actions
- 1: Set mob displayed inside a mob spawner. Custom 1 contains the mob type
Explosion (0x3C)
Server to Client
Sent when an explosion occurs (creepers, TNT, and ghast fireballs).
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x3C | X | double | ||
Y | double | |||
Z | double | |||
Radius | float | 3.0 | Currently unused in the client | |
Record count | int | This is the count, not the size. The size is 3 times this value. | ||
Records | (byte, byte, byte) × count | Each record is 3 bytes, which seem to be XYZ offsets of affected blocks. | ||
Unknown | float | |||
Unknown | float | |||
Unknown | float | |||
Total Size: | 45 bytes + 3*(Record count) bytes |
Player Abilities (0xCA)
This packet has now been compressed into 3 bytes. The latter 2 bytes are used to indicate the walking and flying sppeds respectively, while the first byte is used to determine the value of 4 booleans.
These booleans are whether damage is disabled (god mode), whether the player is flying, whether the player can fly, and whether the player is in creative mode.
To get the values of these booleans, simply AND (&) the byte with 1,2,4 and 8 respectively, to get the 0 or 1 bitwise value. To set them OR (|) them with their repspective masks.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0xCA | Flags | byte | 5 | |
Flying speed | byte | 12 | ||
Walking speed | byte | 25 | ||
Total Size: | 4 bytes |
Removed packets
Chunk Allocation Packet (0x32)
The chunk Allocation Packet is not longer in use. Memory will automatically allocated with a incoming Map Chunk packet. To deallocate memory you need to send a MapChunk packet, which only contains biome data for plains(all biome bytes set to 1). So the Add and Primary bitmap must set to 0, and Ground-up continuous to true. Because the payload of this packet is compressed and static you can use a hardcoded value for it, so you don't need to compress it each time.
This is the payload which is used in the Compressed Data part to deallocate a chunk column:
0x78, 0x9C, 0x63, 0x64, 0x1C, 0xD9, 0x00, 0x00, 0x81, 0x80, 0x01, 0x01
Protocol History
2012-07-24
- 12w30c
- Protocol version 39
- Changed packets 0x84
2012-07-23
- 12w30a
- Protocol version is still 38
- Changed packets 0x14 and 0x35
2012-07-05
- 12w27a
- Protocol version is now 38
- Added packet 0x38
2012-06-21
- 12w25a
- Packet 0xFC and 0xFD include a 4 byte long byte array. This is hashed with the public RSA key and sent back. See Protocol Encryption for further info.
- Packet 0x3E changed to include float rather than byte.
2012-06-14
- 12w24a
- Protocol version is now 36
- Changed Packet 0x01(Login Request), only used as Login Reply
- New Packet 0xCD used for Login Request and Respawn (1 byte payload)
- All items (except the empty hand) now send enchantment data
2012-06-07
- 12w23b
- Protocol version is now 35
- Change packet: Player Block Placement
- New Packet: Block breaking animation
2012-05-24
- 12w21a
- No packet changes but the algorithm was changed to AES128 with the shared key as the IV, will be described in Protocol Encryption
2012-05-10
- 12w19a
- No packet changes, but an other encryption algorythm is used, described in Protocol Encryption
- The items which are not enchantable in 12w18a are now readded
- Fishing floats, spawned by a 0x17 packet do now use the extra fields
2012-05-03
- 12w18a
- Protocol version is now 32
- New packet: 0x3E Name Sound Effect
- Changed packet: 0x01 Login Request
- Changed packet: 0x02 Handshake
- Changed packet: 0xCA Player Abilities
- Changed packet: 0xCC Locale and View Distance
- Changed packet: 0x09 Respawn
- Removed packet: 0x32 Map Column Allocation
- This items are not enchantable in this version: 0x103, 0x105, 0x15A, 0x167, 0x10C, 0x10D, 0x10E, 0x10F, 0x122, 0x110, 0x111, 0x112, 0x113, 0x123, 0x10B, 0x100, 0x101, 0x102, 0x124, 0x114, 0x115, 0x116, 0x117, 0x125, 0x11B, 0x11C, 0x11D, 0x11E, 0x126
2012-04-26
- 12w17a
- Protocol version is now 31
- RC4 based encryption, described in Protocol Encryption
- Changed packet: 0x01 Login Request
- Changed packet: 0x02 Handshake
- Changed packet: 0xCC Locale and View Distance
- Changed packet: 0xCA Player Abilities
- New packet: 0xFC Encryption Key Response
- New packet: 0xFD Encryption Key Request
- New Item: Book & Quills (0x182) is enchantable
- New Item: Written Book (0x183) is enchantable
2012-04-19
- 12w16a
- Protocol version is now 30
- New packet: 0xCB Tab-complete
- New packet: 0xCC Locale and View Distance