Packets #

This document is licensed under a Creative Commons Attribution-ShareAlike 4.0 license. Derivative works must be licensed using the same or a compatible license.

All packets begin with a single "Packet ID" byte. Listed packet size does not include this byte. Packets are either Clientbound, Serverbound, or both. Packets that travel both Clientbound and Serverbound may reuse fields for different purposes.

There is no "length" field; for variable length packets, you must parse to the end to determine the length.

Data Types#

	Size (bytes)	Range	Notes
i8	1	-128 to 127
u8	1	0 to 255
i16	2	-32768 to 32767
i32	4	-2147483648 to 2147483647
i64	8	-9223372036854775808 to 9223372036854775807
f32	4	See here.	Single-precision 32-bit IEEE754 floating point.
f64	8	See here.	Double-precision 64-bit IEEE754 floating point.
str8	>=2	N/A	Modified UTF-8 string. Prefixed by an `i16` containing the length of the string in bytes.
str16	>=2	Minimum length of `0`, maximum character length of `32767`	UTF-16 string. Prefixed by an `i16` containing the length of the string in characters.
bool	1	`0x00` (`false`) or `0x01` (`true`)

There are also additional types being used:

Entity types#

ID	Entity	Category	LivingEntity
1	Item	Misc	❌
9	Painting	Misc	❌
10	Arrow	Projectile	❌
11	Snowball	Projectile	❌
20	Primed TNT	Misc	❌
21	Falling Sand	Misc	❌
40	Minecart	Vehicle	❌
41	Boat	Vehicle	❌
50	Creeper	Hostile	✅
51	Skeleton	Hostile	✅
52	Spider	Hostile	✅
53	Giant	Hostile	✅
54	Zombie	Hostile	✅
55	Slime	Hostile	✅
56	Ghast	Hostile	✅
57	Zombie Pigman	Neutral	✅
90	Pig	Passive	✅
91	Sheep	Passive	✅
92	Cow	Passive	✅
93	Chicken	Passive	✅
94	Squid	Passive	✅
95	Wolf	Passive	✅

Entity Metadata#

Entity metadata has a quirky packing format.

A metadata field is a byte. The top three bits of the byte, when masked off ((byte & 224) >> 5) and interpreted as a three-bit number from 0 to 7, indicate the type of the field.

The lower five bits are unused. The type of the byte indicates the size and type of a payload which follows the initial byte of the field.

The metadata format consists of at least one field, followed by either another field or the magic number 0x7F. 0x7F terminates a metadata stream.

Thus, the example metadata stream 0x00 0x01 0x7f is decoded as a field of type 0, id 0, with a payload of byte 0x00.

Field ID	Field Type
0	i8
1	i16
2	i32
3	f32
4	str16 (maximum character length of 64)
5	ItemStack; `i16` ID, `i8` count, `i16` data
6	Vector of `i32`, 3 long (x,y,z)

More information is available at 0x18 Spawn Living Entity.

Packed f64#

Sent as an i32 on the wire, but is actually an f64.

Java:

public static int floorDouble(double aDouble) {
    int anInteger = (int)aDouble;
    return aDouble < (double)anInteger ? anInteger - 1 : anInteger;
}

Packed Rotation#

Sent as an i8 on the wire, but is actually an f32.

Basically, takes a rotation in degrees (0..360) and maps it into 0..255.

Java:

public static byte packRotation(float rotation) {
    return (byte)((int)(rotation * 256.0F / 360.0F))
}

Packed Motion i8#

Sent as an i8 on the wire, but is actually an f64.

Basically, just multiply the value by 128 and turn it into a (signed) byte.

Java:

public static byte packMotion(double motion) {
    return (byte)((int)(motion * 128.0D))
}

Packed Motion i16#

Sent as an i16 on the wire, but is actually an f64.

Basically, just multiply the value by 128 and turn it into a (signed) byte.

Java:

public static byte packMotion(double motion) {
    return (byte)((int)(motion * 128.0D))
}

0x00 Keep Alive#

Clientbound: [x]
Serverbound: [ ]
Size: 0

This packet must be sent to keep the connection alive.

Keep Alive has no payload.

Clientbound: [x]
Serverbound: [x]
Size: 15 + length of strings

Clientbound#

Sent by the server if it accepts the client's login request. If it didn't it will send a Disconnect instead.

Field Name	Field Type	Example	Notes
Entity ID	i32	`14`	The protocol version of Beta 1.7 is 14
Unused	str16	N/A	Unused by the client. Vanilla server sends an empty string
Map Seed	i64	`0`	Used by the client to determine its current biome, among a few other things
Dimension	i8	`0`	`-1` for the Nether, `0` for the Overworld

Serverbound#

Sent by the client after the handshake to finish logging in.

