Note: While you may use the contents of this page without restriction to create servers, clients, bots, etc… you still need to provide attribution to #mcdevs if you copy any of the contents of this page for publication elsewhere.

Definitions

The Minecraft server accepts connections from TCP clients and communicates with them using packets. A packet is a sequence of bytes sent over the TCP connection. The meaning of a packet depends both on its packet ID and the current state of the connection. The initial state of each connection is Handshaking, and state is switched using the packets Handshake and Login Success.

Data types

All data sent over the network (except for VarInt and VarLong) is big-endian, that is the bytes are sent from most significant byte to least significant byte. The majority of everyday computers are little-endian, therefore it may be necessary to change the endianness before sending data over the network.

UTF-8 string prefixed with its size in bytes as a VarInt. Maximum length of n characters, which varies by context; up to n × 4 bytes can be used to encode n characters and both of those limits are checked. Maximum n value is 32767. The + 3 is due to the max size of a valid length VarInt.

Encoded as an unsigned 128-bit integer (or two unsigned 64-bit integers: the most significant 64 bits and then the least significant 64 bits)

Optional X

0 or size of X

A field of type X, or nothing

Whether or not the field is present must be known from the context.

Array of X

count times size of X

Zero or more fields of type X

The count must be known from the context.

X Enum

size of X

A specific value from a given list

The list of possible values and how each is encoded as an X must be known from the context. An invalid value sent by either side will usually result in the client being disconnected with an error or even crashing.

Byte Array

Varies

Depends on context

This is just a sequence of zero or more bytes, its meaning should be explained somewhere else, e.g. in the packet description. The length must also be known from the context.

Identifier

