Pre-release protocol

This page documents the changes from the last stable Minecraft release (currently 1.18.2, protocol 758) to the current pre-release (currently 22w16b, protocol Snapshot 81). 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

Packet ID shifts have not been included.

ID	Packet name	Documentation
Play clientbound
0x02	Spawn Living Entity	Current
0x03	Spawn Painting	Current
0x05	Sculk Vibration Signal	Current
0x05	Acknowledge Block Changes		Pre
0x08	Acknowledge Player Digging	Current
0x5C	System Message		Pre
Play serverbound
Handshaking serverbound

New/modified data types

No changes so far.

Entity Metadata

Goat

The base class.

Index	Type	Meaning		Default
0	Boolean	Is Screaming Goat		false
1	Boolean	Has Left Horn		true
2	Boolean	Has Right Horn		true

Painting

The base class.

Index	Type	Meaning		Default
0	VarInt	PaintingVariant		0

Player

The base class.

Index	Type	Meaning		Default
0	Float	Additional Hearts		0.0
1	VarInt	Score		0
2	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
3	Byte	Main hand (0 : Left, 1 : Right)		1
4	NBT	Left shoulder entity data (for occupying parrot)		Empty
5	NBT	Right shoulder entity data (for occupying parrot)		Empty
6	Global Position	Optional Last Death Location (used for respawn compass)		Empty

Entity

No changes so far.

Block Actions

No changes so far.

Inventories

No changes so far.

Plugin Channels

No changes so far.

Play

Clientbound

Spawn Entity

Sent by the server when a vehicle or other non-living entity is created.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x00	Play	Client	Entity ID	VarInt	Entity ID.
			Object UUID	UUID
			Type	VarInt	The type of entity (same as in Spawn Living Entity).
			X	Double
			Y	Double
			Z	Double
			Pitch	Angle	To get the real pitch, you must divide this by (256.0F / 360.0F)
			Yaw	Angle	To get the real yaw, you must divide this by (256.0F / 360.0F)
			Head Yaw	Angle
			Data	Int	Meaning dependent on the value of the Type field, see Object Data for details.
			Velocity X	Short	Same units as Entity Velocity. Always sent, but only used when Data is greater than 0 (except for some entities which always ignore it; see Object Data for details).
			Velocity Y	Short
			Velocity Z	Short

Acknowledge Block Changes

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x05	Play	Client	Sequence ID	VarInt	Represents the sequence to acknowledge, this is used for properly syncing block changes to the client after interactions.

Block Action

This packet is used for a number of actions and animations performed by blocks, usually non-persistent. The client ignores the provided block type and instead uses the block state in their world.

See Block Actions for a list of values.

This packet uses a block ID, not a block state.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x0B	Play	Client	Location	Position	Block coordinates.
			Action ID (Byte 1)	Unsigned Byte	Varies depending on block — see Block Actions.
			Action Param (Byte 2)	Unsigned Byte	Varies depending on block — see Block Actions.
			Block Type	VarInt	The block type ID for the block. This must match the block at the given coordinates.
			Sequence	VarInt

Named Sound Effect

See also: #Sound Effect

Used to play a sound effect on the client. Custom sounds may be added by resource packs.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x19 0x16	Play	Client	Sound Name	Identifier	All sound effect names as of 1.16.5 can be seen here.
			Sound Category	VarInt Enum	The category that this sound will be played from (current categories).
			Effect Position X	Int	Effect X multiplied by 8 (fixed-point number with only 3 bits dedicated to the fractional part).
			Effect Position Y	Int	Effect Y multiplied by 8 (fixed-point number with only 3 bits dedicated to the fractional part).
			Effect Position Z	Int	Effect Z multiplied by 8 (fixed-point number with only 3 bits dedicated to the fractional part).
			Volume	Float	1 is 100%, can be more.
			Pitch	Float	Float between 0.5 and 2.0 by Notchian clients.
			Seed	long	Seed used to pick sound varient.

Template:Changed (clientbound)

Identifying the difference between Chat/System Message is important as it helps respect the user's chat visibility options. See processing chat for more info about these positions.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x0F 0x2F	Play	Client	JSON Data	Chat	Limited to 262144 bytes.
			Position	Byte	0: chat (chat box), 1: system message (chat box), 2: game info (above hotbar).
			Sender	UUID	Used by the Notchian client for the disableChat launch option. Setting both longs to 0 will always display the message regardless of the setting.
			Display Name	Component
			Has Team Display Name	Boolean	Used in /teammsg
			Team Display Name	Component	Used in /teammsg
			Timestamp	Long	Used to check that the message was received within 2 minutes of it being sent.
			Salt	Long	Cryptography, TODO:
			Signature Length	VarInt	Array Length
			Message Signature	Bytes	Cryptography, TODO:

System Chat Message (clientbound)

Identifying the difference between Chat/System Message is important as it helps respect the user's chat visibility options. See processing chat for more info about these positions.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x5C	Play	Client	JSON Data	Chat	Limited to 262144 bytes.
			Position	Byte	0: chat (chat box), 1: system message (chat box), 2: game info (above hotbar).

