How to Add Images in WorldPainter: A Complete Guide

WorldPainter is a powerful map-generation tool for Minecraft that lets you paint terrain like a canvas. One of its most useful — and often underused — features is the ability to import images to shape your world. Whether you want to recreate a real-world landscape, use a hand-drawn heightmap, or stamp a custom texture across your terrain, understanding how images work in WorldPainter opens up a serious creative toolkit.

What "Adding Images" Actually Means in WorldPainter

WorldPainter uses images in several distinct ways, and it's worth separating them before diving into the steps:

• Heightmaps — grayscale images that define the elevation of your terrain
• Custom brushes — images used as brush shapes when painting terrain
• Custom overlays — images applied as texture or biome guides across the map

Each of these serves a different purpose and follows a slightly different workflow. Knowing which one you need is the first decision to make.

How to Import a Heightmap Image 🗺️

A heightmap is a grayscale image where pixel brightness determines terrain height — white pixels become mountains, black pixels become ocean floors.

Steps to import a heightmap:

1. Open WorldPainter
2. Go to File → Import → Heightmap
3. Browse to your image file (supported formats include PNG, BMP, and TIFF)
4. A dialog box will appear asking you to configure settings:
   • Scale — how many Minecraft blocks per pixel
   • Height range — the minimum and maximum Y-level the image maps to
   • Water level — where sea level sits relative to the image values
5. Preview the result in the viewport and adjust as needed
6. Click OK to generate the terrain

The bit depth of your image matters here. An 8-bit grayscale image gives 256 distinct elevation values, while a 16-bit image gives 65,536 — meaning significantly smoother elevation transitions and finer detail. If you're building a large, detailed map, a 16-bit PNG or TIFF will produce noticeably better results than a standard 8-bit JPEG.

One important note: JPEG images use lossy compression, which introduces noise artifacts into the grayscale values. This creates jagged, uneven terrain even on what looks like a smooth gradient. Always use PNG, TIFF, or BMP for heightmaps.

How to Add Custom Brush Images

WorldPainter's painting tools use brush shapes to define how terrain is applied. By default, several built-in brushes are available, but you can load any grayscale image as a custom brush.

To add a custom brush image:

1. Select any paint tool from the left toolbar (such as the raise/lower terrain tool)
2. In the brush panel on the right side, click the "+" or "Load custom brush" button
3. Navigate to your PNG image
4. The brush will appear in your brush selector immediately

Custom brushes work best when they are:

• Square images (equal width and height)
• Grayscale, where white areas apply full brush intensity and black areas apply none
• Reasonably sized — very large brush images (above 512×512) may slow performance depending on your system's RAM

How to Use Images as Custom Overlays or Textures

WorldPainter also allows you to reference an image as a color map or overlay to guide biome placement, annotation, or terrain painting across a large map area. This is often done in combination with the custom layer system or the annotations layer.

For painting terrain based on a reference image (like a satellite map of a real location):

1. Import the image as a heightmap first to establish elevation
2. Use the original color image separately as a visual reference in an image viewer alongside WorldPainter
3. Manually paint biomes and surface textures in WorldPainter, using the reference image as a guide

Some advanced users work with third-party tools like QGIS or Photoshop to preprocess satellite data into both a heightmap layer and a separate biome color key before importing.

Key Factors That Affect Your Results

Common Issues When Importing Images

Terrain looks jagged or noisy — almost always caused by using a JPEG. Convert to PNG first using any image editor.

Map is too flat or too extreme in height — adjust the height range sliders in the import dialog. The default range may not suit your source image's actual tonal range.

Image won't import — check that the image is in RGB or grayscale mode, not CMYK. Some design applications export in CMYK by default, which WorldPainter does not support.

Custom brush doesn't appear — confirm the image is a standard PNG with no transparency layers causing conflicts. A flat grayscale PNG on a white background typically works reliably.

The Variables That Make This Personal 🖥️

How well any of this works in practice depends on factors unique to your project. A small creative survival map has entirely different needs than a 1:1 recreation of a real mountain range. The size of your source image, the level of geographic detail you're working with, how much manual painting you plan to do afterward, and the performance ceiling of your hardware all shape which approach makes sense.

Someone importing a simple hand-drawn island sketch will have a very different experience from someone processing 16-bit elevation data from a geological survey. Both are valid uses of the same toolset — but the settings, file prep, and workflow that work well for one may not translate directly to the other.