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-pre6, protocol 333). 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 | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} |
| Play clientbound | |||||
| Entity | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Entity Relative Move | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Entity Look And Relative Move | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Entity Look | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| 0x30 | Unlock Recipes | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} |
| Destroy Entities | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Remove Entity Effect | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Resource Pack Send | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Respawn | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Entity Head Look | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| 0x36 | Advancement Progress | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} |
| World Border | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Camera | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Held Item Change (clientbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Display Scoreboard | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Entity Metadata | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Attach Entity | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Entity Velocity | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Entity Equipment | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Set Experience | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Update Health | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Scoreboard Objective | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Set Passengers | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Teams | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Update Score | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Spawn Position | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Time Update | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Title | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Sound Effect | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Player List Header And Footer | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Collect Item | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Entity Teleport | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| 0x4C | Advancements | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} |
| Entity Properties | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Entity Effect | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Play serverbound | |||||
| 0x01 | Prepare Crafting Grid | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} |
| Tab-Complete (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Chat Message (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Client Status | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Client Settings | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Confirm Transaction (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Enchant Item | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Click Window | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Close Window (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Plugin Message (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Use Entity | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Keep Alive (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Player | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Player Position | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Player Position And Look (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Player Look | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Vehicle Move (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Steer Boat | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Player Abilities (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Player Digging | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Entity Action | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Steer Vehicle | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| 0x17 | Crafting Book Data | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} |
| Resource Pack Status | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| 0x19 | Advancement Tab | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} |
| Held Item Change (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Creative Inventory Action | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Update Sign | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Animation (serverbound) | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Spectate | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Player Block Placement | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
| Use Item | added | Current }} | removed | unchanged | (unchanged) | Pre }} }} | |
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 | ||
Block Actions
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.
{{#if:|}}{{#if: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).|{{#if:| }}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
{{#if:|}}{{#if: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).|{{#if:| }}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)
- {{#if:|
}}{{#if:11: Set the color of a bed|{{#if:| }}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 |
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 | 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 | |||||
| 1: Displayed Recipe | Recipe ID | Int | The internal id of the displayed recipe. | |||
| 2: 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 {{#if:316| |
| 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.