Block Changes in Beta 1.2.13

blockstate_protocol.md

Block Storage & Network Protocol Changes

Paletted chunks & removing BlockIDs brings a few big changes to how blocks are represented. In Bedrock, Blocks used to be represented by their 8 bit ID and 4 bit data; this means that we can only represent 256 blocks and 16 variants for each block. As it happens we ran out of IDs in Update Aquatic, so we had to do something about it :)

After this change, we can represent infinite types of Blocks and infinite BlockStates, just like in Java. BlockStates are what is sent over the network as they are roughly equivalent to the old ID+data information, eg. they're all the information attached to a block.

BlockStates are serialized in two ways:

PersistentID: a PersistentID is a NBT tag containing the BlockState name and its variant number; for example

{
    "name":"minecraft:log",
    "val":14
}

in the future it will contain the actual properties of the BlockState explicitly like in Java. This format is pretty expensive to serialize and send over the network though, so it isn't used in the protocol yet (and possibly never) but it might still be useful information for map makers :)

RuntimeID: a RuntimeID is an alternate ID that is used to refer to a BlockState within a game session. It's an unsigned int that is assigned to each new BlockState we discover when loading a world; worlds with different Behavior packs can (in the future) represent the same BlockState with different RuntimeIDs.

Because of this, you shouldn't ever write RuntimeIDs to disk or make them persist across game sessions, because they should change. A future version of the protocol will let the server send a GlobalPalettePacket which will let you tell the Client which block is which and have it install new blocks.

For the time being however, RuntimeIDs are actually static ( :( ) so you will have to use a lookup table to figure out which is which! The lookup table is appended at the end.

Typically, RuntimeIDs are serialized as varints.

Item changes

We didn't do the same ID removal for Item, because Item's ID was a short already and so it wasn't as much of a concern; what we did was to move new blocks to negative IDs. So, every block past 256 will be -1, -2, -3 and so on.

This means that you can't compare Block IDs and Item IDs directly anymore, even if you keep Block IDs around!

Changed packets

This is a (hopefully exhaustive) list of packets that changed and that your server should handle to talk with this version of Minecraft. If you're wondering where FullChunkDataPacket is, no worries! That one still supports the old format so you don't have to implement block palettes right away. Other packets aren't retrocompatible though, so you'll have to fix those:

• UpdateBlockPacket: BlockID -> RuntimeID
• LevelSoundEventPacket: BlockID -> Data (which is a RuntimeID)
• LevelEventPacket: the Data varint now represents a RuntimeID for ParticlesDestroyBlock, ParticlesCrackBlock, ParticlesCropEaten and ParticlesDestroyArmorStand.
• SetEntityDataPacket: Endermen and FallingBlock use RuntimeID to represent their BlockState.

FullChunkDataPacket FullChunkDataPacket is an exception because it still understands the old format, as we needed to implement that anyway to read old worlds. Anyhow, you should start considering moving to the new format because until you do, you won't be able to send Blocks past 256 to the client!

Also, there's a small penalty to converting old chunks to new chunks on the client, so you should do that for speed as well.

The new SubChunk format

While the LevelChunk format itself is unchanged, what changed is the internal format of each SubChunk. The version is always a byte and there are a few valid SubChunkFormat versions:

• 1.2 format (versions 0,2,3,4,5,6,7) The old format. It's just [version:byte][16x16x16 blocks][16x16x16 data]. There can be light information, but it will be discarded. Note how values 0,2,3,4,5,6,7 all mean this format! We had to do this because tools like MCEdit put those values in that field and we needed to keep those worlds working.

• Palettized format (version 1) This format was introduced in 1.2.13 when palettization was initially implemented. The SubChunk just contains one block storage, so the format is [version:byte][block storage]

• Palettized format with storage list (version 8) This is the new Update Aquatic format, added to allow for several block storages. The additional block storage is used only for water for now, but we made the format generic.
  The format is [version:byte][num_storages:byte][block storage1]...[blockStorageN]

Block Storage

A Block Storage is now its own type of object (different from SubChunk) with its own format and version! Don't put weird numbers in the version field this time :)

Block Storages are comprised primarily of a block-array and a palette. The block arrays store offsets which point to positions in the palette. These block arrays can have different types, each of which uses a different number of bits to represent each block. Valid types that the client understands are:

enum class Type : uint8_t {
	Paletted1 = 1,   // 32 blocks per word, max 2 unique blockstates
	Paletted2 = 2,   // 16 blocks per word, max 4 unique blockstates
	Paletted3 = 3,   // 10 blocks and 2 bits of padding per word, max 8 unique blockstates
	Paletted4 = 4,   // 8 blocks per word, max 16 unique blockstates
	Paletted5 = 5,   // 6 blocks and 2 bits of padding per word, max 32 unique blockstates
	Paletted6 = 6,   // 5 blocks and 2 bits of padding per word, max 64 unique blockstates
	Paletted8  = 8,  // 4 blocks per word, max 256 unique blockstates
	Paletted16 = 16, // 2 blocks per word, max 65536 unique blockstates
}

These bits are stored in arrays of words. (A word is just a 4-byte unsigned int.) The number of blocks per word is sizeof word in bits / bitsPerBlock, where any remainder becomes unused padding bits on each word. Blocks never straddle words, so there are some unused bits in each word when word size doesn't divide exactly by the number of bits per block. Using less bits per block allows lowering memory usage, but also restricts the number of unique blockstates that can exist in a chunk.

Format

• 1 byte: (type << 1) | isRuntime)
  • 7 bits: the blockstorage type from the enum above, i.e. the type of palette that the blockstorage is using. This one is used to select which subclass of BlockStateStorage to create. The padded formats are kind of nasty to implement but the good news are, you don't need to implement all of them (if you do, I suggest to use a template). The server can pick whatever format and the Client will understand it. Of course, if you waste space in the palettes you won't have the best compression.
  • 1 bit: whether the chunk is serialized for Runtime or for Persistence: always 1 when over the network.
• 4096 / blocksPerWord words (plus 1 extra word in padded formats, e.g. for sizes 3,5 and 6): The actual blocks.
• 1 varint: The palette size N
• (for network) N varints: The palette entries, as RuntimeIDs. You should use the RuntimeID table to convert those to actual blocks.
• (for persistence) N NBT tags: The palette entries, as PersistentIDs. You should read the "name" and "val" fields to figure out what blocks it represents.

Note that for the palette size for persistence, the size is a regular int (32bit) little endian. And the NBT is little endian NOT using varint.