How to create «minecraft» maps with worldpainter

Apple Java Extensions

To integrate with Mac OS X on Java 8, the Apple Java Extensions are needed. They are proprietary code which cannot be distributed by us so you will have to download it manually and install it in your local repo the same way as above. They can currently be found ​here. Download the file and extract the file from it. Install it in your local repo with the following command:

mvn install:install-file -DgroupId=com.apple -DartifactId=AppleJavaExtensions -Dversion=1.6 -Dpackaging=jar -Dfile=AppleJavaExtensions.jar

Of course if you are not interested in running the code on Apple Mac OS X, or running it on Java 8, you can also just remove this dependency and the code that uses it. WorldPainter will still run on Mac OS X on Java 8, but it will be less well integrated into the menus.

Set up Maven toolchains

WorldPainter uses the Maven toolchain framework (​https://maven.apache.org/guides/mini/guide-using-toolchains.html) to find the JDK’s it needs. You need to follow the instructions on that page to configure two toolchains: one of type and version pointing to a Java 8 JDK, and one of type and version pointing to a Java 9 JDK. You can do this by placing a file called in your or directory with the following contents:

<toolchains>
        <toolchain>
                <type>jdk</type>
                <provides>
                        <version>9</version>
                </provides>
                <configuration>
                        <jdkHome>PATH TO JAVA 9 JDK</jdkHome>
                </configuration>
        </toolchain>
        <toolchain>
                <type>jdk</type>
                <provides>
                        <version>1.8</version>
                </provides>
                <configuration>
                        <jdkHome>PATH TO JAVA 8 JDK</jdkHome>
                </configuration>
        </toolchain>
</toolchains>

Build WorldPainter

Once all dependencies are installed and the toolchains set up you can build WorldPainter from the command line or using your favourite IDE:

The water is uneven or there are square patches of water on the world

There are various ways this could have happened, for instance:

• There used to be a bug in WorldPainter which could cause patches of water to remain behind if you cancelled a Flood operation. These patches would only be visible after saving and loading the world. The bug has been fixed, but if this happened to your world in the past the water patches might still be there.
• You can get standing columns or walls of water if you flood a valley, and then expand the valley by lowering the land around the edge without re-flooding the lake. When you expand a flooded valley, make sure to re-flood the lake by right-clicking on the water once with the Flood tool, and then left-clicking.
• Another way to get discrepancies in water height is by using the Sponge tool to reset the water level, and not finishing the entire area. When using the Sponge tool to reset the water level (by right-clicking), be careful to apply it to the entire body of water.

Regardless of how it happened, there are a few ways in which you can fix it:

• You can reset the water on the entire map using the «reset all water or lava» operation of the Global Operations tool (Ctrl+G or the globe icon on the Tools panel). This will reset the fluid level and type on the entire map to whatever you originally specified on the New World screen. The downside is of course that any valleys you dried will be refilled and lakes at other than default elevations will be removed or changed.
• Another technique for easily fixing a large body of water is to right-click with the Flood tool on an area of the water that is at the correct height (this will lower any water which was at a higher level), and then left-click to raise it back to the desired height (this will raise any water which was at a lower level).
• For more manual control you can use the Sponge tool. Left clicking completely removes water and lava. Right-clicking resets the water level to the default. See above for how to change the default water level.

Reduce WorldPainter’s memory usage

If that didn’t work, you can try to get WorldPainter to use less memory during the export, by making it export fewer regions in parallel. Normally it tries to use all your CPU cores at once, but each parallel export takes up memory and reducing the parallelisation, while making the export go slower, might avoid the thrashing condition and allow it to actually complete.

1. Determine how many cores it’s trying to use

The first step is to determine how many cores WorldPainter was trying to use for the hanging export, by looking at the log file. The log file is called , and is located in on Windows, on Mac OS X and on UNIX/Linux. Open it using any text editor and look for a line that looks like this:

Make sure it is the one for the hanging export (probably the last one in the file, unless you tried more exports after that). The n is the number of cores it was trying to use.

If n is 1 then it was already using no parallelisation whatsoever and there is no use in proceeding.

2. Configure it to use fewer cores

To configure WorldPainter to use fewer cores, use a text editor to open the file (on Windows and UNIX/Linux) or (on Mac OS X) and add the following line:

Where n is one less than the number determined in step 1! For details about how to find and edit these files, see the MoreMemory page.

3. Rinse and repeat

Save the file, (re)start WorldPainter and retry the export. If it now works, great! If it doesn’t, repeat step 2 until you reach 1 core, at which point there is no use in proceeding.

Note: if you can’t get it to work, then remove this parameter from the file again! Otherwise it will unnecessarily keep throttling WorldPainter while you try other options.

Is Multiplayer supported? How do I put the map on a Minecraft server?

Yes, Multiplayer is supported. Multiplayer maps are exactly the same as Singleplayer maps. Just Export the world like normal. Then, if you run the Minecraft server on the same computer, just move or copy the generated map directory to your Minecraft server installation directory, edit the property in the file to be the same name as the directory, and (re)start the server. If the server is on a different computer the steps are the same, but you will have to transfer the map to the server somehow, generally by zipping it and transferring it to the server using a program such as Filezilla. Those details are beyond the scope of this site though. Ask your server administrator for the best way to transfer maps to the server, or google the subject.

Export from the command line

If none of the above worked and you’re comfortable getting your hands dirty on the command line, you can try using a script to export the world instead of using WorldPainter. Scripts use less memory than WorldPainter proper, so they might succeed if WorldPainter does not. Using a text editor, create a file in the directory where your .world file is stored, named , with the following contents:

var world = wp.getWorld().fromFile(argv1]).go();
wp.exportWorld(world).toDirectory('.').go();

