Pre-release protocol

Under construction In light of the recent release of Minecraft 1.9, this article still contains some changes between 1.8.9 and 1.9, which are currently being merged into Protocol. If you want to contribute, please coordinate with us in #mcdevs, and ping Fenhl before making any edits.

This page documents the changes from the last stable Minecraft release (currently 1.9, protocol 107) to the current pre-release (currently 1.9.1-pre2, protocol 108). 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
0x23	Join Game	Current	Pre
0x25	Entity Relative Move	Current	Pre
0x26	Entity Look And Relative Move	Current	Pre
0x3A	Attach Entity	Current	Pre
Play serverbound
0x00	Teleport Confirm		Pre
0x01	Tab-Complete	Current	Pre
0x03	Client Status	Current	Pre
0x04	Client Settings	Current	Pre
0x0A	Use Entity	Current	Pre
0x10	Vehicle Move (serverbound)		Pre
0x11	Steer Boat		Pre
0x13	Player Digging	Current	Pre
0x14	Entity Action	Current	Pre
0x19	Update Sign	Current	Pre
0x1A	Animation	Current	Pre
0x1C	Player Block Placement	Current	Pre
0x1D	Use Item		Pre

New/modified data types

None so far.

Handshaking

Clientbound

No changes so far.

Serverbound

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 107 108)
			Server Address	String	hostname or IP, e.g. localhost or 127.0.0.1 (does this support IPv6?)
			Server Port	Unsigned Short	default is 25565
			Next State	VarInt Enum	1 for status, 2 for login

Play

Clientbound

Join Game

See Protocol Encryption for information on logging in.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x23	Play	Client	Entity ID	Int	The player's Entity ID (EID)
			Gamemode	Unsigned Byte	0: Survival, 1: Creative, 2: Adventure, 3: Spectator. Bit 3 (0x8) is the hardcore flag.
			Dimension	Byte Int Enum	-1: Nether, 0: Overworld, 1: End
			Difficulty	Unsigned Byte	0: peaceful, 1: easy, 2: normal, 3: hard
			Max Players	Unsigned Byte	Used by the client to draw the player list
			Level Type	String	default, flat, largeBiomes, amplified, default_1_1
			Reduced Debug Info	Boolean	If true, a Notchian client shows reduced information on the debug screen.

Entity Relative Move

This packet is sent by the server when an entity moves less then 8 blocks; if an entity moves more than 8 blocks Entity Teleport should be sent instead.

This packet allows at most 8 blocks movement in any direction, because short range is from -32768 to 32767. And 32768/(128*32)=8.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x15 0x25	Play	Client	Entity ID	VarInt
			Delta X	Byte Short	Change in X position as a Fixed-Point number (currentX * 32 - prevX * 32) * 128
			Delta Y	Byte Short	Change in Y position as a Fixed-Point number (currentY * 32 - prevY * 32) * 128
			Delta Z	Byte Short	Change in Z position as a Fixed-Point number (currentZ * 32 - prevZ * 32) * 128
			On Ground	Boolean

Entity Look And Relative Move

This packet is sent by the server when an entity rotates and moves. Since a short range is limited from -32768 to 32767, and movement is offset of fixed-point numbers, this packet allows at most 8 blocks movement in any direction. (-32768/(32*128) == -8)

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x17 0x26	Play	Client	Entity ID	VarInt
			Delta X	Byte Short	Change in X position as a Fixed-Point number (currentX * 32 - prevX * 32) * 128
			Delta Y	Byte Short	Change in Y position as a Fixed-Point number (currentY * 32 - prevY * 32) * 128
			Delta Z	Byte Short	Change in Z position as a Fixed-Point number (currentZ * 32 - prevZ * 32) * 128
			Yaw	Angle	New angle, not a delta
			Pitch	Angle	New angle, not a delta
			On Ground	Boolean

Attach Entity

This packet is sent when a player has been attached to an entity (e.g. Minecart).

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x1B 0x3A	Play	Client	Entity ID	Int	Attached entity's EID
			Vehicle ID	Int	Vechicle's Entity ID. Set to -1 to detach
			Leash	Boolean	If true leashes the entity to the vehicle

Serverbound

Teleport Confirm

Sent by client as confirmation of Player Position And Look packet.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x00	Play	Server	Teleport ID	VarInt

Tab-Complete

Sent when the user presses tab while writing text.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x14 0x01	Play	Server	Text	String	All text behind the cursor (e.g. to the left of the cursor in left-to-right languages like English)
			Assume Command	Boolean	If true, the server will parse Text as a command even if it doesn't start with a /. Used in the command block GUI.
			Has Position	Boolean
			Looked At Block	Optional Position	The position of the block being looked at. Only sent if Has Position is true.

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
0x16 0x03	Play	Server	Action ID	VarInt Enum	See below

Action ID values:

Action ID	Action
0	Perform respawn
1	Request stats
2	Taking Inventory achievement Open Inventory

Client Settings

Sent when the player connects, or when settings are changed.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x15 0x04	Play	Server	Locale	String	e.g. en_GB
			View Distance	Byte	Client-side render distance, in chunks
			Chat Mode	Byte VarInt Enum	0: enabled, 1: commands only, 2: hidden
			Chat Colors	Boolean	“Colors” multiplayer setting
			Displayed Skin Parts	Unsigned Byte	Skin parts, see note 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) appears to be unused.

