Pre-release protocol

This page documents the changes from the last stable Minecraft release (currently 1.20.2, protocol 764) to the current pre-release (currently 23w45a, protocol Snapshot 162). 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

NBT

The NBT specification was changed so that the root tag is no longer required to be a Compound Tag when sent over the network.

Presently in the pre-release, only Compound Tag and String Tag types are used as root, but the Notchian server/client implementation is able to handle NBT Tags of any type.

Chat

The Chat type is now serialized as a NBT Tag instead of a JSON String, unless explicitly stated otherwise.

Name	Size (bytes)	Encodes	Notes
Chat	≥ 1 ≤ (262144×4) + 3	See Chat	Encoded as a String with max length of 262144.
Chat	Varies	See Chat	Encoded as a NBT Tag, with the type of tag used depending on the case: As a String Tag: For components only containing text (no styling, no events etc.). As a Compound Tag: Every other case.

This affects the following packets and data types containing Chat fields:

• Disconnect (configuration)
• Resource Pack (configuration)
• Boss Bar
• Command Suggestions Response
• Disconnect (play)
• Disguised Chat Message
• Map Data
• Open Screen
• Player Chat Message
• Combat Death
• Player Info Update
• Resource Pack (play)
• Server Data
• Set Action Bar Text
• Update Objectives
• Update Teams
• Set Subtitle Text
• Set Title Text
• System Chat Message
• Set Tab List Header And Footer
• Update Advancements

• Slot data type (values in the item NBT field)
• Chat entity metadata type
• OptChat entity metadata type

However, the following are NOT affected, as to maintain backwards compatibility with older versions:

• Disconnect (login)
• Server List status response (the description field)

Particle

Particle Name	Particle ID	Data
minecraft:ambient_entity_effect	0	None
minecraft:angry_villager	1	None
minecraft:block	2	Field Name Field Type Meaning BlockState VarInt The ID of the block state.
minecraft:block_marker	3	Field Name Field Type Meaning BlockState VarInt The ID of the block state.
minecraft:bubble	4	None
minecraft:cloud	5	None
minecraft:crit	6	None
minecraft:damage_indicator	7	None
minecraft:dragon_breath	8	None
minecraft:dripping_lava	9	None
minecraft:falling_lava	10	None
minecraft:landing_lava	11	None
minecraft:dripping_water	12	None
minecraft:falling_water	13	None
minecraft:dust	14	Field Name Field Type Meaning Red Float The red RGB value, between 0 and 1. Divide actual RGB value by 255. Green Float The green RGB value, between 0 and 1. Divide actual RGB value by 255. Blue Float The blue RGB value, between 0 and 1. Divide actual RGB value by 255. Scale Float The scale, will be clamped between 0.01 and 4.
minecraft:dust_color_transition	15	Field Name Field Type Meaning From Red Float The start red RGB value, between 0 and 1. Divide actual RGB value by 255. From Green Float The start green RGB value, between 0 and 1. Divide actual RGB value by 255. From Blue Float The start blue RGB value, between 0 and 1. Divide actual RGB value by 255. Scale Float The scale, will be clamped between 0.01 and 4. To Red Float The end red RGB value, between 0 and 1. Divide actual RGB value by 255. To Green Float The end green RGB value, between 0 and 1. Divide actual RGB value by 255. To Blue Float The end blue RGB value, between 0 and 1. Divide actual RGB value by 255.
minecraft:effect	16	None
minecraft:elder_guardian	17	None
minecraft:enchanted_hit	18	None
minecraft:enchant	19	None
minecraft:end_rod	20	None
minecraft:entity_effect	21	None
minecraft:explosion_emitter	22	None
minecraft:explosion	23	None
minecraft:gust	24	None
minecraft:gust_emitter	25	None
minecraft:sonic_boom	24 26	None
minecraft:falling_dust	25 27	Field Name Field Type Meaning BlockState VarInt The ID of the block state.
minecraft:firework	26 28	None
minecraft:fishing	27 29	None
minecraft:flame	28 30	None
minecraft:cherry_leaves	29 31	None
minecraft:sculk_soul	30 32	None
minecraft:sculk_charge	31 33	Field Name Field Type Meaning Roll Float How much the particle will be rotated when displayed.
minecraft:sculk_charge_pop	32 34	None
minecraft:soul_fire_flame	33 35	None
minecraft:soul	34 36	None
minecraft:flash	35 37	None
minecraft:happy_villager	36 38	None
minecraft:composter	37 39	None
minecraft:heart	38 40	None
minecraft:instant_effect	39 41	None
minecraft:item	40 42	Field Name Field Type Meaning Item Slot The item that will be used.
minecraft:vibration	41 43	Field Name Field Type Meaning Position Source Type Identifier The type of the vibration source Block Position Position The position of the block the vibration originated from. Only present if Position Type is minecraft:block. Entity ID VarInt The ID of the entity the vibration originated from. Only present if Position Type is minecraft:entity. Entity eye height Float The height of the entity's eye relative to the entity. Only present if Position Type is minecraft:entity. Ticks VarInt The amount of ticks it takes for the vibration to travel from its source to its destination.
minecraft:item_slime	42 44	None
minecraft:item_snowball	43 45	None
minecraft:large_smoke	44 46	None
minecraft:lava	45 47	None
minecraft:mycelium	46 48	None
minecraft:note	47 49	None
minecraft:poof	48 50	None
minecraft:portal	49 51	None
minecraft:rain	50 52	None
minecraft:smoke	51 53	None
minecraft:white_smoke	54	None
minecraft:sneeze	52 55	None
minecraft:spit	53 56	None
minecraft:squid_ink	54 57	None
minecraft:sweep_attack	55 58	None
minecraft:totem_of_undying	56 59	None
minecraft:underwater	57 60	None
minecraft:splash	58 61	None
minecraft:witch	59 62	None
minecraft:bubble_pop	60 63	None
minecraft:current_down	61 64	None
minecraft:bubble_column_up	62 65	None
minecraft:nautilus	63 66	None
minecraft:dolphin	64 67	None
minecraft:campfire_cosy_smoke	65 68	None
minecraft:campfire_signal_smoke	66 69	None
minecraft:dripping_honey	67 70	None
minecraft:falling_honey	68 71	None
minecraft:landing_honey	69 72	None
minecraft:falling_nectar	70 73	None
minecraft:falling_spore_blossom	71 74	None
minecraft:ash	72 75	None
minecraft:crimson_spore	73 76	None
minecraft:warped_spore	74 77	None
minecraft:spore_blossom_air	75 78	None
minecraft:dripping_obsidian_tear	76 79	None
minecraft:falling_obsidian_tear	77 80	None
minecraft:landing_obsidian_tear	78 81	None
minecraft:reverse_portal	79 82	None
minecraft:white_ash	80 83	None
minecraft:small_flame	81 84	None
minecraft:snowflake	82 85	None
minecraft:dripping_dripstone_lava	83 86	None
minecraft:falling_dripstone_lava	84 87	None
minecraft:dripping_dripstone_water	85 88	None
minecraft:falling_dripstone_water	86 89	None
minecraft:glow_squid_ink	87 90	None
minecraft:glow	88 91	None
minecraft:wax_on	89 92	None
minecraft:wax_off	90 93	None
minecraft:electric_spark	91 94	None
minecraft:scrape	92 95	None
minecraft:shriek	93 96	Field Name Field Type Meaning Delay VarInt The time in ticks before the particle is displayed
minecraft:egg_crack	94 97	None
minecraft:dust_plume	98	None
minecraft:gust_dust	99	None
minecraft:trial_spawner_detection	100	None

