Pre-release protocol

From wiki.vg
Revision as of 14:42, 18 May 2017 by Pokechu22 (talk | contribs) (1.12-pre3 to the best of my knowledge)
Jump to navigation Jump to search

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-pre3, protocol 330). 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 Current Pre
Play clientbound
0x08 Advancements Pre
0x08 0x09 Block Break Animation Current (unchanged)
0x09 0x0A Update Block Entity Current Pre
0x0A 0x0B Block Action Current (unchanged)
0x0B 0x0C Block Change Current (unchanged)
0x0C 0x0D Boss Bar Current (unchanged)
0x0D 0x0E Server Difficulty Current (unchanged)
0x0E 0x0F Tab-Complete (clientbound) Current (unchanged)
0x0F 0x10 Chat Message (clientbound) Current (unchanged)
0x10 0x11 Multi Block Change Current (unchanged)
0x11 0x12 Confirm Transation (clientbound) Current (unchanged)
0x12 0x13 Close Window (clientbound) Current (unchanged)
0x13 0x14 Open Window Current (unchanged)
0x14 0x15 Window Items Current (unchanged)
0x15 0x16 Window Property Current (unchanged)
0x16 0x17 Set Slot Current (unchanged)
0x17 0x18 Set Cooldown Current (unchanged)
0x18 0x19 Plugin Message (clientbound) Current (unchanged)
0x19 0x1A Named Sound Effect Current (unchanged)
0x1A 0x1B Disconnect (play) Current (unchanged)
0x1B 0x1C Entity Status Current (unchanged)
0x1C 0x1D Explosion Current (unchanged)
0x1D 0x1E Unload Chunk Current (unchanged)
0x1E 0x1F Change Game State Current (unchanged)
0x1F 0x20 Keep Alive (clientbound) Current (unchanged)
0x20 0x21 Chunk Data Current (unchanged)
0x21 0x22 Effect Current (unchanged)
0x22 0x23 Particle Current (unchanged)
0x23 0x24 Join Game Current (unchanged)
0x24 0x25 Particle Current (unchanged)
0x25 0x26 Entity Relative Move Current (unchanged)
0x26 0x27 Entity Look And Relative Move Current (unchanged)
0x27 0x28 Entity Look Current (unchanged)
0x28 0x29 Entity Current (unchanged)
0x29 0x2A Vehicle Move (clientbound) Current (unchanged)
0x2A 0x2B Open Sign Editor Current (unchanged)
0x2B 0x2C Player Abilities (clientbound) Current (unchanged)
0x2C 0x2D Combat Event Current (unchanged)
0x2D 0x2E Player List Item Current (unchanged)
0x2E 0x2F Player Position And Look (clientbound) Current (unchanged)
0x2F 0x30 Use Bed Current (unchanged)
0x31 Unlock Recipes Pre
0x30 0x32 Destroy Entities Current (unchanged)
0x31 0x33 Remove Entity Effect Current (unchanged)
0x32 0x34 Resource Pack Send Current (unchanged)
0x33 0x35 Respawn Current (unchanged)
0x34 0x36 Entity Head Look Current (unchanged)
0x35 0x37 World Border Current (unchanged)
0x36 0x38 Camera Current (unchanged)
0x37 0x39 Held Item Change (clientbound) Current (unchanged)
0x38 0x3A Display Scoreboard Current (unchanged)
0x39 0x3B Entity Metadata Current (unchanged)
0x3A 0x3C Attach Entity Current (unchanged)
0x3B 0x3D Entity Velocity Current (unchanged)
0x3C 0x3E Entity Equipment Current (unchanged)
0x3D 0x3F Set Experience Current (unchanged)
0x3E 0x40 Update Health Current (unchanged)
0x3F 0x41 Scoreboard Objective Current (unchanged)
0x40 0x42 Set Passengers Current (unchanged)
0x41 0x43 Teams Current (unchanged)
0x42 0x44 Update Score Current (unchanged)
0x43 0x45 Spawn Position Current (unchanged)
0x44 0x46 Time Update Current (unchanged)
0x45 0x47 Title Current (unchanged)
0x46 0x48 Sound Effect Current (unchanged)
0x47 0x49 Player List Header And Footer Current (unchanged)
0x48 0x4A Collect Item Current (unchanged)
0x49 0x4B Entity Teleport Current (unchanged)
0x4A 0x4C Entity Properties Current (unchanged)
0x4B 0x4D Entity Effect Current (unchanged)
0x4E Advancement Progress Pre
Play serverbound
0x01 Prepare Crafting Grid Pre
0x01 0x02 Tab-Complete (serverbound) Current (unchanged)
0x02 0x03 Chat Message (serverbound) Current (unchanged)
0x03 0x04 Client Status Current (unchanged)
0x04 0x05 Client Settings Current (unchanged)
0x05 0x06 Confirm Transaction (serverbound) Current (unchanged)
0x06 0x07 Enchant Item Current (unchanged)
0x07 0x08 Click Window Current (unchanged)
0x08 0x09 Close Window (serverbound) Current (unchanged)
0x09 0x0A Plugin Message (serverbound) Current (unchanged)
0x0A 0x0B Use Entity Current (unchanged)
0x0B 0x0C Keep Alive (serverbound) Current (unchanged)
0x0C 0x0D Player Position Current (unchanged)
0x0D 0x0E Player Position And Look (serverbound) Current (unchanged)
0x0E 0x0F Player Look Current (unchanged)
0x0F 0x10 Player Current (unchanged)
0x10 0x11 Vehicle Move (serverbound) Current (unchanged)
0x11 0x12 Steer Boat Current (unchanged)
0x12 0x13 Player Abilities (serverbound) Current (unchanged)
0x13 0x14 Player Digging Current (unchanged)
0x14 0x15 Entity Action Current (unchanged)
0x15 0x16 Steer Vehicle Current (unchanged)
0x17 Crafting Book Data Pre
0x16 0x18 Resource Pack Status Current (unchanged)
0x17 0x19 Held Item Change (serverbound) Current (unchanged)
0x18 0x1A Creative Inventory Action Current (unchanged)
0x19 0x1B Update Sign Current (unchanged)
0x1A 0x1C Animation (serverbound) Current (unchanged)
0x1B 0x1D Spectate Current (unchanged)
0x1C 0x1E Player Block Placement Current (unchanged)
0x1D 0x1F Use Item Current (unchanged)
0x20 Advancement Tab 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

Huh.png 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.

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

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

Advancements

Packet ID State Bound To Field Name Field Type Notes
0x08 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

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 0x0A 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)
  • 11: Set the color of a bed

Unlock Recipes

Packet ID State Bound To Field Name Field Type Notes
0x31 Play Client
Action Short The action, see below
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 ID Array Integer
Array size 2 VarInt Number of elements in the following array
Recipe ID Array Integer

Action:

  • 1 = All the recipes in the list 1 are added and their icon will be shown in the notification. The notification will only show up if all the recipes in this list weren't displayed before (removing the recipe resets this). All the recipes in the list 2 will added to the recipe book.
  • 2 = Remove all the recipes in the list 1. This allows them to re-displayed when they are readded.
  • 3 = All the recipes in the list 2 will added to the recipe book. All the recipes in list 1 will be tagged as displayed. No notification will be shown.

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
0x4E Play Client Has id Boolean Indicates if the next field is present
ID Optional Identifier

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
2 Open inventory

Crafting Book Data

Packet ID State Bound To Field Name Field Type Notes
0x17 Play Server Type Int 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
0x20 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 316 330)
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.