Identifiers are a namespaced location, in the form of minecraft:thing. If the namespace is not provided, it defaults to minecraft (i.e. thing is minecraft:thing. Custom content should always be in its own namespace, not the default one. The namespace should only use the characters 01​​234​5​6​78​9abcdefghijklmnopqrstuvwxyz-_; actual names may contain more symbols. The naming convention is lower_case_with_underscores. More information.

VarInt and VarLong

Variable-length format such that smaller numbers use fewer bytes. These are very similar to Protocol Buffer Varints: the 7 least significant bits are used to encode the value and the most significant bit indicates whether there's another byte after it for the next part of the number. The least significant group is written first, followed by each of the more significant groups; thus, VarInts are effectively little endian (however, groups are 7 bits, not 8).

VarInts are never longer than 5 bytes, and VarLongs are never longer than 10 bytes.

publicstaticvoidwriteVarInt(intvalue){do{bytetemp=(byte)(value&0b01111111);// Note: >>> means that the sign bit is shifted with the rest of the number rather than being left alonevalue>>>=7;if(value!=0){temp|=0b10000000;}writeByte(temp);}while(value!=0);}

publicstaticvoidwriteVarLong(longvalue){do{bytetemp=(byte)(value&0b01111111);// Note: >>> means that the sign bit is shifted with the rest of the number rather than being left alonevalue>>>=7;if(value!=0){temp|=0b10000000;}writeByte(temp);}while(value!=0);}

Note that Minecraft's VarInts are not encoded using Protocol Buffers; it's just similar. If you try to use Protocol Buffers Varints with Minecraft's VarInts, you'll get incorrect results in some cases. The major differences:

Minecraft's VarInts are all signed, but do not use the ZigZag encoding. Protocol buffers have 3 types of Varints: uint32 (normal encoding, unsigned), sint32 (ZigZag encoding, signed), and int32 (normal encoding, signed). Minecraft's are the int32 variety. Because Minecraft uses the normal encoding instead of ZigZag encoding, negative values always use the maximum number of bytes.

Minecraft's VarInts are never be longer than 5 bytes and its VarLongs will never be longer than 10 bytes, while Protocol Buffer Varints will always use 10 bytes when encoding negative numbers, even if it's an int32.

Note: The details of bit shifting are rather language dependent; the above may work in Java but probably won't in other languages without some tweaking. In particular, you will usually receive positive numbers even if the actual coordinates are negative. This can be fixed by adding something like the following:

Fixed-point numbers

Some fields may be stored as fixed-point numbers, where a certain number of bits represents the signed integer part (number to the left of the decimal point) and the rest represents the fractional part (to the right). Floating points (float and double), in contrast, keep the number itself (mantissa) in one chunk, while the location of the decimal point (exponent) is stored beside it.

Essentially, while fixed-point numbers have lower range than floating points, their fractional precision is greater for higher values. This makes them ideal for representing global coordinates of an entity in Minecraft, as it's more important to store the integer part accurately than position them more precisely within a single block (or meter).

Coordinates are often represented as a 32-bit integer, where 5 of the least-significant bits are dedicated to the fractional part, and the rest store the integer part.

Java lacks support for fractional integers directly, but you can represent them as integers. To convert from a double to this integer representation, use the following formulas:

An EID — or Entity ID — is a 4-byte sequence used to identify a specific entity. An entity's EID is unique on the entire server.

XYZ

In this document, the axis names are the same as those shown in the debug screen (F3). Y points upwards, X points east, and Z points south.

Meter

The meter is Minecraft's base unit of length, equal to the length of a vertex of a solid block. The term “block” may be used to mean “meter” or “cubic meter”.

Global palette

A table/dictionary/palette mapping nonnegative integers to block states. Block state IDs are created in a linear fashion based off of order of assignment. One block state ID allocated for each unique block state for a block; if a block has multiple properties then the number of allocated states is the product of the number of values for each property. A current list of properties and state ID ranges is found on burger.

Alternatively, the vanilla server now includes an option to export the current block state ID mapping, by running java -cp minecraft_server.jar net.minecraft.data.Main --reports. See Data Generators for more information.

Notchian

The official implementation of vanilla Minecraft as developed and released by Mojang.

Packet format

Without compression

Field Name

Field Type

Notes

Length

VarInt

Length of packet data + length of the packet ID

Packet ID

VarInt

Data

Byte Array

Depends on the connection state and packet ID, see the sections below

With compression

Once a Set Compression packet (with a non-negative threshold) is sent, zlib compression is enabled for all following packets. The format of a packet changes slighty to include the size of the uncompressed packet.

Compressed?

Field Name

Field Type

Notes

No

Packet Length

VarInt

Length of Data Length + compressed length of (Packet ID + Data)

No

Data Length

VarInt

Length of uncompressed (Packet ID + Data) or 0

Yes

Packet ID

VarInt

zlib compressed packet ID (see the sections below)

Data

Byte Array

zlib compressed packet data (see the sections below)

The length given by the Packet Length field is the number of bytes that remain in that packet, including the Data Length field.

If Data Length is set to zero, then the packet is uncompressed; otherwise it is the size of the uncompressed packet.

If compressed, the uncompressed length of (Packet ID + Data) must be equal to or over the threshold set in the packet Set Compression, otherwise the receiving party will disconnect.

Compression can be disabled by sending the packet Set Compression with a negative Threshold, or not sending the Set Compression packet at all.

Handshaking

Clientbound

There are no clientbound packets in the Handshaking state, since the protocol immediately switches to a different state after the client sends the first packet.

Calculating the center of an image: given a (width × height) grid of cells, with (0, 0) being the top left corner, the center is (max(0, width / 2 - 1), height / 2). E.g. (1, 0) for a 2×1 painting, or (1, 2) for a 4×4 painting.

List of paintings by coordinates in paintings_kristoffer_zetterstrand.png (where x and y are in pixels from the top left and width and height are in pixels or 16ths of a block):

Spawn Player

This packet is sent by the server when a player comes into visible range, not when a player joins.

This packet must be sent after the Player List Item packet that adds the player data for the client to use when spawning a player. If the Player List Item for the player spawned by this packet is not present when this packet arrives, Notchian clients will not spawn the player entity. The Player List Item packet includes skin/cape data.

Servers can, however, safely spawn player entities for players not in visible range. The client appears to handle it correctly.

Block Break Animation

0–9 are the displayable destroy stages and each other number means that there is no animation on this coordinate.

Block break animations can still be applied on air; the animation will remain visible although there is no block being broken. However, if this is applied to a transparent block, odd graphical effects may happen, including water losing its transparency. (An effect similar to this can be seen in normal gameplay when breaking ice blocks)

If you need to display several break animations at the same time you have to give each of them a unique Entity ID. The entity ID does not need to correspond to an actual entity on the client. It is valid to use a randomly generated number.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x08

Play

Client

Entity ID

VarInt

Entity ID of the entity breaking the block

Location

Position

Block Position

Destroy Stage

Byte

0–9 to set it, any other value to remove it

Update Block Entity

Sets the block entity associated with the block at the given location.

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)

The block type ID for the block. This must match the block at the given coordinates.

Block Change

Fired whenever a block is changed within the render distance.

Changing a block in a chunk that is not loaded is not a stable action. The Notchian client currently uses a shared empty chunk which is modified for all block changes in unloaded chunks; while in 1.9 this chunk never renders in older versions the changed block will appear in all copies of the empty chunk. Servers should avoid sending block changes in unloaded chunks and clients should ignore such packets.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x0B

Play

Client

Location

Position

Block Coordinates

Block ID

VarInt

The new block state ID for the block as given in the global palette. See that section for more information.

Server Difficulty

Chat Message (clientbound)

Identifying the difference between Chat/System Message is important as it helps respect the user's chat visibility options. See processing chat for more info about these positions.

Game info accepts json formatting but does not display it, although the deprecated §-based formatting works. This is not an issue when using the Title packet, so prefer that packet for displaying information in that slot. See MC-119145 for more information.

Tab-Complete (clientbound)

The server responds with a list of auto-completions of the last word sent to it. In the case of regular chat, this is a player username. Command names and parameters are also supported. The client sorts these alphabetically before listing them.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x10

Play

Client

Start

VarInt

Start of the text to replace

Length

VarInt

Length of the text to replace

Count

VarInt

Number of elements in the following array

Matches

Match

Array

String (32767)

One eligible value to insert, note that each command is sent separately instead of in a single string, hence the need for Count. Note that for instance this doesn't include a leading / on commands.

Confirm Transaction (clientbound)

A packet from the server indicating whether a request from the client was accepted, or whether there was a conflict (due to lag). If the packet was not accepted, the client must respond with a serverbound confirm transaction packet.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x12

Play

Client

Window ID

Byte

The ID of the window that the action occurred in

Action Number

Short

Every action that is to be accepted has a unique number. This number is an incrementing integer (starting at 0) with separate counts for each window ID.

Accepted

Boolean

Whether the action was accepted

Close Window (clientbound)

This packet is sent from the server to the client when a window is forcibly closed, such as when a chest is destroyed while it's open.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x13

Play

Client

Window ID

Unsigned Byte

This is the ID of the window that was closed. 0 for inventory.

Open Window

This is sent to the client when it should open an inventory, such as a chest, workbench, or furnace. This message is not sent anywhere for clients opening their own inventory.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x14

Play

Client

Window ID

Unsigned Byte

A unique id number for the window to be displayed. Notchian server implementation is a counter, starting at 1.

Window Property

This packet is used to inform the client that part of a GUI window should be updated.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x16

Play

Client

Window ID

Unsigned Byte

Property

Short

The property to be updated, see below

Value

Short

The new value for the property, see below

The meaning of the Property field depends on the type of the window. The following table shows the known combinations of window type and property, and how the value is to be interpreted.

Window type

Property

Value

Furnace

0: Fire icon (fuel left)

counting from fuel burn time down to 0 (in-game ticks)

1: Maximum fuel burn time

fuel burn time or 0 (in-game ticks)

2: Progress arrow

counting from 0 to maximum progress (in-game ticks)

3: Maximum progress

always 200 on the notchian server

Enchantment Table

0: Level requirement for top enchantment slot

The enchantment's xp level requirement

1: Level requirement for middle enchantment slot

2: Level requirement for bottom enchantment slot

3: The enchantment seed

Used for drawing the enchantment names (in SGA) clientside. The same seed is used to calculate enchantments, but some of the data isn't sent to the client to prevent easily guessing the entire list (the seed value here is the regular seed bitwise and 0xFFFFFFF0).

Set Slot

Sent by the server when an item in a slot (in a window) is added/removed.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x17

Play

Client

Window ID

Byte

The window which is being updated. 0 for player inventory. Note that all known window types include the player inventory. This packet will only be sent for the currently opened window while the player is performing actions, even if it affects the player inventory. After the window is closed, a number of these packets are sent to update the player's inventory window (0).

To set the cursor (the item currently dragged with the mouse), use -1 as Window ID and as Slot.

This packet can only be used to edit the hotbar of the player's inventory if window ID is set to 0 (slots 36 through 44). If the window ID is set to -2, then any slot in the inventory can be used but no add item animation will be played.

Set Cooldown

Applies a cooldown period to all items with the given type. Used by the Notchian server with enderpearls. This packet should be sent when the cooldown starts and also when the cooldown ends (to compensate for lag), although the client will end the cooldown automatically. Can be applied to any item, note that interactions still get sent to the server with the item but the client does not play the animation nor attempt to predict results (i.e block placing).

The NBT of the block or entity. May be a TAG_END (0) in which case no NBT is present.

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

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x1E

Play

Client

X

Float

Y

Float

Z

Float

Radius

Float

Currently unused in the client

Record Count

Int

Number of elements in the following array

Records

Array of (Byte, Byte, Byte)

Each record is 3 signed bytes long, each bytes are the XYZ (respectively) 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

Unload Chunk

Tells the client to unload a chunk column.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x1F

Play

Client

Chunk X

Int

Block coordinate divided by 16, rounded down

Chunk Z

Int

Block coordinate divided by 16, rounded down

It is legal to send this packet even if the given chunk is not currently loaded.

Change Game State

Used for a wide variety of game state things, from whether to bed use to gamemode to demo messages.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x20

Play

Client

Reason

Unsigned Byte

See below

Value

Float

Depends on Reason

Reason codes:

Reason

Effect

Value

0

Invalid Bed

Would be used to switch between messages, but the only used message is 0 for invalid bed

1

End raining

2

Begin raining

3

Change gamemode

0: Survival, 1: Creative, 2: Adventure, 3: Spectator

4

Exit end

0: Immediately send Client Status of respawn without showing end credits; 1: Show end credits and respawn at the end (or when esc is pressed). 1 is sent if the player has not yet received the "The end?" advancement, while if they do have it 0 is used.

Appears to be played when an arrow strikes another player in Multiplayer

7

Fade value

The current darkness value. 1 = Dark, 0 = Bright, Setting the value higher causes the game to change color and freeze

8

Fade time

Time in ticks for the sky to fade

9

Play pufferfish sting sound

10

Play elder guardian mob appearance (effect and sound)

Keep Alive (clientbound)

The server will frequently send out a keep-alive, each containing a random ID. The client must respond with the same packet. If the client does not respond to them for over 30 seconds, the server kicks the client. Vice versa, if the server does not send any keep-alives for 20 seconds, the client will disconnect and yields a "Timed out" exception.

The Notchian server uses a system-dependent time in milliseconds to generate the keep alive ID value.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x21

Play

Client

Keep Alive ID

Long

Chunk Data

The server only sends skylight information for chunk pillars in the Overworld, it's up to the client to know in which dimenison the player is currently located. You can also infer this information from the primary bitmask and the amount of uncompressed bytes sent. This packet also sends all block entities in the chunk (though sending them is not required; it is still legal to send them with Update Block Entity later).

All block entities in the chunk. Use the x, y, and z tags in the NBT to determine their positions.

Effect

Sent when a client is to play a sound or particle effect.

By default, the Minecraft client adjusts the volume of sound effects based on distance. The final boolean field is used to disable this, and instead the effect is played from 2 blocks away in the correct direction. Currently this is only used for effect 1023 (wither spawn) and effect 1028 (enderdragon death); it is ignored on other effects.

Play record: This is actually a special case within this packet. You can start/stop a record at a specific location. Use a valid Record ID to start a record (or overwrite a currently playing one), any other value will stop the record. See Data Generators for information on item IDs.

For icons, a direction of 0 is a vertical icon and increments by 22.5° (360/16).

Types are based off of rows and columns in map_icons.png:

Icon type

Result

0

White arrow (players)

1

Green arrow (item frames)

2

Red arrow

3

Blue arrow

4

White cross

5

Red pointer

6

White circle (off-map players)

7

Small white circle (far-off-map players)

8

Mansion

9

Temple

10

White Banner

11

Orange Banner

12

Magenta Banner

13

Light Blue Banner

14

Yellow Banner

15

Lime Banner

16

Pink Banner

17

Gray Banner

18

Light Gray Banner

19

Cyan Banner

20

Purple Banner

21

Blue Banner

22

Brown Banner

23

Green Banner

24

Red Banner

25

Black Banner

26

Treasure marker

Entity

This packet may be used to initialize an entity.

For player entities, either this packet or any move/look packet is sent every game tick. So the meaning of this packet is basically that the entity did not move/look since the last such packet.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x27

Play

Client

Entity ID

VarInt

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

0x28

Play

Client

Entity ID

VarInt

Delta X

Short

Change in X position as (currentX * 32 - prevX * 32) * 128

Delta Y

Short

Change in Y position as (currentY * 32 - prevY * 32) * 128

Delta Z

Short

Change in Z position as (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

0x29

Play

Client

Entity ID

VarInt

Delta X

Short

Change in X position as (currentX * 32 - prevX * 32) * 128

Delta Y

Short

Change in Y position as (currentY * 32 - prevY * 32) * 128

Delta Z

Short

Change in Z position as (currentZ * 32 - prevZ * 32) * 128

Yaw

Angle

New angle, not a delta

Pitch

Angle

New angle, not a delta

On Ground

Boolean

Entity Look

This packet is sent by the server when an entity rotates.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x2A

Play

Client

Entity ID

VarInt

Yaw

Angle

New angle, not a delta

Pitch

Angle

New angle, not a delta

On Ground

Boolean

Vehicle Move (clientbound)

Note that all fields use absolute positioning and do not allow for relative positioning.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x2B

Play

Client

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

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 Change first.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x2C

Play

Client

Location

Position

Craft Recipe Response

Response to the serverbound packet (Craft Recipe Request), with the same recipe ID. Appears to be used to notify the UI.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x2D

Play

Client

Window ID

Byte

Recipe

Identifier

A recipe ID

Player Abilities (clientbound)

The latter 2 floats are used to indicate the field of view and flying speed respectively, while the first byte is used to determine the value of 4 booleans.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x2E

Play

Client

Flags

Byte

Bit field, see below

Flying Speed

Float

Field of View Modifier

Float

Modifies the field of view, like a speed potion. A Notchian server will use the same value as the movement speed (send in the Entity Properties packet).

The Property field looks as in the response of Mojang API#UUID -> Profile + Skin/Cape, except of course using the protocol format instead of JSON. That is, each player will usually have one property with Name “textures” and Value being a base64-encoded JSON string as documented at Mojang API#UUID -> Profile + Skin/Cape. An empty properties array is also acceptable, and will cause clients to display the player with one of the two default skins depending on UUID.

Ping values correspond with icons in the following way:

A ping that negative (i.e. not known to the server yet) will result in the no connection icon.

A ping under 150 milliseconds will result in 5 bars

A ping under 300 milliseconds will result in 4 bars

A ping under 600 milliseconds will result in 3 bars

A ping under 1000 milliseconds (1 second) will result in 2 bars

A ping greater than or equal to 1 second will result in 1 bar.

Face Player

Used to rotate the client player to face the given location or entity (for /teleport [<targets>] <x> <y> <z> facing).

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x31

Play

Client

Feet/eyes

VarInt enum

Values are feet=0, eyes=1. If set to eyes, aims using the head position; otherwise aims using the feet position.

Target x

Double

x coordinate of the point to face towards

Target y

Double

y coordinate of the point to face towards

Target z

Double

z coordinate of the point to face towards

Is entity

Boolean

If true, additional information about an entity is provided.

Entity ID

Optional VarInt

Only if is entity is true — the entity to face towards

Entity feet/eyes

Optional VarInt enum

Whether to look at the entity's eyes or feet. Same values and meanings as before, just for the entity's head/feet.

If the entity given by entity ID cannot be found, this packet should be treated as if is entity was false.

Player Position And Look (clientbound)

Updates the player's position on the server. This packet will also close the “Downloading Terrain” screen when joining/respawning.

If the distance between the last known position of the player on the server and the new position set by this packet is greater than 100 meters, the client will be kicked for “You moved too quickly :( (Hacking?)”.

Also if the fixed-point number of X or Z is set greater than 3.2E7D the client will be kicked for “Illegal position”.

Yaw is measured in degrees, and does not follow classical trigonometry rules. The unit circle of yaw on the XZ-plane starts at (0, 1) and turns counterclockwise, with 90 at (-1, 0), 180 at (0, -1) and 270 at (1, 0). Additionally, yaw is not clamped to between 0 and 360 degrees; any number is valid, including negative numbers and numbers greater than 360.

Pitch is measured in degrees, where 0 is looking straight ahead, -90 is looking straight up, and 90 is looking straight down.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x32

Play

Client

X

Double

Absolute or relative position, depending on Flags

Y

Double

Absolute or relative position, depending on Flags

Z

Double

Absolute or relative position, depending on Flags

Yaw

Float

Absolute or relative rotation on the X axis, in degrees

Pitch

Float

Absolute or relative rotation on the Y axis, in degrees

Flags

Byte

Bit field, see below

Teleport ID

VarInt

Client should confirm this packet with Teleport Confirm containing the same Teleport ID

About the Flags field:

<Dinnerbone> It's a bitfield, X/Y/Z/Y_ROT/X_ROT. If X is set, the x value is relative and not absolute.

Field

Bit

X

0x01

Y

0x02

Z

0x04

Y_ROT

0x08

X_ROT

0x10

Use Bed

This packet tells that a player goes to bed.

The client with the matching Entity ID will go into bed mode.

This Packet is sent to all nearby players including the one sent to bed.

Any packets sent with a location not currently occupied by a bed will be ignored by clients.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x33

Play

Client

Entity ID

VarInt

Sleeping player's EID

Location

Position

Block location of the head part of the bed

Unlock Recipes

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x34

Play

Client

Action

VarInt

0: init, 1: add, 2: remove

Crafting Recipe Book Open

Boolean

If true, then the crafting recipe book will be open when the player opens its inventory.

Crafting Recipe Book Filter Active

Boolean

If true, then the filtering option is active when the players opens its inventory.

Smelting Recipe Book Open

Boolean

If true, then the smelting recipe book will be open when the player opens its inventory.

Smelting Recipe Book Filter Active

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 Identifier

Array size 2

Optional VarInt

Number of elements in the following array, only present if mode is 0 (init)

Recipe IDs

Optional Array of Identifier, 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.

Destroy Entities

Sent by the server when a list of entities is to be destroyed on the client.

Remove Entity Effect

Resource Pack Send

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x37

Play

Client

URL

String (32767)

The URL to the resource pack.

Hash

String (40)

A 40 character hexadecimal and lowercase SHA-1 hash of the resource pack file. (must be lower case in order to work)If it's not a 40 character hexadecimal string, the client will not use it for hash verification and likely waste bandwidth — but it will still treat it as a unique id

Respawn

To change the player's dimension (overworld/nether/end), send them a respawn packet with the appropriate dimension, followed by prechunks/chunks for the new dimension, and finally a position and look packet. You do not need to unload chunks, the client will do it automatically.

Avoid changing player's dimension to same dimension they were already in unless they are dead. If you change the dimension to one they are already in, weird bugs can occur, such as the player being unable to attack other players in new world (until they die and respawn).

If you must respawn a player in the same dimension without killing them, send two respawn packets, one to a different world and then another to the world you want. You do not need to complete the first respawn; it only matters that you send two packets.

Entity Head Look

Changes the direction an entity's head is facing.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x39

Play

Client

Entity ID

VarInt

Head Yaw

Angle

New angle, not a delta

Select Advancement Tab

Sent by the server to indicate that the client should switch advancement tab. Sent either when the client switches tab in the GUI or when an advancement in another tab is made.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x3A

Play

Client

Has id

Boolean

Indicates if the next field is present

Optional Identifier

String (32767)

See below

The Identifier can be one of the following:

Optional Identifier

minecraft:story/root

minecraft:nether/root

minecraft:end/root

minecraft:adventure/root

minecraft:husbandry/root

If no or an invalid identifier is sent, the client will switch to the first tab in the GUI.

World Border

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x3B

Play

Client

Action

VarInt Enum

Determines the format of the rest of the packet

Action

Field Name

0: set size

Diameter

Double

Length of a single side of the world border, in meters

1: lerp size

Old Diameter

Double

Current length of a single side of the world border, in meters

New Diameter

Double

Target length of a single side of the world border, in meters

Speed

VarLong

Number of real-time milliseconds until New Diameter is reached. It appears that Notchian server does not sync world border speed to game ticks, so it gets out of sync with server lag. If the world border is not moving, this is set to 0.

2: set center

X

Double

Z

Double

3: initialize

X

Double

Z

Double

Old Diameter

Double

Current length of a single side of the world border, in meters

New Diameter

Double

Target length of a single side of the world border, in meters

Speed

VarLong

Number of real-time milliseconds until New Diameter is reached. It appears that Notchian server does not sync world border speed to game ticks, so it gets out of sync with server lag. If the world border is not moving, this is set to 0.

Portal Teleport Boundary

VarInt

Resulting coordinates from a portal teleport are limited to ±value. Usually 29999984.

Warning Time

VarInt

In seconds as set by /worldborder warning time

Warning Blocks

VarInt

In meters

4: set warning time

Warning Time

VarInt

In seconds as set by /worldborder warning time

5: set warning blocks

Warning Blocks

VarInt

In meters

The Notchian client determines how solid to display the warning by comparing to whichever is higher, the warning distance or whichever is lower, the distance from the current diameter to the target diameter or the place the border will be after warningTime seconds. In pseudocode:

Camera

Sets the entity that the player renders from. This is normally used when the player left-clicks an entity while in spectator mode.

The player's camera will move with the entity and look where it is looking. The entity is often another player, but can be any type of entity. The player is unable to move this entity (move packets will act as if they are coming from the other entity).

If the given entity is not loaded by the player, this packet is ignored. To return control to the player, send this packet with their entity ID.

The Notchian server resets this (sends it back to the default entity) whenever the spectated entity is killed or the player sneaks, but only if they were spectating an entity. It also sends this packet whenever the player switches out of spectator mode (even if they weren't spectating an entity).

Update Health

Sent by the server to update/set the health of the player it is sent to.

Food saturation acts as a food “overcharge”. Food values will not decrease while the saturation is over zero. Players logging in automatically get a saturation of 5.0. Eating food increases the saturation as well as the food bar.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x44

Play

Client

Health

Float

0 or less = dead, 20 = full HP

Food

VarInt

0–20

Food Saturation

Float

Seems to vary from 0.0 to 5.0 in integer increments

Scoreboard Objective

This is sent to the client when it should create a new scoreboard objective or remove one.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x45

Play

Client

Objective Name

String (16)

An unique name for the objective

Mode

Byte

0 to create the scoreboard. 1 to remove the scoreboard. 2 to update the display text.

Objective Value

Optional Chat

Only if mode is 0 or 2. The text to be displayed for the score

Type

Optional VarInt enum

Only if mode is 0 or 2. 0 = "integer", 1 = "hearts".

Set Passengers

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x46

Play

Client

Entity ID

VarInt

Vehicle's EID

Passenger Count

VarInt

Number of elements in the following array

Passengers

Array of VarInt

EIDs of entity's passengers

Teams

Creates and updates teams.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x47

Play

Client

Team Name

String (16)

A unique name for the team. (Shared with scoreboard).

Mode

Byte

Determines the layout of the remaining packet

0: create team

Team Display Name

Chat

Friendly Flags

Byte

Bit mask. 0x01: Allow friendly fire, 0x02: can see invisible players on same team

Name Tag Visibility

String Enum (32)

always, hideForOtherTeams, hideForOwnTeam, never

Collision Rule

String Enum (32)

always, pushOtherTeams, pushOwnTeam, never

Formatting

VarInt enum

See below

Team Prefix

Chat

Displayed before the names of players that are part of this team

Team Suffix

Chat

Displayed after the names of players that are part of this team

Entity Count

VarInt

Number of elements in the following array

Entities

Array of String (40)

Identifiers for the entities in this team. For players, this is their username; for other entities, it is their UUID.

1: remove team

no fields

no fields

2: update team info

Team Display Name

Chat

Friendly Flags

Byte

Bit mask. 0x01: Allow friendly fire, 0x02: can see invisible entities on same team

Name Tag Visibility

String Enum (32)

always, hideForOtherTeams, hideForOwnTeam, never

Collision Rule

String Enum (32)

always, pushOtherTeams, pushOwnTeam, never

Formatting

VarInt enum

See below

Team Prefix

Chat

Displayed before the names of players that are part of this team

Team Suffix

Chat

Displayed after the names of players that are part of this team

3: add players to team

Entity Count

VarInt

Number of elements in the following array

Entities

Array of String (40)

Identifiers for the entities added. For players, this is their username; for other entities, it is their UUID.

4: remove players from team

Entity Count

VarInt

Number of elements in the following array

Entities

Array of String (40)

Identifiers for the entities removed. For players, this is their username; for other entities, it is their UUID.

Formatting: The formatting of a team defines how the names of the team members are visualized. The following table lists all the possible formattings.

Update Score

The entity whose score this is. For players, this is their username; for other entities, it is their UUID.

Action

Byte

0 to create/update an item. 1 to remove an item.

Objective Name

String (16)

The name of the objective the score belongs to

Value

Optional VarInt

The score to be displayed next to the entry. Only sent when Action does not equal 1.

Spawn Position

Sent by the server after login to specify the coordinates of the spawn point (the point at which players spawn at, and which the compass points to). It can be sent at any time to update the point compasses point at.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x49

Play

Client

Location

Position

Spawn location

Time Update

Time is based on ticks, where 20 ticks happen every second. There are 24000 ticks in a day, making Minecraft days exactly 20 minutes long.

The time of day is based on the timestamp modulo 24000. 0 is sunrise, 6000 is noon, 12000 is sunset, and 18000 is midnight.

The default SMP server increments the time by 20 every second.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x4A

Play

Client

World Age

Long

In ticks; not changed by server commands

Time of day

Long

The world (or region) time, in ticks. If negative the sun will stop moving at the Math.abs of the time

To remove the footer, send a empty translatable component: {"translate":""}

Collect Item

Sent by the server when someone picks up an item lying on the ground — its sole purpose appears to be the animation of the item flying towards you. It doesn't destroy the entity in the client memory, and it doesn't add it to your inventory. The server only checks for items to be picked up after each Player Position (and Player Position And Look) packet sent by the client. The collector entity can be any entity, it does not have to be a player.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x4F

Play

Client

Collected Entity ID

VarInt

Collector Entity ID

VarInt

Pickup Item Count

VarInt

Seems to be 1 for XP orbs, otherwise the number of items in the stack.

Entity Teleport

This packet is sent by the server when an entity moves more than 8 blocks.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x50

Play

Client

Entity ID

VarInt

X

Double

Y

Double

Z

Double

Yaw

Angle

New angle, not a delta

Pitch

Angle

New angle, not a delta

On Ground

Boolean

Advancements

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x51

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?

0x01: Is ambient - was the effect spawned from a beacon? All beacon-generated effects are ambient. Ambient effects use a different icon in the HUD (blue border rather than gray). If all effects on an entity are ambient, the "Is potion effect ambient" living metadata field should be set to true. Usually should not be enabled.

0x02: Show particles - should all particles from this effect be hidden? Effects with particles hidden are not included in the calculation of the effect color, and are not rendered on the HUD (but are still rendered within the inventory). Usually should be enabled.

Declare Recipes

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x54

Play

Client

Num Recipes

VarInt

Number of elements in the following array

Recipe

Recipe ID

Array

Identifier

Type

String

The recipe type, see below

Data

Optional, varies

Additional data for the recipe. For some types, there will be no data.

Recipe types:

Type

Description

Data

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.

Query Block NBT

An incremental ID so that the client can verify that the response matches.

Location

Position

The location of the block to check.

Chat Message (serverbound)

Used to send a chat message to the server. The message may not be longer than 256 characters or else the server will kick the client.

If the message starts with a /, the server will attempt to interpret it as a command. Otherwise, the server will broadcast the same chat message to all players on the server (including the player that sent the message), prepended with player's name. Specifically, it will respond with a translate chat component, "chat.type.text" with the first parameter set to the display name of the player (including some chat component logic to support clicking the name to send a PM) and the second parameter set to the message. See processing chat for more information.

Tab-Complete (serverbound)

Sent when the client needs to tab-complete a minecraft:ask_server suggestion type.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x05

Play

Server

Transaction Id

VarInt

The id received in the tab completion request packet, must match or the client will ignore this packet. Client generates this and increments it each time it sends another tab completion that doesn't get a response.

Text

String (32500)

All text behind the cursor without the / (e.g. to the left of the cursor in left-to-right languages like English)

Confirm Transaction (serverbound)

If a transaction sent by the client was not accepted, the server will reply with a Confirm Transaction (clientbound) packet with the Accepted field set to false. When this happens, the client must send this packet to apologize (as with movement), otherwise the server ignores any successive transactions.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x06

Play

Server

Window ID

Byte

The ID of the window that the action occurred in

Action Number

Short

Every action that is to be accepted has a unique number. This number is an incrementing integer (starting at 1) with separate counts for each window ID.

When right-clicking on a stack of items, half the stack will be picked up and half left in the slot. If the stack is an odd number, the half left in the slot will be smaller of the amounts.

The distinct type of click performed by the client is determined by the combination of the Mode and Button fields.

Mode

Button

Slot

Trigger

0

0

Normal

Left mouse click

1

Normal

Right mouse click

1

0

Normal

Shift + left mouse click

1

Normal

Shift + right mouse click (identical behavior)

2

0

Normal

Number key 1

1

Normal

Number key 2

2

Normal

Number key 3

⋮

⋮

⋮

8

Normal

Number key 9

3

2

Normal

Middle click, only defined for creative players in non-player inventories.

4

0

Normal*

Drop key (Q) (* Clicked item is different, see above)

1

Normal*

Ctrl + Drop key (Ctrl-Q) (drops full stack)

0

-999

Left click outside inventory holding nothing (no-op)

1

-999

Right click outside inventory holding nothing (no-op)

5

0

-999

Starting left mouse drag

4

-999

Starting right mouse drag

8

-999

Starting middle mouse drag, only defined for creative players in non-player inventories. (Note: the vanilla client will still incorrectly send this for non-creative players - see MC-46584)

1

Normal

Add slot for left-mouse drag

5

Normal

Add slot for right-mouse drag

9

Normal

Add slot for middle-mouse drag, only defined for creative players in non-player inventories. (Note: the vanilla client will still incorrectly send this for non-creative players - see MC-46584)

2

-999

Ending left mouse drag

6

-999

Ending right mouse drag

10

-999

Ending middle mouse drag, only defined for creative players in non-player inventories. (Note: the vanilla client will still incorrectly send this for non-creative players - see MC-46584)

6

0

Normal

Double click

Starting from version 1.5, “painting mode” is available for use in inventory windows. It is done by picking up stack of something (more than 1 item), then holding mouse button (left, right or middle) and dragging held stack over empty (or same type in case of right button) slots. In that case client sends the following to server after mouse button release (omitting first pickup packet which is sent as usual):

packet with mode 5, slot -999, button (0 for left | 4 for right);

packet for every slot painted on, mode is still 5, button (1 | 5);

packet with mode 5, slot -999, button (2 | 6);

If any of the painting packets other than the “progress” ones are sent out of order (for example, a start, some slots, then another start; or a left-click in the middle) the painting status will be reset.

The server will send back a Confirm Transaction packet. If the click was not accepted, the client must send a matching serverbound confirm transaction packet before sending more Click Window packets, otherwise the server will reject them silently. The Notchian server also sends a Window Items packet for the open window and Set Slot packets for the clicked and cursor slot, but only when the click was not accepted, probably to resynchronize client and server.

Close Window (serverbound)

This packet is sent by the client when closing a window.

Notchian clients send a Close Window packet with Window ID 0 to close their inventory even though there is never an Open Window packet for the inventory.

This packet is used to indicate whether the player is on ground (walking/swimming), or airborne (jumping/falling).

When dropping from sufficient height, fall damage is applied when this state goes from false to true. The amount of damage applied is based on the point where it last changed from true to false. Note that there are several movement related packets containing this state.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x0F

Play

Server

On Ground

Boolean

True if the client is on the ground, false otherwise

Player Position

Updates the player's XYZ position on the server.

Checking for moving too fast is achieved like this:

Each server tick, the player's current position is stored

When a player moves, the changes in x, y, and z coordinates are compared with the positions from the previous tick (Δx, Δy, Δz)

If the total movement distance squared value minus the expected movement distance squared value is more than 100 (300 if the player is using an elytra), they are moving too fast.

If the player is moving too fast, it will be logged that "<player> moved too quickly! " followed by the change in x, y, and z, and the player will be teleported back to their current (before this packet) serverside position.

Also, if the absolute value of X or the absolute value of Z is a value greater than 3.2×107, or X, Y, or Z are not finite (either positive infinity, negative infinity, or NaN), the client will be kicked for “Invalid move player packet received”.

Player Look

The unit circle for yaw

The unit circle of yaw, redrawn

Updates the direction the player is looking in.

Yaw is measured in degrees, and does not follow classical trigonometry rules. The unit circle of yaw on the XZ-plane starts at (0, 1) and turns counterclockwise, with 90 at (-1, 0), 180 at (0,-1) and 270 at (1, 0). Additionally, yaw is not clamped to between 0 and 360 degrees; any number is valid, including negative numbers and numbers greater than 360.

Pitch is measured in degrees, where 0 is looking straight ahead, -90 is looking straight up, and 90 is looking straight down.

The yaw and pitch of player (in degrees), standing at point (x0, y0, z0) and looking towards point (x, y, z) can be calculated with:

The server will first search the player's hotbar for an empty slot, starting from the current slot and looping around to the slot before it. If there are no empty slots, it will start a second search from the current slot and find the first slot that does not contain an enchanted item. If there still are no slots that meet that criteria, then the server will use the currently selected slot.

After finding the appropriate slot, the server swaps the items and then send 3 packets:

Set Slot, with window ID set to -2 and slot set to the newly chosen slot and the item set to the item that is now in that slot (which was previously at the slot the client requested)

Set Slot, with window ID set to -2 and slot set to the slot the player requested, with the item that is now in that slot and was previously on the hotbar slot

Player Digging

Sent when the player mines a block. A Notchian server only accepts digging packets with coordinates within a 6-unit radius between the center of the block and 1.5 units from the player's feet (not their eyes).

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x18

Play

Server

Status

VarInt 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

Indicates that the currently held item should have its state updated such as eating food, pulling back bows, using buckets, etc. Location is always set to 0/0/0, Face is always set to -Y.

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:

Value

Offset

Face

0

-Y

Bottom

1

+Y

Top

2

-Z

North

3

+Z

South

4

-X

West

5

+X

East

Entity Action

Sent by the client to indicate that it has performed certain actions: sneaking (crouching), sprinting, exiting a bed, jumping with a horse, and opening a horse's inventory while riding it.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x19

Play

Server

Entity ID

VarInt

Player ID

Action ID

VarInt Enum

The ID of the action, see below

Jump Boost

VarInt

Only used by the “start jump with horse” action, in which case it ranges from 0 to 100. In all other cases it is 0.

Action ID can be one of the following values:

ID

Action

0

Start sneaking

1

Stop sneaking

2

Leave bed

3

Start sprinting

4

Stop sprinting

5

Start jump with horse

6

Stop jump with horse

7

Open horse inventory

8

Start flying with elytra

Leave bed is only sent when the “Leave Bed” button is clicked on the sleep GUI, not when waking up due today time.

Open horse inventory is only sent when pressing the inventory key (default: E) while on a horse — all other methods of opening a horse's inventory (involving right-clicking or shift-right-clicking it) do not use this packet.

Steer Vehicle

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x1A

Play

Server

Sideways

Float

Positive to the left of the player

Forward

Float

Positive forward

Flags

Unsigned Byte

Bit mask. 0x1: jump, 0x2: unmount

Also known as 'Input' packet.

Recipe Book Data

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x1B

Play

Server

Type

VarInt

Determines the format of the rest of the packet

Type

Field Name

0: Displayed Recipe

Recipe ID

Identifier

A recipe ID

1: Recipe Book States

Crafting Recipe Book Open

Boolean

Whether the player has the crafting recipe book currently opened/active.

Crafting Recipe Filter Active

Boolean

Whether the player has the crafting recipe book filter option currently active.

Smelting Recipe Book Open

Boolean

Whether the player has the smelting recipe book currently opened/active.

Smelting Recipe Filter Active

Boolean

Whether the player has the smelting recipe book filter option currently active.

The Recipe Book Status type is sent when one of the states changes.

Name Item

Sent as a player is renaming an item in an anvil (each keypress in the anvil UI sends a new Name Item packet). If the new name is empty, then the item loses its custom name (this is different from setting the custom name to the normal name of the item). The item name may be no longer than 35 characters long, and if it is longer than that, then the rename is silently ignored.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x1C

Play

Server

Item name

String (32767)

The new name of the item

Resource Pack Status

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x1D

Play

Server

Result

VarInt Enum

0: successfully loaded, 1: declined, 2: failed download, 3: accepted

Advancement Tab

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x1E

Play

Server

Action

VarInt enum

0: Opened tab, 1: Closed screen

Tab ID

Optional identifier

Only present if action is Opened tab

Select Trade

When a player selects a specific trade offered by a villager NPC.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x1F

Play

Server

Selected slot

VarInt

The selected slot int the players current (trading) inventory. (Was a full Integer for the plugin message)

Update Command Block

0x01: Track Output (if false, the output of the previous command will not be stored within the command block); 0x02: Is conditional; 0x04: Automatic

Update Command Block Minecart

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x23

Play

Server

Entity ID

VarInt

Command

String

Track Output

Boolean

If false, the output of the previous command will not be stored within the command block.

Creative Inventory Action

While the user is in the standard inventory (i.e., not a crafting bench) in Creative mode, the player will send this packet.

Clicking in the creative inventory menu is quite different from non-creative inventory management. Picking up an item with the mouse actually deletes the item from the server, and placing an item into a slot or dropping it out of the inventory actually tells the server to create the item from scratch. (This can be verified by clicking an item that you don't mind deleting, then severing the connection to the server; the item will be nowhere to be found when you log back in.) As a result of this implementation strategy, the "Destroy Item" slot is just a client-side implementation detail that means "I don't intend to recreate this item.". Additionally, the long listings of items (by category, etc.) are a client-side interface for choosing which item to create. Picking up an item from such listings sends no packets to the server; only when you put it somewhere does it tell the server to create the item in that location.

This action can be described as "set inventory slot". Picking up an item sets the slot to item ID -1. Placing an item into an inventory slot sets the slot to the specified item. Dropping an item (by clicking outside the window) effectively sets slot -1 to the specified item, which causes the server to spawn the item entity, etc.. All other inventory slots are numbered the same as the non-creative inventory (including slots for the 2x2 crafting menu, even though they aren't visible in the vanilla client).

The Notchian client uses update data to indicate no special action should be taken (i.e. the done button).

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

0x26

Play

Server

Location

Position

Block Coordinates

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

Animation (serverbound)

Sent when the player's arm swings.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x27

Play

Server

Hand

VarInt Enum

Hand used for the animation. 0: main hand, 1: off hand.

Spectate

Teleports the player to the given entity. The player must be in spectator mode.

The Notchian client only uses this to teleport to players, but it appears to accept any type of entity. The entity does not need to be in the same dimension as the player; if necessary, the player will be respawned in the right world. If the given entity cannot be found (or isn't loaded), this packet will be ignored. It will also be ignored if the player attempts to teleport to themselves.

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x28

Play

Server

Target Player

UUID

UUID of the player to teleport to (can also be an entity UUID)

Player Block Placement

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x29

Play

Server

Location

Position

Block position

Face

VarInt Enum

The face on which the block is placed (as documented at Player Digging)

Hand

VarInt Enum

The hand from which the block is placed; 0: main hand, 1: off hand

Cursor Position X

Float

The position of the crosshair on the block, from 0 to 1 increasing from west to east

Cursor Position Y

Float

The position of the crosshair on the block, from 0 to 1 increasing from bottom to top

Cursor Position Z

Float

The position of the crosshair on the block, from 0 to 1 increasing from north to south

Upon placing a block, this packet is sent once.

The Cursor Position X/Y/Z fields (also known as in-block coordinates) are calculated using raytracing. The unit corresponds to sixteen 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.0–0.5) or as a top slab (values 0.5-1.0). The Cursor Position Z should be 1.0 since the player was looking at the southernmost part of the block.

Use Item

Sent when pressing the Use Item key (default: right click) with an item in hand.

Set Compression, if present, must be sent before Login Success. Note that anything sent after Set Compression must use the Post Compression packet format.

For unauthenticated and localhost connections (either of the two conditions is enough for an unencrypted connection) there is no encryption. In that case Login Start is directly followed by Login Success.

Set Compression

Enables compression. If compression is enabled, all following packets are encoded in the compressed packet format. Negative values will disable compression, meaning the packet format should remain in the uncompressed packet format. However, this packet is entirely optional, and if not sent, compression will also not be enabled (the notchian server does not send the packet when compression is disabled).

Packet ID

State

Bound To

Field Name

Field Type

Notes

0x03

Login

Client

Threshold

VarInt

Maximum size of a packet before it is compressed

Login Plugin Request

Unlike plugin messages in "play" mode, these messages follow a lock-step request/response scheme, where the client is expected to respond to a request indicating whether it understood. The notchian client always responds that it hasn't understood, and sends an empty payload.