MineFlat Binary World Storage Specification

HEADER:

The first 16184 bytes (16 KiB) of the save file are reserved for a header. The header will contain global world information as well as binary addresses within the file.

Key-value pairs in the header are prefixed by two bytes denoting their values' size in bytes. The next two bytes are the key, and the rest of the section as per the specified size are the value. For example, an excerpt from the header file might look like this:
...000C000152A8EF2B88600090001E3F1119D500060004867D9B...
Punctuated for readability:
...000C-0001:52A8EF2B886|0009-0001:E3F1119D5|0006-0004:867D9B...
The present key-value pairs being:
0x0000: 0x52A8EF2B886
0x0001: 0xE3F1118D5
0x0004: 0x867D9B

KEYS:

Each key occupies two bytes of the header. The first byte represents the key type (file metadata, pointer, etc.). The second byte represents the precise information type stored by the value (exact metadata value, pointer type, etc.).

0x00XX: Storage metadata. These keys contain information pertaining to the save file itself, such as revision, bytes allocated for certain purposes, and timestamps.
0x0000: Format revision (two bytes). This may be used for cross-compatibility, or to prevent reading of incompatible saves.
0x0001: Last compatible revision (two bytes). This is used to determine compatibility between game versions and save format revisions.
0x0002: Creation time as a UNIX timestamp (eight bytes).
0x0003: Last revision time as a UNIX timestamp (eight bytes).
0x00FF: End of header. This is always prefixed by 0x0000, as the value does not exist. All header bytes after this key are ignored, though they should remain as 0x00.

0x01XX: Metadata pertaining to the world.
0x0100: World name as a UTF-8 string (256 bytes).
0x0101: World time in ticks (two bytes).
0x0102: Chunk width (two bytes).
0x0103: Chunk height (two bytes).

0x02XX: Pointers used to point to a section by its binary address. The first four bytes represent the size in bytes of the section, while the next four bytes represent its location in storage. This system means that the body will never be read but in small sections as denoted by the header.
0x0200: Chunk pointers.
0x0201: Entity pointers.
0x0202: Inventory pointers.

BODY:

Everything after the first 16 KiB of the file is body content, used to store specific data for the world. It is divided into sections, each referenced by the header. The first byte represents the content type, and should match the second byte of the pointer in the header. This serves the purpose of verification. The next four bytes represent the section's size, and should also match the corresponding bytes of the pointer in the header. This also serves the purpose of verfication. Should these first bytes not match the expected values from the header, the section should be skipped.

Chunk definitions:

Sections of type 0x00 contain information pertaining to a chunk. This includes chunk number and block data.

The first three bytes are a binary representation of the chunk's number in the world, the first byte being reserved as a negative flag (if 0x01, the chunk number is negative).

All remaining bytes of the section are reserved for block data, as detailed below.

Block definitions:

Each chunk definition is divided into multiple subsections which use a similar syntax as header data storage. The first two bytes of each block definition are reserved for the section's size. The subsection is thereupon divided into even more subsections, each a key-value pair. The first two bytes of each tertiary division are reserved for its value's size, and all remaining bytes are used for key-value pairs. Each key occupies two bytes. The possible keys are listed below:

0x0000: Block x-position (two bytes).
0x0001: Block y-position (two bytes).
0x0002: Block type (two bytes). This value represents the ingame ID of the block's type, as determined by the Material enum.
0x0003: Block data value (two bytes). This represents a specific variant of a block, much like wool colors in Minecraft.
0x0100: Skip flag (two bytes). This may be used for file compression to represent large quantities of identical blocks with a single block definition. If present, the number of blocks after the current one denoted by the value will use the same information as the one containing this flag.

Entity definitions:

An entity definition contains data pertaining to a single entity in the world. It follows the same key-value syntax as the header. The first two bytes are reserved for the value's size. The remaining bytes are occupied by key-value pairs. The possible keys are listed below:

0x00XX: Static data. These values should not change between saves.
0x0000: Entity ID (two bytes). This value represents the ingame ID of the entity's type, as determined by the EntityType enum.
0x0001: Entity UUID (two bytes). This value represents the unique ID of the entity in the world. No two entities may have the same UUID.
0x01XX: Dynamic data. These values may change between saves.
0x0100: Chunk number (three bytes). The first byte is reserved as a negative flag.
0x0101: x-position (two bytes).
0x0102: y-position (three bytes). The first byte is reserved as a negative flag, as the entity may be above the y=0. In the event that the absolute y-value exceeds 65,536 (2^32), the entity's y-position will be reset to that value.
0x0103: Health level (one byte). This value represents the current health level of the entity.
0x0104: Maximum health level (one byte). This value represents the maximum health level the entity may have.
0x0105: Hunger level (one byte). This value represents the current hunger level of the entity.
0x0106: Maximum hunger level (one byte). This value represents the maximum hunger level the entity may have.
0x0107: Entity data value (two bytes). This may be used to store a single piece of information about the entity, such as the item ID of an item drop.
0x0200: Metadata key-value pair. The first byte represents the size of the metadata key. The following bytes as per the key size are a UTF-8 representation of the key's title. The remaining bytes are a UTF-8 representation of the value.
0x0300: Player flag (zero bytes). If present, the entity will be marked as the main player. This will be ignored if the entity's type is not PLAYER.

Inventory definitions:

Inventory definitions contain information about an inventory. This inventory is assigned to a block or an entity upon being loaded. It follows a key-value syntax, with the first two bytes being reserved for value size, and the next two for the key. Possible keys are listed below:

0x0000: Entity flag (one byte). If this is 0x00, the inventory will belong to a player. If this is 0x01, the inventory will be assigned to an entity.
0x0001: Block chunk (three bytes). First byte is dedicated to a negative flag. Applicable only to block inventories.
0x0002: Block x-position (two bytes). Applicable only to block inventories.
0x0003: Block y-position (two bytes). Applicable only to block inventories.
0x0004: Entity UUID (two bytes). Applicable only to entity inventories.
0x0100: Inventory size (one byte).
0x02XX: Inventory slot definition, detailed below (variable size). XX represents the slot number in the inventory.

Inventory slot definitions:

Inventory slot definitions contain information pertaining to a slot in an inventory. They are a subsection of inventory definitions. They follow a key-value syntax. Possible keys are listed below:

0x0000: Item ID (two bytes).
0x0001: Quantity (one byte).