Packets

ID	Packet name	Documentation
Configuration clientbound
0x07	Feature Flags	Current	Pre
Play clientbound
0x1E	Explosion	Current	Pre
0x20	Game Event	Current	Pre
0x6C	Set Ticking State		Pre
0x6D	Step Tick		Pre
0x6C 0x6E	Update Advancements	Current	(unchanged)
0x6D 0x6F	Update Attributes	Current	(unchanged)
0x6E 0x70	Entity Effect	Current	(unchanged)
0x6F 0x71	Update Recipes	Current	(unchanged)
0x70 0x72	Update Tags	Current	(unchanged)
Play serverbound
0x0F	Change Container Slot State		Pre
0x0F 0x10	Serverbound Plugin Message (play)	Current	(unchanged)
0x10 0x11	Edit Book	Current	(unchanged)
0x11 0x12	Query Entity Tag	Current	(unchanged)
0x12 0x13	Interact	Current	(unchanged)
0x13 0x14	Jigsaw Generate	Current	(unchanged)
0x14 0x15	Serverbound Keep Alive (play)	Current	(unchanged)
0x15 0x16	Lock Difficulty	Current	(unchanged)
0x16 0x17	Set Player Position	Current	(unchanged)
0x17 0x18	Set Player Position and Rotation	Current	(unchanged)
0x18 0x19	Set Player Rotation	Current	(unchanged)
0x19 0x1A	Set Player On Ground	Current	(unchanged)
0x1A 0x1B	Move Vehicle	Current	(unchanged)
0x1B 0x1C	Paddle Boat	Current	(unchanged)
0x1C 0x1D	Pick Item	Current	(unchanged)
0x1D 0x1E	Ping Request (play)	Current	(unchanged)
0x1E 0x1F	Place Recipe	Current	(unchanged)
0x1F 0x20	Player Abilities	Current	(unchanged)
0x20 0x21	Player Action	Current	(unchanged)
0x21 0x22	Player Command	Current	(unchanged)
0x22 0x23	Player Input	Current	(unchanged)
0x23 0x24	Pong (play)	Current	(unchanged)
0x24 0x25	Change Recipe Book Settings	Current	(unchanged)
0x25 0x26	Set Seen Recipe	Current	(unchanged)
0x26 0x27	Rename Item	Current	(unchanged)
0x27 0x28	Resource Pack Response (play)	Current	(unchanged)
0x28 0x29	Seen Advancements	Current	(unchanged)
0x29 0x2A	Select Trade	Current	(unchanged)
0x2A 0x2B	Set Beacon Effect	Current	(unchanged)
0x2B 0x2C	Set Held Item	Current	(unchanged)
0x2C 0x2D	Program Command Block	Current	(unchanged)
0x2D 0x2E	Program Command Block Minecart	Current	(unchanged)
0x2E 0x2F	Set Creative Mode Slot	Current	(unchanged)
0x2F 0x30	Program Jigsaw Block	Current	Pre
0x30 0x31	Program Structure Block	Current	(unchanged)
0x31 0x32	Update Sign	Current	(unchanged)
0x32 0x33	Swing Arm	Current	(unchanged)
0x33 0x34	Teleport To Entity	Current	(unchanged)
0x34 0x35	Use Item On	Current	(unchanged)
0x35 0x36	Use Item	Current	(unchanged)

