Pre-release protocol

This page documents the changes from the last stable Minecraft release (currently 1.19.4, protocol 762) to the current pre-release (currently 23w18a, protocol Snapshot 133). 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.

ID	Packet name	Documentation
Play clientbound
0x24	Chunk Data and Update Light	Current	Pre
0x27	Update Light	Current	Pre
0x31	Open Sign Editor	Current	Pre
0x43	Update Section Blocks	Current	Pre
0x69	Update Advancements	Current	Pre
0x6B	Feature Flags	Current	Pre
0x6D	Update Recipes	Current	Pre
Play serverbound
0x2E	Update Sign	Current	Pre

New/modified data types

No changes so far.

Entity Metadata

No changes so far.

Entity

No changes so far.

Block Actions

No changes so far.

Inventories

Type	Name	Description
0	minecraft:generic_9x1	A 1-row inventory, not used by the notchian server.
1	minecraft:generic_9x2	A 2-row inventory, not used by the notchian server.
2	minecraft:generic_9x3	General-purpose 3-row inventory. Used by Chest, minecart with chest, ender chest, and barrel
3	minecraft:generic_9x4	A 4-row inventory, not used by the notchian server.
4	minecraft:generic_9x5	A 5-row inventory, not used by the notchian server.
5	minecraft:generic_9x6	General-purpose 6-row inventory, used by large chests.
6	minecraft:generic_3x3	General-purpose 3-by-3 square inventory, used by Dispenser and Dropper
7	minecraft:anvil	Anvil
8	minecraft:beacon	Beacon
9	minecraft:blast_furnace	Blast Furnace
10	minecraft:brewing_stand	Brewing stand
11	minecraft:crafting	Crafting table
12	minecraft:enchantment	Enchantment table
13	minecraft:furnace	Furnace
14	minecraft:grindstone	Grindstone
15	minecraft:hopper	Hopper or minecart with hopper
16	minecraft:lectern	Lectern
17	minecraft:loom	Loom
18	minecraft:merchant	Villager, Wandering Trader
19	minecraft:shulker_box	Shulker box
20	minecraft:legacy_smithing	Smithing Table The Notchian server only sends this type if feature flag update_1_20 was not enabled
21 20	minecraft:smithing	Smithing Table ~~The Notchian server only sends this type if feature flag update_1_20 was enabled~~
22 21	minecraft:smoker	Smoker
23 22	minecraft:cartography	Cartography Table
24 23	minecraft:stonecutter	Stonecutter

Plugin Channels

No changes so far.

Play

Clientbound

Chunk Data and Update Light

Main article: Chunk Format

See also: #Unload Chunk

	The following information needs to be added to this page:
	How do biomes work now? The biome change happened at the same time as the seed change, but it's not clear how/if biomes could be computed given that it's not the actual seed... (/r/mojira discussion which notes that it seems to be some kind of interpolation)

