Java Edition protocol/Data types

This feature is exclusive to Java Edition.

 

This article defines the data types used in the 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.

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.-_/]

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 leftmost bits are filled with zeroes regardless of the sign,
        // rather than being filled with copies of the sign bit to preserve the sign.
        // In languages that don't have a ">>>" operator, This behavior can often be selected by
        // performing the shift on an unsigned type.
        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 leftmost bits are filled with zeroes regardless of the sign,
        // rather than being filled with copies of the sign bit to preserve the sign.
        // In languages that don't have a ">>>" operator, This behavior can often be selected by
        // performing the shift on an unsigned type.
        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:

Sample VarLongs:

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 arithmetic shift), 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 }

Some fields may be stored as fixed-point numbers, 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);

The types Array and Prefixed Array represent a collection of X in a specified order.

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 String Array with the values ["Hello", "World!"] has the following data when encoded:

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

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

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

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

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.

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.

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

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

These types are commonly used in conjuction with ID or X to specify custom data inline.

Describes a sound that can be played.

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

The chat type decorations look like:

A bit field represented as an Int, 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.

packed_xz = ((blockX & 15) << 4) | (blockZ & 15) // encode
x = packed_xz >> 4, z = packed_xz & 15 // decode

Describes a Minecraft player profile.

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.

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

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

If the absolute maximum of every double is beneath ${\displaystyle \frac{1}{32766}\approx 3.05\times 10^{-5}}$, 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 VarInt.

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.

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

Pseudocode to read and write LpVec3:

private static final double MAX_QUANTIZED_VALUE = 32766.0;

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;
}

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));
        }
    }
}

Sample LpVec3:

This article is licensed under a Creative Commons Attribution-ShareAlike 3.0 license.

 

This article has been imported from wiki.vg or is a derivative of such a page. Thus, the wiki's usual license does not apply.
Derivative works must be licensed using the same or a compatible license.