BlockStorage

Welcome to the circus!

BlockStorage maintains persistent storage for blocks. Why is this necessary? Due to limitations of Paper/Minecraft, we cannot associate arbitrary data with blocks like we can with entities.

BlockStorage guarantees that a chunk's blocks will never be loaded if the chunk is not loaded.

We store blocks by chunk, in each chunk's persistent data containers.

This works based on chunks rather than individual blocks. When a chunk is loaded, the associated data for all the Pylon blocks in that chunk is loaded. And conversely, when a chunk is unloaded, all the data for that chunk is saved. Additionally, there are autosaves so chunks that are not ever unloaded are still saved occasionally.

When saving, we can simply ask the block to write its state to a PDC, then we write that PDC to the chunk. And when loading, we go through each block PDC stored in the chunk, and figure out which block type it is, and then create a new block of that type, using the container to restore the state it had when it was saved.

Read AND write access to the loaded block data must be synchronized, as there are multiple fields for loaded blocks. If access is not synchronized, situations may occur where these fields are briefly out of sync. For example, if we unload a chunk, there will be a short delay between deleting the chunk from blocksByChunk, and deleting all of its blocks from blocks.

See also