This packet sends all block entities in the chunk (though sending them is not required; it is still legal to send them with Block Entity Data later). The light data in this packet is the same format as in the Update Light packet.

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x24	Play	Client	Chunk X		Int		Chunk coordinate (block coordinate divided by 16, rounded down)
			Chunk Z		Int		Chunk coordinate (block coordinate divided by 16, rounded down)
			Heightmaps		NBT		Compound containing one long array named `MOTION_BLOCKING`, which is a heightmap for the highest solid block at each position in the chunk (as a compacted long array with 256 entries, with the number of bits per entry varying depending on the world's height, defined by the formula `ceil(log2(height + 1))`). The Notchian server also adds a `WORLD_SURFACE` long array, the purpose of which is unknown, but it's not required for the chunk to be accepted.
			Size		VarInt		Size of Data in bytes
			Data		Byte array		See data structure in Chunk Format
			Number of block entities		VarInt		Number of elements in the following array
			Block Entity	Packed XZ	Array	Byte	The packed section coordinates, calculated from `((blockX & 15) << 4) \| (blockZ & 15)`
				Y		Short	The height relative to the world
				Type		VarInt	The type of block entity
				Data		NBT	The block entity's data, without the X, Y, and Z values
			Trust Edges		Boolean		If edges should be trusted for light updates.
			Sky Light Mask		BitSet		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has data in the Sky Light array below. The least significant bit is for blocks 16 blocks to 1 block below the min world height (one section below the world), while the most significant bit covers blocks 1 to 16 blocks above the max world height (one section above the world).
			Block Light Mask		BitSet		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has data in the Block Light array below. The order of bits is the same as in Sky Light Mask.
			Empty Sky Light Mask		BitSet		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has all zeros for its Sky Light data. The order of bits is the same as in Sky Light Mask.
			Empty Block Light Mask		BitSet		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has all zeros for its Block Light data. The order of bits is the same as in Sky Light Mask.
			Sky Light array count		VarInt		Number of entries in the following array; should match the number of bits set in Sky Light Mask
			Sky Light arrays	Length	Array	VarInt	Length of the following array in bytes (always 2048)
			Sky Light arrays	Sky Light array	Array	Array of 2048 bytes	There is 1 array for each bit set to true in the sky light mask, starting with the lowest value. Half a byte per light value. Indexed `((y<<8) \| (z<<4) \| x) / 2` If there's a remainder, masked 0xF0 else 0x0F.
			Block Light array count		VarInt		Number of entries in the following array; should match the number of bits set in Block Light Mask
			Block Light arrays	Length	Array	VarInt	Length of the following array in bytes (always 2048)
			Block Light arrays	Block Light array	Array	Array of 2048 bytes	There is 1 array for each bit set to true in the block light mask, starting with the lowest value. Half a byte per light value. Indexed `((y<<8) \| (z<<4) \| x) / 2` If there's a remainder, masked 0xF0 else 0x0F.

Note that the Notchian client requires an Set Center Chunk packet when it crosses a chunk border, otherwise it'll only display render distance + 2 chunks around the chunk it spawned in.

The compacted array format has been adjusted so that individual entries no longer span across multiple longs, affecting the main data array and heightmaps.

New format, 5 bits per block, containing the following references to blocks in a palette (not shown): 122344566480743131516914101202

0020863148418841 0000000000100000100001100011000101001000010000011000100001000001
01018A7260F68C87 0000000100000001100010100111001001100000111101101000110010000111

Update Light

Updates light levels for a chunk. See Light for information on how lighting works in Minecraft.

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x27	Play	Client	Chunk X		VarInt		Chunk coordinate (block coordinate divided by 16, rounded down)
			Chunk Z		VarInt		Chunk coordinate (block coordinate divided by 16, rounded down)
			Trust Edges		Boolean		If edges should be trusted for light updates.
			Sky Light Mask		BitSet		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has data in the Sky Light array below. The least significant bit is for blocks 16 blocks to 1 block below the min world height (one section below the world), while the most significant bit covers blocks 1 to 16 blocks above the max world height (one section above the world).
			Block Light Mask		BitSet		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has data in the Block Light array below. The order of bits is the same as in Sky Light Mask.
			Empty Sky Light Mask		BitSet		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has all zeros for its Sky Light data. The order of bits is the same as in Sky Light Mask.
			Empty Block Light Mask		BitSet		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has all zeros for its Block Light data. The order of bits is the same as in Sky Light Mask.
			Sky Light array count		VarInt		Number of entries in the following array; should match the number of bits set in Sky Light Mask
			Sky Light arrays	Length	Array	VarInt	Length of the following array in bytes (always 2048)
			Sky Light arrays	Sky Light array	Array	Array of 2048 bytes	There is 1 array for each bit set to true in the sky light mask, starting with the lowest value. Half a byte per light value.
			Block Light array count		VarInt		Number of entries in the following array; should match the number of bits set in Block Light Mask
			Block Light arrays	Length	Array	VarInt	Length of the following array in bytes (always 2048)
			Block Light arrays	Block Light array	Array	Array of 2048 bytes	There is 1 array for each bit set to true in the block light mask, starting with the lowest value. Half a byte per light value.

A bit will never be set in both the block light mask and the empty block light mask, though it may be present in neither of them (if the block light does not need to be updated for the corresponding chunk section). The same applies to the sky light mask and the empty sky light mask.

Open Sign Editor

Sent when the client has placed a sign and is allowed to send Update Sign. There must already be a sign at the given location (which the client does not do automatically) - send a Block Update first.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x31	Play	Client	Location	Position
0x31	Play	Client	Is Front Text	Boolean	Whether the opened editor is for the front or on the back of the sign

Update Section Blocks

Fired whenever 2 or more blocks are changed within the same chunk on the same tick.

Changing blocks in chunks not loaded by the client is unsafe (see note on Block Update).

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x43	Play	Client	Chunk section position	Long	Chunk section coordinate (encoded chunk x and z with each 22 bits, and section y with 20 bits, from left to right).
			Suppress Light Updates	Boolean	Whether to ignore light updates caused by the contained changes. Always inverse the preceding Update Light packet's "Trust Edges" bool
			Blocks array size	VarInt	Number of elements in the following array.
			Blocks	Array of VarLong	Each entry is composed of the block state id, shifted left by 12, and the relative block position in the chunk section (4 bits for x, z, and y, from left to right).

Chunk section position is encoded:

((sectionX & 0x3FFFFF) << 42) | (sectionY & 0xFFFFF) | ((sectionZ & 0x3FFFFF) << 20);

and decoded:

sectionX = long >> 42;
sectionY = long << 44 >> 44;
sectionZ = long << 22 >> 42;

Blocks are encoded:

blockStateId << 12 | (blockLocalX << 8 | blockLocalZ << 4 | blockLocalY)
//Uses the local position of the given block position relative to its respective chunk section

Update Advancements

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x69	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.
			Advancement mapping	Value	Array	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.
			Progress mapping	Value	Array	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.
Criteria	Value	Array	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.
Requirements	Requirement	Array	Array of String	Array of required criteria.
Sends telemetry data		Boolean		Whether the client should include this achievement in the telemetry data when it's completed. The Notchian client only sends data for advancements on the `minecraft` namespace.

Advancement display:

Field Name	Field Type	Notes
Title	Chat
Description	Chat
Icon	Slot
Frame type	VarInt Enum	0 = `task`, 1 = `challenge`, 2 = `goal`.
Flags	Int	0x01: has background texture; 0x02: `show_toast`; 0x04: `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.
Criteria	Criterion progress	Array	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`.

Feature Flags

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

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

As of ~~1.19.4~~ 1.20, the following feature flags are available:

minecraft:vanilla - enables vanilla features
minecraft:bundle - enables support for the bundle
~~minecraft:update_1_20 - enables all the Minecraft 1.20 features that are available in 1.19.4~~

Update Recipes

Packet ID	State	Bound To	Field Name		Field Type		Notes
0x6D	Play	Client	Num Recipes		VarInt		Number of elements in the following array.
			Recipe	Type	Array	Identifier	The recipe type, see below.
				Recipe ID		Identifier
				Data		Varies	Additional data for the recipe.

Recipe types:

Type Description Data

minecraft:crafting_shapeless

Shapeless crafting recipe. All items in the ingredient list must be present, but in any order/slot.

As follows:

Name	Type	Description
Group	String	Used to group similar recipes together in the recipe book. Tag is present in recipe JSON.
Category	VarInt Enum	Building = 0, Redstone = 1, Equipment = 2, Misc = 3
Ingredient count	VarInt	Number of elements in the following array.
Ingredients	Array of Ingredient.
Result	Slot

minecraft:crafting_shaped

Shaped crafting recipe. All items must be present in the same pattern (which may be flipped horizontally or translated).

As follows:

Name	Type	Description
Width	VarInt
Height	VarInt
Group	String	Used to group similar recipes together in the recipe book. Tag is present in recipe JSON.
Category	VarInt Enum	Building = 0, Redstone = 1, Equipment = 2, Misc = 3
Ingredients	Array of Ingredient	Length is `width * height`. Indexed by `x + (y * width)`.
Result	Slot
Show notification	Boolean	Show a toast when the recipe is added.

minecraft:crafting_special_armordye

Recipe for dying leather armor

As follows:

Name	Type	Description
Category	VarInt Enum	Building = 0, Redstone = 1, Equipment = 2, Misc = 3

minecraft:crafting_special_bookcloning Recipe for copying contents of written books

minecraft:crafting_special_mapcloning Recipe for copying maps

minecraft:crafting_special_mapextending Recipe for adding paper to maps

minecraft:crafting_special_firework_rocket Recipe for making firework rockets

minecraft:crafting_special_firework_star Recipe for making firework stars

minecraft:crafting_special_firework_star_fade Recipe for making firework stars fade between multiple colors

minecraft:crafting_special_repairitem Recipe for repairing items via crafting

minecraft:crafting_special_tippedarrow Recipe for crafting tipped arrows

minecraft:crafting_special_bannerduplicate Recipe for copying banner patterns

minecraft:crafting_special_shielddecoration Recipe for applying a banner's pattern to a shield

minecraft:crafting_special_shulkerboxcoloring Recipe for recoloring a shulker box

minecraft:crafting_special_suspiciousstew Recipe for crafting suspicious stews

minecraft:crafting_decorated_pot

Recipe for crafting decorated pots

~~The Notchian server only sends this recipe if feature flag update_1_20 was enabled~~

minecraft:smelting

Smelting recipe

As follows:

Name	Type	Description
Group	String	Used to group similar recipes together in the recipe book.
Category	VarInt Enum	Food = 0, Blocks = 1, Misc = 2
Ingredient	Ingredient
Result	Slot
Experience	Float
Cooking time	VarInt

minecraft:blasting Blast furnace recipe

minecraft:smoking Smoker recipe

minecraft:campfire_cooking Campfire recipe

minecraft:stonecutting

Stonecutter recipe

As follows:

Name	Type	Description
Group	String	Used to group similar recipes together in the recipe book. Tag is present in recipe JSON.
Ingredient	Ingredient
Result	Slot

minecraft:smithing

Smithing table recipe

The Notchian server only sends this recipe if feature flag update_1_20 was not enabled

As follows:

Name	Type	Description
Base	Ingredient	First item.
Addition	Ingredient	Second item.
Result	Slot

minecraft:smithing_transform

Recipe for smithing netherite gear
~~The Notchian server only sends this recipe if feature flag update_1_20 was enabled. It supersedes the minecraft:smithing recipe type~~

As follows:

Name	Type	Description
Template	Ingredient	The smithing template.
Base	Ingredient	The base item.
Addition	Ingredient	The additional ingredient.
Result	Slot

minecraft:smithing_trim

Recipe for applying armor trims
~~The Notchian server only sends this recipe if feature flag update_1_20 was enabled. It supersedes the minecraft:smithing recipe type~~

As follows:

Name	Type	Description
Template	Ingredient	The smithing template.
Base	Ingredient	The base item.
Addition	Ingredient	The additional ingredient.

Ingredient is defined as:

Name	Type	Description
Count	VarInt	Number of elements in the following array.
Items	Array of Slot	Any item in this array may be used for the recipe. The count of each item should be 1.

Serverbound

Update Sign

This message is sent from the client to the server when the “Done” button is pushed after placing a sign.

The server only accepts this packet after Open Sign Editor, otherwise this packet is silently ignored.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x2E	Play	Server	Location	Position	Block Coordinates.
			Is Front Text	Boolean	Whether the updated text is in front or on the back of the sign
			Line 1	String (384)	First line of text in the sign.
			Line 2	String (384)	Second line of text in the sign.
			Line 3	String (384)	Third line of text in the sign.
			Line 4	String (384)	Fourth line of text in the sign.

Status

Clientbound

No changes so far.

Serverbound

No changes so far.

Login

Clientbound

No changes so far.

Serverbound

No changes so far.

Pre-release protocol

Contents

Contents

Data types

Packets

New/modified data types

Entity Metadata

Entity

Block Actions

Inventories

Plugin Channels

Play

Clientbound

Chunk Data and Update Light

Update Light

Open Sign Editor

Update Section Blocks

Update Advancements

Feature Flags

Update Recipes

Serverbound

Update Sign

Status

Clientbound

Serverbound

Login

Clientbound

Serverbound

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools