Minecraft:Java Edition protocol/Data types

Template:Exclusive This article defines the data types used in the Minecraft:Java Edition protocol. 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.

Definitions

Name	Size (bytes)	Encodes	Notes
Template:Type	1	Either false or true	True is encoded as 0x01, false as 0x00.
Template:Type	1	An integer between -128 and 127	Signed 8-bit integer, two's complement
Template:Type	1	An integer between 0 and 255	Unsigned 8-bit integer
Template:Type	2	An integer between -32 768 and 32 767	Signed 16-bit integer, two's complement
Template:Type	2	An integer between 0 and 65 535	Unsigned 16-bit integer
Template:Type	4	An integer between -2 147 483 648 and 2 147 483 647	Signed 32-bit integer, two's complement
Template:Type	8	An integer between -9 223 372 036 854 775 808 and 9 223 372 036 854 775 807	Signed 64-bit integer, two's complement
Template:Type	4	A single-precision 32-bit IEEE 754 floating point number
Template:Type	8	A double-precision 64-bit IEEE 754 floating point number
Template:Type (n)	≥ 1 ≤ (n×3) + 3	A sequence of Unicode scalar values	UTF-8 string prefixed with its size in bytes as a VarInt. Maximum length of n characters, which varies by context. The encoding used on the wire is regular UTF-8, not Java's "slight modification". However, the length of the string for purposes of the length limit is its number of UTF-16 code units, that is, scalar values > U+FFFF are counted as two. Up to n × 3 bytes can be used to encode a UTF-8 string comprising n code units when converted to UTF-16, 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.
Template:Type	Varies	See Minecraft:Text component format	Encoded as a NBT Tag, with the type of tag used depending on the case: As a String Tag: For components only containing text (no styling, no events etc.). As a Compound Tag: Every other case.
Template:Type	≥ 1 ≤ (262144×3) + 3	See Minecraft:Text component format	The maximum permitted length when decoding is 262 144, but the vanilla server since 1.20.3 refuses to encode longer than 32 767. This may be a bug.
Template:Type	≥ 1 ≤ (32767×3) + 3	See Identifier below	Encoded as a String with max length of 32 767.
Template:Type	≥ 1 ≤ 5	An integer between -2 147 483 648 and 2 147 483 647	Variable-length data encoding a two's complement signed 32-bit integer; more info in their section
Template:Type	≥ 1 ≤ 10	An integer between -9 223 372 036 854 775 808 and 9 223 372 036 854 775 807	Variable-length data encoding a two's complement signed 64-bit integer; more info in their section
Template:Type	Varies	Miscellaneous information about an entity	See Entity metadata#Entity Metadata Format
Template:Type	Varies	An item stack in an inventory or container	See Slot Data
Template:Type	Varies	Similar to Slot, but with the data component values being sent as a hash instead of their actual contents	See Slot Data#Hashed Format
Template:Type	Varies	Depends on context	See NBT
Template:Type	8	An integer/block position: x (-33 554 432 to 33 554 431), z (-33 554 432 to 33 554 431), y (-2048 to 2047)	x as a 26-bit integer, followed by z as a 26-bit integer, followed by y as a 12-bit integer (all signed, two's complement). See also the section below.
Template:Type	1	A rotation angle in steps of 1/256 of a full turn	Whether or not this is signed does not matter, since the resulting angles are the same.
Template:Type	16	A UUID	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)
Template:Type	Varies	See #BitSet below	A length-prefixed bit set.
Template:Type (n)	ceil(n / 8)	See #Fixed BitSet below	A bit set with a fixed length of n bits.
Template:Type 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.
Template:Type X	size of Template:Type + (is present ? Size of X : 0)	A boolean and if present, a field of type X	The boolean is true if the field is present.
Template:Type of X	length times size of X	Zero or more fields of type X	The length must be known from the context.
Template:Type of X	size of Template:Type + size of X * length	See #Prefixed Array below	A length-prefixed array.
X Template:Type	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.
Template:Type	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.
Template:Type X	size of Template:Type + (size of X or 0)	See #ID or X below	Either a registry ID or an inline data definition of type X.
Template:Type	Varies	See #ID Set below	Set of registry IDs specified either inline or as a reference to a tag.
Template:Type	Varies	See #Sound Event below	Parameters for a sound event.
Template:Type	Varies	See #Chat Type below	Parameters for a direct chat type.
Template:Type	4	See #Teleport Flags below	Bit field specifying how a teleportation is to be applied on each axis.
Template:Type	Varies	See Recipes#Recipe Display structure	Description of a recipe for use for use by the client.
Template:Type	Varies	See Recipes#Slot Display structure	Description of a recipe ingredient slot for use for use by the client.
Template:Type	Varies	See #Light Data below
Template:Type X or Y	size of Template:Type + (isX ? size of X : size of Y)	A boolean followed by either X or Y	The boolean is true if X is encoded, and false if Y is encoded.
Template:Type	Varies	See #Game Profile below	A Minecraft player profile.
Template:Type	Varies	See #Resolvable Profile below
Template:Type	Varies	See #Debug Subscription Event below
Template:Type	Varies	See #Debug Subscription Update below
Template:Type	Varies	See #LpVec3 below	Usually used for low velocities.

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. Both the namespace and value can use all lowercase alphanumeric characters (a-z and 0-9), dot (.), dash (-), and underscore (_). In addition, values can use slash (/). The naming convention is lower_case_with_underscores. More information. For ease of determining whether a namespace or value is valid, here are regular expressions for each:

• Namespace: [a-z0-9.-_]
• Value: [a-z0-9.-_/]

VarInt and VarLong

Java Edition protocol/VarInt and VarLong

Position

Note: What you are seeing here is the latest version of the Data types article, but the position type was different before 1.14.

64-bit value split into three signed integer parts:

• x: 26 MSBs
• z: 26 middle bits
• y: 12 LSBs

For example, a 64-bit position can be broken down as follows:

Example value (big endian): 01000110000001110110001100 10110000010101101101001000 001100111111

• The red value is the X coordinate, which is 18357644 in this example.
  
• The blue value is the Z coordinate, which is -20882616 in this example.
  
• The green value is the Y coordinate, which is 831 in this example.
  

Encoded as follows:

((x & 0x3FFFFFF) << 38) | ((z & 0x3FFFFFF) << 12) | (y & 0xFFF)

And decoded as:

val = read_long();
x = val >> 38;
y = val << 52 >> 52;
z = val << 26 >> 38;

Note: The above assumes that the right shift operator sign extends the value (this is called an Template:Wikipedia), so that the signedness of the coordinates is preserved. In many languages, this requires the integer type of val to be signed. In the absence of such an operator, the following may be useful:

if x >= 1 << 25 { x -= 1 << 26 }
if y >= 1 << 11 { y -= 1 << 12 }
if z >= 1 << 25 { z -= 1 << 26 }

Fixed-point numbers

