Difference between revisions of "Data types"

From wiki.vg
Jump to navigation Jump to search
(Add info about max length of strings)
(Add a note for time travellers)
(20 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<noinclude>This article defines the '''data types''' used in the [[protocol]]. </noinclude>All data sent over the network (except for VarInt and VarLong) is [[wikipedia:Endianness#Big-endian|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.
+
<noinclude>This article defines the '''data types''' used in the [[protocol]]. </noinclude>All data sent over the network (except for VarInt and VarLong) is [[wikipedia:Endianness#Big-endian|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.<includeonly>
<noinclude>
+
{{#ifeq: {{PAGEID}}|{{PAGEID:Protocol}}| {{#ifeq: {{REVISIONID}}|{{REVISIONID:Protocol}}||{{Warning2|NOTE: This information is from the '''most recent''' version of the [[Data types]] article and may not be correct for this protocol version.  Check that article's history for any differences that happened since this version.}}}}}}
 +
</includeonly><noinclude>
 
== Definitions ==
 
== Definitions ==
 
</noinclude>
 
</noinclude>
 +
 
{| class="wikitable"
 
{| class="wikitable"
 
  |-
 
  |-
Line 56: Line 58:
 
  |-
 
  |-
 
  ! String (n)
 
  ! String (n)
  | ≥ 1 <br />≤ n &times; 4
+
  | ≥ 1 <br />≤ (n&times;4) + 3
 
  | A sequence of [[wikipedia:Unicode|Unicode]] [http://unicode.org/glossary/#unicode_scalar_value scalar values]
 
  | A sequence of [[wikipedia:Unicode|Unicode]] [http://unicode.org/glossary/#unicode_scalar_value scalar values]
  | [[wikipedia:UTF-8|UTF-8]] string prefixed with its size in bytes as a VarInt.  Maximum length of <code>n</code> characters, which varies by context; up to <code>n &times; 4</code> bytes can be used to encode <code>n</code> characters and both of those limits are checked.  Maximum <code>n</code> value is 32767.
+
  | [[wikipedia:UTF-8|UTF-8]] string prefixed with its size in bytes as a VarInt.  Maximum length of <code>n</code> characters, which varies by context; up to <code>n &times; 4</code> bytes can be used to encode <code>n</code> characters and both of those limits are checked.  Maximum <code>n</code> value is 32767.  The + 3 is due to the max size of a valid length VarInt.
 
  |-
 
  |-
 
  ! Chat
 
  ! Chat
  | ≥ 1 <br />≤ 32767 &times; 4
+
  | ≥ 1 <br />≤ (32767&times;4) + 3
 
  | See [[Chat]]
 
  | See [[Chat]]
 +
| Encoded as a String with max length of 32767.
 +
|-
 +
! Identifier
 +
| ≥ 1 <br />≤ (32767&times;4) + 3
 +
| See [[#Identifier|Identifier]] below
 
  | Encoded as a String with max length of 32767.
 
  | Encoded as a String with max length of 32767.
 
  |-  
 
  |-  
Line 74: Line 81:
 
  | An integer between -9223372036854775808 and 9223372036854775807
 
  | An integer between -9223372036854775808 and 9223372036854775807
 
  | Variable-length data encoding a two's complement signed 64-bit integer; more info in [[#VarInt and VarLong|their section]]
 
  | Variable-length data encoding a two's complement signed 64-bit integer; more info in [[#VarInt and VarLong|their section]]
|-
 
! Chunk Section
 
| Varies
 
| A 16×16×16 chunk of blocks
 
| See [[SMP Map Format]]
 
 
  |-
 
  |-
 
  ! Entity Metadata
 
  ! Entity Metadata
Line 130: Line 132:
 
  | 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.
 
  | 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.
 
  |}
 
  |}
 +
 +
<noinclude>== Identifier ==</noinclude><includeonly>=== Identifier ===</includeonly>
 +
 +
Identifiers are a namespaced location, in the form of <code>minecraft:thing</code>.  If the namespace is not provided, it defaults to <code>minecraft</code> (i.e. <code>thing</code> is <code>minecraft:thing</code>.  Custom content should always be in its own namespace, not the default one.  The namespace should only use the characters <code>01​​234​5​6​78​9abcdefghijklmnopqrstuvwxyz-_</code>; actual names may contain more symbols.  The naming convention is <code>lower_case_with_underscores</code>.  [https://minecraft.net/en-us/article/minecraft-snapshot-17w43a More information].
  
 
<noinclude>== VarInt and VarLong ==</noinclude><includeonly>=== VarInt and VarLong ===</includeonly>
 
<noinclude>== VarInt and VarLong ==</noinclude><includeonly>=== VarInt and VarLong ===</includeonly>
  
Variable-length format such that smaller numbers use fewer bytes.  These are very similar to [http://developers.google.com/protocol-buffers/docs/encoding#varints 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).
+
{{:VarInt_And_VarLong}}
  
VarInts are never longer than 5 bytes, and VarLongs are never longer than 10 bytes.
+
<noinclude>== Position ==</noinclude><includeonly>=== Position ===</includeonly>
  
Pseudocode to read and write VarInts and VarLongs:
+
<b>Note:</b> What you are seeing here is the latest version of the [[Data types]] article, but the position type was [https://wiki.vg/index.php?title=Data_types&oldid=14345#Position different before 1.14].
  
<syntaxhighlight lang="java">
+
64-bit value split in to three parts
public static int readVarInt() {
 
    int numRead = 0;
 
    int result = 0;
 
    byte read;
 
    do {
 
        read = readByte();
 
        int value = (read & 0b01111111);
 
        result |= (value << (7 * numRead));
 
  
        numRead++;
+
* x: 26 MSBs
        if (numRead > 5) {
+
* z: 26 middle bits
            throw new RuntimeException("VarInt is too big");
+
* y: 12 LSBs
        }
 
    } while ((read & 0b10000000) != 0);
 
  
    return result;
+
Encoded as followed:
}
 
</syntaxhighlight>
 
<syntaxhighlight lang="java">
 
public static long readVarLong() {
 
    int numRead = 0;
 
    long result = 0;
 
    byte read;
 
    do {
 
        read = readByte();
 
        int value = (read & 0b01111111);
 
        result |= (value << (7 * numRead));
 
  
        numRead++;
+
((x & 0x3FFFFFF) << 38) | ((z & 0x3FFFFFF) << 12) | (y & 0xFFF)
        if (numRead > 10) {
 
            throw new RuntimeException("VarLong is too big");
 
        }
 
    } while ((read & 0b10000000) != 0);
 
  
    return result;
+
And decoded as:
}
 
</syntaxhighlight>
 
<syntaxhighlight lang="java">
 
public static void writeVarInt(int value) {
 
    do {
 
        byte temp = (byte)(value & 0b01111111);
 
        // Note: >>> means that the sign bit is shifted with the rest of the number rather than being left alone
 
        value >>>= 7;
 
        if (value != 0) {
 
            temp |= 0b10000000;
 
        }
 
        writeByte(temp);
 
    } while (value != 0);
 
}
 
</syntaxhighlight>
 
<syntaxhighlight lang="java">
 
public static void writeVarLong(long value) {
 
    do {
 
        byte temp = (byte)(value & 0b01111111);
 
        // Note: >>> means that the sign bit is shifted with the rest of the number rather than being left alone
 
        value >>>= 7;
 
        if (value != 0) {
 
            temp |= 0b10000000;
 
        }
 
        writeByte(temp);
 
    } while (value != 0);
 
}
 
</syntaxhighlight>
 
  
{{Warning2|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:
+
val = read_unsigned_long();
*Minecraft's VarInts are all signed, but do not use the ZigZag encoding. Protocol buffers have 3 types of Varints: <code>uint32</code> (normal encoding, unsigned), <code>sint32</code> (ZigZag encoding, signed), and <code>int32</code> (normal encoding, signed).  Minecraft's are the <code>int32</code> variety.  Because Minecraft uses the normal encoding instead of ZigZag encoding, negative values always use the maximum number of bytes.
+
  x = val >> 38;
*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 <code>int32</code>.}}
+
  y = val & 0xFFF;
 +
  z = (val << 26 >> 38);
  
Sample VarInts:
+
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 }
 +
 
 +
<noinclude>== Fixed-point numbers ==</noinclude><includeonly>=== Fixed-point numbers ===</includeonly>
 +
 
 +
Some fields may be stored as [https://en.wikipedia.org/wiki/Fixed-point_arithmetic 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);
 +
 
 +
<noinclude>== Particle ==</noinclude><includeonly>=== Particle ===</includeonly>
 +
 
 +
{| class="wikitable"
 +
! 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.
 +
|}
  
 
{| class="wikitable"
 
{| class="wikitable"
! Value !! Hex
 
 
  |-
 
  |-
  | 0 || 0x00
+
! Particle Name
 +
! Particle ID
 +
! Data
 +
  |-
 +
| <code>minecraft:ambient_entity_effect</code>
 +
| 0
 +
| None
 +
|-
 +
| <code>minecraft:angry_villager</code>
 +
| 1
 +
| None
 +
|-
 +
| <code>minecraft:barrier</code>
 +
| 2
 +
| None
 +
|-
 +
| <code>minecraft:block</code>
 +
| 3
 +
|
 +
{| class="wikitable"
 +
  ! Field Name
 +
  ! Field Type
 +
  ! Meaning
 +
  |-
 +
  | BlockState
 +
  | VarInt
 +
  | The ID of the block state.
 +
  |}
 +
|-
 +
| <code>minecraft:bubble</code>
 +
| 4
 +
| None
 +
|-
 +
| <code>minecraft:cloud</code>
 +
| 5
 +
| None
 +
|-
 +
| <code>minecraft:crit</code>
 +
| 6
 +
| None
 +
|-
 +
| <code>minecraft:damage_indicator</code>
 +
| 7
 +
| None
 +
|-
 +
| <code>minecraft:dragon_breath</code>
 +
| 8
 +
| None
 +
|-
 +
| <code>minecraft:dripping_lava</code>
 +
| 9
 +
| None
 +
|-
 +
| <code>minecraft:falling_lava</code>
 +
| 10
 +
| None
 +
|-
 +
| <code>minecraft:landing_lava</code>
 +
| 11
 +
| None
 +
|-
 +
| <code>minecraft:dripping_water</code>
 +
| 12
 +
| None
 +
|-
 +
| <code>minecraft:falling_water</code>
 +
| 13
 +
| None
 +
|-
 +
| <code>minecraft:dust</code>
 +
| 14
 +
|
 +
{| class="wikitable"
 +
  ! 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.
 +
  |}
 +
|-
 +
| <code>minecraft:effect</code>
 +
| 15
 +
| None
 +
|-
 +
| <code>minecraft:elder_guardian</code>
 +
| 16
 +
| None
 +
|-
 +
| <code>minecraft:enchanted_hit</code>
 +
| 17
 +
| None
 +
|-
 +
| <code>minecraft:enchant</code>
 +
| 18
 +
| None
 +
|-
 +
| <code>minecraft:end_rod</code>
 +
| 19
 +
| None
 +
|-
 +
| <code>minecraft:entity_effect</code>
 +
| 20
 +
| None
 +
|-
 +
| <code>minecraft:explosion_emitter</code>
 +
| 21
 +
| None
 +
|-
 +
| <code>minecraft:explosion</code>
 +
| 22
 +
| None
 +
|-
 +
| <code>minecraft:falling_dust</code>
 +
| 23
 +
|
 +
{| class="wikitable"
 +
  ! Field Name
 +
  ! Field Type
 +
  ! Meaning
 +
  |-
 +
  | BlockState
 +
  | VarInt
 +
  | The ID of the block state.
 +
  |}
 +
|-
 +
| <code>minecraft:firework</code>
 +
| 24
 +
| None
 +
|-
 +
| <code>minecraft:fishing</code>
 +
| 25
 +
| None
 +
|-
 +
| <code>minecraft:flame</code>
 +
| 26
 +
| None
 +
|-
 +
| <code>minecraft:flash</code>
 +
| 27
 +
| None
 +
|-
 +
| <code>minecraft:happy_villager</code>
 +
| 28
 +
| None
 +
|-
 +
| <code>minecraft:composter</code>
 +
| 29
 +
| None
 +
|-
 +
| <code>minecraft:heart</code>
 +
| 30
 +
| None
 +
|-
 +
| <code>minecraft:instant_effect</code>
 +
| 31
 +
| None
 
  |-
 
  |-
  | 1 || 0x01
+
  | <code>minecraft:item</code>
 +
| 32
 +
|
 +
{| class="wikitable"
 +
  ! Field Name
 +
  ! Field Type
 +
  ! Meaning
 +
  |-
 +
  | Item
 +
  | [[Slot]]
 +
  | The item that will be used.
 +
  |}
 
  |-
 
  |-
  | 2 || 0x02
+
  | <code>minecraft:item_slime</code>
 +
| 33
 +
| None
 
  |-
 
  |-
  | 127 || 0x7f
+
  | <code>minecraft:item_snowball</code>
 +
| 34
 +
| None
 
  |-
 
  |-
  | 128 || 0x80 0x01
+
  | <code>minecraft:large_smoke</code>
 +
| 35
 +
| None
 
  |-
 
  |-
  | 255 || 0xff 0x01
+
  | <code>minecraft:lava</code>
 +
| 36
 +
| None
 
  |-
 
  |-
  | 2147483647 || 0xff 0xff 0xff 0xff 0x07
+
  | <code>minecraft:mycelium</code>
 +
| 37
 +
| None
 
  |-
 
  |-
  | -1 || 0xff 0xff 0xff 0xff 0x0f
+
  | <code>minecraft:note</code>
 +
| 38
 +
| None
 
  |-
 
  |-
  | -2147483648 || 0x80 0x80 0x80 0x80 0x08
+
| <code>minecraft:poof</code>
  |}
+
| 39
 
+
| None
Sample VarLongs:
+
|-
 
+
| <code>minecraft:portal</code>
{| class="wikitable"
+
| 40
  ! Value !! Hex
+
| None
 +
|-
 +
| <code>minecraft:rain</code>
 +
| 41
 +
| None
 +
  |-
 +
| <code>minecraft:smoke</code>
 +
| 42
 +
  | None
 +
|-
 +
| <code>minecraft:sneeze</code>
 +
| 43
 +
| None
 +
  |-
 +
| <code>minecraft:spit</code>
 +
| 44
 +
| None
 +
|-
 +
| <code>minecraft:squid_ink</code>
 +
| 45
 +
| None
 +
|-
 +
| <code>minecraft:sweep_attack</code>
 +
| 46
 +
| None
 +
|-
 +
| <code>minecraft:totem_of_undying</code>
 +
| 47
 +
| None
 +
|-
 +
| <code>minecraft:underwater</code>
 +
| 48
 +
| None
 +
|-
 +
| <code>minecraft:splash</code>
 +
| 49
 +
| None
 +
|-
 +
| <code>minecraft:witch</code>
 +
| 50
 +
| None
 
  |-
 
  |-
  | 0 || 0x00
+
  | <code>minecraft:bubble_pop</code>
 +
| 51
 +
| None
 
  |-
 
  |-
  | 1 || 0x01
+
  | <code>minecraft:current_down</code>
 +
| 52
 +
| None
 
  |-
 
  |-
  | 2 || 0x02
+
  | <code>minecraft:bubble_column_up</code>
 +
| 53
 +
| None
 
  |-
 
  |-
  | 127 || 0x7f
+
  | <code>minecraft:nautilus</code>
 +
| 54
 +
| None
 
  |-
 
  |-
  | 128 || 0x80 0x01
+
  | <code>minecraft:dolphin</code>
 +
| 55
 +
| None
 
  |-
 
  |-
  | 255 || 0xff 0x01
+
  | <code>minecraft:campfire_cosy_smoke</code>
 +
| 56
 +
| None
 
  |-
 
  |-
  | 2147483647 || 0xff 0xff 0xff 0xff 0x07
+
  | <code>minecraft:campfire_signal_smoke</code>
 +
| 57
 +
| None
 
  |-
 
  |-
  | 9223372036854775807 || 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0x7f
+
  | <code>minecraft:dripping_honey</code>
 +
| 58
 +
| None
 
  |-
 
  |-
  | -1 || 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0x01
+
  | <code>minecraft:falling_honey</code>
 +
| 59
 +
| None
 
  |-
 
  |-
  | -2147483648 || 0x80 0x80 0x80 0x80 0xf8 0xff 0xff 0xff 0xff 0x01
+
  | <code>minecraft:landing_honey</code>
 +
| 60
 +
| None
 
  |-
 
  |-
  | -9223372036854775808 || 0x80 0x80 0x80 0x80 0x80 0x80 0x80 0x80 0x80 0x01
+
  | <code>minecraft:falling_nectar</code>
 +
| 61
 +
| None
 
  |}
 
  |}
  
<noinclude>== Position ==</noinclude><includeonly>=== Position ===</includeonly>
 
 
64-bit value split in to three parts
 
 
* x: 26 MSBs
 
* z: 26 LSBs
 
* y: 12 bits between them
 
 
Encoded as followed:
 
 
((x & 0x3FFFFFF) << 38) | ((y & 0xFFF) << 26) | (z & 0x3FFFFFF)
 
 
And decoded as:
 
 
val = read_unsigned_long();
 
x = val >> 38;
 
y = (val >> 26) & 0xFFF;
 
z = val << 38 >> 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 }
 
 
<noinclude>== Fixed-point numbers ==</noinclude><includeonly>=== Fixed-point numbers ===</includeonly>
 
 
Some fields may be stored as [https://en.wikipedia.org/wiki/Fixed-point_arithmetic 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;
 
And back again:
 
 
  double = (double)abs_int / 32;
 
 
<noinclude>
 
<noinclude>
 
[[Category:Protocol Details]]
 
[[Category:Protocol Details]]
 
[[Category:Minecraft Modern]]
 
[[Category:Minecraft Modern]]

Revision as of 15:30, 9 July 2020

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
≤ (32767×4) + 3
See Chat Encoded as a String with max length of 32767.
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 Entities#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;
    }
}

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

Warning.png 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:barrier 2 None
minecraft:block 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:effect 15 None
minecraft:elder_guardian 16 None
minecraft:enchanted_hit 17 None
minecraft:enchant 18 None
minecraft:end_rod 19 None
minecraft:entity_effect 20 None
minecraft:explosion_emitter 21 None
minecraft:explosion 22 None
minecraft:falling_dust 23
Field Name Field Type Meaning
BlockState VarInt The ID of the block state.
minecraft:firework 24 None
minecraft:fishing 25 None
minecraft:flame 26 None
minecraft:flash 27 None
minecraft:happy_villager 28 None
minecraft:composter 29 None
minecraft:heart 30 None
minecraft:instant_effect 31 None
minecraft:item 32
Field Name Field Type Meaning
Item Slot The item that will be used.
minecraft:item_slime 33 None
minecraft:item_snowball 34 None
minecraft:large_smoke 35 None
minecraft:lava 36 None
minecraft:mycelium 37 None
minecraft:note 38 None
minecraft:poof 39 None
minecraft:portal 40 None
minecraft:rain 41 None
minecraft:smoke 42 None
minecraft:sneeze 43 None
minecraft:spit 44 None
minecraft:squid_ink 45 None
minecraft:sweep_attack 46 None
minecraft:totem_of_undying 47 None
minecraft:underwater 48 None
minecraft:splash 49 None
minecraft:witch 50 None
minecraft:bubble_pop 51 None
minecraft:current_down 52 None
minecraft:bubble_column_up 53 None
minecraft:nautilus 54 None
minecraft:dolphin 55 None
minecraft:campfire_cosy_smoke 56 None
minecraft:campfire_signal_smoke 57 None
minecraft:dripping_honey 58 None
minecraft:falling_honey 59 None
minecraft:landing_honey 60 None
minecraft:falling_nectar 61 None