Pre-release protocol

This page documents the changes from the last stable Minecraft release (currently 1.11.2, protocol 316) to the current pre-release (currently 17w14a, protocol 320). Note that this page contains bleeding-edge information that may not be completely or correctly documented.

One who wishes to commandeer the merging of this into Protocol when an update is made must be sure to respect any changes that may have occurred to the respective packets there.

Contents

Data types

No changes so far.

Packets

ID	Packet name	Documentation
Handshaking serverbound
0x00	Handshake	Current	Pre
Play clientbound
0x08	Advancements		Pre
0x08 0x09	Block Break Animation	Current	(unchanged)
0x09 0x0A	Update Block Entity	Current	(unchanged)
0x0A 0x0B	Block Action	Current	(unchanged)
0x0B 0x0C	Block Change	Current	(unchanged)
0x0C 0x0D	Boss Bar	Current	(unchanged)
0x0D 0x0E	Server Difficulty	Current	(unchanged)
0x0E 0x0F	Tab-Complete (clientbound)	Current	(unchanged)
0x0F 0x10	Chat Message (clientbound)	Current	(unchanged)
0x10 0x11	Multi Block Change	Current	(unchanged)
0x11 0x12	Confirm Transation (clientbound)	Current	(unchanged)
0x12 0x13	Close Window (clientbound)	Current	(unchanged)
0x13 0x14	Open Window	Current	(unchanged)
0x14 0x15	Window Items	Current	(unchanged)
0x15 0x16	Window Property	Current	(unchanged)
0x16 0x17	Set Slot	Current	(unchanged)
0x17 0x18	Set Cooldown	Current	(unchanged)
0x18 0x19	Plugin Message (clientbound)	Current	(unchanged)
0x19 0x1A	Named Sound Effect	Current	(unchanged)
0x1A 0x1B	Disconnect (play)	Current	(unchanged)
0x1B 0x1C	Entity Status	Current	(unchanged)
0x1C 0x1D	Explosion	Current	(unchanged)
0x1D 0x1E	Unload Chunk	Current	(unchanged)
0x1E 0x1F	Change Game State	Current	(unchanged)
0x1F 0x20	Keep Alive (clientbound)	Current	(unchanged)
0x20 0x21	Chunk Data	Current	(unchanged)
0x21 0x22	Effect	Current	(unchanged)
0x22 0x23	Particle	Current	(unchanged)
0x23 0x24	Join Game	Current	(unchanged)
0x24 0x25	Particle	Current	(unchanged)
0x25 0x26	Entity Relative Move	Current	(unchanged)
0x26 0x27	Entity Look And Relative Move	Current	(unchanged)
0x27 0x28	Entity Look	Current	(unchanged)
0x28 0x29	Entity	Current	(unchanged)
0x29 0x2A	Vehicle Move (clientbound)	Current	(unchanged)
0x2A 0x2B	Open Sign Editor	Current	(unchanged)
0x2B 0x2C	Player Abilities (clientbound)	Current	(unchanged)
0x2C 0x2D	Combat Event	Current	(unchanged)
0x2D 0x2E	Player List Item	Current	(unchanged)
0x2E 0x2F	Player Position And Look (clientbound)	Current	(unchanged)
0x2F 0x30	Use Bed	Current	(unchanged)
0x31	Unlock Recipes		Pre
0x30 0x32	Destroy Entities	Current	(unchanged)
0x31 0x33	Remove Entity Effect	Current	(unchanged)
0x32 0x34	Resource Pack Send	Current	(unchanged)
0x33 0x35	Respawn	Current	(unchanged)
0x34 0x36	Entity Head Look	Current	(unchanged)
0x35 0x37	World Border	Current	(unchanged)
0x36 0x38	Camera	Current	(unchanged)
0x37 0x39	Held Item Change (clientbound)	Current	(unchanged)
0x38 0x3A	Display Scoreboard	Current	(unchanged)
0x39 0x3B	Entity Metadata	Current	(unchanged)
0x3A 0x3C	Attach Entity	Current	(unchanged)
0x3B 0x3D	Entity Velocity	Current	(unchanged)
0x3C 0x3E	Entity Equipment	Current	(unchanged)
0x3D 0x3F	Set Experience	Current	(unchanged)
0x3E 0x40	Update Health	Current	(unchanged)
0x3F 0x41	Scoreboard Objective	Current	(unchanged)
0x40 0x42	Set Passengers	Current	(unchanged)
0x41 0x43	Teams	Current	(unchanged)
0x42 0x44	Update Score	Current	(unchanged)
0x43 0x45	Spawn Position	Current	(unchanged)
0x44 0x46	Time Update	Current	(unchanged)
0x45 0x47	Title	Current	(unchanged)
0x46 0x48	Sound Effect	Current	(unchanged)
0x47 0x49	Player List Header And Footer	Current	(unchanged)
0x48 0x4A	Collect Item	Current	(unchanged)
0x49 0x4B	Entity Teleport	Current	(unchanged)
0x4A 0x4C	Entity Properties	Current	(unchanged)
0x4B 0x4D	Entity Effect	Current	(unchanged)
Play serverbound
0x01	Unknown		Pre
0x01 0x02	Tab-Complete (serverbound)	Current	(unchanged)
0x02 0x03	Chat Message (serverbound)	Current	(unchanged)
0x03 0x04	Client Status	Current	(unchanged)
0x04 0x05	Client Settings	Current	(unchanged)
0x05 0x06	Confirm Transaction (serverbound)	Current	(unchanged)
0x06 0x07	Enchant Item	Current	(unchanged)
0x07 0x08	Click Window	Current	(unchanged)
0x08 0x09	Close Window (serverbound)	Current	(unchanged)
0x09 0x0A	Plugin Message (serverbound)	Current	(unchanged)
0x0A 0x0B	Use Entity	Current	(unchanged)
0x0B 0x0C	Keep Alive (serverbound)	Current	(unchanged)
0x0C 0x0D	Player Position	Current	(unchanged)
0x0D 0x0E	Player Position And Look (serverbound)	Current	(unchanged)
0x0E 0x0F	Player Look	Current	(unchanged)
0x0F 0x10	Player	Current	(unchanged)
0x10 0x11	Vehicle Move (serverbound)	Current	(unchanged)
0x11 0x12	Steer Boat	Current	(unchanged)
0x12 0x13	Player Abilities (serverbound)	Current	(unchanged)
0x13 0x14	Player Digging	Current	(unchanged)
0x14 0x15	Entity Action	Current	(unchanged)
0x15 0x16	Steer Vehicle	Current	(unchanged)
0x17	Recipe Displayed		Pre
0x16 0x18	Resource Pack Status	Current	(unchanged)
0x17 0x19	Held Item Change (serverbound)	Current	(unchanged)
0x18 0x1A	Creative Inventory Action	Current	(unchanged)
0x19 0x1B	Update Sign	Current	(unchanged)
0x1A 0x1C	Animation (serverbound)	Current	(unchanged)
0x1B 0x1D	Spectate	Current	(unchanged)
0x1C 0x1E	Player Block Placement	Current	(unchanged)
0x1D 0x1F	Use Item	Current	(unchanged)

