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.

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 my 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 chunks of gold 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 sublayers inside a layer, which again can have sublayers 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. 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 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.

Your first landscape

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 Example1 {
	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. Now the actual definition is inside the brackets { }. To close the definiton 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, see also the documentation.

Colors!

That first map is somewhat limited. Maybe you could do a submarine battle in it, but that's about it. So we start creating new layers!

map Example2 {
	mat=Water; tex=Smooth;
	overlay {
		mat=Gold; tex=Rough;
		x=10; y=10; wdt=80; hgt=80;
	};
};

-Rectangular Wealth-

We added a sublayer to the map layer. That sublayer will be filled with gold, and 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).

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

You can combine layers in multiple ways. Watch and see:

map Example3 {
	mat=Water; tex=Smooth;
	overlay {
		mat=Gold; tex=Rough; x=10; y=10; wdt=80; hgt=80;
		overlay { 
			x=10; y=10; wdt=50; hgt=50; 
		} ^ overlay { 
			mat=Rock; tex=Rough; x=40; y=40; wdt=50; hgt=50;
		};
	};
};

-Set Theory in Clonk-

Here begins the fun. The first layer (the gold layer) got two sublayers which were combined by an 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 the left to the right.

The operator ^ is the X-OR operator. That means anything covered by both layers will not be drawn, anything else covered by one of the layers will be drawn. The example shows this well. 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.

Layers can be combined and sub-layered (meaning put into another layer) in any way you want. Other operators are the logical And (&), which draws any overlapping parts of the two layers; and the logical Or (|), which draws anything any of the two layers would draw on their own.

That's all?

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 start playing around with operators and sublayers.

The next part of this tutorial: