mcmap - Isometric map visualizer

Original project by Simon Rettberg. All the credit goes to him for the idea and vision.

mcmap is a tool allowing you to create isometric renders of your Minecraft save file.

This project is under heavy development, but compatible with newer versions of Minecraft.

Usage

Basic invocation

mcmap <options> path/to/<your save>

The standard save path is different between OSes:

• On Linux, it is $HOME/.minecraft/saves;
• On macOS, under ~/Library/Application\ Support/minecraft/saves;
• On Windows, the standard path is %AppData%\.minecraft\saves. If using Ubuntu on Windows, the path to access the save folder is the following: /mnt/c/<Your user>/AppData/Roaming/.minecraft/saves.

Native Windows is now supported. Pre-compiled binaries can be downloaded from the releases page. For now, the program can only be used via terminal/powershell on Linux/Macos or Windows respectively. A GUI is in the works, but needs to be compiled from sources.

Options

Note: Currently you need both -from and -to to define bounds.

Tips

mcmap will render the terrain in batches using all the threads of your computer. Unfortunately, when those batches merge, some artifacts are created: lines appear in oceans where the merge was operated.

Use -tile with a bigger value to limit the amount of batches and thus of artifacts. This is limited by the available memory, as rendering a whole map iin one go may require 10+ gigabytes of ram.

Use -tile with a lower value to increase performance. 256 and 512 tiles are really efficient.

Color file format

mcmap supports changing the colors of blocks. To do so, prepare a custom color file by editing the output of mcmap -dumpcolors, and pass it as an argument using the -colors argument.

The accepted format is a json file, with a specific structure. The root contains a list of block IDs to modify, with the namespace prefix, such as namespace:block.

Simple block

To define a color for a simple, regular block, provide an entry in a JSON file. The color format is a hexadecimal color code. If the alpha is not specified, it is assumed to be opaque.

"namespace:block": #rrggbbaa (or #rrggbb)

Examples:

{
    "minecraft:dirt":   #7b573b,
    "minecraft:ice":    #7dadff9f, 
    ...
}

Complex block

Some blocks are better looking when drawn in a specific way. To specify that a block has to be drawn differently, you have to provide a json structure with the following fields:

"namespace:block": {
    "type":     <BlockType>,
    "color":    "#rrggbbaa",
    "accent":   "#rrggbbaa" (Optional)
}

The available available block types are:

NOTE: Waterlogged blocks will be rendered within water instead of air by default according to their blockstates. However, sea-grass and kelp are hardcoded to be underwater and their blockstates won't reflect this, so they have to be defined as UnderwaterPlants.

Examples:

{
    "minecraft:dirt":   "#7b573b",  // Full block with solid color

    "minecraft:grass_block": {
        "type":     "Grown",        // Use a special block type
        "accent":   "#4c7a40",      // Accent supported for `Grown`
        "color":    "#7b573b"
    },

    "minecraft:water": {
        "type": "Clear"
        "color": "#0734c832",       // Transparency enabled
    },
}

Compilation

mcmap depends on the PNG and zlib libraries. Development was made using gcc version 10, and can be compiled with gcc 8 or later or clang 10 or later. Configuration is done using CMake.

Linux

Getting the libraries depends on your distribution:

• Ubuntu: apt update && apt install git make g++ libpng-dev cmake;
• Archlinux: pacman -S --needed git gcc make libpng cmake.

Then get the code and compile:

git clone http://github.com/spoutn1k/mcmap
cd mcmap
cmake .
make -j

macOS

In an Apple environment, you need a developer toolkit recent enough, with the version of g++ --version superior to 10.

Using brew:

brew install libpng libomp
git clone http://github.com/spoutn1k/mcmap
cd mcmap
cmake .
make -j

Windows

mcmap was successfully compiled for Windows using Visual Studio/Visual C++ and MinGW. As there is no package manager on Windows, libpng and zlib need to be compiled/installed manually. If compiling the GUI version, you will also need Qt.

You can also download and set up Ubuntu on windows then the steps are the same as Linux/Ubuntu.

Troubleshooting

Compilation fails

Check g++ --version. Supported versions are at least 8.0.0. If your version is not up to date, install a more recent one using your package manager. You will have access to the new version using g++-Y with Y being the version number. Compile using CXX=g++-Y make.

Compilation fails complaining about OMP something

Try compiling with OPENMP=NOTHXM8 make. This disables the underlying threading code, so performance may drop.

Output has lines in the ocean

This is due to the merging algorithm. Try increasing the tile size with the -tile option, or change the color of the water block to use the Full block type to make it less noticeable.