Some fields may be stored as Template:Wikipedia, where a certain number of bits represent the signed integer part (number to the left of the decimal point) and the rest represent the fractional part (to the right). Floating point numbers (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 point numbers, their fractional precision is greater for higher values.

Prior to version 1.9 a fixed-point format with 5 fraction bits and 27 integer bits was used to send entity positions to the client. Some uses of fixed point remain in modern versions, but they differ from that format.

Most programming languages lack support for fractional integers directly, but you can represent them as integers. The following C or Java-like pseudocode converts a double to a fixed-point integer with n fraction bits:

 x_fixed = (int)(x_double * (1 << n));

And back again:

 x_double = (double)x_fixed / (1 << n);

Arrays

The types Template:Type and Template:Type represent a collection of X in a specified order.

Array

Represents a list where the length is not encoded. The length must be known from the context. If the array is empty nothing will be encoded.

A Template:Type Array with the values ["Hello", "World!"] has the following data when encoded:

Field Name	Field Type	Value
First element	Template:Type	Hello
Second element	Template:Type	World!

Prefixed Array

Represents an array prefixed by its length. If the array is empty the length will still be encoded.

Field Name	Field Type
Length	Template:Type
Data	Template:Type of X

Bit sets

The types Template:Type and Template:Type represent packed lists of bits. The vanilla implementation uses Java's BitSet class.

BitSet

Bit sets of type BitSet are prefixed by their length in longs.

Field Name	Field Type	Meaning
Length	Template:Type	Number of longs in the following array. May be 0 (if no bits are set).
Data	Template:Type of Template:Type	A packed representation of the bit set as created by BitSet.toLongArray.

The ith bit is set when (Data[i / 64] & (1 << (i % 64))) != 0, where i starts at 0.

Fixed BitSet

Bit sets of type Fixed BitSet (n) have a fixed length of n bits, encoded as ceil(n / 8) bytes. Note that this is different from BitSet, which uses longs.

Field Name	Field Type	Meaning
Data	Template:Type (n)	A packed representation of the bit set as created by BitSet.toByteArray, padded with zeroes at the end to fit the specified length.

The ith bit is set when (Data[i / 8] & (1 << (i % 8))) != 0, where i starts at 0. This encoding is not equivalent to the long array in BitSet.

Registry references

ID or X

Represents a data record of type X, either inline, or by reference to a registry implied by context.

Field Name	Field Type	Meaning
ID	Template:Type	0 if value of type X is given inline; otherwise registry ID + 1.
Value	Template:Type X	Only present if ID is 0.

ID Set

Represents a set of IDs in a certain registry (implied by context), either directly (enumerated IDs) or indirectly (tag name).

Field Name	Field Type	Meaning
Type	Template:Type	Value used to determine the data that follows. It can be either: 0 - Represents a named set of IDs defined by a tag. Anything else - Represents an ad-hoc set of IDs enumerated inline.
Tag Name	Template:Type Template:Type	The registry tag defining the ID set. Only present if Type is 0.
IDs	Template:Type Template:Type of Template:Type	An array of registry IDs. Only present if Type is not 0. The size of the array is equal to Type - 1.

Registry data

These types are commonly used in conjuction with Template:Type X to specify custom data inline.

Sound Event

Describes a sound that can be played.

Name	Type	Description
Sound Name	Template:Type
Has Fixed Range	Template:Type	Whether this sound has a fixed range, as opposed to a variable volume based on distance.
Fixed Range	Template:Type Template:Type	The maximum range of the sound. Only present if Has Fixed Range is true.

Chat Type

Describes a direct chat type that a message can be sent with.

Name	Type	Description
Chat	(See below)
Narration	(See below)

The chat type decorations look like:

Name	Type	Description
Translation Key	Template:Type
Parameters	Template:Type of Template:Type Template:Type	0: sender, 1: target, 2: content
Style	Template:Type

Teleport Flags

A bit field represented as an Template:Type, specifying how a teleportation is to be applied on each axis.

In the lower 8 bits of the bit field, a set bit means the teleportation on the corresponding axis is relative, and an unset bit that it is absolute.

Hex Mask	Field
0x0001	Relative X
0x0002	Relative Y
0x0004	Relative Z
0x0008	Relative Yaw
0x0010	Relative Pitch
0x0020	Relative Velocity X
0x0040	Relative Velocity Y
0x0080	Relative Velocity Z
0x0100	Rotate velocity according to the change in rotation, before applying the velocity change in this packet. Combining this with absolute rotation works as expected—the difference in rotation is still used.

Light Data

Field Name		Field Type		Notes
Sky Light Mask		Template:Type		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has data in the Sky Light array below. The least significant bit is for blocks 16 blocks to 1 block below the min world height (one section below the world), while the most significant bit covers blocks 1 to 16 blocks above the max world height (one section above the world).
Block Light Mask		Template:Type		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has data in the Block Light array below. The order of bits is the same as in Sky Light Mask.
Empty Sky Light Mask		Template:Type		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has all zeros for its Sky Light data. The order of bits is the same as in Sky Light Mask.
Empty Block Light Mask		Template:Type		BitSet containing bits for each section in the world + 2. Each set bit indicates that the corresponding 16×16×16 chunk section has all zeros for its Block Light data. The order of bits is the same as in Sky Light Mask.
Sky Light arrays	Sky Light array	Template:Type	Template:Type (2048) of Template:Type	The length of any inner array is always 2048; There is 1 array for each bit set to true in the sky light mask, starting with the lowest value. Half a byte per light value.
Block Light arrays	Block Light array	Template:Type	Template:Type (2048) of Template:Type	The length of any inner array is always 2048; There is 1 array for each bit set to true in the block light mask, starting with the lowest value. Half a byte per light value.

Game Profile

Describes a Minecraft player profile.

Name		Type		Description
UUID		Template:Type
Username		Template:Type (16)
Properties	Name	Template:Type (16)	Template:Type (64)
	Value		Template:Type (32767)
	Signature		Template:Type Template:Type (1024)

The Properties field looks like the response of querying a player's skin and cape from Mojang's official API, with the difference being the usage of the protocol format instead of JSON. That is, each player will usually have one property with Name being “textures” and Value being a JSON string encoded using Base64. An empty properties array is also acceptable, and will cause clients to display the player with one of the default skins depending on their UUID. For more information, refer to the aforementioned Mojang API page.

Resolvable Profile

Name	Type	Meaning
Profile Kind	Template:Type Template:Type	Defines how the next field is read; either partial or complete.
Unpack	Varies	Profile Kind Name Type Description 0 Partial Username Template:Type Template:Type (16) UUID Template:Type Template:Type Properties Name Template:Type (16) Template:Type (64) Value Template:Type (32767) Signature Template:Type Template:Type (1024) 1 Complete Template:Type
Body	Template:Type Template:Type	An override for the skin texture to use, from the player's textures directory.
Cape	Template:Type Template:Type	An override for the cape texture to use, same format as body.
Elytra	Template:Type Template:Type	An override for the elytra texture to use, same format as body.
Model	Template:Type Template:Type	WIDE = 0, SLIM = 1

Debug subscriptions

Types used in certain packets that are meant to help with debugging the game.

Debug Subscription Event

Name	Type	Description
Debug subscription type	Template:Type Template:Type	ID of the debug subscription type for the next field.
Data	Debug Subscription Data	Value of the debug subscription.

Debug Subscription Update

Name	Type	Description
Subscription type	Template:Type Template:Type	ID of the debug subscription type for the next field.
Data	Template:Type Debug Subscription Data	Value of the debug subscription.

Debug Subscription Data

Subscription Type	Field Name	Field Type	Meaning
0: Dedicated server tick time	no fields
1: Bee	Hive position	Template:Type Template:Type
	Flower position	Template:Type Template:Type
	Travel ticks	Template:Type
	Blacklisted hives	Template:Type of Template:Type
2: Villager brain	Name	Template:Type
	Profession	Template:Type
	XP	Template:Type
	Health	Template:Type
	Max health	Template:Type
	Inventory	Template:Type
	Wants golem	Template:Type
	Anger level	Template:Type
	Activities	Template:Type of Template:Type
	Behaviors	Template:Type of Template:Type
	Memories	Template:Type of Template:Type
	Gossips	Template:Type of Template:Type
	POIs	Template:Type of Template:Type
	Potential POIs	Template:Type of Template:Type
3: Breeze	Attack target	Template:Type Template:Type
	Jump target	Template:Type Template:Type
4: Goal selector	Priority	Template:Type
	Is running	Template:Type
	Name	Template:Type (255)
5: Entity path	Reached	Template:Type
	Next block index	Template:Type
	Block position	Template:Type
	Nodes	Template:Type of Debug Path Node
	Target nodes	Template:Type of Debug Path Node
	Open set	Template:Type of Debug Path Node
	Closed set	Template:Type of Debug Path Node
	Max node distance	Template:Type
6: Entity block intersection	ID	Template:Type Template:Type	IN_BLOCK = 0, IN_FLUID = 1, IN_AIR = 2
7: Bee hive	Type	Template:Type Template:Type	ID in the minecraft:block registry.
	Occupant count	Template:Type
	Honey level	Template:Type
	Sedated	Template:Type
8: POI	Position	Template:Type
	Type	Template:Type Template:Type	ID in the minecraft:point_of_interest_type registry.
	Free ticket count	Template:Type
9: Redstone wire orientation	ID	Template:Type
10: Village section	no fields
11: Raid	Positions	Template:Type of Template:Type
12: Structure	Structures	Template:Type of Debug Structure Info
13: Game event listener	Listener radius	Template:Type
14: Neighbor update	Position	Template:Type
15: Game event	Event	Template:Type Template:Type	ID in the minecraft:game_event registry.
	X	Template:Type
	Y	Template:Type
	Z	Template:Type

Debug Path Node

Field name	Field type	Meaning
X	Template:Type
Y	Template:Type
Z	Template:Type
Walked distance	Template:Type
Cost malus	Template:Type
Closed	Template:Type
Type	Template:Type Template:Type	BLOCKED = 0, OPEN = 1, WALKABLE = 2, WALKABLE_DOOR = 3, TRAPDOOR = 4, POWDER_SNOW = 5, DANGER_POWDER_SNOW = 6, FENCE = 7, LAVA = 8, WATER = 9, WATER_BORDER = 10, RAIL = 11, UNPASSABLE_RAIL = 12, DANGER_FIRE = 13, DAMAGE_FIRE = 14, DANGER_OTHER = 15, DAMAGE_OTHER = 16, DOOR_OPEN = 17, DOOR_WOOD_CLOSED = 18, DOOR_IRON_CLOSED = 19, BREACH = 20, LEAVES = 21, STICKY_HONEY = 22, COCOA = 23, DAMAGE_CAUTIOUS = 24, DANGER_TRAPDOOR = 25
F	Template:Type

Debug Structure Info

Field name		Field type		Meaning
Bounding box min		Template:Type
Bounding box max		Template:Type
Pieces	Piece bounding box min	Template:Type	Template:Type
	Piece bounding box max		Template:Type
	Is start		Template:Type

LpVec3

Encodes 3 doubles in (usually) 6 bytes. Only used in Minecraft:Java Edition protocol/Packets#Spawn Entity and Java Edition Protocol/Packets#Set Entity Velocity.

If the absolute maximum of every double is beneath <math>\frac{1}{32766} \approx 3.05 \times 10^{-5}</math>, it will only encode it as a single byte containing 0x00.

If the rounded up absolute maximum of every double is below 3, the continuation flag will not be set, and the absolute maximum is sent as 2 unsigned bits.

If the rounded up absolute maximum of every double is above 3, the continuation flag will be set, and the least significant two bits will be sent. The rest will be sent afterwards as a Template:Type.

The protocol packs the doubles by dividing by their combined absolute maximum (Thus scaling them to a range of -1 to 1). Afterwards, they will be scaled to the range 0 to 1 and multiplied by 32766, to scale them to the range of a 16 bit short. As the resulting number will always be positive, so the sign bit can be discarded and thus represented as a 15 bit unsigned value.

Bit distribution

Packed X	Packet Y	Packed Z	Continuation Flag	Scale Factor
15 bits	15 bits	15 bits	1 bit	2 bits

The protocol then sends the first 2 bytes in little-endian, and the last 4 bytes in big-endian:

Network Order (Indices Little-Endian)

1st	2nd	3rd	4th	5th	6th
Byte 1	Byte 2	Byte 6	Byte 5	Byte 4	Byte 3

Pseudocode to read and write LpVec3: <syntaxhighlight lang="java"> private static final double MAX_QUANTIZED_VALUE = 32766.0; </syntaxhighlight>

<syntaxhighlight lang="java"> private static long pack(double value) {

   return Math.round((value * 0.5 + 0.5) * MAX_QUANTIZED_VALUE));

}