Then export the world by opening a terminal or command prompt window, navigating to the directory where your .world file is stored, and executing the following command. For more information about what the «command prompt» is and how to access and use it on Windows, see ​this page. Similar information can be found for Mac OS X and UNIX/Linux. Google is your friend.

wpscript exportworld.js "MyWorldName.world"

Where is the name of your .world file, in double quotes in case the name contains spaces. This will export the map to a subdirectory of the current directory (which is the directory in which your .world file is stored), which you will then have to move to the Minecraft directory manually. You don’t have to use the command line for that; you can drag and drop it.

Note: the export script operation gives no progress feedback. This is normal, but it means there is no way to tell visually whether it is hanging or not, or how far along it is. Instead you should regularly check the total size of the files in the map directory it has created (on Windows you can do that by opening the properties of the folder in Explorer) to check whether it keeps steadily increasing.

Note: with this method you cannot change the export settings from WorldPainter’s Export screen. Those settings are stored in the .world file, so you can change them by starting an export with the desired settings in WorldPainter, immediately cancelling the export, and then saving the .world file. If you then export it with the script method the same settings will be used as for the aborted export.

There is water underneath all of my land

If there is ocean underneath your land after Exporting your world and opening it in Minecraft, you probably exported it in the wrong format with Populate enabled. If you Export the world in 1.12 format, and you used the Populate layer or you enabled «allow Minecraft to populate the entire terrain», and then you open the map in Minecraft 1.13 or later, then Minecraft will regenerate (part of) all the chunks marked as «to populate».

To prevent this, Export the world in Minecraft 1.15+ format. Unfortunately Minecraft 1.13 and later don’t support populating chunks, so you will have to use WorldPainter layers to generate all the structures you need, including vegetation, trees, lakes, buildings, etc..

Types of Terrain in WorldPainter

By changing the size of the brushes, you can make a small lava pit or a vast river or ocean. It is easy to make a grassy oasis in a desert world. In our Minecraft desert map, an oasis will be a big help for players, as they will need water and dirt blocks to farm their own food and go fishing.

I used a small, round brush to apply a jungle layer to this strand of grassland.

WorldPainter runs out of memory

• First, reconsider whether you really need to create a world of the size you’re trying to create. Focus on quality, not quantity, especially for adventure maps. A large map will take far longer to make, and many Minecraft hosters won’t allow maps larger than 5000 blocks squared. Server maps can generally support hundreds of players with just a few thousand blocks squared.
• Windows only: 64-bit WorldPainter can use much more memory than 32-bit WorldPainter. If you have 64-bit hardware, make sure to use the 64-bit version of Windows, Java and WorldPainter. If the installer tells you it can’t find a Java VM, you may have to install 64-bit Java first, which you can get here (pick the file ending in ).
• If you installed WorldPainter using an installer, it is already using the maximum recommended amount of memory (unless you are on Windows and are using the 32-bit version, see above). Install more memory (and reinstall WorldPainter, so that it will use it).
• If you installed WorldPainter from an archive, you can manually increase the amount of memory allocated to it by editing the file (Windows or Linux) or file (Mac OS X). See the MoreMemory page for details on how to do that.

How do I make the borders of the map look nice and integrate well with the Minecraft landscape?

When you leave the WorldPainter-generated chunks, Minecraft will start generating land again, according to the seed you specified and its own algorithms. There is nothing WorldPainter can do to avoid that. If you don’t take this into account, the edges or seams between your world and the Minecraft world may be very abrupt and ugly. There are several strategies for making the seams look good:

1. Make the edges of your world all water, and use the «ocean» Minecraft seed option (the default) on the New World screen. Make sure to use the default water level for your world (62) and make the water depth around the edges at least fifteen blocks so it will match the ocean floor better. This will embed your world into a huge ocean and since the seams are all water they will be almost unnoticeable. Note that this does mean that there will be no other continents anywhere nearby though!
2. Configure a border on the Export screen. Note that this doesn’t get rid of the seams, it just moves them further away. Also note that if the edges of your world are land (instead of water), or if the water level of your map is different than the border level, there will still be an ugly edge between your land and the border.
3. Use the «bedrock wall» option on the Export screen to make it hard to leave your world. Note that it is still possible to leave it, since you can just build your way to the top of the wall and walk right over it. And of course it means an ugly wall all around your world. You can combine this option with a border, so that you at least can’t see the wall from the shores of your world.
4. Use the Import/Merge functions to smooth the seams after the fact:
   • Export your world
   • Load it in Minecraft, and fly along all the edges, forcing Minecraft to generate all the chunks around the edges
   • Import the map into WorldPainter using Ctrl+I or File -> Import -> Existing Minecraft map…
   • Use the Smooth tool, terrain tools, and any other tool of your choice to merge and smooth the seams
   • Select the Read-only layer, select a large and solid brush and set the intensity to full, and paint the entire interior of the world with the Read-only layer. This will greatly speed up the merge process. Be careful not to mark any chunks near the seams read-only though, as your edits in those chunks would be lost
   • Merge the changes with the original map using Ctrl+R or File -> Merge World…
   • The downside of this is that changing the slope of the land will mess up any trees that were on it. You’ll have to visit all the seams again in Minecraft to manually fix problems introduced by the merge

How do I change what Minecraft does when I use Populate? How do I get rid of all the small water and lava lakes?

The small water and lava lakes aren’t created by WorldPainter, they are created by Minecraft when you use the Populate layer, or enable the «allow Minecraft to populate the entire terrain» option. WorldPainter has no control over what Minecraft does when it populates a chunk, at least not for the Default and Large Biomes world types. All it can do is tell it to populate the chunk, or not, for each individual chunk. If Minecraft populates a chunk it will add underground resources, vegetation, trees, small water and lava lakes, snow and ice, villages, ravines, strongholds and abandoned mines. It will not generate caves. For more details about the proper use of the Populate layer, see the Populate page.

If you don’t want the small water and lava lakes, you do have one option: you can set the world type to Superflat, and then use the Superflat preset to configure exactly what you want Minecraft to do during the population step. For more details about this technique, see ​this YouTube video by Fornan II.

You should also consider whether you need Populate, as WorldPainter has its own layers for almost everything. The only thing that WorldPainter can’t generate itself is structures (mines, villages, etc.). By default the Resources layer is «on everywhere», so WorldPainter already generates underground resources. You can use the other layers to add things like Deciduous or Pine forests, snow and ice, underground Caverns and Chasms, etc.

Applying a Terrain Type Directly

A terrain type can also be applied to a world directly, without a height map but optionally with a filter:

wp.applyTerrain() // The terrain type index to set
    .toWorld(world) // See "Loading a World" or "Creating a World from a Height Map"
    .withFilter(filter) // Optional. Specifies conditions for where the layer will be applied. See below for details about creating a filter
    .applyToSurface() // Optional. Mutually exclusive with applyToNether() and applyToEnd(). Indicates that the layer should be applied to the Surface dimension. This is the default
    .applyToNether() // Optional. Mutually exclusive with applyToSurface() and applyToEnd(). Indicates that the layer should be applied to the Nether dimension
    .applyToEnd() // Optional. Mutually exclusive with applyToSurface() and applyToNether(). Indicates that the layer should be applied to the End dimension
    .go();

For an overview of the actual terrain type indices to use in applyTerrain() and the terrain types to which they correspond, see this page. Note that if you want to include Custom Terrain types which aren’t already present in the world, you must install the Custom Terrain type on the world first (see «Installing a Custom Terrain» above) and that operation will return the terrain index to use for that particular Custom Terrain.

Using WorldPainter in your own code

If you only want to write your own code making use of WorldPainter, rather than make changes to WorldPainter itself, then you don’t need to build WorldPainter! The WorldPainter binaries, along with Javadoc and source code jars, are in Maven Central. For details, see this page.

Check out the source code

The WorldPainter source code is hosted on GitHub: ​https://github.com/Captain-Chaos/WorldPainter

Check it out from there, or fork it and then check out your own fork. The command for checking out the code anonymously from the command line is:

git clone https://github.com/Captain-Chaos/WorldPainter.git

Install missing dependencies

WorldPainter uses some dependencies which are not present in Maven Central, either because they are commercial products, or they are too old, or the creators aren’t aware of Maven. Some of these dependencies (JPen; the NetBeans Dark Look and Feel) are hosted in a private Maven repo on www.worldpainter.net (see the pom.xml for the WorldPainter module), but some you will have to download and install manually:

TODO: JPen has native libraries, which are currently missing (meaning the tablet support won’t actually work. This has yet to be incorporated in the build somehow.

How do I edit existing Minecraft maps?

WorldPainter is a map generator, not an editor! The basic idea is to use it for generating new maps which you then edit with other tools such as creative mode, ​WorldEdit, ​VoxelSniper or ​MCEdit.

Having said that, WorldPainter does have limited support for making changes to existing maps, using the Import and Merge operations. Import (Ctrl+I or File -> Import -> Existing Minecraft map…) will create a new WorldPainter world based on the landscape (terrain height and type and biome information, but no underground or above ground structures, trees, etc.) of an existing map. Merge (Ctrl+R or File -> Merge world…) will merge any changes you make back to the existing map.

Important notes:

• You have to use Merge (Ctrl+R), not Export, to save your changes back to the existing map!
• When Importing an existing map, any chunks containing man-made blocks will be marked read-only, visible by a black cross across them. This includes underground blocks from mines and strongholds. Chunks that are marked read-only are not merged during the Merge process. You can still make changes to them in the editor, but those changes won’t be saved. This is to protect man made structures from the merge process, which can be destructive and mangle structures, especially if you changed the slope of the terrain. If you still want to make changes to those chunks (at your own risk), you can remove the read-only layer (like any other layer: select the Read-only button and right-click to remove it). Note that you can also add the read-only layer to areas where you don’t intend to make changes, which will speed up the merge process.

Types of Layers in WorldPainter

By using different brush textures and layers, users can create many different features on their Minecraft map. The jungle layer above the water above was applied with the spike circle brush to create a soft of oasis for players; this way, wood can be obtained outside of the desert. Experiment with different types of terrain to see what you like!

The pyramid tool is a fun way to add large, realistic structures to a desert world.

Applying a Height Map to the Terrain Type

To apply a height map to a world as the terrain type:

wp.applyHeightMap(heightMap) // See "Loading a Height Map"
    .toWorld(world) // See "Loading a World" or "Creating a World from a Height Map"
    .withFilter(filter) // Optional. Specifies conditions for where the terrain will be applied. See below for details about creating a filter
    .applyToSurface() // Optional. Mutually exclusive with applyToNether() and applyToEnd(). Indicates that the terrain should be changed of the Surface dimension. This is the default
    .applyToNether() // Optional. Mutually exclusive with applyToSurface() and applyToEnd(). Indicates that the terrain should be changed of the Nether dimension
    .applyToEnd() // Optional. Mutually exclusive with applyToSurface() and applyToNether(). Indicates that the terrain should be changed of the End dimension
    .scale(100) // Optional. The % at which to scale the height map. Default value: 100%
    .shift(, ) // Optional. The number of blocks the height map should be shifted east and south respectively (negative numbers shift west and north). Default value: 0, 0
    .applyToTerrain()
    .fromLevel().toTerrain() // Optional. Repeatable. Specifies that a single value from the image must be mapped to a single terrain type (see below)
    .fromLevels(, 255).toTerrain() // Optional. Repeatable. Specifies that a range of values from the image must be mapped to a single terrain type (see below)
    .fromColour(, , ).toTerrain() // Optional. Repeatable. Specificies that a single colour, in the form of red, green and blue components from 0 to 255 (inclusive), from the image must be mapped to a single terrain type (see below). The alpha value is assumed to be 255 (fully opaque)
    .fromColour(, , , ).toTerrain() // Optional. Repeatable. Specificies that a single colour, in the form of alpha, red, green and blue components from 0 to 255 (inclusive), from the image must be mapped to a single terrain type (see below)
    .go();

About the mapping:

You may map EITHER grey scale values (using fromLevel() and fromLevels()) OR colour values (using fromColour()), but you may not mix both. Mapping colour values obviously is only useful if the height map was derived from a colour image. Note that the colours are only matched exactly as specified. Slightly different colours don’t match. Therefore you must make sure that your input image contains only solid areas of discrete colours and has no anti-aliasing, smoothing, mixing of colours, gradients, etc.

For applying a height map to the terrain, the mapping is to arbitrary terrain type indices which correspond to different terrain types. It depends on the type of height map what kind of mapping makes sense. If it is a genuine height map (i.e. it corresponds to surface heights) then you can use it to map different height ranges to different terrain types, and it makes sense to use the ranged setter (fromLevels().toLevel()) to set up the mapping.

If instead the «height map» is a value map or mask which directly indicates which terrain types must be used then using the ranged setter does not make sense and it would be better to use the one on one setter (fromLevel().toLevel() or fromColour().toLevel()) repeatedly to set up each mapping of a «height map» value or colour to a terrain type.

For an overview of the actual terrain type indices to use and the terrain types to which they correspond, see this page. Note that if you want to include Custom Terrain types which aren’t already present in the world, you must install the Custom Terrain type on the world first (see «Installing a Custom Terrain» above) and that operation will return the terrain index to use for that particular Custom Terrain.