Field Name	Field Type	Example	Notes
Protocol version	i32	`14`	The protocol version of Beta 1.7 is 14
Username	str16	`kokiriglade`	The name of the player attempting to login. Max length of 16
Map Seed	i64	`0`	Can be safely ignored by the server
Dimension	i8	`0`	`-1` for the Nether, `0` for the Overworld. Can be safely ignored by the server

0x02 Handshake#

Clientbound: [x]
Serverbound: [x]
Size: 2 + length of strings

Clientbound#

Field Name	Field Type	Example	Notes
Connection Hash	str16	`2e66f1dc032ab5f0`	A unique, per-connection hash. The vanilla server sends a random `i64` stringified as a hexadecimal number. For offline-mode, the string is always a single `-`

Serverbound#

Field Name	Field Type	Example	Notes
Username	str16	`kokiriglade`	The name of the player attempting to connect. Maximum character length of 16

0x03 Chat Message#

Clientbound: [x]
Serverbound: [x]
Size: 2 + length of strings

Field Name	Field Type	Example	Notes
Message	str16	`<kokiriglade> Hello!`	The name of the player attempting to connect. Maximum character length of 119

0x04 Update Time#

Clientbound: [x]
Serverbound: [ ]
Size: 8

The time of day is based on timestamp % 24000, where:

0 is sunrise
6000 is noon
12000 is sunset
18000 is midnight

Field Name	Field Type	Example	Notes
Time	i64		The world time in ticks

0x05 Set Player Equipment#

Clientbound: [x]
Serverbound: [ ]
Size: 10

After each player spawn, there will be five of these packets for the equipped item and armor. If there are changes in visible equipment, another one of these packets is sent.

Field Name	Field Type	Example	Notes
Entity ID	i32		Player's entity ID
Slot	i16	`4`	Equipment slot. See below
Item ID	i16	`-1`	Equipped item (`-1` for aempty slot)
Data	i16		Item data value

Equipment slots#

(These only apply to this packet)

0: Held item
1: Helmet
2: Chestpate
3: Leggings
4: Boots

0x06 Spawn Position#

Clientbound: [x]
Serverbound: [ ]
Size: 12

Sent after login to specify the coordinates of the spawn point (the location at which players spawn, and which the compass points to).

It can be sent at any time to update the point compasses point to.

Field Name	Field Type	Example	Notes
X	i32	`117`	Spawn X in block coordinates
Y	i32	`70`	Spawn Y in block coordinates
Z	i32	`-46`	Spawn Z in block coordinates

0x07 Use Entity#

Clientbound: [ ]
Serverbound: [x]
Size: 9

Sent upon attacking or right clicking an entity.

Field Name	Field Type	Example	Notes
Entity ID	i32		Player's entity ID. Ignored by the server
Target entity ID	i32		Entity ID of the entity being interacted with
Left click	bool	`true`	`true` if the interaction was caused by a left click, `false` otherwise

0x08 Update Health#

Clientbound: [x]
Serverbound: [ ]
Size: 2

Field Name	Field Type	Example	Notes
Health	i16	`20`	Half a heart = 1

0x09 Respawn#

Clientbound: [X]
Serverbound: [X]
Size: 1

Sent by the client when the player presses the "Respawn" button after dying. The server then teleports the player to the spawn point, and sends a respawn packet in response. The client will not leave the respawn screen until it receives a respawn packet.

Field Name	Field Type	Example	Notes
Dimension	i8	`0`	`-1` for the Nether, `0` for the Overworld. Can be safely ignored by the server

0x0A On Ground#

Clientbound: [x]
Serverbound: [x]
Size: 1

Field Name	Field Type	Example	Notes
On Ground	bool	`true`	`true` if the player is on the ground, `false` otherwise

0x0B Player Position#

Clientbound: [x]
Serverbound: [x]
Size: 33

Updates the player position on the server. If (stance - y) < 0.1 || (stance - y) > 1.65 then the stance is illegal.

If the distance between the last known position of the player and the new position set by this packet is greater than 100, then the movement is illegal.

If the absolute number of x or z are set greater than 3.2E7 then the position is illegal.

Field Name	Field Type	Example	Notes
X	f64	`102.809`
Y	f64	`70.00`
Stance	f64	`71.62`	Used to modify the players bounding box when going up stairs, crouching, etc.
Z	f64	`68.30`
On Ground	bool	`true`	`true` if the player is on the ground, `false` otherwise

0x0C Player Look#

Clientbound: [x]
Serverbound: [x]
Size: 9

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 backwards towards (-1, 0), or in other words, it turns clockwise instead of counter-clockwise. Additionally, yaw is not clamped to between 0 and 360 degrees; any number is valid, including negative numbers and numbers greater than 360.

Field Name	Field Type	Example	Notes
Yaw	f32	`0.0`	Rotation on the X Axis, in degrees
Pitch	f32	`0.0`	Rotation on the Y axis, in degrees
On Ground	bool	`true`	`true` if the player is on the ground, `false` otherwise

0x0D Player Position and Look#

Clientbound: [x]
Serverbound: [x]
Size: 41

A combination of Player Look and Player Position.

Field Name	Field Type	Example	Notes
X	f64	`102.809`
Y	f64	`70.00`
Stance	f64	`71.62`	Used to modify the players bounding box when going up stairs, crouching, etc.
Z	f64	`68.30`
Yaw	f32	`0.0`	Rotation on the X Axis, in degrees
Pitch	f32	`0.0`	Rotation on the Y axis, in degrees
On Ground	bool	`true`	`true` if the player is on the ground, `false` otherwise

0x0E Block Dig#

Clientbound: [ ]
Serverbound: [x]
Size: 11

Sent when the player is digging a block.

Field Name	Field Type	Example	Notes
Status	i8	`1`	The action the player is taking against the block (see below)
X	i32	`32`	Block position
Y	i8	`64`	Block position
Z	i32	`32`	Block position
Face	i8	`3`	The face being hit (see below)

Status#

Status can be:

0: Started digging
2: Finished digging
4: Drop item

Special cases#

For some unthinkable reason, when the player drops an item, it sends this packet but the status is 4, and all other values are 0.

Face#

Face can be:

0: Negative Y
1: Positive Y
2: Negative Z
3: Positive Z
4: Negative X
5: Positive X

0x0F Block Interact#

Clientbound: [ ]
Serverbound: [x]
Size: 12 or 15

Sent when the player places a block or (probably) an item. The coordinates sent in this packet are actually the block being built against, which combined with the direction offset tell you where the block should be placed. This is required to correctly position furnaces, torches, etc.

Field Name	Field Type	Example	Notes
X	i32	`32`	Block position
Y	i8	`64`	Block position
Z	i32	`32`	Block position
Face	i8	`3`	The face being placed against (see Block Dig)
Block or Item ID	i16	`1`	The block or item to be placed
Count	Optional	`34`	The count of the itemstack in the players hand
Data	Optional	`83`	The data value of the itemstack

If the Block/ItemID field is greater than or equal to 0, then the last 2 fields (count and data) are read. Otherwise, they are not read.

When 'placing' (Or more accurately, using) your empty hand, the client sends -1 as the Block/Item ID.

Special cases#

This packet has a special case where X, Y, Z, and Direction are all -1. This special packet indicates that the currently held item for the player should have its state updated such as eating food, shooting bows, using buckets, etc.

When using buckets, the 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 Vanilla 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 blocks.

0x10 Change Current Slot#

Clientbound: [ ]
Serverbound: [x]
Size: 2

Sent when the player changes their current/active slot.

Field Name	Field Type	Example	Notes
Slot ID	i16	`1`	Valid values are 0..8 (inclusive)

0x11 Sleep#

Clientbound: [x]
Serverbound: [ ]
Size: 14

Sent to indicate a player is sleeping in a bed.

Field Name	Field Type	Example	Notes
Entity ID	i32	`89`	Player's entity ID
Unknown	i8	`0`	Always 0, unused
X	i32	`-247`	Block coordinate
Y	i8	`78`	Block coordinate
Z	i32	`128`	Block coordinate

0x12 Animation#

Clientbound: [x]
Serverbound: [x]
Size: 5

Field Name	Field Type	Example	Notes
Entity ID	i32	`55534`	Player's entity ID
Animate	i8	`1`	See below

Animate#

Animate can be:

0: No animation
1: Swing arm
2: Damage animation
3: Leave bed

0x13 Player Action#

Clientbound: [ ]
Serverbound: [x]
Size: 5

Sent when crouching and leaving a bed.

Field Name	Field Type	Example	Notes
Entity ID	i32	`55534`	Player's entity ID
Action	i8	`1`	See below

Action#

Action can be:

1: Start crouching
2: Stop crouching
3: Leave bed

0x14 Spawn Player#

Clientbound: [x]
Serverbound: [ ]
Size: 22 + length of strings

Sent when a player comes into visible range. The vanilla client is not okay with receiving player entity packets that refer to its own username or EID; it will teleport to the absolute origin of the map and fall through the void any time it receives them.

Field Name	Field Type	Example	Notes
Entity ID	i32	`94453`	Player's entity ID
Name	str16	`kokiriglade`	Maximum character length of 16
X	i32	`102.809`	Packed f64
Y	i32	`70.00`	Packed f64
Z	i32	`68.30`	Packed f64
Yaw	i8	`0.0`	Packed rotation
Pitch	i8	`0.0`	Packed rotation
Held Item	i16	`0`	The item the player is holding. `0` for no item. Must not be negative

0x15 Spawn Item#

