Introduction Hello everybody and welcome to the XML Guide. This guide will teach you how to write the XML code for your map. To make it easier to follow and to consult, this guide is divided in three different parts. The first part is an Overview section about what's "the map XML", why you need it if you want to make a map, and how it works. The second part is a quick Tutorial. In that part we will first create the XML for the Classic map. After that,in the third part, the XML Tags Index, we will look more in depth the code structure, understand any single feature currently available and finally we will learn how to use the advanced features like objectives, autodeploy, or killing neutrals, etc.
Naming Convention Across the text, different types of letters, colours, and other effects to highlight important parts or to differentiate it in some way will be used. Below you can find the meaning of each one of those special font types:
This kind of letter is used to highlight something in the text.
This colour is for XML tags when used inside normal text. When something could be hidden at first glance (for example, when it's suggested to try yourself before looking at the result), the test is hidden inside a spoiler box.
Overview Pretty graphics are not enough to make a successful map. You also need to think up good gameplay rules and write them down in an XML file. This tutorial will explain how to do that. Don't worry, you don't need any technical skills or special software. Just pay attention and fire up your favourite text editor, such as notepad.
XML is made up of tags. Tags let the game engine know which information means what. Tags are surrounded with <angled brackets> and come in pairs – one for <opening> and one for </closing>. For example, this is how you specify the name of a country with tags:
2.1-Creating the Classic Map For the first part of the tutorial we will work with an old friend of ours, the Classic Map.
This map has 42 regions representing 42 of the most important cities in the world. The circles are the place where the CC engine will display the armies present in that city. The lines represent connections between the cities, along which players can attack and move reinforcments. However, the lines only show the connections: they do not define them. The XML will do that.
Those cities are grouped by continent, making a total of 6 continents. Holding a full continent at the beginning of turn grants an extra bonus to a player. In the next sections, we will create the map step by step.
2.2 -Creating the XML file Now that we know what we want to do, let's start by creating the map XML file. For this task you will need nothing more than a simple text editor, like the Notepad, but you can also use an editor like UltraEdit, Notepad++ or another code editor.
Open your editor and write the skeleton of the XML file
It's pretty short and simple. Isn't it? Don't worry. We will soon fill it with a lot of code.
The header The first line is the XML header. It identifies the file as written in XML language. All maps need to have this header as the first line.
The <map> tag encloses all the other information. Everything you write except for the header needs to be inside this tag.
XML tags And talking about tags, please notice that tags must come in pairs. There is an opening <tag> and a closing </tag>. They are named the same, except that the closing tag has a slash. Everything between the opening and closing tags is considered to be information describing that element. As an example, most map elements will have sub-tags inside describing their names.
Comments A comment is a tag in the style <!-- Comment -->. Although comments are optional, it's a good practice to use comments to structure your code, and also to help understand it and navigate through it.
2.3 -Territories Territories are the basic unit for constructing any map. The map is described by a collection of territories, how they connect to each other, and how they group in continents. Territories always have an owner (even if it's the "neutral" player) and each player needs at least one territory to stay alive. Troops are placed in territories, and battles are fought for the control of such territories. In some parts of Conquer Club, territories are referred to as regions.
A territory is described by the tag of the same name, <territory>.
Nested inside the <territory> tag there are other sub-tags that describe all the properties of that territory.
Naming a territory We use the <name> tag to name a territory. In this example we will start by the Anchorage city, as it is the first in alphabetic order (this doesn't mean you have to do the same, in fact the game engine lists the territories in alphabetical order in any case).
Setting the coordinates on the map How does the CC engine know where to place the armies numbers for each territory? We provide this information via the <coordinates> tag. As you know, there are two sizes for any map. The small size and the large size. For this reason we need to provide the coordinates for both sizes.
If you don't know exactly how to center the coordinates, there are some tools that can help you in doing this.How to use these tools is explained in their dedicated topic into the Foundry Tools Forum.
Borders with other territories Now we have a city in our map. But it is isolated without connections with any other city. To link territories, we use the <borders> tag. Inside this tag there will be a <border> sub-tag for each territory that borders the one we are describing. Looking at the image, there are three cities bordering Anchorage. So we place all of them in our code.
An important thing to remember is that borders are only one way, like adjacencies in a graph. This means that Edmonton, Vancouver and Magadan also need to have in their own descriptions a <border> with Anchorage. If we linked Anchorage with Edmonton, but forgot linking Edmonton to Anchorage, we would make it a one way trip. We would be able to go from Anchorage to Edmonton, but we would not be able to come back.
Territory summary We have just finished describing our first territory. In this case, the city of Anchorage. This is how it looks when we put everything together:
Writing the code for the rest of territories We will now repeat the process for the rest of the cities. As we have already explained it, we won't repeat all the process, just post here how it all looks once it's finished. It's recommend you to practice writing the description for the rest of the cities in the map by yourself. Once you are finished, you can click the show link and compare what you have written with the code here.
2.4 -Continents Continents are groups of territories that provide an extra bonus when held together at the beginning of a turn. In the Classic map Africa is a continent, but America is divided in two continents (North America and South America). We describe continents in our XML file by using the <continent> tag.
Notice that depending on the map theme, "Continents" could be something different from the geographical continents. They could be other zones of the map that share something in common. For this reason they are also called bonus zones. As said, a continent is a group of territories.
Similar to what happened with territories, the <continent> tag contains other tags nested inside that define the different properties of that bonus region.
Naming a continent We use the <name> tag to name a continent. The following example is how you would name Africa.
Naming continent components Inside the <components> tag we list all the components of that continent. This will tell the engine which territories a player has to own at the beginning of the turn to receive the zone bonus. Let's list the territories that form Africa.
Continent bonus We know how to name continents and how to specify the territories that form that continent. The last thing left is saying how many troops a player receives for holding the continent at the beginning of the turn. We specify that information with the <bonus> tag. For Africa, the bonus tag looks like this:
Writing the code for the rest of continents We are about to finish the XML code for the Classic Map. In order to do that, we need to write the remaining code for the rest of continents: Asia, Europe, North America, Oceania and South America. Try to do it yourself to get some practice. And when you are finished, check what you have written with the actual code here:
Once you have finished writing all the XML code for your map, you have to upload or link it to the forum topic where your map is being developed (the "map thread"). In this way, the file can be officially checked and eventually uploaded to the active portion of the Conquer Club site for beta play, followed by full active play. There are various file hosting web sites that offer you a free account to upload your xml files, but without any doubt the best, quickest and safest way to upload your file is to attach it to the map thread.
Attaching a file to a post is really easy to do, but in case you're wondering how to do so, please take a look at this section of the Foundry Handbook.
Remember that you're always able to delete your attached files. In fact, if you enter your Conquer Club Control Panel (via the Control Panel entry under the Personal Menu displayed on the left of the screen) you can see the "manage attachments" section under the "overview" folder. In this tab, all your uploaded attachments are listed and you can easily manage them.
When uploaded, the map topic will have a "small clip icon" on it and the attached files will be displayed in your post, for the classic map xml of this tutorial:
Encloses all the code that describes a map. Syntax <map>Map tags</map>
Map tags: All the rest of the tags that describe the map. Each of them must follow a specific order and has its own syntax. For the order, check section 3.1-File structure. For the syntax, check the section dedicated to that tag.
Location: The opening tag goes after <?xml version="1.0" encoding="UTF-8"?>, and the closing tag goes at the end.
Example: In this fragment of code, we are using the <map> tag to indicate the beginning and the end of the file, as indicated.
Adjusts the value of minimum reinforcements for the map. At the beginning of every turn, each player is guaranteed to get at least the number of troops specified in this tag, no matter how many territories or bonuses he has.
Syntax <minreinforcement>Number or troops</minreinforcement>
Number of troops: The minimum of troops we want players to receive at the beginning of each turn.
Notes: If this tag is not specified, the map will have a default value of 3 troops minimum.
The minimum number of reinforcement troops can't be 0. It has to be at least 1.
Location: It goes after the opening <map> tag and before the <reinforcements> tag.
Example: Imagine we want to eliminate the standard minimum of 3 troops. We can do it by setting the value to 1. (It can't be 0). The City Mogul map does it.
This tag is a list of subtags describing segments. Each segment has the following parameters:
From: The segment starts applying when the player owns this number of territories. To: The segment stops applying when the player owns this number of territories. Divisor: The player will get an extra army each Divisor armies or fraction.
The default value features a single segment providing one reinforcement army per each 3 territories. We can change this by defining one or more segments, and assigning a different rate to each segment. If you define two or more segments, ensure that they do not overlap.
If you leave spaces not covered by the segments defined, the default value of one army per each 3 territories will apply in the undefined areas. However, best practice suggests that if you are using this tag, you should define segments covering all the range of territories, even if the default rate applies at some of them. You should also list them in order.
The divisor applies only inside the segment defined. For example, if you define two segments...
Segment A - from 1 to 30. One army per 3 territories.
Segment B - from 31 to 100. One army per 5 territories.
...and the player has 50 armies, he will receive 30/3+(50-30)/5 = 30/3+20/5 = 10+4=14 armies at the begining of turn. He will not receive 50/5 = 10 armies
Please notice this tag does not affect reinforcements received from bonus regions (continents) as that is a completely different concept.
Location: It goes after the <reinforcements> tag and before the <positions> tag.
Examples: This code implements the default rate of 1 army for each 3 territories in the Classic Map.
If present, defines which territories will be owned by players when the game starts, and how they will be distributed between such players. The territories not present inside this tag are dealt out in the standard way.
The tag contains a list of positions, each of them identified by a <position> subtag. At the beginning of the game, the positions are divided evenly between the players. If there is a remainder, the territories of those start positions are dealt out in the same way as other territories.
TerrName: Is the name of the territory that forms part of the position.
Notes: The most common way to use this tag is with a list of 8 positions. In that case, the number of positions allocated to each player will depend on the number of starting players:
8 to 5 players: 1 position
4 to 3 players: 2 positions
2 players: 4 positions
If the number of positions is not evenly divisible by the number of players, the territories within the remaining positions are distributed as normal territories. As an example, suppose each position has two territories, with 5 players, the three remaining positions contain a total of 6 territories. If there are no other territories on the map to be distributed, one territory will be given to each of the players, and one territory will start as neutral.
Info about a more extensive use of Starting Positions can be found here: Starting Positions
Location: It goes after the <reinforcements> tag and before the <requirement> tag.
Examples: The map New World provides a good example of how to use the <positions> tag to create a Conquest map (a map in which all the territories start as neutral except for the starting players positions):
3.6-<requirement> The requirement is a list of territories and / or continents. In order to stay alive, players have to hold one or more items from each list. A subtag specifies how many items need to be owned to continue playing. This feature is known as Losing Conditions.
ReqName: Is the name that we assign to the Requirement. Such as "Holding one capital". TerrName: The name of an individual territory that forms part of the requirement. ContName: The name of a continent that forms part of the requirement. ItemsReq: The number of items that each player has to own at least to stay in the game.
Notes: The requirement can be composed by a mix of territories and continents.
If no <required> subtag is specified, it is enough to hold only one item from the list to stay in the game.
Location: It goes after the <positions> tag and before the <objectives> tag.
Examples: The Antarctica map requires players to own at least one base to survive.
ObjName: Is the name that we assign to the Requirement. Such as "Conquer the Eternal City". TerrName: The name of an individual territory that forms part of the objective. ContName: The name of a continent that forms part of the objective. ItemsReq: If present, a player only needs to hold at least that number of items to win the game
Notes: Conquering a territory does not automatically end the game. To win the game, the player has to own the objective at the beginning of his turn. That means conquering the objective one turn and holding it from other players during a full turn.
The objective can be composed by a mix of territories and continents.
If no <required> subtag is specified, all the items in the list must be owned. If the subtag is present, then it's enough to hold the number of items specificed.
Even if the <objective> tag is present, traditional victory by killing all the other players is still valid.
Location: It goes after the <requirement> tag and before the <continents> tag.
Examples: In the Oasis map, players can win by finding the treasure hidden in the center of the Oasis. It is described in the XML as that:
At its most basic version, this tag contains only the <name> of the continent, the list of <territories> forming it, and how many reinforcement troops are given to the player holding the bonus zone at the beginning of a turn.
ConName: The name given to this group of territories as a whole. ReinfBonus: How many armies will be added to player's income for holding the continent. TerrName: The name of each of one of the <territories> forming the continent.
Notes: Like territories, continents can be used as components of another continent as well. The tag can be expanded with optional subtags, If you are looking for a more extensive use of Continents, you can find some info here, here and here.
Location: It goes after the <objectives> tag and before the <territories> tag
Examples: The West bonus area (continent) we find on the USA is composed of 4 territories. If you hold all them you receive a bonus of 2 troops. The code for this bonus looks like this: