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
== Identifier == === Identifier ===

Identifiers are a namespaced location, in the form of. If the namespace is not provided, it defaults to  (i.e.   is  .  Custom content should always be in its own namespace, not the default one.  The namespace should only use the characters  ; actual names may contain more symbols.  The naming convention is  .  More information.

== VarInt and VarLong == === 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.

Pseudocode to read and write VarInts and VarLongs:

Sample VarInts:

Sample VarLongs:

== Position == === Position ===

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 < > 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 == === 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 == === Particle ===

{| class="wikitable" |- ! Particle Name ! Particle ID ! Data |- |  | 0 | None |- |  | 1 | None |- |  | 2 | None |- |  | 3 | |- |   | 4 | None |- |  | 5 | None |- |  | 6 | None |- |  | 7 | None |- |  | 8 | None |- |  | 9 | None |- |  | 10 | None |- |  | 11 | None |- |  | 12 | None |- |  | 13 | None |- |  | 14 |  |- |   | 15 | None |- |  | 16 | None |- |  | 17 | None |- |  | 18 | None |- |  | 19 | None |- |  | 20 | None |- |  | 21 | None |- |  | 22 | None |- |  | 23 |

|- |  | 24 | None |- |  | 25 | None |- |  | 26 | None |- |  | 27 | None |- |  | 28 | None |- |  | 29 | None |- |  | 30 | None |- |  | 31 | None |- |  | 32 | |- |   | 33 | None |- |  | 34 | None |- |  | 35 | None |- |  | 36 | None |- |  | 37 | None |- |  | 38 | None |- |  | 39 | None |- |  | 40 | None |- |  | 41 | None |- |  | 42 | None |- |  | 43 | None |- |  | 44 | None |- |  | 45 | None |- |  | 46 | None |- |  | 47 | None |- |  | 48 | None |- |  | 49 | None |- |  | 50 | None |- |  | 51 | None |- |  | 52 | None |- |  | 53 | None |- |  | 54 | None |- |  | 55 | None |- |  | 56 | None |- |  | 57 | None |}