Skip to content

Introduction

Jump to bottom
Bert Speckels edited this page Jan 11, 2020 · 26 revisions

In this introduction I would like to introduce the program including all required data and configurations. The other chapters in this wiki then give a deeper insight into the conversion of maps into Minecraft worlds.

We use the following terms:

  • 'terrain' for the shape of the landscape, the elevantion of individual landscape points.
  • 'surface' for the look of the landscape which is defined by the top block type and additional block types on it (the items)
  • 'items' are addtional blocks on top of the surface like tree saplings, lanterns and such.
  • 'color palette' is a table of (up to 256) colors which are assigned to a specific index, a number that represents the corlor used in the image.
  • 'normal map' or 'real world map' is what we mostly mean when talking about maps: They show what is on the surface of a world (real world or just fantasy): Forests, maedows, rivers and roads.

Running the application

map2mc only needs one directory for execution, in which all data including a configuration file are then available:

java -jar map2mc-<VERSION>.jar -dir=<data directory>

If the directory does not exist, map2mc will create the directory, an initial configuration file and empty mapping files. This is a good start for your own map.

If the directory exists, map2mc expects at least one configuration file config.properties as well as the necessary image and mapping files.

The contents of the directory and the configuration are explained in detail in the next sections. Further practical information on the maps and mapping files can be found in other chapters that are linked on the main page.

About the images

You need at least one map to convert from it a Minecraft world. Depending on type and quality of the map other maps are useful.

Minecraft and map2mc require some prerequisites regarding the images that are presented below.

Image format

You must use a raster format that supports indexed color palettes and does not distort the colors. I use simple BMP files. The PNG format is also possible, but offers many variants in the way it is stored. Therefore, I cannot say with certainty whether every PNG file will work.

Image dimensions

The width and height of the images must be a multiple of 512 like the following examples:

  • 1024x1024
  • 1024x1536
  • 3584x2560

The minecraft world is organized in regions of 32x32 chunks. Each chunk contains 16x16 blocks. So each region has 512x512 blocks!

Color palette

All maps must use an indexed color palette because the index of each color in this table of colors is used to map landscape heights and surface.

  • Choose a suitable color palette
  • In the GIMP Tips chapter I give some useful tips on how to optimize the color palette

Map types

All together there are three different kinds of the maps which are used for the conversion in a Minecraft world:

  1. a 'terrain map' in two flavors:
  • A height map clearly defines the heights in the landscape based on their colors: Each color determines exactly one landscape height, above and below water. But surface information is missing.
  • A normal map such as is often found in atlases or used in role-playing games defines the landscape of the underwater world (coast vs. deep sea) quite well, but on land the colors indicate the surface of the landscape: Forests, Stone, Grasland ... So height information on land is missing.

Depending on the flavor of the 'terrain map' you have to put the missing information into another map:

  1. A 'surface map' supplements a height map with information about the landscape surface, for example vegetation and stone types. In the case of a normal 'terrain map' the 'surface map' is identical with the 'terrain map'.
  2. A 'mountain map' supplements the missing height information of a normal map.

Mapping files

With a pure height map, in which each color defines the height of the landscape in ascending order, no mapping of the colors is actually necessary. At the latest with the 'surface map' the color values ​​(indexes) must be assigned to the Minecraft block types.

There are two mapping files:

  • A CSV file terrain.csv, which assigns the color indices of a 'terrain map' to the actual heights of the Minecraft world

    • With a height map, as I said, this is not absolutely necessary. However, a mapping file can still be useful.
    • With a normal map, the mapping is mandatory to differentiate between water and land and to define the heights of the underwater world. On land, there are rather few differences in height (for this is a mountain map required).

  • A CSV file surface.csv, which assigns the color indices of a 'surface map' to the actual block type in the Minecraft world.

Configuration

A configuration file defines some basic settings of the conversion:

# The world:
# 'level.base' defines the height of the foundation stone (1 bedrock + (value-1) stone-blocks)
# 'level.sea' is the height of the water on it
# level.base + level.sea  is therefore the height of the sea surface in the Minecraft world
level.base=40
level.sea=20
# Options:
# 'option.threadCount' specifies how many parallel calculation can be performed
# 'option.validate-blocks' should be used to identify unknown block types. These are output at the end of the calculation and make troubleshooting much easier.
option.threadCount=4
option.validate-blocks=true
# Files:
# Referencing the required maps and mapping files.
# The path can be absolute or - as here - relative to the directory with this configuration file.
file.surface.image=./terrain.bmp
file.surface.csv=./surface.csv
file.terrain.csv=./terrain.csv
file.terrain.image=./terrain.bmp
file.mountains.image=./mountains.bmp
#
# Output directory:
# Temporary files are stored in 'directory.output.tmp'.
# The files of the generated Minecraft are saved in 'directory.output.region'.
# All directories are completely deleted and newly created before each calculation.
directory.output.region=~/.minecraft/saves/RealMap/region
directory.output.tmp=./tmp

Some hints:

  • level.sea has different meanings depending on the flavor of 'terrain map':
    • For a height map with an empty terrain.csv, the value defines the number of colors in the color palette that represent water depths.
    • For a normal map, the value is less important, but must specify at least the maximum water depth.
  • options.threadCount can have a significant influence on the speed of the calculation, but also on the load on the computer. A value between 1 and 8 usually makes sense.
  • Validating the block types is very useful
    • Minecraft does not render the complete 16x16 chunk if it contains at least one unknown block type.
    • map2mc defines a list of expected block types and outputs all that are not in this list at the end of the rendering phase. So it may well be that you use block types that map2mc simply did not expect but are supported by Minecraft.
  • In this example the 'terrain map' is obviously a normal map, because there is no separate 'surface map' but a 'mountain map'. Nevertheless, the 'surface map' must be defined: Just the 'terrain map' is used.
  • In the directory and file paths, the tilde character ~ can be used to reference the user directory (as is common in Linux). This also works on Windows.
Clone this wiki locally