Pre-release protocol

This page documents the changes from release 1.21.1 (protocol 767) to the current release (1.21.3, protocol 768). The stable protocol documentation is currently lagging behind, and the changes documented here will be merged soon, once they are complete. The current pre-release (snapshot 24w44a) is not yet 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

Name	Size (bytes)	Encodes	Notes
ID Set	Varies	Set of registry IDs specified either inline or as a reference to a tag.	See #ID Set

ID Set

Represents a set of IDs in a certain registry (implied by context), either directly (enumerated IDs) or indirectly (tag name).

Name	Type	Description
Type	VarInt	Identifier used to determine the data that follows. It can be either: 0 - Represents a named set of IDs defined by a tag. Anything else - Represents an ad-hoc set of IDs enumerated inline.
Tag Name	Optional Identifier	The registry tag defining the ID set. Only present if Type is 0.
IDs	Optional Array of VarInt	An array of registry IDs. Only present if Type is not 0. The size of the array is equal to Type - 1.

Packets

ID	Packet name	Documentation
Play clientbound
0x15	Set Container Slot	Current	Pre
0x17	Set Cooldown	Current	Pre
0x20	Synchronize Entity Position		Pre
0x20 0x21	Explosion	Current	Pre
0x31	Move Minecart Along Track		Pre
0x37 0x39	Place Ghost Recipe	Current	Pre
0x41	Update Recipe Book	Current
0x43	Player Rotation		Pre
0x44	Recipe Book Add		Pre
0x45	Recipe Book Remove		Pre
0x46	Recipe Book Settings		Pre
0x5a	Set Cursor Item		Pre
0x53 0x63	Set Held Item	Current	(unchanged)
0x66	Set Player Inventory Slot		Pre
0x64 0x6b	Update Time	Current	Pre
Play serverbound
0x02	Bundle Item Selected		Pre
0x0b	Client Tick End		Pre

Handshake

No changes so far.

Status

No changes so far.

Login

No changes so far.

Configuration

No changes so far.

Play

Clientbound

Set Container Slot

Sent by the server when an item in a slot (in a window) is added/removed.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x15	Play	Client	Window ID	Byte	The window which is being updated. 0 for player inventory. The client ignores any packets targeting a Window ID other than the current one; see below for exceptions , unless it is 0 (see below).
			State ID	VarInt	A server-managed sequence number used to avoid desynchronization; see #Click Container.
			Slot	Short	The slot that should be updated.
			Slot Data	Slot

If Window ID is 0, the hotbar and offhand slots (slots 36 through 45) may be updated even when a different container window is open. (The Notchian server does not appear to utilize this special case.) Updates are also restricted to those slots when the player is looking at a creative inventory tab other than the survival inventory. (The Notchian server does not handle this restriction in any way, leading to MC-242392.)

If Window ID is -1, the item being dragged with the mouse is set. In this case, State ID and Slot are ignored.

If Window ID is -2, any slot in the player's inventory can be updated irrespective of the current container window. In this case, State ID is ignored, and the Notchian server uses a bogus value of 0. Used by the Notchian server to implement the #Pick Item functionality.

When a container window is open, the server never sends updates targeting Window ID 0—all of the window types include slots for the player inventory. The client must automatically apply changes targeting the inventory portion of a container window to the main inventory; the server does not resend them for ID 0 when the window is closed. However, since the armor and offhand slots are only present on ID 0, updates to those slots occurring while a window is open must be deferred by the server until the window's closure.

Set Cooldown

Applies a cooldown period to all items with the given type. Used by the Notchian server with enderpearls. This packet should be sent when the cooldown starts and also when the cooldown ends (to compensate for lag), although the client will end the cooldown automatically. Can be applied to any item, note that interactions still get sent to the server with the item but the client does not play the animation nor attempt to predict results (i.e block placing).

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x17	Play	Client	Item ID Cooldown Group	VarInt Identifier	Numeric ID of the item Group of items to apply a cooldown to.
			Cooldown Ticks	VarInt	Number of ticks to apply a cooldown for, or 0 to clear the cooldown.

Synchronize Entity Position

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x20	Play	Client	Entity ID	VarInt
			X	Double
			Y	Double
			Z	Double
			Velocity X	Double
			Velocity Y	Double
			Velocity Z	Double
			Yaw	Float	Rotation on the X axis, in degrees.
			Pitch	Float	Rotation on the Y axis, in degrees.
			On Ground	Boolean

Explosion

Sent when an explosion occurs (creepers, TNT, and ghast fireballs).

Each block in Records is set to air. Coordinates for each axis in record is int(X) + record.x