Clientbound: [x]
Serverbound: [ ]
Size: 24

Sent when a thrown item comes into range of the player.

Field Name	Field Type	Example	Notes
Entity ID	i32	`157617`	Item's entity ID
Item ID	i16	`4`
Count	i8	`1`	The count of the itemstack
Data	i16	Item data
X	i32	`102.809`	Packed f64
Y	i32	`70.00`	Packed f64
Z	i32	`68.30`	Packed f64
Motion X	i8	`0.0`	Packed motion-i8
Motion Y	i8	`0.0`	Packed motion-i8
Motion Z	i8	`0.0`	Packed motion-i8

0x16 Pickup Item#

Clientbound: [x]
Serverbound: [ ]
Size: 8

Sent when someone picks up an item lying on the ground - its sole purpose is the animation of the item flying towards the player.

It doesn't destroy the entity in the client memory (Destroy Entity does that), and it doesn't add it to the player's inventory (Set Slot does that).

The server only checks for items to be picked up after each Player Position and Player Position and Look packet sent by the client.

Field Name	Field Type	Example	Notes
Collected Entity ID	i32	`28`	Collected item's entity ID
Collector Entity ID	i32	`30`	Collector's entity ID

0x17 Spawn Non-Living Entity#

Clientbound: [x]
Serverbound: [ ]
Size: 21 or 27

Sent when a Non-Living entity is created.

Field Name	Field Type	Example	Notes
Entity ID	i32	`62`
Entity Type	i8	`11`	See Entity Types (must be of kind `Living`)
X	i32	`16080`	Packed f64
Y	i32	`2290`	Packed f64
Z	i32	`592`	Packed f64
Has Motion	i32	`0`	If this flag is bigger than 0 then the following fields are sent
Motion X	i16	`0`	Packed motion-i16
Motion Y	i16	`0`	Packed motion-i16
Motion Z	i16	`0`	Packed motion-i16

0x18 Spawn Living Entity#

Clientbound: [x]
Serverbound: [ ]
Size: 19 + Metadata (at least 1)

Sent when a Living Entity is created.

Field Name	Field Type	Example	Notes
Entity ID	i32	`62`
Living Entity Type	i8	`11`	See below
X	i32	`16080`	Packed f64
Y	i32	`2290`	Packed f64
Z	i32	`592`	Packed f64
Yaw	i8	`-27`	Packed rotation
Pitch	i8	`0`	Packed rotation
Entity Metadata	Entity Metadata	`127`	Indexed metadata, terminated by `0x7F` - see below

Living Entity types#

50: Creeper
- Index 16 is i8, for fuse
  - 1 for blowing up, -1 otherwise
- Index 17 is bool, for is charged
51: Skeleton
52: Spider
53: Giant Zombie
54: Zombie
55: Slime
- Index 16 is i8, for size
56: Ghast
- Index 16 is i8, for is attacking
57: Zombie Pigman
90: Pig
- Index 16 is i8, for is saddled
91: Sheep
- Index 16 is i8 for coat
  - You can use a 0x10 bit mask for shearedness and 0x0F for color - see below
92: Cow
93: Chicken
94: Squid
95: Wolf
- Index 16 is i8, and is a bitmask:
  - 0x01 for is sitting
  - 0x02 for is aggressive
  - 0x04 for is tamed
- Index 17 is string16, and is the name of the player who tamed the wolf
- Index 18 is i32, and is the health of the wolf

Metadata index 0 is an i8 representing a set of 8 bools:

0x01: On fire
0x02: Is crouched
0x04: Is riding

Sheep colors#

0: White
1: Orange
2: Magenta
3: Light Blue
4: Yellow
5: Lime
6: Pink
7: Gray
8: Light Gray (Silver)
9: Cyan
10: Purple
11: Blue
12: Brown
13: Green
14: Red
15: Black

0x19 Spawn Painting#

Clientbound: [x]
Serverbound: [ ]
Size: 22 + length of strings

Sent when a painting is created.

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

2x1 (1, 0)
4x4 (1, 2)

Field Name	Field Type	Example	Notes
Entity ID	i32	`326`
Title	str16	`Creepers`	Name of the painting. Maximum character length of 13
X	i32	`50`	Center X coordinate
Y	i32	`66`	Center Y coordinate
Z	i32	`-50`	Center Z coordinate
Direction	i32	`0`	Direction the painting is facing, see below

Direction#

0: Negative Z
1: Negative X
2: Positive Z
3: Positive X

0x1C Update Velocity#

Clientbound: [x]
Serverbound: [ ]
Size: 10

Velocity is believed to be in units of 1/32000 of a block per server tick (200ms); for example, -1343 would move (-1343 / 32000) = -0.04196875 blocks per tick (or -0.20984375 blocks per second).

Each axis' velocity is capped between -0.9 and 0.9 blocks per tick (packet values -28800 to 28800).