Use Entity

This packet is sent from the client to the server when the client attacks or right-clicks another entity (a player, minecart, etc).

A Notchian server only accepts this packet if the entity being attacked/used is visible without obstruction and within a 4-unit radius of the player's position.

Note that middle-click in creative mode is interpreted by the client and sent as a Creative Inventory Action packet instead.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x02 0x0A	Play	Server	Target	VarInt
			Type	VarInt Enum	0: interact, 1: attack, 2: interact at
			Target X	Optional Float	Only if Type is interact at
			Target Y	Optional Float	Only if Type is interact at
			Target Z	Optional Float	Only if Type is interact at
			Hand	Optional VarInt Enum	Only if Type is interact or interact at; 0: main hand, 1: off hand

Vehicle Move (serverbound)

Sent when a player moves in a vehicle. Fields are the same as in Player Position And Look. Note that all fields use absolute positioning and do not allow for relative positioning.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x10	Play	Server	X	Double	Absolute position (X coordinate)
			Y	Double	Absolute position (Y coordinate)
			Z	Double	Absolute position (Z coordinate)
			Yaw	Float	Absolute rotation on the vertical Axis, in degrees
			Pitch	Float	Absolute rotation on the horizontal Axis, in degrees

Steer Boat

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x11	Play	Server	Boolean	Unknown
			Boolean	Unknown 2

Player Digging

Sent when the player mines a block. A Notchian server only accepts digging packets with coordinates within a 6-unit radius of the player's position.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x07 0x13	Play	Server	Status	Byte 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)

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: depends 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	Location is always set to 0/0/0, Face is always set to Special.
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 (or the Special value used for “shoot arrow / finish eating”):

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

Entity Action

Sent at least when crouching, leaving a bed, or sprinting. To send action animation to client use 0x28. The client will send this with Action ID = 3 when “Leave Bed” is clicked.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x0B 0x14	Play	Server	Entity ID	VarInt	Player ID
			Action ID	VarInt Enum	The ID of the action, see below
			Jump Boost	VarInt	Horse jump boost. Ranged from 0 to 100.

Action ID can be one of the following values:

ID	Action
0	Crouch
1	Uncrouch
2	Leave bed
3	Start sprinting
4	Stop sprinting
5	Start Jump with horse
6	Stop Jump with horse
7	Open ridden horse inventory
8	Start Elytra Flying

“Open inventory” is now sent via the Client Status packet.

Update Sign

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

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x12 0x19	Play	Server	Location	Position	Block Coordinates
			Line 1	Chat String	First line of text in the sign
			Line 2	Chat String	Second line of text in the sign
			Line 3	Chat String	Third line of text in the sign
			Line 4	Chat String	Fourth line of text in the sign

Animation

Sent when the player's arm swings.

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x0A 0x1A	Play	Server	Hand	VarInt Enum	Hand used for the animation

Player Block Placement

Packet ID	State	Bound To	Field Name	Field Type	Notes
0x08 0x1C	Play	Server	Location	Position	Block position
			Face	Byte VarInt Enum	The face on which the block is placed (as documented at Player Digging)
			Held Item	Slot
			Hand	VarInt Enum	The hand from which the block is placed; 0: main hand, 1: off hand
			Cursor Position X	Unsigned Byte	The position of the crosshair on the block, from 0 to 15 increasing from west to east
			Cursor Position Y	Unsigned Byte	The position of the crosshair on the block, from 0 to 15 increasing from bottom to top
			Cursor Position Z	Unsigned Byte	The position of the crosshair on the block, from 0 to 15 increasing from north to south

In normal operation (i.e. placing a block), this packet is sent once, with the values set normally.

The Cursor Position X/Y/Z fields (also known as in-block coordinates) are calculated using raytracing. The unit corresponds to one pixel in the default resource pack. For example, let's say a slab is being placed against the south face of a full block. The Cursor Position X will be higher if the player was pointing near the right (east) edge of the face, lower if pointing near the left. The Cursor Position Y will be used to determine whether it will appear as a bottom slab (values 0–7) or as a top slab (values 8–15). The Cursor Position Z should be 15 since the player was looking at the southernmost part of the block.

This packet has a special case where X, Y, Z, and Direction are all -1. (Note that Y is unsigned so set to 255.) This special packet indicates that the currently held item for the player should have its state updated such as eating food, pulling back bows, using buckets, etc.

Special note on using buckets: When using buckets, the Notchian client might send two packets: first a normal and then a special case. The first normal packet is sent when you're looking at a block (e.g. the water you want to scoop up). This normal packet does not appear to do anything with a Notchian server. The second, special case packet appears to perform the action — based on current position/orientation and with a distance check — it appears that buckets can only be used within a radius of 6 units.

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
0x1D	Play	Server	Hand	VarInt Enum	Hand used for the animation

Status

Clientbound

No changes so far.

Serverbound

No changes so far.

Login

Clientbound

No changes so far.

Serverbound

No changes so far.