New/modified data types

Entity Metadata

Note that entity metadata is a totally distinct concept from block metadata. It is not required to send all metadata fields, or even any metadata fields, so long as the terminating entry is correctly sent.

Entity Metadata is an array of entries, each of which looks like the following:

Name	Type	Meaning
Index	Unsigned Byte	Unique index key determining the meaning of the following value, see the table below. If this is 0xff then the it is the end of the Entity Metadata array and no more is read.
Type	Optional Byte Enum	Only if Index is not 0xff; the type of the index, see the table below
Value	Optional value of Type	Only if Index is not 0xff: the value of the metadata field

Value of Type field	Type of Value field	Notes
0	Byte
1	VarInt
2	Float
3	String
4	Chat
5	Slot
6	Boolean
7	Rotation	3 floats: rotation on x, rotation on y, rotation on z
8	Position
9	OptPosition (Boolean + Optional Position)	Position is present if the Boolean is set to true
10	Direction (VarInt)	(Down = 0, Up = 1, North = 2, South = 3, West = 4, East = 5)
11	OptUUID (Boolean + Optional UUID)	UUID is present if the Boolean is set to true
12	OptBlockID (VarInt)	0 for absent otherwise, id << 4 | data
13	NBT Tag

Entity classes also recursively inherit fields from classes they extend.

Parrot

Extends TameableAnimal.

Index	Type	Meaning		Default
15	VarInt	Variant (0: red/blue, 1: blue, 2: green, 3: yellow/blue, 4: silver)		0

Player

Extends Living.

Index	Type	Meaning		Default
11	Float	Additional Hearts		0.0
12	VarInt	Score		0
13	Byte	The Displayed Skin Parts bit mask that is sent in Client Settings		0
		Bit mask	Meaning
		0x01	Cape enabled
		0x02	Jacket enabled
		0x04	Left sleeve enabled
		0x08	Right sleeve enabled
		0x10	Left pants leg enabled
		0x20	Right pants leg enabled
		0x40	Hat enabled
		0x80	Unused
