The basic way to add images in WorldPainter

WorldPainter does not import images directly into the terrain itself. Instead, you use images as reference layers that sit on top of your map while you paint, then disappear when you export. This means you can load a photograph, a sketch, or a map and paint over it to match the terrain you want to build.

To add an image, open WorldPainter and go to View in the menu bar, then select Import Image as Layer. A file browser will open. Choose a PNG, JPG, or BMP file from your computer. WorldPainter will place the image on your map at full size, and you can then paint underneath it or adjust how transparent it is.

The image layer appears in the Layers panel on the right side of the screen. You can toggle it on and off by clicking the eye icon next to its name, or delete it by right-clicking and selecting Remove Layer. The image stays on top of all your terrain layers, so it never blocks your view of what you are painting.

Key Takeaways

  • Images in WorldPainter are reference layers only — they help you paint but do not become part of the final map export.
  • Import images through View > Import Image as Layer, and choose PNG, JPG, or BMP files from your computer.
  • Adjust image transparency using the Opacity slider in the Layers panel so you can see your terrain underneath.
  • Scale and position images by right-clicking the layer and using the Transform option to match your map size.
  • Delete images before export if you do not want them visible in the final map, or leave them if they are part of your design.

Resizing and positioning an image to fit your map

When you import an image, it may not match the size or position of your map. WorldPainter places it at the top-left corner by default, and it may be much larger or smaller than your terrain. To fix this, right-click the image layer in the Layers panel and select Transform Layer.

A transform dialog will open. You can drag the corners of the image to resize it, or drag from the center to move it around the map. Hold Shift while dragging a corner to keep the image proportions the same. Once the image is positioned where you want it, click outside the transform box or press Enter to confirm.

If your image is a map or blueprint you want to match exactly, zoom in on both the image and your terrain to line them up precisely. The grid overlay (View > Show Grid) can help you align features. Take your time with this step — a well-positioned reference image makes painting much faster and more accurate.

Adjusting image transparency and blending

By default, an imported image is fully opaque, which means it blocks your view of the terrain underneath. To see both at once, adjust the Opacity slider in the Layers panel. Drag it to the left to make the image more transparent, or to the right to make it more solid.

Most painters set opacity between 30 and 60 percent so they can see the reference image clearly but also watch the terrain take shape as they paint. If you are using a photograph as a reference, lower opacity helps you avoid copying it exactly and instead use it as a guide for terrain features like hills, rivers, or forests.

WorldPainter does not offer blend modes like other image editors do. The only control you have is opacity. If you need more complex blending, edit your reference image in an external program like GIMP or Photoshop before importing it.

Using images as terrain guides for specific features

Reference images work best when they show the features you want to paint. A satellite photo of a real landscape, a hand-drawn map, or a heightmap (a grayscale image where brightness represents elevation) can all guide your terrain work. Heightmaps are especially useful because you can see exactly where mountains, valleys, and plateaus should go.

If you are painting from a heightmap, set the image opacity to about 50 percent and use the Elevation tool to match the brightness values. Dark areas in the image should become low terrain, and bright areas should become high terrain. This method is slower than using WorldPainter's built-in heightmap import, but it gives you more control over the final result.

For photographs or hand-drawn maps, use the image to place features like forests, water, roads, or settlements. Paint biomes and terrain types over the image, then adjust details by eye. The image is just a starting point — your final map does not have to match it exactly.

Removing images before you export your map

Image layers are not part of your exported map file. When you export to Minecraft or another format, WorldPainter automatically leaves out all image layers. However, if you want to clean up your workspace or make sure no reference images are visible, you can delete them before export.

Right-click an image layer in the Layers panel and select Remove Layer. The image disappears immediately. If you deleted it by mistake, use Ctrl+Z (or Cmd+Z on Mac) to undo. You can also toggle the image on and off using the eye icon without deleting it — this is useful if you want to keep the reference but work without seeing it for a while.

Some painters leave images in their project file even after export, in case they need to adjust the map later and want the reference back. WorldPainter saves image layers in the .world project file, so they will still be there the next time you open the map.

Troubleshooting common image import problems

If an image does not appear after you import it, check that the file format is supported. WorldPainter accepts PNG, JPG, and BMP files. If you have a GIF, TIFF, or other format, open it in an image editor and save it as PNG or JPG first.

If the image appears but is too small or too large, use the Transform Layer option to resize it. If it is positioned off the edge of your map, drag it back into view using Transform. If the image is extremely large (several thousand pixels wide), WorldPainter may slow down — crop or resize the image in an external program before importing.

If you cannot find the Import Image as Layer option, make sure you are in the main map editor window, not in a brush or tool settings panel. The option is in the View menu at the top of the screen. If the menu is grayed out, you may need to create or open a map first.

Frequently Asked Questions

Can I import a heightmap image directly into WorldPainter?

WorldPainter has a separate heightmap import tool (File > Import Heightmap) that reads grayscale images and converts them to terrain elevation automatically. This is faster than importing an image as a layer and painting over it manually. However, importing as a layer gives you more control over how the heightmap affects your terrain.

Will the image I import show up in my exported Minecraft map?

No. Image layers are reference only and are never included in exports. They exist only in your WorldPainter project file to help you paint. Once you export to Minecraft or another format, the image is left behind.

Can I import multiple images at the same time?

Yes. Go to View > Import Image as Layer multiple times to add as many reference images as you need. Each one becomes a separate layer in the Layers panel. You can adjust the opacity and position of each image independently.

What image size works best for reference layers?

Match your image size to your map size for easiest alignment. If your map is 512×512 blocks, a 512×512 pixel image will fit perfectly. Larger images slow down WorldPainter slightly, so crop or resize very large images before importing.

Can I paint on top of an image, or do I paint underneath it?

You paint underneath. The image layer always stays on top, so you see both your terrain and the reference at the same time. Lower the image opacity to see your terrain work more clearly as you paint.