Entity Sound Effect

Plays a sound effect from an entity.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x5C 0x59	Play	Client	Sound ID	VarInt	ID of hardcoded sound event (events as of 1.16.5).
			Sound Category	VarInt Enum	The category that this sound will be played from (current categories).
			Entity ID	VarInt
			Volume	Float	1.0 is 100%, capped between 0.0 and 1.0 by Notchian clients.
			Pitch	Float	Float between 0.5 and 2.0 by Notchian clients.
			Seed	long	Seed used to pick sound varient.

Sound Effect

This packet is used to play a number of hardcoded sound events. For custom sounds, use Named Sound Effect.

Numeric sound effect IDs are liable to change between versions

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x5D 0x5A	Play	Client	Sound ID	VarInt	ID of hardcoded sound event (events as of 1.16.5).
			Sound Category	VarInt Enum	The category that this sound will be played from (current categories).
			Effect Position X	Int	Effect X multiplied by 8 (fixed-point number with only 3 bits dedicated to the fractional part).
			Effect Position Y	Int	Effect Y multiplied by 8 (fixed-point number with only 3 bits dedicated to the fractional part).
			Effect Position Z	Int	Effect Z multiplied by 8 (fixed-point number with only 3 bits dedicated to the fractional part).
			Volume	Float	1.0 is 100%, capped between 0.0 and 1.0 by Notchian clients.
			Pitch	Float	Float between 0.5 and 2.0 by Notchian clients.
			Seed	long	Seed used to pick sound varient.

Entity Effect

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x65 0x62	Play	Client	Entity ID	VarInt
			Effect ID	VarInt	See this table.
			Amplifier	Byte	Notchian client displays effect level as Amplifier + 1.
			Duration	VarInt	Duration in ticks.
			Flags	Byte	Bit field, see below.
			Has Factor Data	boolean	Used in DARKNESS effect
			Factor Codec	NBT Tag	See below

Within flags:

• 0x01: Is ambient - was the effect spawned from a beacon? All beacon-generated effects are ambient. Ambient effects use a different icon in the HUD (blue border rather than gray). If all effects on an entity are ambient, the "Is potion effect ambient" living metadata field should be set to true. Usually should not be enabled.
• 0x02: Show particles - should all particles from this effect be hidden? Effects with particles hidden are not included in the calculation of the effect color, and are not rendered on the HUD (but are still rendered within the inventory). Usually should be enabled.
• 0x04: Show icon - should the icon be displayed on the client? Usually should be enabled.

Factor Data

Name	Type	Notes
padding_duration	TAG_INT
factor_target	TAG_FLOAT
factor_current	TAG_FLOAT
effect_changed_timestamp	TAG_INT
factor_previous_frame	TAG_FLOAT
had_effect_last_tick	TAG_BOOLEAN

Serverbound

Player Digging

Sent when the player mines a block. A Notchian server only accepts digging packets with coordinates within a 6-unit radius between the center of the block and 1.5 units from the player's feet (not their eyes).

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x1A	Play	Server	Status	VarInt Enum	The action the player is taking against the block (see below).
			Location	Position	Block position.
			Face	Byte Enum	The face being hit (see below).
			Sequence	VarInt

Status can be one of seven values:

Value	Meaning	Notes
0	Started digging
1	Cancelled digging	Sent when the player lets go of the Mine Block key (default: left click).
2	Finished digging	Sent when the client thinks it is finished.
3	Drop item stack	Triggered by using the Drop Item key (default: Q) with the modifier to drop the entire selected stack (default: Control or Command, depending on OS). Location is always set to 0/0/0, Face is always set to -Y.
4	Drop item	Triggered by using the Drop Item key (default: Q). Location is always set to 0/0/0, Face is always set to -Y.
5	Shoot arrow / finish eating	Indicates that the currently held item should have its state updated such as eating food, pulling back bows, using buckets, etc. Location is always set to 0/0/0, Face is always set to -Y.
6	Swap item in hand	Used to swap or assign an item to the second hand. Location is always set to 0/0/0, Face is always set to -Y.

The Face field can be one of the following values, representing the face being hit:

Value	Offset	Face
0	-Y	Bottom
1	+Y	Top
2	-Z	North
3	+Z	South
4	-X	West
5	+X	East

Set Beacon Effect

Changes the effect of the current beacon.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x24	Play	Server
			Primary Effect Present	Boolean
			Primary Effect	VarInt	A Potion ID. (Was a full Integer for the plugin message).
			Secondary Effect Present	Boolean
			Secondary Effect	VarInt	A Potion ID. (Was a full Integer for the plugin message).

Use Item

Sent when pressing the Use Item key (default: right click) with an item in hand.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x2F	Play	Server	Hand	VarInt Enum	Hand used for the animation. 0: main hand, 1: off hand.
			Sequence	VarInt

Status

Clientbound

No changes so far.

Serverbound

No changes so far.

Login

Clientbound

No changes so far.

Serverbound

No changes so far.