New/modified data types

No changes so far.

Entity Metadata

Type (VarInt Enum)	Value (Varies)	Notes
0	Byte
1	VarInt
2	VarLong
3	Float
4	String
5	Chat
6	OptChat (Boolean + Chat)	Chat is present if the Boolean is set to true
7	Slot
8	Boolean
9	Rotation	3 Floats: rotation on x, rotation on y, rotation on z
10	Position
11	OptPosition (Boolean + Position)	Position is present if the Boolean is set to true
12	Direction (VarInt)	(Down = 0, Up = 1, North = 2, South = 3, West = 4, East = 5)
13	OptUUID (Boolean + UUID)	UUID is present if the Boolean is set to true
14	BlockID (VarInt)
15	OptBlockID (VarInt)	0 for absent (implies air); otherwise, a block state ID as per the global palette
16	NBT
17	Particle
18	Villager Data	3 VarInts: villager type, villager profession, level
19	OptVarInt	0 for absent; 1 + actual value otherwise. Used for entity IDs.
20	Pose	A VarInt enum: 0: STANDING, 1: FALL_FLYING, 2: SLEEPING, 3: SWIMMING, 4: SPIN_ATTACK, 5: SNEAKING, 6: LONG_JUMPING, 7: DYING, 8: CROAKING, 9: USING_TONGUE, 10: SITTING, 11: ROARING, 12: SNIFFING, 13: EMERGING, 14: DIGGING, 15: SLIDING, 16: SHOOTING, 17: INHALING
21	Cat Variant	A VarInt that points towards the CAT_VARIANT registry.
22	Frog Variant	A VarInt that points towards the FROG_VARIANT registry.
23	OptGlobalPos (Boolean + GlobalPos)	GlobalPos consists of a dimension identifier and Position.
24	Painting Variant	A VarInt that points towards the PAINTING_VARIANT registry.
25	Sniffer State	A VarInt enum: IDLING = 0, FEELING_HAPPY = 1, SCENTING = 2, SNIFFING = 3, SEARCHING = 4, DIGGING = 5, RISING = 6
26	Vector3	3 Floats: x, y, z
27	Quaternion	4 Floats: x, y, z, w

Abstract Vehicle

Extends Entity.

Index	Type	Meaning		Default
8	VarInt	Shaking power		0
9	VarInt	Shaking direction		1
10	Float	Shaking multiplier		0.0

Abstract Minecart

Extends Abstract Vehicle.

Index	Type	Meaning		Default
8	VarInt	Shaking power		0
9	VarInt	Shaking direction		1
10	Float	Shaking multiplier		0.0
11	VarInt	Custom block ID and damage		0
12	VarInt	Custom block Y position (in 16ths of a block)		6
13	Boolean	Show custom block		false

Boat

Extends Abstract Vehicle.

Index	Type	Meaning		Default
8	VarInt	Time since last hit		0
9	VarInt	Forward direction		1
10	Float	Damage taken		0.0
11	VarInt	Type (0=oak, 1=spruce, 2=birch, 3=jungle, 4=acacia, 5=dark oak)		0
12	Boolean	Is left paddle turning		false
13	Boolean	Is right paddle turning		false
14	VarInt	Splash timer		0

Block Actions

No changes so far.

Inventories

No changes so far.

Plugin Channels

No changes so far.

Status

Clientbound

No changes so far.

Serverbound

No changes so far.

Login