Field Name	Field Type	Example	Notes
Entity ID	i32	`1805`
X	i16	`-1343`	Velocity on the X axis
Y	i16	`0`	Velocity on the Y axis
Z	i16	`0`	Velocity on the Z axis

0x1D Destroy Entity#

Clientbound: [x]
Serverbound: [ ]
Size: 4

Field Name	Field Type	Example	Notes
Entity ID	i32	`446`

0x1E Entity#

Clientbound: [x]
Serverbound: [ ]
Size: 4

Most entity-related packets are subclasses of this packet. When sent from the server to the client, it may initialize the entry.

For player entities, either this packet or any move/look packet is sent several times per second. So the meaning of this packet is basically that the entity did not move/look since the last such packet.

Field Name	Field Type	Example	Notes
Entity ID	i32	`446`

0x1F Entity Relative Move#

Clientbound: [x]
Serverbound: [ ]
Size: 7

Field Name	Field Type	Example
Entity ID	i32	`446`
Relative X	i8	`1`
Relative Y	i8	`-7`
Relative Z	i8	`5`

Solid documentation on what these relative coordinates actually are is kind of lacking - apologies. I'll figure it out eventually though.

0x20 Entity Look#

Clientbound: [x]
Serverbound: [ ]
Size: 6

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

Example: Yaw=64 means a 90 degree turn.

Field Name	Field Type	Example	Notes
Entity ID	i32	`459`
Yaw	i8	`64`	Packed rotation
Pitch	i8	`0`	Packed rotation

0x21 Entity Look and Relative Move#

Clientbound: [x]
Serverbound: [ ]
Size: 9

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

Since i8 range is limited from -128 to 127, this packet allows at most four b locks movement in any direction. (-128/32 == -4)

Field Name	Field Type	Example	Notes
Entity ID	i32	`446`
Relative X	i8	`1`
Relative Y	i8	`-7`
Relative Z	i8	`5`
Yaw	i8	`64`	X axis rotation as a fraction of 360
Pitch	i8	`0`	Y axis rotation as a fraction of 360

0x22 Entity Teleport#

Clientbound: [x]
Serverbound: [ ]
Size: 18

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

Field Name	Field Type	Example	Notes
Entity ID	i32	`446`
X	i32	`14162`	Packed f64
Y	i32	`2176`	Packed f64
Z	i32	`1111`	Packed f64
Yaw	i8	`64`	Packed rotation
Pitch	i8	`0`	Packed rotation

0x26 Entity Status#

Clientbound: [x]
Serverbound: [ ]
Size: 5

Field Name	Field Type	Example	Notes
Entity ID	i32	`446`
Status	i8	`2`	See below

Status#

2: (Living Entities only) Attack animation
3: (Living Entities only) Death animation
6: (Wolf only) Make smoke particles
7: (Wolf only) Make hearts particles
8: (Wolf only) Shaking

0x27 Ride Entity#

Clientbound: [x]
Serverbound: [ ]
Size: 8

This packet is sent when a player starts riding an entity.

Field Name	Field Type	Example	Notes
Player Entity ID	i32	`446`	Player's entity ID
Vehicle Entity ID	i32	`1805`	Vehicle's entity ID

0x28 Update Entity Metadata#

Clientbound: [x]
Serverbound: [ ]
Size: 4 + Metadata (at least 1)

Field Name	Field Type	Example	Notes
Entity ID	i32	`446`	Entity ID
Entity Metadata	Entity Metadata	`127`	Indexed metadata, terminated by `0x7F` - see link

0x32 Initialize Chunk#

Clientbound: [x]
Serverbound: [ ]
Size: 9

The client is expected to allocate space for a full chunk (16 x 128 x 16 blocks).

One or more Chunk Data packets will follow, specifying actual data to fill the chunk with.

Whenever you send this packet the client will clear any previous chunk at that spot if one has previously been sent. Clients don't like being in or next to an unloaded chunk, so try not to unload it if players are nearby. If the player appears to be twitching and stuck in place after joining the world, there is probably an unloaded chunk too close to them.

Field Name	Field Type	Example	Notes
X	i32	`-9`	Chunk coordinate
Z	i32	`12`	Chunk coordinate
Load/Unload	bool	`true`	If `false`, the client unloads the chunk. If `true`, the client initializes the chunk

0x33 Chunk Data#

Clientbound: [x]
Serverbound: [ ]
Size: 17 + compressed chunk size

Field Name	Field Type	Example	Notes
X	i32	`128`	Block coordinate
Y	i16	`0`	Block coordinate
Z	i32	`-192`	Block coordinate
Size X	i8	`15`	Size X is Actual X Size -1
Size Y	i8	`127`	Size Y is Actual Y Size -1
Size Z	i8	`15`	Size Z is Actual Z Size -1
Compressed size	i32	`3663`	Size of compressed region data
Compressed data	Vec<u8>	`...`	Compressed region data (zlib deflate)

