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 1.12-pre2, protocol 329). 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	Pre
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	Prepare Crafting Grid		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	Crafting Book Data		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.

IllusionIllager

Extends EvocationIllager.

• Entity ID: 37.

Parrot

Extends TameableAnimal.

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

• Entity ID: 105.

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

Note Block

Displays a colored note particle and plays the appropriate note sound effect.

Action IDs

The action ID is used to determine the instrument to play.

Type ID	Instrument	Material/block	Sound
0	Harp	Any other material	block.note.harp
1	Bass Drum	Stone	block.note.harp
2	Snare Drum	Sand	block.note.snare
3	Clicks/Sticks	Glass	block.note.hat
4	Bass guitar	Wood	block.note.bass
5	Flute	Clay	block.note.flute
6	Bell	Gold block	block.note.bell
7	Guitar	Wool	block.note.guitar
8	Chime	Packed ice	block.note.chime
9	Xylophone	Bone block	block.note.xylophone

Any unknown ID is treated as if it were 0.

The sound event block.note.pling is unassigned and unused.

Action param

The pitch of the note (between 0–24 inclusive where 0 is the lowest and 24 is the highest). More information about how the pitch values correspond to notes in real life and how they correspond to pitch scaling on the sound effects can be found in the Note Block article on the Minecraft wiki.

Chat components

Keybind component

Displays the client's current keybind for the specified key. If the component contains a keybind key, then it is a keybind component. The value is named after the keys in options.txt (for instance, for key_key.forward in options.txt, key.forward would be used in the component and W would be displayed). For keys that are not known, the value provided should be displayed instead (for instance key.invalid would remain as key.invalid).

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.
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
Description	Chat
Icon	Slot
Frame type	VarInt enum	0 = task, 1 = challenge, 2 = goal
Flags	Integer	0x1: has background texture; 0x2: show_toast; 0x4: hidden
Background texture	Optional Identifier	Background texture location. Only if flags indicates it.
X coord	Float
Y coord	Float

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 achieving	Optional Long	As returned by Date.getTime

Update Block Entity

Sets tile entity associated with the block at the given location.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x09 0x0A	Play	Client	Location	Position
			Action	Unsigned Byte	The type of update to perform, see below
			NBT Data	NBT Tag	Data to set. May be a TAG_END (0), in which case the block entity at the given location is removed (though this is not required since the client will remove the block entity automatically on chunk unload or block removal)

Action field:

• 1: Set data of a mob spawner (everything except for SpawnPotentials: current delay, min/max delay, mob to be spawned, spawn count, spawn range, etc.)
• 2: Set command block text (command and last execution status)
• 3: Set the level, primary, and secondary powers of a beacon
• 4: Set rotation and skin of mob head
• 5: Set type of flower in flower pot
• 6: Set base color and patterns on a banner
• 7: Set the data for a Structure tile entity
• 8: Set the destination for a end gateway
• 9: Set the text on a sign
• 10: Declare a shulker box (unclear if there is any actual data)
• 11: Set the color of a bed

Unlock Recipes

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x31	Play	Client
			Action		Short		The action, see below
			Crafting Book Open		Boolean		If true, then the crafting book will be open when the player opens its inventory.
			Filtering Craftable		Boolean		If true, then the filtering option is active when the players opens its inventory.
			Array size 1		VarInt		Number of elements in the following array
			Recipe ID		Array	Integer
			Array size 2		VarInt		Number of elements in the following array
			Recipe ID		Array	Integer

Action:

• 1 = All the recipes in the list 1 are added and their icon will be shown in the notification. The notification will only show up if all the recipes in this list weren't displayed before (removing the recipe resets this). All the recipes in the list 2 will added to the recipe book.
• 2 = Remove all the recipes in the list 1. This allows them to re-displayed when they are readded.
• 3 = All the recipes in the list 2 will added to the recipe book. All the recipes in list 1 will be tagged as displayed. No notification will be shown.

Recipe ID: These are hardcoded values in the client and server, all the recipe json files will be loaded in a specific order (alphabetical, like sounds) and internal ids will be assigned in that order. There are also inbuilt recipes like fireworks, banners, etc., these are the first recipes to have their id assigned. Due the fact that the recipes are loaded in a specific order will the ids very likely change when recipes get added. Custom recipes are scheduled for Minecraft 1.13, so most likely will things change a bit in that version.

Serverbound

Prepare Crafting Grid

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.
			Array size		Short		Number of elements in the following array
			Return Entry	Item	Array	Slot	The item stack that will be put in the inventory slot
				Crafting Slot		Byte	The crafting slot index in the active container
				Player Slot		Byte	The player slot index in the player inventory
			Array Size		Short		Number of elements in the following array
			Prepare Entry	Item	Array	Slot	The item stack that will be put in the crafting slot
				Crafting Slot		Byte	The crafting slot index in the active container
				Player Slot		Byte	The player slot index in the player inventory

This packet is send when a player clicks a recipe in the crafting book that is craftable (white border).

1. Return Entries:

• All the items on the crafting slot are set to null/empty.
• Every entry item stack will be added to the player inventory, to the specific player slot.

2. Prepare Entries:

• All the items on the player inventory slots their quantity is decreased by 1.
• Every entry item stack will be put in the proper crafting grid slot.

The server will send a Confirm Transaction packet back to the client with the provided transaction id.

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

Crafting Book Data

Packet ID	State	Bound To	Field Name		Field Type	Notes
0x17	Play	Server	Type		Int	Determines the format of the rest of the packet
			Type	Field Name
			1: Displayed Recipe	Recipe ID	Int	The internal id of the displayed recipe.
			2: Crafting Book Status	Crafting Book Open	Boolean	Whether the player has the crafting book currently openened/active.
				Crafting Filter	Boolean	Whether the player has the crafting filter option currently active.

The Crafting Book Status type is send when the player closes its inventory.

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