Tutorial: Map Generator - The Basics

In OpenClonk there are three ways to create a landscape, these are:

  • Dynamic maps using Scenario.txt, which has the drawback of only having stretched and scaled sinusoidal landscapes.
  • Static maps where a drawn landscape is stored in a Map.bmp file, where each pixel represents MapZoom pixels ingame.
  • Generated maps using a Landscape.txt file where you can create dynamic landscapes with as many design parameters as a static landscape.

This tutorial covers the last method, which is called the map generator. Of course, this kind of dynamic landscape design is not as simple as moving bars, you need to have at least a basic understanding of sets and logical operators and know how to create scenarios.

Introduction & Features

The landscape generator allows one to create dynamic and interesting landscapes. Dynamic in this context means that every time you start a scenario the landscape will look different. This is a great benefit opposed to static maps, depending of the type of scenario a dynamic map may be a must. On the other hand it is harder to create landscapes that look exactly the way you want it. The map generator can't simply be told to put in five nice looking gold chunks of some size into the ground.

Instead you have bit-layers which get a two dimensional 1-bit-texture. Then a material-texture-combination is assigned to that layer. Also you can create many sub layers inside a layer, which again can have sub layers and a material-texture-combination. Maybe it's easier to imagine as cutting several designs into pieces of paper and putting them behind each other, you'll get blank spots (where all papers have a hole), which will be like "Sky". Maybe you set the first layer to be some kind of an "Earth", that layer then has some shreds of paper on it that represent "Gold". But once you get to some really complicated combinations you'll see that that comparison is somewhat non-representative of the map-generator.

The approach taken in this tutorial is "learning by doing", as it should be the most fun and allows for a smooth introduction into the generator. Though this tutorial can't be completed by just anyone, basic knowledge of scenario creation is understood. The tutorial is divided up in parts, each part covers some theory explained in examples and ends with an exercise. The examples contain a snippet from Landscape.txt file together with some explanation and the generated map displayed on the right. But before starting of with the theory and some example landscapes we need a scenario to view our dynamic landscapes. You can create a scenario or download the scenario containing the first example here[TODO: file]. The map generator reads out the Landscape.txt file inside the scenario folder and generates the landscape at the start of the round. Either create a new Landscape.txt file or open the existing one in the downloaded example scenario. You can only view one example at a time, to view a new one clean the file and copy & paste the new example into your Landscape.txt file. Landscapes are best viewed in editor mode as you can scroll through the landscape.

The map generator also has its own documentation. Here all features of the generator can be found, and of course we will use it frequently in this sequence of tutorials. Furthermore we want to write readable generator code, so that we ourselves but most importantly others can profit from it. For this reason style guidelines for map generator code have been compiled which should be followed within the OpenClonk project.

Your First Landscape

One big lake!

The map generator works with nesting, similar to HTML, XML and others. Therefore we start by creating the outer element, the map. This basically is a layer that spans the whole landscape of a scenario. So without further ado, here is your first example landscape. 

// My first dynamic landscape!
map ExampleFirstLandscape {
	mat=Water; tex=water;
};

As you might have noticed this simply fills the whole map with water, but how does it work. The first line is a comment, everything after a // will be ignored until a new line occurs. Also multi line comments are possible, anything after a /* will be ignored completely until a */ is found. The third line has the keyword map. Example1 is the name of that map. The actual definition is inside the brackets { }. To close the definition you also need to put a semicolon behind the closing bracket.

In this example we define the material (keyword mat) and the texture (keyword tex) of the map. This map will simply be completely filled with Water and that water will have the texture water. Valid materials and textures can be found in the TexMap.txt file in the Material.c4g folder, which is explained in the material documentation.

Layers

A golden layer submerged in water.

That first map is somewhat limited. Maybe you could do a submarine battle in it, but that's about it. So let's add a new layer, new layers can be created with overlay. 

// Introduced a golden layer.
map ExampleLayers {
	mat=Water; tex=water;
	overlay {
		mat=Gold; tex=gold;
		x=10; y=10; wdt=80; hgt=80;
	};
};

We added a sublayer to the map layer and that sublayer will be filled with the material Gold. Furthermore we told the layer to be limited to the area that starts at x, y (in percent of the upper layer, the map) and to a height and width of 80% of the upper layer (the map).

Notice that changing the map size in the Scenario.txt will automatically fit your map to the new size and the percentages of the sublayer will also automatically scale themselves to the new values.

Combining Layers

Combined rock and gold layers.

You can combine layers in multiple ways. Low and behold: 

// Gold, rock and set theory.
map ExampleCombinedLayers {
	mat=Water; tex=water;
	overlay {
		mat=Gold; tex=gold; 
		x=10; y=10; wdt=80; hgt=80;
		overlay { 
			x=10; y=10; wdt=50; hgt=50; 
		} ^ overlay { 
			mat=Rock; tex=rock;
			x=40; y=40; wdt=50; hgt=50;
		};
	};
};

Here begins the fun. The first layer (the gold layer) has got two sublayers which were combined by a logical operator - the ^. Since both layers are inside that gold-layer they will not affect anything outside of that layer. Any coordinates or percentage values are relative to that outer layer.

The two inner layers are combined by an operator. The last layer defines what material and texture will be used for that layer combination. You could also add more operators and layers, the operators will then be handled from left to right. Layers can be combined and sub-layered (meaning put into another layer) in any way you want. There are three logical operators:

  • ^ is the XOR operator, that means anything covered by both layers will not be drawn, anything else covered by one of the layers will be drawn. This is shown in the example, the grey area in the top left corner is part of the first layer, the one in the lower left corner is the part of the second layer. The center is the part covered by both layers, which is not drawn due to the ^ operator.
  • & is the AND operator, which draws any overlapping parts of the two layers.
  • | is the OR operator, which draws anything any of the two layers would draw on their own.

As an exercise you can replace the XOR operator with the AND or the OR operator and see what happens. To be able to work with the landscape generator basic understanding of set theory and logical operators is quite handy.

Exercise: Set Theory

Exercise: Create this landscape.

Since basic understanding of sets is required it will be tested in the this exercise. Try to construct a 5 by 5 checkers board out of gold and rock, looking like the landscape in the figure. There are multiple solutions, but try to use as little overlays as possible.

[TODO: solution as some sort of spoiler] 

// Checkers board out of gold and rock.
map ExerciseSetTheory {
	mat=Rock; tex=rock;
	overlay { 
		x=20; y=0; wdt=20; hgt=100; 	
	} ^ overlay { 
		x=60; y=0; wdt=20; hgt=100; 	
	} ^ overlay { 
		x=0; y=20; wdt=100; hgt=20;
	} ^ overlay {
		mat=Gold; tex=gold;
		x=0; y=60; wdt=100; hgt=20;
	};
};

Summary

Of course, this tutorial only covered the most important basics of dynamic landscapes. The following tutorials will require full knowledge about this one. If you have problems with the things covered by this tutorial it is most advisable to play around with operators and sublayers a little more.

The next part of this tutorial about algorithms and transformations is here.

Retrieved from "https://wiki.openclonk.org/index.php?title=Tutorial:_Map_Generator_-_The_Basics&oldid=1363"