X,Y,Z#

This is the start position of the region, in world block coordinates.

To find which chunk is affected, in the same coordinates given by Initialize Chunk:

chunkX = X >> 4
chunkY = Y >> 7
chunkZ = Z >> 4

And conversely, which local block in the chunk to start at:

startX = X & 15
startY = Y & 127  (not always 0!)
startZ = Z & 15

Size X,Y,Z#

This is the size of the region, in blocks. The server will subtract one from the sizes and then cast them to a byte before sending. This is so that chunks as large as 256 are possible.

Compressed data#

The data is compressed using the deflate() function in zlib. After uncompressing, the data consists of four sequential sections, in order:

Block ID array (1 byte per block)
Block metadata array (half byte/nibble per block)
Block Light array (half byte/nibble per block)
Sky Light array (half byte/nibble per block)

The data is exactly (sizeX+1) * (sizeY+1) * (sizeZ+1) * 2.5 bytes long. Nibbles are not rounded either direction, which means that at least one dimension of the chunk must be even.

The arrays are not interlaced.

In other words, there are sizeX number of x planes, each plane made up of sizeZ number of z rows, each row made up of sizeY blocks indexed by y coordinate in order.

The Block ID array is indexed with:

index = y + (z * (sizeY+1)) + (x * (sizeY+1) * (sizeZ+1))

The other arrays are similar but you need to divide the index by two after calculating the above. Then each byte contains data for two blocks. The low four bits contain the first (lower Y) nibble and the high four bits contain the second nibble.

If you have a FULL map chunk (sizeX = 15, sizeY = 127, sizeZ = 15), you can calculate index coordinates:

x = X + ( index >> 11 )
y = index & 0x7F
z = Z + ( (index & 0x780) >> 7 )

0x34 Multi Block Change#

Clientbound: [x]
Serverbound: [ ]
Size: 10 + arrays

This is a multiple-block-change command; if you take the three arrays, and put together elements with the same index, and then decompose the i16 into coordinates (top 4 bits is X, next 4 bits is Z, bottom 8 bits is Y), you get arrays like [((8, 7, 4), 11, 0), ((7, 13, 6), 11, 0), ((13, 1, 8), 11, 0), ((7, 6, 6), 11, 0)].

Field Name	Field Type	Example	Notes
X	i32	`-9`	Chunk coordinate
Z	i32	`12`	Chunk coordinate
Array size	i16	`2`	The total number of elements per array
Coordinate array	Vec<i16>	`...`	The coordinates of the blocks to change
Block ID array	Vec<i8>	`...`	The ID for each block to change
Block metadata array	Vec<i8>	`...`	The metadata for each block changed

See blocks for information on the metadata variable.

0x35 Block Change#

Clientbound: [x]
Serverbound: [ ]
Size: 11

Field Name	Field Type	Example	Notes
X	i32	`128`	Block coordinate
Y	i8	`0`	Block coordinate
Z	i32	`-192`	Block coordinate
Block ID	i8	`78`	The type for the block
Block metadata	i8	`0`	The metadata for the block

See blocks for information on the metadata variable.

0x36 Play Note Block#

Clientbound: [x]
Serverbound: [ ]
Size: 12

Sent when a note block is played.

Field Name	Field Type	Example	Notes
X	i32	`128`	Block coordinate
Y	i16	`0`	Block coordinate
Z	i32	`-192`	Block coordinate
Instrument type	i8	`3`	See below
Pitch	i8	`17`	The pitch of the note (between 0..24 inclusive)

Instrument types#

0: Harp
1: Double Bass
2: Snare Drum
3: Clicks/Sticks (Hihat)
4: Bass Drum

0x3C Explosion#

Clientbound: [x]
Serverbound: [ ]
Size: 32 + 3*(coordinate count)

Sent when an explosion occurs.

Field Name	Field Type	Example	Notes
X	f64	`128.0`	Center coordinate
Y	f64	`0.0`	Center coordinate
Z	f64	`-192.0`	Center coordinate
Radius	f32	`4.0`
Coordinate count	i32	`60`
Records	(i8, i8, i8) * count	`...`	XYZ offsets of affected blocks

0x3D Play Effect#

Clientbound: [x]
Serverbound: [ ]
Size: 17

Sent when a client is to play an effect.

Field Name	Field Type	Example	Notes
Effect ID	i32	`1003`	See below
X	i32	`128.0`	Block coordinate
Y	i8	`0.0`	Block coordinate
Z	i32	`-192.0`	Block coordinate
Data	i32	`0`	See below

Effects#

