World Generation

Warning

These docs were written for SpongeAPI 7 and are likely out of date. If you feel like you can help update them, please submit a PR!

World Generation in Minecraft is a complicated process, and Sponge adds its own complications too. Here we provide a basic overview of how it works for the interested reader. You may choose to skip this and move directly to the API details at:

• WorldGeneratorModifiers
• Modifying World Generation

An Overview of World Generation in Minecraft

World generation in Minecraft is based on chunks. Whenever the game calls for a chunk which does not yet exist, a request is made to the world generator to provide that chunk. The process to provide this chunk is split into two distinct phases, named Generation and Population.

The Generation Phase

The first phase in providing a chunk is the Generation Phase. This is primarily responsible for the creation of the base terrain shape, the generation of biomes, and larger features such as villages and caves.

Note

Block placement in the generation phase takes place entirely within a buffer, as the Chunk object is not created until the last step in the phase.

The first step is for the biome generator to populate a 2d biome buffer with the biomes that will correspond to each 1x1 column within the chunk. Next, the base GenerationPopulator creates the basic shape of the terrain. At this stage the world is entirely made of stone. Default generation is simply a heightmap generated from perlin noise, then filled in - leaving air if higher than sea level, and water if below. This step can be overridden by calling WorldGenerator#setBaseGenerationPopulator(GenerationPopulator) to provide your own custom populator to the world generator.

Next, using the biome buffer created above, the generator replaces the top layers of the terrain with the BlockStates and depths specified by the biome’s GroundCoverLayers. The biomes are provided by a BiomeGenerator - which may also be applied to the world generator with the WorldGenerator#setBiomeGenerator(BiomeGenerator) method.

Now that the base terrain has been generated and primed, we run through the GenerationPopulators. These come in two groups: those specified globally for the world generator, and those specified for a specific biome. The set of GenerationPopulators used is the union of the GenerationPopulators specified for each of the unique biomes within the chunk.

GenerationPopulators are designed for large intensive operations, and are applied to the buffer rather than the (as yet non-existent) Chunk object. This means that there must be the restriction that GenerationPopulators may not place any blocks outside of the confines of the currently generating chunk. Content being generated by a GenerationPopulator which spans multiple chunks must generate in pieces using the chunk position and world seed to determine which piece of the whole goes into the current chunk.

Finally, with the base terrain created, the biomes applied, and the GenerationPopulators run, we have completed the generation phase, and the Chunk object can be constructed and returned.

The Population Phase

The Population Phase can only run on a chunk once the three chunks adjacent to it in the positive x and z directions are loaded. This allows objects during this phase to expand outside the 16x16 chunk area being populated, without requiring the partial generation used for GenerationPopulators. To support this, the actual area populated during this phase is a 16x16 area offset by 8 in each of the x and z axes.

Only the Populators of the biome at the position (x*16+16, 0, z*16+16) are applied to this area. It does not apply a union of all the biomes as is the case for GenerationPopulators.

Populators are ideal for small features (e.g. desert wells) and additional terrain covering (e.g. trees). Sponge provides access to a great number of vanilla specified populators which may be reconfigured for your use.