Chunks/blocks retrieved through the API have an inconsistent state

With this thread I would like to make plugin developers aware of a disturbing design flaw in the Bukkit API, that has been overlooked for far too long.

Every plugin that performs any form of interrogation or block manipulation inside a chunk is affected by this problem. And errors occuring because of this fact are very hard to trace if you don't understand what's happening under the hood.

In essence, blocks in chunks are generated after the chunk's been created. Forcing this to happen occurs with a call to world.loadChunk with the last parameter set to true. But this shouldn't give you peace of mind. Another stage, called chunk population, occurs after this stage, and you lack any sort of control over when this is happening. Chunk population is triggered by loading the neighbouring chunks, and is responsible for further modifying the chunk by replacing the existing blocks with lakes, structures, etc. The end of this stage effectively means you are now safe to work with the chunk and its blocks in any way you want.

What is really disturbing is the fact Bukkit doesn't give you a way to interrogate whether a chunk has been fully generated and populated and offers you no way of forcing it to happen. A workaround is to load all the neighbouring chunks and assuming your chunk was populated before you start working in it. Hooking up to the ChunkPopulated event is not an option, because this event won't fire if the chunk was fully generated and besides, going down this road will lead to elaborate schemes of inter-event synch mechanisms, prone to errors and deadlocks.

In Mojang code, chunks have a flag indicating they are ready to use. The Bukkit team however decided to let us struggle with half baked chunks. I've been trying to make them aware of this issue with the bug #2753, with little luck so far.

Bukkit is moving forward, ignoring this problem and adding more on top. In a dev build of 1.4.5 R0.3 I saw a commit that would move the logic for all these stages onto a different thread. They also versioned the CraftBukkit packages, meaning that if you've decided to overcome these limitations by going one level deep (accessing CraftWorld or CraftChunk for example), you end up being dependant on the Craftbukkit version.

So there it is. To this moment, for plugin development, there is still no reliable way of working with the most basic elements of this game: chunks and blocks.