Pre-release protocol

This page documents the changes from the last stable Minecraft release (currently 1.3.2) to the current pre-release (or weekly release).

New packets

-None-

Changed packets

Time Update (0x04)

Server to Client

Time is based on ticks, where 20 ticks happen every second. There are 24000 ticks in a day, making Minecraft days exactly 20 minutes long.

The time of day is based on the timestamp modulo 24000. 0 is sunrise, 6000 is noon, 12000 is sunset, and 18000 is midnight.

The default SMP server increments both by 20 every second.

The 'Time' is the Age of the world. It is not changing on server commands and will increased by 20 every second.

Packet ID	Field Name	Field Type	Example	Notes
0x04	Time	long	45464654	The 'Age of the world', in ticks
	Day Time	long	21321	The world (or region) time, in ticks
Total Size:	17 Bytes

Spawn Named Entity (0x14)

See the change in metadata below. (Under Protocol History, 2012-08-24)

Spawn Dropped Item (0x15)

TODO

It includes a new byte array after the "Damage" field, and before the "X" field if certain conditions are met. If the array does not exist, then the length of the array is "-1".

Spawn Mob (0x18)

See the change in metadata below. (Under Protocol History, 2012-08-24)

Entity Metadata (0x28)

See the change in metadata below. (Under Protocol History, 2012-08-24)

Sound Or Particle Effect (0x3D)

Server to Client

Sent when a client is to play a sound or particle effect.

Packet ID	Field Name	Field Type	Example	Notes
0x3D	Effect ID	int	1003	The ID of the effect, see below.
	X	int		The X location of the effect.
	Y	byte		The Y location of the effect.
	Z	int		The Z location of the effect.
	Data	int	0	Extra data for certain effects, see below.
	No Volume Decrease	boolean	false	If true the volume of the soundeffect will not spawn at the position specified in this packet. it will spawn 2 blocks away from the player, but in the right direction. In vanilla, this is only implemented for sound effect 1013 (mob.wither.spawn). If the packet is sent with an other id it will be ignored.
Total Size:	18 bytes

Click Window (0x66)

Client to Server

This packet is sent by the player when it clicks on a slot in a window.

Packet ID	Field Name	Field Type	Example	Notes
0x66	Window id	byte	0	The id of the window which was clicked. 0 for player inventory.
	Slot	short	36	The clicked slot. See below.
	Right-click	byte	1
	Action number	short	12	A unique number for the action, used for transaction handling (See the Transaction packet).
	Shift	byte	0	This is 1 if the user was holding keyboard shift when they clicked. See below.
	Clicked item	slot
Total Size:	9 bytes + slot data

When the user middle-clicks a slot, "shift" is 2 and "right click" is 3. The vanilla software treats a middle click as if no click occurred in the first place.

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
	Show Cape	boolean	true	Client-side "show cape" option
Total Size:	9 bytes + length of string

Server List Ping (0xFE)

Client to Server

Packet ID	Field Name	Field Type	Example	Notes
0xFE	Magic Number	byte	1	always 1
Total Size:	2 bytes

To load server info in the multiplayer menu, the notchian client connects to each known server and sends an 0xFE.

In return, the server sends a kick (0xFF), with its string containing §1 and data (server protocol version, server version string, server description, number of users, number of slots), delimited by a 0(0x00).

Note that as this is the last packet you'll see, you can get away with just chopping off the first three bytes (the ident and the string length) and decoding the remainder as a UCS-2 string.

The server severs the socket connection after sending the kick (0xFF) packet. You will need to open a new socket to continue communicating.

If the number of available slots sent is equal to or less than 0, the client should display it as "???".

This would be an example for such a kick message:

§1\047\012w42b\0Wiki.vg Minecraft Server\05\010 (protocol version 47, minecraft version 12w42b, motd 'Wiki.vg Minecraft Server', 5 users, 10 slots)

Note that '\0' is a 0x0000.

The client will show a notice with the server version string if the server protocol version is not equal to the client version.

The official client and server are backward compatible and can read and write the old format too.

Entity Metadata Format

Note that entity metadata is a totally distinct concept from block metadata.

The entity metadata format is quirky dictionary format, where the key and the value's type are packed in a single byte.

To parse, repeat the following procedure:

1. Read an unsigned byte
2. If this byte == 127, stop reading
3. Decompose the byte.
   The bottom 5 bits (0x1F) serve as an identifier (key) for the data to follow.
   The top 3 bits (0xE0) serve as a type.
4. Read and unpack based on the type (below)

Type	Meaning
0	byte
1	short
2	int
3	float
4	string16
5	short, byte, short (slot type) - If first short is less than 0, no further data is sent.
6	int, int, int (x, y, z)

In Python-like code:

#socket is positioned at the beginning of the metadata array. Also note that the method unpack() doesn't exist in socket
metadata = {}
x = socket.unpack('byte')
while x != 127:
    index = x & 0x1F # Lower 5 bits
    ty    = x >> 5   # Upper 3 bits
    if ty == 0: val = socket.unpack('byte') 
    if ty == 1: val = socket.unpack('short') 
    if ty == 2: val = socket.unpack('int') 
    if ty == 3: val = socket.unpack('float') 
    if ty == 4: val = socket.unpack('string16')
    if ty == 5:
        val = {}
        val["id"] = socket.unpack('short')
        if val["id"] != -1:
            val["count"]  = socket.unpack('byte')
            val["damage"] = socket.unpack('short')
    if ty == 6:
        val = []
        for i in range(3):
            val.append(socket.unpack('int'))
    metadata[index] = (ty, val)
    x = socket.unpack('byte')
return metadata

Removed packets

-None-

Protocol History

2012-10-11

• 12w41a
• Protocol version is now 46
• 0xcc Changed to include boolean 'show cape' field.
• Spawn named entity metadata includes an int at index 16, 1 = show cape, 0 = don't show cape

2012-10-04

• 12w40a
• Protocol version is now 45
• Packet 0x66 changed

2012-09-06

• 12w36a
• Protocol version is now 42

2012-08-24

• 12w34b
• Protocol version is now 41

• Changed Entity Metadata Format

2012-08-09

• 12w32a
• Protocol version is now 40

• Changed Time Update packet