1000: Play sound random.click with pitch 1.0
1001: Play sound random.click with pitch 1.2
1002: Play sound random.bow with pitch 1.2
1003: Play sound randomly between random.door_open and random.door_close with random uniform pitch between 0.0 and 1.0
1004: Play sound random.fizz with volume 0.5 and random pitch
1005: Play record sound.
- The record item ID is given in the effect data.
2000: Spawn smoke particles
- The radius is given in effect data with two bits for X and Z axis, like this: 0bZZXX
2001: Play and show block break sound and particles.
- The block id is given in effect data.

0x46 Notification#

Clientbound: [x]
Serverbound: [ ]
Size: 1

Sent to notify the client of some state.

Field Name	Field Type	Example	Notes
Reason	i8	`1`	See below

Reason#

0: Invalid bed
1: Start raining
2: Stop raining

0x47 Lightning#

Clientbound: [x]
Serverbound: [ ]
Size: 17

Notifies the client of thunderbolts striking somewhere. The coordinates specify where exactly the thunderbolt strikes.

Field Name	Field Type	Example	Notes
Entity ID	i32	`4`	Lightning bolt entity ID
???	bool	`true`	Always `true`
X	i32	`133`	Packed f64
Y	i32	`913`	Packed f64
Z	i32	`63552`	Packed f64

0x64 Open Inventory#

Clientbound: [x]
Serverbound: [ ]
Size: 5 + length of strings

Field Name	Field Type	Example	Notes
Inventory ID	i8	`123`
Inventory Type	i8	`0`	See below
Title	str8	`Chest`	Only used for chests
Number of slots	i8	`3`

Inventory Type#

0: Chest
1: Crafting table
2: Furnace
3: Dispenser

0x65 Close Inventory#

Clientbound: [x]
Serverbound: [x]
Size: 1

Clients send this packet with Inventory ID 0 when they close their inventory.

Field Name	Field Type	Example	Notes
Inventory ID	i8	`123`	0 for player's inventory

0x66 Click Inventory#

Clientbound: [ ]
Serverbound: [x]
Size: 9 or 12

Sent when the playuer clicks on a slot in an inventory.

Field Name	Field Type	Example	Notes
Inventory ID	i8	`123`	0 for player's inventory
Cicked Slot	i16	`36`
Right clicking	bool	`true`	`true` if right cicking, `false` otherwise
Action number	`i16`	`12`	Unique number for the action, used for transaction handling
Shift	bool	`fase`	`true` if the player was holding shift, `false` otherwise
Item ID	`i16`	`3`	ID of the item that was in the slot. `-1` for no item. If `-1`, this is the last field in the packet.
Item Count	`i8`	`64`
Item Data	`i16`	`10`

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 Action number is actually a counter, starting at 1. This number is used by the server as a transaction ID to send back a transaction packet.

For help with slot IDs, see the next packet.

0x67 Set Inventory Slot#

Clientbound: [x]
Serverbound: [ ]
Size: 5 or 8

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

Field Name	Field Type	Example	Notes
Inventory ID	i8	`123`	0 for player's inventory
Slot	i16	`36`
Item ID	`i16`	`3`	`-1` for no item. If `-1`, this is the last field in the packet.
Item Count	`i8`	`64`
Item Data	`i16`	`10`

Note that if window ID and slot are both -1, it means the item currently attached to the cursor.

Slot#

Minecraft inventory with slot IDs crudely labelled

0x68 Set Inventory Slots#

Clientbound: [x]
Serverbound: [ ]
Size: 3 + size of payload

Sent by the server when items in slots are added/removed. This includes the player inventory, equipped armor, and crafting slots.

Field Name	Field Type	Example	Notes
Inventory ID	i8	`123`	0 for player's inventory
Payload count	i16	`4`	See below
Payload	...		See below

This packet is a bit trickier to parse than most others because the size of its payload is variable. The payload is an array of shorts (item ID) optionally followed by a byte-short pair (count and data) as long as the item ID does not equal -1, which signifies an empty slot.

offset = 0

for slot in count:
    item_id = payload[offset] as short
    offset += 2
    if item_id is not equal to -1:
        count = payload[offset] as byte
        offset += 1
        uses = payload[offset] as short
        offset += 2
        inventory[slot] = new item(item_id, count, uses)
    else:
        inventory[slot] = None

0x69 Update Progress Bar#

Clientbound: [x]
Serverbound: [ ]
Size: 5

Field Name	Field Type	Example	Notes
Inventory ID	i8	`123`	0 for player's inventory
Progress Bar	i16	`1`	See below
Value	i16	650	See below

Furnace#

Progress bar#

0: Arrow
1: Fire
2: Current Item Burn Time
- time in ticks that the fuel item takes to burn

Value#

0: Empty
Full progress arrow: approx. 180
Full fire icon: approx. 250

0x6A Transaction#

Clientbound: [x]
Serverbound: [x]
Size: 4

