Data types

This article defines the data types used in the 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
Boolean	1	Either false or true	True is encoded as 0x01, false as 0x00.
Byte	1	An integer between -128 and 127	Signed 8-bit integer, two's complement
Unsigned Byte	1	An integer between 0 and 255	Unsigned 8-bit integer
Short	2	An integer between -32768 and 32767	Signed 16-bit integer, two's complement
Unsigned Short	2	An integer between 0 and 65535	Unsigned 16-bit integer
Int	4	An integer between -2147483648 and 2147483647	Signed 32-bit integer, two's complement
Long	8	An integer between -9223372036854775808 and 9223372036854775807	Signed 64-bit integer, two's complement
Float	4	A single-precision 32-bit IEEE 754 floating point number
Double	8	A double-precision 64-bit IEEE 754 floating point number
String (n)	≥ 1 ≤ (n×4) + 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; 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.
Chat	≥ 1 ≤ (262144×4) + 3	See Chat	Encoded as a String with max length of 262144.
Identifier	≥ 1 ≤ (32767×4) + 3	See Identifier below	Encoded as a String with max length of 32767.
VarInt	≥ 1 ≤ 5	An integer between -2147483648 and 2147483647	Variable-length data encoding a two's complement signed 32-bit integer; more info in their section
VarLong	≥ 1 ≤ 10	An integer between -9223372036854775808 and 9223372036854775807	Variable-length data encoding a two's complement signed 64-bit integer; more info in their section
Entity Metadata	Varies	Miscellaneous information about an entity	See Entity_metadata#Entity Metadata Format
Slot	Varies	An item stack in an inventory or container	See Slot Data
NBT Tag	Varies	Depends on context	See NBT
Position	8	An integer/block position: x (-33554432 to 33554431), y (-2048 to 2047), z (-33554432 to 33554431)	x as a 26-bit integer, followed by y as a 12-bit integer, followed by z as a 26-bit integer (all signed, two's complement). See also the section below.
Angle	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.
UUID	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)
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. Within these limits, unnecessarily long encodings (e.g. 81 00 to encode 1) are allowed.

Pseudocode to read and write VarInts and VarLongs:

private static final int SEGMENT_BITS = 0x7F;
private static final int CONTINUE_BIT = 0x80;

public int readVarInt() {
    int value = 0;
    int position = 0;
    byte currentByte;

    while (true) {
        currentByte = readByte();
        value |= (currentByte & SEGMENT_BITS) << position;

        if ((currentByte & CONTINUE_BIT) == 0) break;

        position += 7;

        if (position >= 32) throw new RuntimeException("VarInt is too big");
    }

    return value;
}

public long readVarLong() {
    long value = 0;
    int position = 0;
    byte currentByte;

    while (true) {
        currentByte = readByte();
        value |= (long) (currentByte & SEGMENT_BITS) << position;

        if ((currentByte & CONTINUE_BIT) == 0) break;

        position += 7;

        if (position >= 64) throw new RuntimeException("VarLong is too big");
    }

    return value;
}

public void writeVarInt(int value) {
    while (true) {
        if ((value & ~SEGMENT_BITS) == 0) {
            writeByte(value);
            return;
        }

        writeByte((value & SEGMENT_BITS) | CONTINUE_BIT);

        // Note: >>> means that the sign bit is shifted with the rest of the number rather than being left alone
        value >>>= 7;
    }
}

public void writeVarLong(long value) {
    while (true) {
        if ((value & ~((long) SEGMENT_BITS)) == 0) {
            writeByte(value);
            return;
        }

        writeByte((value & SEGMENT_BITS) | CONTINUE_BIT);

        // Note: >>> means that the sign bit is shifted with the rest of the number rather than being left alone
        value >>>= 7;
    }
}

Note Minecraft's VarInts are identical to LEB128 with the slight change of throwing a exception if it goes over a set amount of bytes.

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

Sample VarInts:

Value	Hex bytes	Decimal bytes
0	0x00	0
1	0x01	1
2	0x02	2
127	0x7f	127
128	0x80 0x01	128 1
255	0xff 0x01	255 1
25565	0xdd 0xc7 0x01	221 199 1
2097151	0xff 0xff 0x7f	255 255 127
2147483647	0xff 0xff 0xff 0xff 0x07	255 255 255 255 7
-1	0xff 0xff 0xff 0xff 0x0f	255 255 255 255 15
-2147483648	0x80 0x80 0x80 0x80 0x08	128 128 128 128 8

Sample VarLongs:

Value	Hex bytes	Decimal bytes
0	0x00	0
1	0x01	1
2	0x02	2
127	0x7f	127
128	0x80 0x01	128 1
255	0xff 0x01	255 1
2147483647	0xff 0xff 0xff 0xff 0x07	255 255 255 255 7
9223372036854775807	0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0x7f	255 255 255 255 255 255 255 255 127
-1	0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0x01	255 255 255 255 255 255 255 255 255 1
-2147483648	0x80 0x80 0x80 0x80 0xf8 0xff 0xff 0xff 0xff 0x01	128 128 128 128 248 255 255 255 255 1
-9223372036854775808	0x80 0x80 0x80 0x80 0x80 0x80 0x80 0x80 0x80 0x01	128 128 128 128 128 128 128 128 128 1

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 in to three parts

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

Encoded as followed:

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

And decoded as:

val = read_unsigned_long();
x = val >> 38;
y = val & 0xFFF;
z = (val << 26 >> 38);

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:

if x >= 2^25 { x -= 2^26 }
if y >= 2^11 { y -= 2^12 }
if z >= 2^25 { z -= 2^26 }

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:

 abs_int = (int) (double * 32.0D);

And back again:

 double = (double) (abs_int / 32.0D);

Particle

Field Name	Field Type	Meaning
ID	VarInt	The ID of the particle type, see below.
Data	Varies	Varies based on the particle type, see below.

Particle Name	Particle ID	Data
minecraft:ambient_entity_effect	0	None
minecraft:angry_villager	1	None
minecraft:block	2	Field Name Field Type Meaning BlockState VarInt The ID of the block state.
minecraft:block_marker	3	Field Name Field Type Meaning BlockState VarInt The ID of the block state.
minecraft:bubble	4	None
minecraft:cloud	5	None
minecraft:crit	6	None
minecraft:damage_indicator	7	None
minecraft:dragon_breath	8	None
minecraft:dripping_lava	9	None
minecraft:falling_lava	10	None
minecraft:landing_lava	11	None
minecraft:dripping_water	12	None
minecraft:falling_water	13	None
minecraft:dust	14	Field Name Field Type Meaning Red Float Red value, 0-1 Green Float Green value, 0-1 Blue Float Blue value, 0-1 Scale Float The scale, will be clamped between 0.01 and 4.
minecraft:dust_color_transition	15	Field Name Field Type Meaning FromRed Float Red value, 0-1 FromGreen Float Green value, 0-1 FromBlue Float Blue value, 0-1 Scale Float The scale, will be clamped between 0.01 and 4. ToRed Float Red value, 0-1 ToGreen Float Green value, 0-1 ToBlue Float Blue value, 0-1
minecraft:effect	16	None
minecraft:elder_guardian	17	None
minecraft:enchanted_hit	18	None
minecraft:enchant	19	None
minecraft:end_rod	20	None
minecraft:entity_effect	21	None
minecraft:explosion_emitter	22	None
minecraft:explosion	23	None
minecraft:falling_dust	24	Field Name Field Type Meaning BlockState VarInt The ID of the block state.
minecraft:firework	25	None
minecraft:fishing	26	None
minecraft:flame	27	None
minecraft:soul_fire_flame	28	None
minecraft:soul	29	None
minecraft:flash	30	None
minecraft:happy_villager	31	None
minecraft:composter	32	None
minecraft:heart	33	None
minecraft:instant_effect	34	None
minecraft:item	35	Field Name Field Type Meaning Item Slot The item that will be used.
minecraft:vibration	36	Field Name Field Type Meaning Origin Position Starting position PositionType String Type of destination BlockPosition Position Present if PositionType is "minecraft:block" EntityId Varint Present if PositionType is "minecraft:entity" Ticks Varint
minecraft:item_slime	37	None
minecraft:item_snowball	38	None
minecraft:large_smoke	39	None
minecraft:lava	40	None
minecraft:mycelium	41	None
minecraft:note	42	None
minecraft:poof	43	None
minecraft:portal	44	None
minecraft:rain	45	None
minecraft:smoke	46	None
minecraft:sneeze	47	None
minecraft:spit	48	None
minecraft:squid_ink	49	None
minecraft:sweep_attack	50	None
minecraft:totem_of_undying	51	None
minecraft:underwater	52	None
minecraft:splash	53	None
minecraft:witch	54	None
minecraft:bubble_pop	55	None
minecraft:current_down	56	None
minecraft:bubble_column_up	57	None
minecraft:nautilus	58	None
minecraft:dolphin	59	None
minecraft:campfire_cosy_smoke	60	None
minecraft:campfire_signal_smoke	61	None
minecraft:dripping_honey	62	None
minecraft:falling_honey	63	None
minecraft:landing_honey	64	None
minecraft:falling_nectar	65	None
minecraft:falling_spore_blossom	66	None
minecraft:ash	67	None
minecraft:crimson_spore	68	None
minecraft:warped_spore	69	None
minecraft:spore_blossom_air	70	None
minecraft:dripping_obsidian_tear	71	None
minecraft:falling_obsidian_tear	72	None
minecraft:landing_obsidian_tear	73	None
minecraft:reverse_portal	74	None
minecraft:white_ash	75	None
minecraft:small_flame	76	None
minecraft:snowflake	77	None
minecraft:dripping_dripstone_lava	78	None
minecraft:falling_dripstone_lava	79	None
minecraft:dripping_dripstone_water	80	None
minecraft:falling_dripstone_water	81	None
minecraft:glow_squid_ink	82	None
minecraft:glow	83	None
minecraft:wax_on	84	None
minecraft:wax_off	85	None
minecraft:electric_spark	86	None
minecraft:scrape	87	None

BitSet

Represents Java's BitSet, a list of bits.

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

The nth bit in a BitSet is set when (longs[n/64] & (1L << (n % 64))) != 0, where n starts at 0.