Pre-release protocol
This page documents the changes from the last stable Minecraft release (currently 1.1) to the current pre-release
New packets
Entity Head Look (0x23)
Changes the direction an entity's head is facing.
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x23 | Entity ID | int | ||
Head Yaw | byte | Head yaw in steps of 2π/256 | ||
Total Size: | 6 bytes |
Update Tile Entity (0x84)
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 | ||
Custom 1 | int | Varies | ||
Custom 2 | int | Varies | ||
Custom 3 | int | Varies | ||
Total Size: | 24 bytes |
Actions
- 1: Set mob displayed inside a mob spawner. Custom 1 contains the mob type
Changed packets
Login Request (0x01)
World height field is no longer used, always 0.
Map seed field removed
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x01 | Entity ID | int | 1298
|
The Players Entity ID |
Not used | string | (empty string) | Not used | |
Level Type | string | default | default or SUPERFLAT; level-type in server.properties | |
Server mode | int | 0
|
0 for survival, 1 for creative | |
Dimension | int | 0
|
-1 : The Nether, 0 : The Overworld, 1 : The End
| |
Difficulty | byte | 1
|
0 thru 3 for Peaceful, Easy, Normal, Hard
| |
World height | byte | 0
|
Probably not used anymore since Map Chunk is hardcoded to 256 blocks. | |
Max players | unsigned byte | 8
|
Used by the client to draw the player list | |
Total Size: | 19 bytes + length of strings |
Handshake (0x02)
Client to Server
The hostname and port were added to this packet, most likely to allow virtual hosting .(sample implementation)
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x02 | UsernameAndHost | string | TkTech;localhost:25565
|
The username of the player attempting to connect, and the host he is connecting to, seperated by a semicolon. |
Total Size: | 3 bytes + length of strings |
Respawn (0x09)
Dimension is now an int, slightly bizarrely. I wonder if they intended to make world_height an int, in line with 0x01 login?
Map seed field removed
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 | 128
|
Defaults to 128
| |
Level Type | string | DEFAULT | See 0x01 login | |
Total Size: | 11 bytes + length of string |
Mob Spawn (0x18)
New byte field: head yaw
This needs confirmation!
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 2π/256 | |
Pitch | byte | 0
|
The pitch in steps of 2π/256 | |
Head Yaw | byte | Head yaw in steps of 2π/256 | ||
Metadata | Metadata | 127
|
Varies by mob, see Entities | |
Total Size: | 21 bytes + Metadata (at least 1) |
Map Chunk (0x33)
This is currently a best guess
Here's a packet capture: https://gist.github.com/1835702
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 contiguous | boolean | This is True if the chunks consists of a contiguous column of non-air (i.e., indicated with a '1' in the bitmask) chunks starting at Y=0, followed by any number of unsent chunks containing only air. | ||
Primary bit map | short | 15 | Bitmask with 1 for every 16x16x16 chunk which data follows in the compressed data. | |
Add bit map | short | 0 | Same as above, but this is used exclusively for the 'add' portion of the payload | |
Compressed size | int | Size of compressed region data. | ||
Unused int | int | 0 | Doesn't seem to be used by the client. Always 0. I expect this is Mod API stuff. | |
Compressed data | unsigned byte array | …
|
The region data is compressed using ZLib Deflate function. | |
Total Size: | 22 bytes + Compressed chunk size |
The payload is a set of 16x16x16 chunks, sharing the same X and Z chunk coordinates. What is and isn't sent is provided by the two bitmask fields. The least significant bit is '1' if the chunk spanning from Y=0 to Y=15 is not completely air, and so forth. For block IDs, metadata, and lighting, the primary bitmask is used. A secondary bitmask is used for 'add' data, which is mojang's means of provided Block IDs past 256. In vanilla minecraft, you can expect this to always be zero.
The data is compressed using the deflate() function in zlib. After uncompressing, the data consists of five (or six) sequential sections, in order:
- Block type array (1 byte per block, 4096 bytes per chunk)
- Block metadata array (half byte per block, 2048 bytes per chunk)
- Block light array (half byte per block, 2048 bytes per chunk)
- Sky light array (half byte per block, 2048 bytes per chunk)
- Add array (half byte per block, 2048 bytes per chunk, uses second bitmask)
- Biome array (1 byte per XZ column, 256 bytes total, only sent if 'ground up contiguous' is true)
In each section except biome data, your loop should look something like this:
//Loop over 16x16x16 chunks in the 16x256x16 column
for (i=0;i<16;i++) {
//If the bitmask indicates this chunk has been sent...
if (bitmask & 1 << i) {
//Read data...
cubic_chunk_data = io.read(4096); //2048 for the other arrays, where you'll need to split the data
for(int j=0; j<len(cubic_chunk_data); j++) {
//Retrieve x,y,z and data from each element in cubic_chunk_array
//Byte arrays
x = chunk_x*16 + (j & 0xF0) >> 4;
y = i*16 + j & 0x0F;
z = chunk_z*16 + j >> 8;
data = cubic_chunk_data[j]
//Nibble arrays
data1 = cubic_chunk_data[j] & 0x0F;
data2 = cubic_chunk_data[j] >> 4;
k = 2*j;
x1 = chunk_x*16 + (k & 0xF0) >> 4;
y1 = i*16 + k & 0x0F;
z1 = chunk_z*16 + k >> 8;
k++;
x2 = chunk_x*16 + (k & 0xF0) >> 4;
y2 = i*16 + k & 0x0F;
z2 = chunk_z*16 + k >> 8;
}
}
}
Each biome byte can have the values from 0 to 22, higher will cause the client to crash.
The 'add' array uses the second bitmask. Block IDs are presumed to be block_id | add << 8
Multi Block Change (0x34)
Like 0x33, this follows a new format. Arrays are now interlaced rather than sequential!
Packet ID | Field Name | Field Type | Example | Notes |
---|---|---|---|---|
0x34 | Chunk X | int | -9
|
Chunk X Coordinate |
Chunk Z | int | 12
|
Chunk Z Coordinate | |
Record count | short | The number of blocks affected | ||
Data size | int | The total size of the data, in bytes. Should always be 4*record count - please confirm. | ||
Data | …
|
Coordinates, type, and metadata of blocks to change. | ||
Total Size: | 15 bytes + Arrays |
Each record is four bytes.
Bit mask | Width | Meaning |
---|---|---|
00 00 00 0F | 4 bits | Block metadata |
00 00 FF F0 | 12 bits | Block ID |
00 FF 00 00 | 8 bits | Y co-ordinate |
0F 00 00 00 | 4 bits | Z co-ordinate, relative to chunk |
F0 00 00 00 | 4 bits | X co-ordinate, relative to chunk |
Protocol History
2012-02-23
- 12w08a
- Protocol version is now 28
- Updated packets: 0x01, 0x09, 0x34
2012-02-15
- 12w07a
- Protocol version is now 27
- Updated packets: 0x01, 0x09, 0x33
2012-02-09
- 12w06a
- Protocol version is now 25
- New packet: 0x84
2012-01-26
- 12w04a
- Protocol version has not been changed
- Handshake Packet by client (0x02) now contains the server host and port
- Window Open Packet (0x64): WindowTitle is now longer than accepted by older clients. Contains a keyword such as "container.furnace"
2012-01-19
- 12w03a
- Protocol version is now 24
- New packet: 0x23
- MobSpawn: new field, 1 byte inserted before metadata.