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

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