Clientbound

No changes so far.

Serverbound

No changes so far.

Configuration

Clientbound

Feature Flags

Used to enable and disable features, generally experimental ones, on the client.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x07	Configuration	Client	Total Features	VarInt	Number of features that appear in the array below.
			Feature Flags	Identifier Array

As of 1.20.2 1.20.3, the following feature flags are available:

• minecraft:vanilla - enables vanilla features
• minecraft:bundle - enables support for the bundle
• minecraft:trade_rebalance - enables support for the rebalanced villager trades
• minecraft:update_1_21 - enables support for 1.21 features

Serverbound

No changes so far.

Play

Clientbound

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

There is currently a disparity in the Notchian implementation between the data that is read from and written to the network. The write logic only serializes the particle id for the fields Small explosion particle and Large explosion particle, while the read logic expects the particle id and extra required data. See MC-266537 for more information.

Packet ID	State	Bound To	Field Name		Field Type	Notes
0x1E	Play	Client	X		Double
			Y		Double
			Z		Double
			Strength		Float	A strength greater than or equal to 2.0 spawns a minecraft:explosion_emitter particle, while a lesser strength spawns a minecraft:explosion particle. 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.
			Player Motion X		Float	X velocity of the player being pushed by the explosion.
			Player Motion Y		Float	Y velocity of the player being pushed by the explosion.
			Player Motion Z		Float	Z velocity of the player being pushed by the explosion.
			Block interaction		VarInt Enum	0 = keep, 1 = destroy, 2 = destroy_with_decay, 3 = trigger_block.
			Small explosion particle		VarInt	The particle ID listed in the particle data type.
			Large explosion particle		VarInt	The particle ID listed in the particle data type.
			Explosion sound	Sound Name	Identifier	The name of the sound played.
				Has Fixed Range	Optional Boolean	Whether is has fixed range.
				Range	Optional Float	The fixed range of the sound. Only present if previous boolean is true.

Game Event

Used for a wide variety of game events, from weather to bed use to game mode to demo messages.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x20	Play	Client	Event	Unsigned Byte	See below.
			Value	Float	Depends on Event.

Events:

Event	Effect	Value
0	No respawn block available	Note: Displays message 'block.minecraft.spawn.not_valid' (You have no home bed or charged respawn anchor, or it was obstructed) to the player.
1	Begin raining
2	End raining
3	Change game mode	0: Survival, 1: Creative, 2: Adventure, 3: Spectator.
4	Win game	0: Just respawn player. 1: Roll the credits and respawn player. Note that 1 is only sent by notchian server when player has not yet achieved advancement "The end?", else 0 is sent.
5	Demo event	0: Show welcome to demo screen. 101: Tell movement controls. 102: Tell jump control. 103: Tell inventory control. 104: Tell that the demo is over and print a message about how to take a screenshot.
6	Arrow hit player	Note: Sent when any player is struck by an arrow.
7	Rain level change	Note: Seems to change both sky color and lighting. Rain level ranging from 0 to 1.
8	Thunder level change	Note: Seems to change both sky color and lighting (same as Rain level change, but doesn't start rain). It also requires rain to render by notchian client. Thunder level ranging from 0 to 1.
9	Play pufferfish sting sound
10	Play elder guardian mob appearance (effect and sound)
11	Enable respawn screen	0: Enable respawn screen. 1: Immediately respawn (sent when the doImmediateRespawn gamerule changes).
12	Limited crafting	0: Disable limited crafting. 1: Enable limited crafting (sent when the doLimitedCrafting gamerule changes).
13	Start waiting for level chunks	Instructs the client to begin the waiting process for the level chunks. Sent by the server after the level is cleared on the client and is being re-sent (either during the first, or subsequent reconfigurations).

Set Ticking State

Used to adjust the ticking rate of the client, and whether it's frozen.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x6C	Play	Server	Tick rate	Float
			Is frozen	Boolean

Step Tick

Advances the client processing by the specified number of ticks. Has no effect is the client ticking is not frozen.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x6D	Play	Client	Tick steps	VarInt

Serverbound

Change Container Slot State

This packet is sent by the client when toggling the state of a Crafter.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x0F	Play	Server	Slot ID	VarInt	This is the ID of the slot that was changed.
			Window ID	VarInt	This is the ID of the window that was changed.
			State	Boolean	The new state of the slot. True for enabled, false for disabled.

Program Jigsaw Block

Sent when Done is pressed on the Jigsaw Block interface.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x2F	Play	Server	Location	Position	Block entity location
			Name	Identifier
			Target	Identifier
			Pool	Identifier
			Final state	String (32767)	"Turns into" on the GUI, final_state in NBT.
			Joint type	String (32767)	rollable if the attached piece can be rotated, else aligned.
			Selection priority	VarInt
			Placement priority	VarInt