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.

How it works

The main goal of the new landscape generator was to create changing and interesting landscapes. That makes it hard to create a landscape that looks just as you wanted it. You can't simply tell the generator 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. Now 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.

Your first landscape

Learning by doing is the most fun I guess: Create a new scenario. Unpack it, that makes life easier. Create a "Landscape.txt". You'll be writing all your dynamic landscape code here. (Copy pasting an example from here will work, but don't insert multiple examples, so erease everything before trying to create a new landscape, or move your Landscape.txt somewhere else as a backup and create a new one)

MapCreatorS2 works with nesting (similar to HTML, XML or so). Therefore we start by creating the outer Element, the "map".

/* A first testmap

with multiline comments!*/

map Example1 { // my first dynamic landscape!

mat=Water; tex=Smooth;

};

-A first dynamic map!-

This simply fills the whole map with water. The first 2 lines are a comment. Anything after a /* will be ignored completely until a */ is found. Everything after a // will be ignored until a newline occurs (meaning everything after // but only in this line). 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 "Smooth". Valid textures can be found in the Material.c4g

It doesn't matter where you put linebreaks comments or tabs. Therefore choose the code design you can read the easiest. That also makes it easier for others to understand and learn from your code.

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: