All directories, filenames, IDs, and more are case-sensitive as they are referenced within the XML files.

Firstly navigate to your Towns Mod directory which you can find easily by doing the following:

• Start menu -> click your name
  
• .towns -> mods

Now we want to create a mod so create a new directory and name it anything you like, for this tutorial I’ll be calling it “Tutorial”. Within this directory make a new directory called “data”. Within “data” create a new file called “campaigns.xml” and a new directory called “campaigns”.

Within the “campaigns” directory create a new directory called “custom”, you can name this to anything you like but remember that it is case-sensitive when referenced. Within “custom” you also need to make one final directory that I will call “tutmap”, again you can name this anything you like but remember that this again will be referenced so it will be case-sensitive.

Now that the directory structure is complete you should have something similar to this (all custom names are in square brackets):

• %userprofile%\.towns\mods\[Tutorial]\data\campaigns\[custom]\[tutmap]

From here I will reference custom directories in square brackets.

In the [new] directory create four new files and name them:

• gen_dungeons.xml
  
• gen_items.xml
  
• gen_livingentities.xml
  
• gen_map.xml

You should now have a basis for making your first map. Before the map can work though you need to make some basic additions to the new files.

In the four above files add the following line:


This must be present in all XML files and must stay at the very top before anything else. For the next lines it’s quite simple, basically you create tags for each of the filenames, so for gen_dungeons.xml you would have, after the XML line, the following:


Repeat the process for the other three remaining files and you should have something similar to the following using gen_dungeons as an example:


In the campaigns.xml file located in the data directory you do exactly the same as above so you should end up with the following:

In order for the maps to show up in the game you need to edit the campaigns.xml file further. In between the campaigns tags add the following:


The way this works is that the game calls the file campaigns.xml and finds the tags campaigns, in there the game says “ok this is where the campaigns are held”. To initiate a campaign, which in a way is a map, it finds the tag campaign (note the missing “s”), this tells the game that there is a campaign available and reads its contents. The campaign in this example is called [custom] and in the game we want it shown as “Custom Maps” so that we know where to pick maps we want to play on.

To enable the map for selection the game looks for the mission (or map) and gives reference for it in game, the id is the name of the directory in which case this tutorial’s map is called [tutmap]. We called the map “Tutorial Map” so we can see in game the map name.

If there are several missions per campaign then do not close the campaign map but instead add another mission directly after closing the other mission tag.

To finally finish off creating a new map there is a need to actually create the map in question. Navigate back to the gen_map.xml file and open it, in between the gen_map tags add the following:


What is done here is you initialise the map with the init tags, these tags require an id so give it the “init” id to keep things simple. In between these init tags is where the map is generated.

Before we know the number of outside and underground levels we need to know one main thing, how many levels do you want to have? The official maps have 12 levels outside and 20 levels underground giving a total of 32 levels, the game has a maximum level count of 64 so it all depends how high you want to be able to build your houses and how many dungeons you want to include in your map. For my map I want to have my heroes travel across around 20 dungeons, giving a level space between each dungeon will mean that I will require at least 40 levels, the remaining levels will be for the outside so that is set to 24.

The number of citizens is generally set to a low number to give a sense of accomplishment to the player as well as a form of progression. Here I have set the number to 100, the reason being is so that I can quickly test the depth of the map as well as test out other future things.

The starting level is where the citizens start on the map, this must be the number of outside levels minus one, the reason is because you can’t have your citizens start in the terrain. All layers in the game start from the top and work downwards, so level 1 is actually the very top of the map while level 64 is at the very bottom of the dungeon.

Lastly the final initialisation for the map is the terrain, the mainTerrain tag is an in-order layer of terrain for the map. Having it set to “grass” will have the entire level and dungeons covered in grass tiles only. Setting it to “grass,dirt” will mean that the first layer is grass and all subsequent layers are mud. If you set it to “grass,dirt,stone” then you will have the top layer as grass, the second layer as mud, and the remaining layers as stone. Swapping these around will give different results though having stone on top of mud and then on top of grass is quite odd!

Save the file and then run the game. In the Mods menu turn off all Mods that just happen to be turned on and then turn on [Tutorial], remember that this is the name of the Mod directory. Next go to New Game and select [Custom Maps], the name of the custom map will be whataever you name it as well so in this tutorial it’s [Tutorial Map].

Don’t use any buried towns and start the map, you should end up with only grass as the terrain for both the top layer and for all subsequent layers below, dig and see how the layers have turned out if you tried something different like “grass, mud, stone”.

Congratulations you have now created your first map!

Here's the code for all of the files:

%userprofile%\.towns\mods\[Tutorial]\data\campaigns.xml

%userprofile%\.towns\mods\[Tutorial]\data\campaigns\[custom]\[tutmap]\gen_dungeons.xml

%userprofile%\.towns\mods\[Tutorial]\data\campaigns\[custom]\[tutmap]\gen_items.xml

%userprofile%\.towns\mods\[Tutorial]\data\campaigns\[custom]\[tutmap]\gen_livingentities.xml

%userprofile%\.towns\mods\[Tutorial]\data\campaigns\[custom]\[tutmap]\gen_map.xml