CustomItems region storage format - jojodmo/CustomItems GitHub Wiki

CustomItems stores blocks in the "CustomItems region" format.

The region files are stored in world folders in the "customitems_blocks" folders, and follow the format r_(x)(z).cui, where (x) and (z) are the x- and z-coordinates of the region. CustomItems regions are areas of 32x32 chunks (the same size as Minecraft's region file format, so r-1_7.cui corresponds to the region r.-1.7.mca or r.-1.7.mcr from Minecraft). For example, chunks with x 0 through 31 and z 0 through 31 are in the file r_0_0.cui, and chunks with x -32 through 1 and z 224 through 255 are in the file r_-1_7.

Here is the format of the file:

[byte(s)] what it does

[0 through 3] 0xD0 0xC0 0xC0 0xC0 [4] Major version. Currently 0x01 [5] Minor Version. Currently 0x01 [6 through 9] Reserved

[10 through 13] Length of constant pool in bytes, L [14 through 14 + L] Constant Pool [14 + L through 17 + L] Reserved [18 + L through end] Blocks

Constant Pool

For each item in the constant pool:

[0] Type (currently only 0x01, meaning "block") [1 through 2] Integer ID for the CustomItem [3 through end - 1] ID of the CustomItem, encoded as UTF-8 [end] Null terminator, 0x00

Blocks

For each block:

[0 through 3] Location in region [4 through 5] ID from the Constant Pool [6 through 9] Length of extra data in bytes (extra data doesn't exist yet, so this is always 0x00, 0x00, 0x00, 0x00)

Locations

Given the x, y, and z coordinates of the block relative to the region, the 4 location bytes are the integer (x << 19) + (z << 8) + y. Here's the code for generating the location key from the x, y, and z positions, as well as code for converting the location key back to the relative x, y, and z positions

int makeKey(int x, int y, int z){
    x = x < 0 ? 512 + x : x;
    z = z < 0 ? 512 + z : z;

    return (x << 18) + (z << 9) + y;
}

int getX(int s){
    return (s >>> 18); // move bits 17 - 25 to bits 0 - 8
}

int getY(int s){
    return s & 0x0000_00ff; // get only the last 8 bits
}

int getZ(int s){
    return (s >>> 9) & 0x0000_01ff;
}