Skip to content


Emiel van Rooijen edited this page Jul 31, 2018 · 10 revisions

Install the Modpack

Use git to clone or download a zip of master. Get the entire modpack, which will give you the multi_map core API and engine as well as a sample with map generator plugins and an init.lua to kick everything off. Place this in your subgame's mods folder and create a new game for that subgame, or add it to your Minetest mods folder and enable it on a newly created world. When creating a game or adding this to a subgame, make sure you set the water_level to -31000 and chose the singlenode mapgen!

Modify the Supplied init.lua

The multi_map_generators mod comes with a few preinstalled map generator plugins. You can create your own mod which depends on multi_map_core and multi_map_generators. If you do so, move the init.lua supplied to your own mod's folder or create a new init.lua and remove the one in multi_map_generators.

Regardless of using your own init.lua or changing the one in multi_map_generators, consider the following code:

local multi_map_generators_path = minetest.get_modpath("multi_map_generators")

multi_map.number_of_layers = 1
multi_map.layers_start_chunk = 0
multi_map.layer_height_chunks = 20
multi_map.register_generator(0, mmgen_levels.generate)

The above would create a world that only has one layer. The layer would be placed at starting chunk 0, meaning Y = -30912. The layer would be 20 chunks high, which is 80 * 20 = 1600. After these initial settings, we register a generator plugin for this layer. We use the multi_map.register_generator function to register generator plugins for a layer. In this case we set layer 0 to call the generate function in mmgen_levels (see mmgen_levels.lua in multi_map_generators).

When you start the game, you would be placed at 0,0,0, but this level is of course at Y = -30912. So grant yourself all privileges (/grant singleplayer all), enable noclip, fast and fly (pres keys h, j and k) so you stop falling. Now teleport to the center of the first layer. As the layer is 1600 nodes high, the "Y centerpoint" is at 800. Therefore we take -30912 (minimum Y) and add 800 to that, which is -30112. Teleport to this Y level (/teleport 0,-30112,0) and fly up in case you are in the ground. If all is well, you should see terrain being generated.

We only have 1 layer now, which is of course not mutliple map layers as per the name of this mod. So, let's create a second layer!

Adding Layers

Edit the init.lua. Leave the get_mod_path and dofile lines in there, and change the code below that to:

multi_map.number_of_layers = 2
multi_map.layers_start_chunk = 0
multi_map.layer_height_chunks = 20
multi_map.register_generator(0, mmgen_levels.generate)
multi_map.register_generator(1, mmgen_levels.generate)

In the above, we change the global setting multi_map.number_of_layers to 2. In addition, we need to specify which map generator to use for this layer. Do we want to use the same one? This would give you a similar terrain as the one in layer 0. We call this "world extension", and there are actually mechanisms to virtually allow map layers to blend into one another and move between them. Do we want to use a different one? We call this "multiple worlds", where we can have a terran world, alien worlds, nether like worlds, cloud worlds, etc.

Restart the game. If you now fly up or teleport 1600 nodes higher, you will end up in the next layer (e.g. /teleport 0,-28512,0). Notice that the terrain is the same levels terrain, but that it looks different from the one in the layer below! One configuration change, one extra line! This is all it takes to have a completely new layer that reuses all the logic of the levels mapgen! Yet, the terrain looks completely different!

Let's add yet another layer, but this time one using the simple map generator plugin. Make sure you add a dofile for the mmgen_simple.lua in there as well:

local multi_map_generators_path = minetest.get_modpath("multi_map_generators")

multi_map.number_of_layers = 3
multi_map.layers_start_chunk = 0
multi_map.layer_height_chunks = 20
multi_map.register_generator(0, mmgen_levels.generate)
multi_map.register_generator(1, mmgen_levels.generate)
multi_map.register_generator(2, mmgen_simple.generate)

The third layer is now set to the mmgen_simple plugin, which creates a singlenode terrain. Restart the game, fly up or teleport to 0,-26912,0 and fly around a bit to generate terrain. You will see it is quite boring flat stone terrain, only useful for maybe a creative world. But the simple plugin is also for testing and debugging purposes, and as such it allows us to investigate some other interesting aspects of the framework.

Layer Parameters

Let's change the stone of our flat land into something different. Change the layer 2 registration call into:

multi_map.register_generator(2, mmgen_simple.generate,
                             { nodetype = "default:sandstone" })

The third argument to the registration call is a parameter that will be passed to the plugin. You can pass a table with parameters to the simple plugin. The nodetype will tell mmgen_simple which node to place during the generation of the terrain. Restart the game and fly around to generate some new terrain. Notice that at some point the terrain is no longer stone, but sandstone.

The parameters are plugin specific and can be used to control a whole range of settings for plugins. They could add or subtract to/ from temperature or humidity maps allowing you to create a layer of desert and a layer of jungle. All using the same plugin, the same underlying logic, but again with different terrain and by tweaking some parameters even with completely different biomes.

Which parameters are available for the map generator plugin is plugin specific, so you will have to check what parameters there are in the documentation or the plugin's code.

Relative Coordinates and Layer Names

By default, you will see a "zone" and some coordinates in the bottom right of the screen. If you do not set a name for a level, this "zone" will show the layer number that you are currently in. You can add a name to be shown in the HUD by adding the following lines. Teleport between the layers and notice how it shows names now instead of just the "zone" number:

multi_map.set_layer_params(0, { name = "Near Home Lands" })
multi_map.set_layer_params(1, { name = "Remote Lands" })
multi_map.set_layer_params(2, { name = "Flat Lands" })

Restart the game and teleport between the layers (/teleport 0,-30112,0 ; /teleport 0,-28512,0 ; /teleport 0,-26912,0). Keep an eye on the "zone" name and notice how it changes.

Did you also notice the coordinates? And how it shows you a different value for the Y coordinate than what you see in the debug info (F5). The coordinates you see are called the "offset Y" or "relative Y". This is the Y coordinate relative to the layer's Y centerpoint. E.g. the Y centerpoint of layer 0 is -30112. Suppose we are at Y = -30100, it would be nice to show a proper "overworld" Y coordinate to the player instead of this large negative value right? Something that is closer to what the player is actually experiencing, like Y = 12 instead of Y = -30100.

This is why we have offset Y/ relative Y. Internally this is also used by map generator plugins to get sane Y levels for terrain generation, but that is described in the Map Generator Plugins.


This is just the tip of the iceberg. Read Concepts to learn about the terminology used in this mod. The Cookbook contains many different "recipes" (or, scenarios if you will) how to achieve certain goals with the framework. The API pages describe the configuration, functions and internal tables of the mod. If you want to understand the inner workings, please have a look at Detailed Overview.

Do you have a mapgen that you want to port to multi_map? Or do you want to create a map generator plugin for use in the framework? Or do you want to have a general overview of how map generator plugins are being called and which coordinates to use when? Then you should have a look at Map Generator Plugins.

The Q and A section answers some questions or concerns you may have and some general info on how this mod came to be.

Enjoy the framework!

You can’t perform that action at this time.