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

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, 2: 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	63 is 100%, can be more
	Pitch	byte	63	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
	Unknown	byte	1	?
Total Size:	4 bytes

Changed packets

Login Request (0x01)

Two-Way

See Protocol Encryption for information on logging in.

Client to Server

Just 1 byte C->S

Packet ID
0x01

Server to Client

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

Two-Way

Sent by the client when the player presses the "Respawn" button after dying. The server then teleports the user to the spawn point, and sends a respawn packet in response. The client will not leave the respawn screen until it receives a respawn packet.

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.

Client to Server

Packet ID
0x09

Server to Client

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

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

Player Abilities (0xCA)

This packet changed with 12w17a. It now contains 3 booleans but the values of these 3 booleans are not currently known.

Packet ID	Field Name	Field Type	Example	Notes
0xCA	Flags	byte	5
	Walking speed	byte	12
	Flying speed	byte	25
	Total Size:	4 bytes

Player Block Placement (0x0F)

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
	Unknown	byte	0 - 0x0B (or more)	?
	Unknown	byte	0 - 0x10	?
	Unknown	byte	0 - 0x10	?
Total Size:	11 bytes + slot data

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 encrypted and static you can use a hardcoded value for it, so you don't need to encrypt 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-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: 0x3D 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