Need help with mcmap?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

spoutn1k
159 Stars 39 Forks GNU General Public License v3.0 529 Commits 4 Opened issues

Description

Pixel-art map visualizer for Minecraft. Maps are drawn from an isometric perspective.

Services available

!
?

Need anything else?

Contributors list

# 170,492
JavaScr...
spotify
Windows
Sass
362 commits
# 392,966
C#
HTML
Shell
pixel-a...
4 commits
# 130,194
Go
JavaScr...
Shell
flowcha...
1 commit
# 660,812
C
HTML
Shell
pixel-a...
1 commit
# 66,278
Lua
sd-card
raspber...
TypeScr...
1 commit
# 252,782
Windows
macOS
JavaScr...
HTML
1 commit
# 6,979
JavaScr...
js
Shell
stubs
1 commit

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.

sample

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

Usage

Basic invocation

mcmap  path/to/

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//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

| Name | Description | |--------------|------------------------------------------| |

-from X Z
|sets the coordinates of the block to start rendering at| |
-to X Z
|sets the coordinates of the block to end rendering at| |
-min/max VAL
|minimum/maximum Y index (height) of blocks to render| |
-file NAME
|sets the output filename to 'NAME'; default is
./output.png
| |
-colors NAME
|sets the custom color file to 'NAME'| |
-nw
-ne
-se
-sw
|controls which direction will point to the top corner; North-West is default| |
-marker x z color
|draw a marker at
x
z
of color
color
in
red
,
green
,
blue
or
white
; can be used up to 256 times | |
-nowater
|do not render water| |
-nobeacons
|do not render beacon beams| |
-shading
|toggle shading (brightens blocks depending on height)| |
-nether
|render the nether| |
-end
|render the end| |
-dim[ension] [namespace:]id
|render a dimension by namespaced ID| |
-mb VAL
|maximum memory to use at once (default 3.5G, increase for large maps if you have the ram)| |
-tile VAL
|render terrain in tiles of the specified size (default 1024)| |
-padding
|padding around the final image, in pixels (default: 5)| |
-h[elp]
|display an option summary| |
-v[erbose]
|toggle debug mode| |
-dumpcolors
|dump a json with all defined colors|

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":     ,
    "color":    "#rrggbbaa",
    "accent":   "#rrggbbaa" (Optional)
}

The available available block types are:

|Name|Appearance|Accent support| |-|-|-| |

Full
|Default. Full-block.|No| |
Hide
|Do not render the block entirely.|No| |
Clear
|This block is optimized for transparent block in large quantities, such as glass and water. The top of the block is not rendered, making for a smooth surface when blending blocks together.|No| |
Thin
|Will color only the top of the block underneath. Used for snow, rails, pressure plates.|No| |
Slab
|Half block.|No| |
Stair
|Renders a stair block.|No| |
Rod
|A slimmer block, used for fences and walls.|No| |
Wire
|Small dot on the floor, used for tripwire and redstone.|No| |
Head
|Smaller block, also used for pots, pickles, and mushrooms.|No| |
Plant
|Used in a variety of cases, renders a leaf-like block.|No| |
UnderwaterPlant
|Same as
Plant
, but the air is water-colored. Used for sea-grass and kelp.|No| |
Fire
|Fire-like. Used for fire.|No| |
Beam
|Internal block type, used for markers and beacon beams.|No| |
Torch
|Three pixels in a vertical line, with the top pixel rendered with the accent color.|Yes| |
Ore
|Block with veins of color. The vein is rendered with the accent color.|Yes| |
Grown
|Blocks that have a different layer on top. Grass, nylium, etc. The top layer is rendered with the accent color.|Yes| |
Log
|Directionnal block, to render logs/pillars as close as possible. The center of the pillar is rendered with the accent color. Used for logs, pillars, basalt.|Yes|

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.