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, protocol 335). 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
0x28 0x25	Entity	Current	(unchanged)
0x25 0x26	Entity Relative Move	Current	(unchanged)
0x26 0x27	Entity Look And Relative Move	Current	(unchanged)
0x27 0x28	Entity Look	Current	(unchanged)
0x30	Unlock Recipes		Pre
0x30 0x31	Destroy Entities	Current	(unchanged)
0x31 0x32	Remove Entity Effect	Current	(unchanged)
0x32 0x33	Resource Pack Send	Current	(unchanged)
0x33 0x34	Respawn	Current	(unchanged)
0x34 0x35	Entity Head Look	Current	(unchanged)
0x36	Advancement Progress		Pre
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)
0x4C	Advancements		Pre
0x4A 0x4D	Entity Properties	Current	(unchanged)
0x4B 0x4E	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	Pre
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)
0x0F 0x0D	Player	Current	(unchanged)
0x0C 0x0E	Player Position	Current	(unchanged)
0x0D 0x0F	Player Position And Look (serverbound)	Current	(unchanged)
0x0E 0x10	Player Look	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)
0x19	Advancement Tab		Pre
0x17 0x1A	Held Item Change (serverbound)	Current	(unchanged)
0x18 0x1B	Creative Inventory Action	Current	(unchanged)
0x19 0x1C	Update Sign	Current	(unchanged)
0x1A 0x1D	Animation (serverbound)	Current	(unchanged)
0x1B 0x1E	Spectate	Current	(unchanged)
0x1C 0x1F	Player Block Placement	Current	(unchanged)
0x1D 0x20	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

Translation component

	The following information needs to be added to this page:
	Is using this with an invalid key intended or deprecated? Also, what exactly happens on invalid formats?

Translates text into the current language. If the JSON contains a translate key, then the component is a translation component.

Translation supports %s and %% format tokens. %% is just an escaped percent symbol. %s marks text to replace using content from the optional with tag. with is an array of components.

As a special case, if the translation key is chat.type.text, it will be changed to chat.type.text.narrate when passed to narrator (although it will remain as chat.type.text in chat).

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

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	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
0x30	Play	Client
			Action	VarInt	0: init, 1: add, 2: remove
			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 IDs	Array of VarInt
			Array size 2	Optional VarInt	Number of elements in the following array, only present if mode is 0 (init)
			Recipe IDs	Optional Array of VarInt, only present if mode is 0 (init)

Action:

• 0 (init) = All the recipes in the list 2 will added to the recipe book. All the recipes in list 1 will be tagged as displayed, recipes that aren't tagged will be shown in the notification. VERIFY LIST ORDER?
• 1 (add) = All the recipes in the list are added and their icon will be shown in the notification.
• 2 (remove) = Remove all the recipes in the list. This allows them to re-displayed when they are readded.

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.

Advancement Progress

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x36	Play	Client	Has id	Boolean	Indicates if the next field is present
			ID	Optional Identifier

Advancements

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x4C	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

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

Client Settings

Sent when the player connects, or when settings are changed.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x05	Play	Server	Locale	String (7 16)	e.g. en_GB.
			View Distance	Byte	Client-side render distance, in chunks
			Chat Mode	VarInt Enum	0: enabled, 1: commands only, 2: hidden. See processing chat for more information.
			Chat Colors	Boolean	“Colors” multiplayer setting
			Displayed Skin Parts	Unsigned Byte	Bit mask, see below
			Main Hand	VarInt Enum	0: Left, 1: Right

Displayed Skin Parts flags:

• Bit 0 (0x01): Cape enabled
• Bit 1 (0x02): Jacket enabled
• Bit 2 (0x04): Left Sleeve enabled
• Bit 3 (0x08): Right Sleeve enabled
• Bit 4 (0x10): Left Pants Leg enabled
• Bit 5 (0x20): Right Pants Leg enabled
• Bit 6 (0x40): Hat enabled

The most significant bit (bit 7, 0x80) is unused.

Crafting Book Data

Packet ID	State	Bound To	Field Name		Field Type	Notes
0x17	Play	Server	Type		VarInt	Determines the format of the rest of the packet
			Type	Field Name
			0: Displayed Recipe	Recipe ID	Int	The internal id of the displayed recipe.
			1: 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.

Advancement Tab

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x19	Play	Server	Action	VarInt enum	0: Opened tab, 1: Closed screen
			Tab ID	Optional identifier	Only present if action is Opened tab

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