WorldGeneratorApi 1.3

Advanced but easy to use API to customize your terrain

  1. rutgerkok
    Native Minecraft Version:
    Tested Minecraft Versions:
    • 1.17
    Source Code:
    Wiki and plugin tutorials - Bug reports

    Designing your own world generator for Bukkit is hard. Bukkit doesn't let you hook into the Minecraft terrain generator, so if you just want to change the shape of the terrain, you would need to rewrite almost the entirety of the Minecraft terrain generator. Alternatively, you can hook into Minecraft internals, but this is tricky and tends to break on every Minecraft update.

    WorldGeneratorApi provides a clean API to design your own world generator, while still using components of Minecraft if you want. In just a few lines of code, we can create a complete plugin that generates flat worlds:

    Code (Java):

    public class YourPlugin extends JavaPlugin {
       public ChunkGenerator getDefaultWorldGenerator(String worldName, String id) {
           return WorldGeneratorApi.getInstance(this, 0, 6).createCustomGenerator(WorldRef.ofName(worldName), generator -> {
               // Code modifying the world generator goes here
               generator.setBaseTerrainGenerator(new BaseTerrainGenerator() {
                   public int getHeight(BiomeGenerator biomeGenerator, int x, int z, HeightType type) {
                       // Used by for example village generation to probe if the terrain is not too hilly
                       // If calculating the terrain height would be too complex, you can also extend a
                       // "BaseNoiseGenerator" instead of a "BaseChunkGenerator" - that class automatically
                       // calculates the terrain height based on the noise function you give it
                       return 70;

                   public void setBlocksInChunk(GeneratingChunk chunk) {
                       chunk.getBlocksForChunk().setRegion(0, 0, 0, CHUNK_SIZE, 70, CHUNK_SIZE, Material.STONE);


    As you can see, only the shape of the terrain is modified, the rest of the world generator is untouched. Want to disable flowers and grass? Add generator.getWorldDecorator().withoutDefaultDecorations(DecorationType.VEGETAL_DECORATION);. Don't like caves and ravines? Add generator.getWorldDecorator().withoutDefaultDecorations(DecorationType.CARVING_AIR);.

    • Control the base shape of the terrain.
    • Control the locations of biomes.
    • Disable vanilla resources (caves, flowers, villages, etc.)
    • Add custom resources
    • Supports the async chunk generator of Spigot and Paper
    See the wiki for how to get started writing your plugin.

    • There is no way to add custom biomes yet.
    • There is no way to spawn entities yet.
    For server admins
    You'll only need this plugin if another plugin asks you to download it. To modify the terrain, you will need to download one of the plugins listed below at "Plugins using WorldGeneratorApi".

    There's a command /worldgeneratorapi reload that you may find useful: it reloads the world generators of all worlds, applying any updated settings. This might save you quite a few server restarts. The permission node for the command is worldgeneratorapi.command. OPs have this permission node by default.

    Plugins using WorldGeneratorApi

    Dough World Generator
    This is a little plugin designed to show the power of WorldGeneratorApi. It allows you to customize the shape of your terrain. It can import the settings from the old Customized world type.


    More information - Install

    Pancake World Generator
    This is a tiny plugin that flattens your terrain, while leaving all other elements of world generation intact. So you will still have biomes, caves, structures, ores, trees, grass, etc.


    More information - Install

    Bento's Boxed
    Start in a tiny box, which expands as you gain achievements. Uses WorldGeneratorApi for custom terrain height and biome placement.

    More information

    Made a plugin? Please tell me, I will add it here!

Recent Reviews

  1. WoterStudio
    Version: 1.2.2
    I like this API! Its very usefull and performant! Also nice tutorials in the Wiki :D
  2. LukasUnstopp
    Version: 1.1.4
    Really like it! Dont use EpicWorldGenerator etc. Now generate you own world :D!
  3. Proxxo
    Version: 1.0
    Just tried the dev pancake tutorial with a 1.16.1 server. Got it working within minutes. Wlil now dig deeper and hopefully use it to generate a customized farm world for my server. Awesome work, thanks a lot!
  4. Ultimga
    Version: 0.6
    Thank you for sharing this! I've been trying to modify vanilla gen for my own terrain plugin and this is a massive time saver. Easy to pickup API, dropped right into my code base. Great job!
  5. OnyxianSoul
    Version: 0.5
    Thanks a lot for sharing this. It seems really interesting and helpful.

    I can't wait to see how far it goes!
  6. Jabbablocker
    Version: 0.5
    I'm going to put a 30gb hosted server on full grind see what I can get Pancake and Dough to do with a decent seed in 1.15.2. I thank you for creating this API <3. Might post Dynmap online map of worlds link with progress update. I hope more plugins use your API in future. Good job, sir!