Packet ID	State	Bound To	Field Name		Field Type	Notes
0x20 0x21	Play	Client	X		Double
			Y		Double
			Z		Double
			Strength		Float	If the strength is greater or equal to 2.0, or the block interaction is not 0 (keep), large explosion particles are used. Otherwise, small explosion particles are used.
			Record Count		VarInt	Number of elements in the following array.
			Records		Array of (Byte, Byte, Byte)	Each record is 3 signed bytes long; the 3 bytes are the XYZ (respectively) signed offsets of affected blocks.
			Has Player Motion		Boolean
			Player Motion X		Optional Float	X velocity of the player being pushed by the explosion. Only present if Has Player Motion is true.
			Player Motion Y		Optional Float	Y velocity of the player being pushed by the explosion. Only present if Has Player Motion is true.
			Player Motion Z		Optional Float	Z velocity of the player being pushed by the explosion. Only present if Has Player Motion is true.
			Block Interaction		VarInt Enum	0 = keep, 1 = destroy, 2 = destroy_with_decay, 3 = trigger_block.
			Small Explosion Particle ID		VarInt	The particle ID listed in Particles.
			Small Explosion Particle Data		Varies	Particle data as specified in Particles.
			Large Explosion Particle ID		VarInt	The particle ID listed in Particles.
			Large Explosion Particle Data		Varies	Particle data as specified in Particles.
			Explosion Sound	Sound ID	VarInt	Represents the Sound ID + 1. If the value is 0, the packet contains a sound specified by Identifier.
				Sound Name	Optional Identifier	The name of the sound played. Only present if Sound ID is 0.
				Has Fixed Range	Optional Boolean	Whether is has fixed range. Only present if Sound ID is 0.
				Range	Optional Float	The fixed range of the sound. Only present if previous boolean is true and Sound ID is 0.

Move Minecart Along Track

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x31	Play	Client	Entity ID		VarInt
			Step Count		VarInt		Number of elements in the following array.
			Steps	X	Array	Double
				Y		Double
				Z		Double
				Velocity X		Double
				Velocity Y		Double
				Velocity Z		Double
				Yaw		Angle
				Pitch		Angle
				Weight		Float

Player Rotation

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x43	Play	Client	Yaw	Float	Rotation on the X axis, in degrees.
			Pitch	Float	Rotation on the Y axis, in degrees.

Place Ghost Recipe

Response to the serverbound packet (Place Recipe), with the same recipe ID. Appears to be used to notify the UI.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x37 0x39	Play	Client	Window ID	Byte VarInt
			Recipe	Identifier	A recipe ID.
			Recipe Display ID	VarInt	ID in the minecraft:recipe_display registry.
			Recipe Data	Varies	Depends on Recipe Type; see below.

below

Recipe Book Add

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x44	Play	Client	Recipe Count		VarInt		Number of elements in the following array.
			Recipes	Recipe ID	Array	VarInt	ID to assign to the recipe.
				Display ID		VarInt	ID in the minecraft:recipe_display registry.
				Group ID		VarInt
				Category ID		VarInt	ID in the minecraft:recipe_book_category registry.
				Has Ingredients		Boolean
				Ingredient Count		Optional VarInt	Number of elements in the following array. Only present if Has Ingredients is true.
				Ingredients		Optional Array of ID Set	Only present if Has Ingredients is true.
			Flags		Byte		0x01: show notification; 0x02: highlight as new

Recipe Book Remove

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x45	Play	Client	Recipe Count	VarInt	Number of elements in the following array.
			Recipes	Array of VarInt	IDs of recipes to remove.

Recipe Book Settings

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x46	Play	Client	Crafting Recipe Book Open	Boolean	If true, then the crafting recipe book will be open when the player opens its inventory.
			Crafting Recipe Book Filter Active	Boolean	If true, then the filtering option is active when the players opens its inventory.
			Smelting Recipe Book Open	Boolean	If true, then the smelting recipe book will be open when the player opens its inventory.
			Smelting Recipe Book Filter Active	Boolean	If true, then the filtering option is active when the players opens its inventory.
			Blast Furnace Recipe Book Open	Boolean	If true, then the blast furnace recipe book will be open when the player opens its inventory.
			Blast Furnace Recipe Book Filter Active	Boolean	If true, then the filtering option is active when the players opens its inventory.
			Smoker Recipe Book Open	Boolean	If true, then the smoker recipe book will be open when the player opens its inventory.
			Smoker Recipe Book Filter Active	Boolean	If true, then the filtering option is active when the players opens its inventory.

Set Cursor Item

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x5A	Play	Client	Slot Data	Slot

Update Time

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 the time by 20 every second.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x64 0x6b	Play	Client	World Age	Long	In ticks; not changed by server commands.
			Time of day	Long	The world (or region) time, in ticks. If negative the sun will stop moving at the Math.abs of the time.
			Time of day increasing	Boolean	If true, the client should automatically advance the time of day according to its ticking rate.

Set Player Inventory Slot

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x66	Play	Client	Slot	VarInt
			Slot Data	Slot

Serverbound

Bundle Item Selected

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x02	Play	Server	Slot of Bundle	VarInt
			Slot in Bundle	VarInt

Client Tick End

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x0B	Play	Server	no fields