14	Byte	Main hand (0 : Left, 1 : Right)		1
15	NBT Tag	Left shoulder entity data
16	NBT Tag	Right shoulder entity data

Block Actions

No changes so far.

Plugin Channels

No changes so far.

Play

Clientbound

Advancements

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x08	Play	Client	Reset/Clear		Boolean		Whether to reset/clear the current advancements
			Mapping size		VarInt		Size of the following array
			Advancement mapping	Key	Array	Identifier	The identifier of the advancement
				Value		Advancement	See below
			List size		VarInt		Size of the following array
			Identifiers		Array of Identifier		The identifiers of the advancements that should be removed
			Progress size		VarInt		Size of the following array
			Progress mapping	Key	Array	Identifier	The identifier of the advancement
				Value		Advancement progress	See below

Advancement structure:

Field Name		Field Type		Notes
Has parent		Boolean		Indicates whether the next field exists. INVALID (Is only written, not read.)
Parent id		Optional Identifier		The identifier of the parent advancement.
Has display		Boolean		Indicates whether the next field exists
Display data		Optional advancement display		See below.
Number of criteria		VarInt		Size of the following array
Criteria	Key	Array	Identifier	The identifier of the criterion
	Value		Void	There is no content written here. Perhaps this will be expanded in the future?
Array length		VarInt		Number of arrays in the following array
Requirements	Array length 2	Array	VarInt	Number of elements in the following array
	Requirement		Array of String	Array of required criteria

Advancement display:

Field Name	Field Type	Notes
Title	Chat
Icon	VarInt	Advancement icon item id. 0 indicates null
Frame type	VarInt enum	0 = TASK, 1 = CHALLENGE
Has background	Boolean	Indicates whether the next field exists
Background texture	Optional Identifier	Background texture location
X coord	VarInt
Y coord	VarInt

Advancement progress:

Field Name		Field Type		Notes
Size		VarInt		Size of the following array
Criteria	Criterion identifier	Array	Identifier	The identifier of the criterion.
	Criterion progress		Criterion progress

Criterion progress:

Field Name	Field Type	Notes
Achieved	Boolean	If true, next field is present
Date of acheiving	Optional Long	As returned by Date.getTime

Unlock Recipes

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x31	Play	Client
			Unknown Flag 1		Boolean
			Unknown Flag 2		Boolean
			Unknown Flag 3		Boolean
			Array size		VarInt		Number of elements in the following array
			Recipes	Identifier	Array	Identifier
				Is unlocked		Boolean
				Has been displayed		Boolean

Serverbound

Unknown

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x01	Play	Server	Window ID		Byte		The window id.
			Action number		Short		The transaction number. Will be send to the client in a Confirm Transaction packet.
			Flag		Boolean		See below
			Array size		Byte		Number of elements in the following array
			Entry	Item Identifier	Array	String (64)	The partial identifier of an item type (without prefix minecraft:), or empty if not present
				Item Data		Short	The data value of the item, or 0 if not present
				Slot A		Byte	The target slot index in the active container
				Slot B		Byte	The target slot index in the player inventory

If the flag is set to true:

• The amount if items in Slot B is descreased by one.
• A item stack created from the provided identifier and data will be put in Slot A.

Otherwise:

• The amount if items in Slot B is increased by one if not empty, otherwise will a new stack be created from the provided identifier and data.
• The item in Slot A will be cleared.

In both cases will the crafting grid be updated and a Confirm Transaction packet send back to the client, with the window id and action number send by the client.

Client Status

Sent when the client is ready to complete login and when the client is ready to respawn after death.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x04	Play	Server	Action ID	VarInt Enum	See below

Action ID values:

Action ID	Action
0	Perform respawn
1	Request stats
2	Open inventory

Recipe displayed

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x17	Play	Server	Identifier	Identifier
			?	Int	Currently always -1

Handshaking

Clientbound

No changes so far.

Serverbound

No changes so far.

Handshake

This causes the server to switch into the target state.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x00	Handshaking	Server	Protocol Version	VarInt	See protocol version numbers (currently 316 319)
			Server Address	String	Hostname or IP, e.g. localhost or 127.0.0.1, that was used to connect. The Notchian server does not use this information.
			Server Port	Unsigned Short	Default is 25565. The Notchian server does not use this information.
			Next State	VarInt Enum	1 for status, 2 for login

Status

Clientbound

No changes so far.

Serverbound

No changes so far.

Login

Clientbound

No changes so far.

Serverbound

No changes so far.