A packet from the server indicating whether a request from the client was accepted, or whether there was a conflict (due to lag). This packet is also sent from the client to the server in response to a server transaction rejection packet.

Field Name	Field Type	Example	Notes
Inventory ID	i8	`123`	0 for player's inventory
Action Number	i16	`12`
Accepted	bool	`true`

0x82 Update Sign#

Clientbound: [x]
Serverbound: [x]
Size: 10 + length of strings

This message is sent from the server to the client whenever a sign comes into view distance or created. This message is sent from the client to the server when the "Done" button is pressed after placing a sign.

Field Name	Field Type	Example
X	i32	`123`
Y	i16	`0`
Z	i32	`-128`
Text1	str16	`First line`
Text2	str16	`Second line`
Text3	str16	`Third line`
Text4	str16	`Fourth line`

0x83 Map Data#

Clientbound: [x]
Serverbound: [ ]
Size: 5 + length of payload

Sends map updates (columns of pixels or decorations).

It allows the server to stream partial changes to a map rather than the entire 128x128 bitmap.

Field Name	Field Type	Example	Notes
Item ID	i16	`358`
Item Data	i16	`0`
Payload length	u8	`35`
Payload	Vec<i8>	`...`	See below

Payload formats#

The first byte of the payload is a tag indicating the type of update:

Tag `0` (Column update)#

u8 x_start: X coordinate (0..127) of the column.
u8 y_start: Y coordinate (0..127) of the starting pixel.
Vec<u8> colors: Palette indices (one per pixel) written downwards starting at (x_start, y_start).

Each color is a raw color (0–255), not a limited palette enum. The raw value is base_id * 4 + shade, where:

base_id is one of the 14 map palette entries.
shade is 0..3 for brightness variation.

Tag `1` (Decorations)#

Sequence of entries, each 3 bytes:

u8 data: Upper 4 bits = direction (0..15), lower 4 bits = type (always 0).
u8 x: X coordinate of the decoration on the map (0..127).
u8 y: Y coordinate of the decoration on the map (0..127).

Decorations are only used to show the player cursors on the map in Beta 1.7.

0xC8 Increment Statistic#

Clientbound: [x]
Serverbound: [ ]
Size: 5

Field Name	Field Type	Example	Notes
Statistic ID	i32	`1003`	See below
Amount	i8	`1`	Negative to decrement

Statistic ID#

TODO :-( - but you can try this forum post?

0xFF Disconnect#

Clientbound: [x]
Serverbound: [x]
Size: 2 + length of strings

Sent by the server before it disconnects a client, or by the client before it disconnects from the server. The receiver of this packet assumes that the sender has already closed the connection by the time the packet arrives.

Field Name	Field Type	Example	Notes
Reason	str16	`The server is full!`

Packets #

Data Types#

Entity types#

Entity Metadata#

Packed f64#

Packed Rotation#

Packed Motion i8#

Packed Motion i16#

0x00 Keep Alive#

0x01 Login Request#

Clientbound#

Serverbound#

0x02 Handshake#

Clientbound#

Serverbound#

0x03 Chat Message#

0x04 Update Time#

0x05 Set Player Equipment#

Equipment slots#

0x06 Spawn Position#

0x07 Use Entity#

0x08 Update Health#

0x09 Respawn#

0x0A On Ground#

0x0B Player Position#

0x0C Player Look#

0x0D Player Position and Look#

0x0E Block Dig#

Status#

Special cases#

Face#

0x0F Block Interact#

Special cases#

0x10 Change Current Slot#

0x11 Sleep#

0x12 Animation#

Animate#

0x13 Player Action#

Action#

0x14 Spawn Player#

0x15 Spawn Item#

0x16 Pickup Item#

0x17 Spawn Non-Living Entity#

0x18 Spawn Living Entity#

Living Entity types#

Sheep colors#

0x19 Spawn Painting#

Direction#

0x1C Update Velocity#

0x1D Destroy Entity#

0x1E Entity#

0x1F Entity Relative Move#

0x20 Entity Look#

0x21 Entity Look and Relative Move#

0x22 Entity Teleport#

0x26 Entity Status#

Status#

0x27 Ride Entity#

0x28 Update Entity Metadata#

0x32 Initialize Chunk#

0x33 Chunk Data#

X,Y,Z#

Size X,Y,Z#

Compressed data#

0x34 Multi Block Change#

0x35 Block Change#

0x36 Play Note Block#

Instrument types#

0x3C Explosion#

0x3D Play Effect#

Effects#

0x46 Notification#

Reason#

0x47 Lightning#

0x64 Open Inventory#

Inventory Type#

0x65 Close Inventory#

0x66 Click Inventory#

0x67 Set Inventory Slot#

Slot#

Tag `0` (Column update)#

Tag `1` (Decorations)#