private static double unpack(long value) {

   return Math.min((double)(value & 32767L), MAX_QUANTIZED_VALUE) * 2.0 / MAX_QUANTIZED_VALUE - 1.0;

} </syntaxhighlight>

<syntaxhighlight lang="java"> public static Vec3 readLpVec3() {

   int byte1 = readUnsignedByte();
   if (byte1 == 0) {
       return Vec3(0.0, 0.0, 0.0);
   }

   int byte2 = readUnsignedByte();
   long bytes3To4 = readUnsignedInt();
   long packed = bytes3To4 << 16) | (long)(byte2 << 8) | (long)byte1;
   long scaleFactor = byte1 & 3;
   if ((byte1 & 4) == 4) {
       scaleFactor |= ((long)readVarInt() & 0xFFFFFFFFL) << 2L;
   }

   double scaleFactorD = (double)scaleFactor;
   return Vec3(
       unpack(packed >> 3L)  * scaleFactorD,
       unpack(packed >> 18L) * scaleFactorD,
       unpack(packed >> 33L) * scaleFactorD
   );

}

// Ensure vec3's coordinates are not nan, and clamped between -1.7179869183e10 and 1.7179869183e10 public static writeLpVec3(Vec3 vec3) {

   double maxCoordinate = Math.max(Math.abs(vec3.x), Math.max(Math.abs(vec3.y), Math.abs(vec3.z)));
   if (maxCoordinate < 3.051944088384301e-5) {
       writeByte(0);
   } else {
       long maxCoordinateI = (long)maxCoordinate;
       long scaleFactor = maxCoordinate > (double)maxCoordinateI ? maxCoordinateI + 1L : maxCoordinateI;
       boolean needContinuation = (scaleFactor & 3L) != scaleFactor;
       long packedScale = needContinuation ? scaleFactor & 3L | 4L : scaleFactor;
       long packedX = pack(vec3.x / (double)scaleFactor) << 3L;
       long packedY = pack(vec3.y / (double)scaleFactor) << 18L;
       long packedZ = pack(vec3.z / (double)scaleFactor) << 33L;
       long packed = packedZ | packedY | packedX | packedScale;
       writeByte((byte)packed);
       writeByte((byte)(packed >> 8L));
       writeInt((int)(packed >> 16L));
       if (needContinuation) {
           writeVarInt((int)(scaleFactor >> 2L));
       }
   }

} </syntaxhighlight>

Sample LpVec3:

Value	Hex bytes	Decimal bytes
(0.0, 0.0, 0.0)	0x00	0
(1.0, 0.0, -1.0)	0xF1 0xFF 0x00 0x00 0xFF 0xFF	241 255 0 0 255 255
(10.0, 0.2, -5.0)	0xF6 0xFF 0x40 0x01 0x05 0x1F 0x02	246 255 64 1 5 31 2
(123457.0, 15.071, 0.0)	0xF5 0xFF 0x7F 0xFF 0x00 0x07 0x90 0xF1 0x01	245 255 127 255 0 7 144 241 1