Conquer Club

[Official] XML Guide

How to make a map. Official Handbook, Guides, Tutorials and more...

Moderator: Cartographers

Forum rules
Please read the Community Guidelines before posting.

[Official] XML Guide

Postby thenobodies80 on Mon Jan 07, 2013 4:07 pm

XML Guide

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.

But before to start, a very special "Thank You!" for contributing with the development of this XML Guide goes to OliverFA, MrBenn, ender516, natty dread and the whole Cartographers Team

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.
Code: Select all
This effect is used for XML Code.

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.
show


Index
  1. -Overview
  2. -Tutorial
  3. - XML Tag Index
  4. - Advanced concepts; Creating more complex maps
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

Overview

Postby thenobodies80 on Mon Jan 07, 2013 4:07 pm

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.


Tags

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:

Code: Select all
<name>Western United States</name>


The ā€œheaderā€

First of all, your XML file must begin with this on the first line:

Code: Select all
<?xml version="1.0" encoding="UTF-8"?>

Don't worry about understanding it ā€“ it's a special tag that tells the game engine that this is an XML file.

Next you need a map tag which will contain everything else.

Code: Select all
<?xml version="1.0" encoding="UTF-8"?>
<map>
   .   
   .
   .
</map>

It is customary to indent tags when they are nested inside other tags and put one tag on each line. This isn't necessary but makes your XML easier to read.

A very important thing to remember when you write a map xml is the order of the tags, if you want to know about the exact order to use please read here.

Now, before to proceeding further and see in detail each tag, we see how to write the xml of the map we are most known, the classic one.
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

2.1-Basic concepts; Creating the Classic Map

Postby thenobodies80 on Mon Jan 07, 2013 4:08 pm

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.

Image

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.
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

2.2 -Creating the XML file

Postby thenobodies80 on Mon Jan 07, 2013 4:08 pm

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

Code: Select all
<?xml version="1.0" encoding="UTF-8"?>
<map>
  <!-- Classic -->
</map>


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.
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

2.3 -Territories

Postby thenobodies80 on Mon Jan 07, 2013 4:24 pm

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>.

Code: Select all
   <territory>
   </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).

Code: Select all
   <territory>
      <name>Anchorage</name>
   </territory>

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.

Code: Select all
   <territory>
      <coordinates>
         <smallx>30</smallx>
         <smally>125</smally>
         <largex>35</largex>
         <largey>145</largey>
      </coordinates>
   </territory>

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.

Code: Select all
   <territory>
      <borders>
         <border>Edmonton</border>
         <border>Vancouver</border>
         <border>Magadan</border>
      </borders>
   </territory>

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:

Code: Select all
   <territory>
      <name>Anchorage</name>
      <borders>
         <border>Edmonton</border>
         <border>Vancouver</border>
         <border>Magadan</border>
      </borders>
      <coordinates>
         <smallx>30</smallx>
         <smally>125</smally>
         <largex>35</largex>
         <largey>145</largey>
      </coordinates>
   </territory>


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.

show
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

2.4 -Continents

Postby thenobodies80 on Mon Jan 07, 2013 4:24 pm

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.

Code: Select all
   <continent>
   </continent>

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.

Code: Select all
   <continent>
      <name>Africa</name>
   </continent>

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.

Code: Select all
   <continent>
      <components>
         <territory>Dakar</territory>
         <territory>Cairo</territory>
         <territory>Nairobi</territory>
         <territory>Lagos</territory>
         <territory>Cape Town</territory>
         <territory>Johannesburg</territory>
      </components>
   </continent>

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:

Code: Select all
   <continent>
      <bonus>3</bonus>
   </continent>

Continent summary
Let's summarize all the components of the <continent> tag using Africa as an example:
Code: Select all
   <continent>
      <name>Africa</name>
      <bonus>3</bonus>
      <components>
         <territory>Dakar</territory>
         <territory>Cairo</territory>
         <territory>Nairobi</territory>
         <territory>Lagos</territory>
         <territory>Cape Town</territory>
         <territory>Johannesburg</territory>
      </components>
   </continent>



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:

show
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

2.5 -Attaching the XML file to the map thread

Postby thenobodies80 on Mon Jan 07, 2013 4:25 pm

2.5 -Attaching the XML file to the map thread

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 Image and the attached files will be displayed in your post, for the classic map xml of this tutorial:
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

3.1 -File Structure and <!--Comments-->

Postby thenobodies80 on Mon Jan 07, 2013 4:25 pm

3.1 -File Structure and <!--Comments-->

File structure
The following table shows the structure of an XML map file, displaying all the first level tags:

Code: Select all
<?xml version="1.0"?>
<map>
   <minreinforcement/>
   <reinforcements/>
   <positions/>
   <requirement/>
   <objectives/>
   <continents/>
   <territories/>
</map>

It's very important to place tags in the same order as they appear here. If you change the order, the results might not be what you are expecting.

If you don't need a particular tag, just skip it and continue with the next. I.e., if your map did not have starting positions, just skip the <positions> tag.

<!-- Comments -->
Provides a way to document the code.

Syntax
<!-- Comment -->

Comment: The comment we want to place in order to document the code. It can be anything.

Location:
It can be placed anywhere in the code.

Example:
In this fragment of code, we are using the comment feature to specify the map's name.
Code: Select all
<?xml version="1.0"?>
<map>
  <!-- Classic -->
   <continent>
...
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

3.2 -<map>

Postby thenobodies80 on Mon Jan 07, 2013 4:26 pm

3.2-<map>

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.
Code: Select all
<?xml version="1.0" encoding="UTF-8"?>
<map>
  <!-- Classic -->
   <continent>
...
   </territory>
</map>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

3.3 -<minreinforcement>

Postby thenobodies80 on Mon Jan 07, 2013 4:26 pm

3.3-<minreinforcement>

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.
Code: Select all
<minreinforcement>1</minreinforcement>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

3.4 -<reinforcements>

Postby thenobodies80 on Mon Jan 07, 2013 4:27 pm

3.4-<reinforcements>

Adjusts the rate of reinforcements received from territories owned.

If this tag is not specified, the map will have a default rate of 1 army per 3 territories or fraction.

Syntax
<reinforcements>
__<reinforcement>
____<lower>From</lower>
____<upper>To</upper>
____<divisor>Divisor</divisor>
__</reinforcement>
<reinforcements>


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.

Notes:

Info about a more extensive use of Adjusted Reinforcements can be found here: Reinforcement Adjustment

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.
Code: Select all
<reinforcements>
   <reinforcement>
      <lower>1</lower>
      <upper>42</upper>
      <divisor>3</divisor>
   </reinforcement>
</reinforcements>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

3.5 -<positions>

Postby thenobodies80 on Mon Jan 07, 2013 4:27 pm

3.5-<positions>

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.

Syntax
<positions>
__<position>
____<territory>TerrName</territory>
____...
__</position>
__<position>
__...
__</position>
</positions>


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):
Code: Select all
<!-- Start Positions -->
<positions>
   <position>
      <territory>Britain</territory>
   </position>
   <position>
      <territory>France</territory>
   </position>
   <position>
      <territory>Holland</territory>
   </position>
   <position>
      <territory>Spain</territory>
   </position>
   <position>
      <territory>Portugal</territory>
   </position>
   <position>
      <territory>Inuit Homeland</territory>
   </position>
   <position>
      <territory>Comanche Homeland</territory>
   </position>
   <position>
      <territory>Aztec Homeland</territory>
   </position>
   <position>
      <territory>Mapuche Homeland</territory>
   </position>
</positions>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

3.6 -<requirement>

Postby thenobodies80 on Mon Jan 07, 2013 4:28 pm

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.

Syntax
<requirement>
__<name>ReqName</name>
__<components>
____( <territory>TerrName</territory> | <continent>ContName</continent> )
____...
__</components>
__[<required>ItemsReq</required>]
</requirement>


The <required> subtag is optional.

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.
Code: Select all
<!-- losing conditions -->
<requirement>
    <name>a Base and freezes to death</name>
    <components>
         <territory>Base A</territory>
         <territory>Base B</territory>
         <territory>Base C</territory>
         <territory>Base D</territory>
         <territory>Base E</territory>
         <territory>Base F</territory>
         <territory>Base G</territory>
         <territory>Base H</territory>
         <territory>Base I</territory>
         <territory>Base J</territory>
         <territory>Base K</territory>
         <territory>Base L</territory>
         <territory>Base M</territory>
         <territory>Base N</territory>
         <territory>Base O</territory>
         <territory>Base P</territory>
    </components>
    <required>1</required>
</requirement>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

3.7 -<objectives>

Postby thenobodies80 on Mon Jan 07, 2013 4:28 pm

3.7-<objectives>

An objective is a territory or a group of territories. If a player holds the objective through a full round, that player wins the game.
This feature is known as Winning Conditions.

Syntax
<objective>
__<name>ObjName</name>
__<components>
____( <territory>TerrName</territory> | <continent>ContName</continent> )
____...
__</components>
__[<required>ItemsReq</required>]
</requirement>


The <required> subtag is optional.

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:
Code: Select all
<objective>
   <name>Find The Treasure</name>
   <components>
      <territory>Grand Oasis 1</territory>
      <territory>Grand Oasis 2</territory>
      <territory>Grand Oasis 3</territory>
   </components>
</objective>

Objectives are very flexible, and can be something else than just a list of territories. In the Third Crusade map, victory is achieved by fulfilling four conditions:
  • Any starting point.
  • Jerusalem.
  • Antioch.
  • Vatican or Granada.
And here's how it is coded:
Code: Select all
   <!-- Objectives Begin -->
   <objective>
      <name>Victory Condition</name>
      <components>
         <continent>Any Starting Territory</continent>
         <territory>Jerusalem</territory>
         <territory>Antioch</territory>
         <continent>The Vatican or Granada</continent>
      </components>
   </objective>
   <!-- Objective Continents -->
   <continent>
      <name>Any Starting Territory</name>
      <bonus>0</bonus>
      <components>
         <territory>London</territory>
         <territory>Paris</territory>
         <territory>Ratisbon</territory>
         <territory>Castile</territory>
         <territory>Thessalonica</territory>
         <territory>Tunis</territory>
         <territory>Cairo</territory>
         <territory>Amasia</territory>
      </components>
      <required>1</required>
   </continent>
   <continent>
      <name>The Vatican or Granada</name>
      <bonus>0</bonus>
      <components>
         <territory>The Vatican</territory>
         <territory>Granada</territory>
      </components>
      <required>1</required>
   </continent>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

3.8 -<continents>

Postby thenobodies80 on Mon Jan 07, 2013 4:29 pm

3.8-<continents>

This tag defines a group of map regions that, when held by the player at turn start, provides a reinforcement bonus. Some optional subtags provide additional control over the bonus zone structure.

Syntax
<continent>
__<name>ConName</name>
__<bonus>ReinfBonus</bonus>
__<components>
____<territory>TerrName</territory>
____...
__</components>
</continent>


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:
Code: Select all
<continent>
    <name>West</name>
    <bonus>2</bonus>
    <components>
       <territory>Washington</territory>
       <territory>Oregon</territory>
       <territory>California</territory>
       <territory>Nevada</territory>
    </components>
</continent>


The 13 Colonies map shows that is possible to use the <continent> tag as component. In this case, the 3 bonus troops are awarded if the player holds any 2 of the component continents.
Code: Select all
...
<continent>
   <name>2 colonies</name>
   <bonus>3</bonus>
   <components>
      <continent>Georgia</continent>
      <continent>South Carolina</continent>
      <continent>North Carolina</continent>
      <continent>Virginia</continent>
      <continent>Maryland</continent>
      <continent>Delaware</continent>
      <continent>Pennsylvania</continent>
      <continent>New Jersey</continent>
      <continent>New York</continent>
      <continent>Connecticut</continent>
      <continent>Rhode Island</continent>
      <continent>Massachusetts</continent>
      <continent>New Hampshire</continent>
      <required>2</required>
    </components>
...
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

3.9 -<territories>

Postby thenobodies80 on Mon Jan 07, 2013 4:30 pm

3.9-<territories>

This tag defines the regions on your map; their names, borders, and position on the images. You need one for each region on your map. A region is a point on a map at which troops are placed. Some optional subtags provide additional control.

Syntax
<territory>
__<name>TerName</name>
____<borders>
______<border>AdjName</border>
_________...
____</borders>
____<coordinates>
______<smallx>SXCoord</smallx>
______<smally>SYCoord</smally>
______<largex>LXCoord</largex>
______<largey>LYCoord</largey>
____</coordinates>
</territory>


For each territory you'll also need to specify <name>, <borders> and <coordinates>. Borders is a list of <border> tags containing exact names of other territories that can be assaulted from this one (and consequently, can be reinforced once conquered). Coordinates is a list of the X and Y coordinates (in pixels) where the armies should be printed on the small and large maps. At its most basic version, this tag contains only the <name> of the region, the list of <borders>, and where the <coordinates> where the troop count should be printed.

TerName: The name given to this territory.
AdjName: The name of an adjacent territory (TerName can assault AdjName)
SXCoord: The value of the X Coordinate, in pixels, for the small map.
SYCoord: The value of the Y Coordinate, in pixels, for the small map.
LXCoord: The value of the X Coordinate, in pixels, for the large map.
LYCoord: The value of the Y Coordinate, in pixels, for the large map.

Notes:
The tag can be expanded with optional subtags, If you are looking for a more extensive use of the <territories> tag, you can find some info here (Autodeploy and Decay), here (Starting Neutrals and Killer Neutrals), here (One Way and Ranged Attacks), here (Bombardaments) and here (Conditional Borders).

Location:
It goes after the <continents> tag and before the closing </map> tag.

Examples:
Berlin region on the Germany map. It borders with Schwerin and Potsdam.
The code for this region looks this way:
Code: Select all
<territory>
   <name>Berlin</name>
   <borders>
   <border>Schwerin</border>
   <border>Potsdam</border>
   </borders>
   <coordinates>
      <smallx>514</smallx>
      <smally>180</smally>
      <largex>601</largex>
      <largey>221</largey>
   </coordinates>
</territory>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

4.1 -Reinforcement Adjustment

Postby thenobodies80 on Mon Jan 07, 2013 4:30 pm

4.1 -Reinforcement Adjustment

We have defined here the very basic use of <minreinforcement> and <reinforcements> tags.

Now we are going to see the whole set of tricks that we can use, but first, a few rules:

Rules:
  • The minimum reinforcement must be a number greater than zero.
  • If you create 2 or more <reinforcement> tag, ensure that they don't overlap.
  • Where not specified, applies the standard reinforcement +1 every 3 regions.

You should keep in mind the above rules while playing with your reinforcements, or your map won't work in the proper way or at all.

Standard Reinforcement:
This code implements the default rate of 1 army for each 3 territories in the Classic Map.
Code: Select all
<reinforcements>
   <reinforcement>
      <lower>1</lower>
      <upper>42</upper>
      <divisor>3</divisor>
   </reinforcement>
</reinforcements>

With this case the number of regions we hold is divided by 3. So we will receive 4 armies instead of 3 when we hold the 12th regions at the start of a turn.Then 5 armies with 15 regions, etc.

Change the divisor:
In First Nations of the Americas, the reinforcement rate was lowered to 1 army per each 4 territories. Here you can see how that was made:
Code: Select all
<minreinforcement>4</minreinforcement>
<reinforcements>
   <reinforcement>
      <lower>1</lower>
      <upper>127</upper>
      <divisor>4</divisor>
   </reinforcement>
</reinforcements>


Set 2+ <reinforcement> tags:
The map Conquer Man adjusts territories applying the Diminishing Returns Law meaning that the more territories a player has, the more he needs to add to get the next reinforcement, following the table:

  • 1-30 occupied territories: One army for every 3 territories.
  • 31-60 occupied territories: One army for every 4 territories.
  • 61-100 occupied territories: One army for every 5 territories.
  • 101-151 occupied territories: One army for every 6 territories.

This table is coded with those lines:
Code: Select all
<reinforcements>
   <reinforcement>
      <lower>1</lower>
      <upper>30</upper>
      <divisor>3</divisor>
      <lower>31</lower>
      <upper>60</upper>
      <divisor>4</divisor>
      <lower>61</lower>
      <upper>100</upper>
      <divisor>5</divisor>
      <lower>101</lower>
      <upper>151</upper>
      <divisor>6</divisor>
   </reinforcement>
</reinforcements>


Capped Reinforcements:
The Hive map sets a maximum for territories reinforcement. After the 36th territory, players do not get additional reinforcements on this basis. It is achieved by setting a divisor number higher than the number of territories in the last segment.
Code: Select all
   <minreinforcement>3</minreinforcement>
   <reinforcements>
      <reinforcement>
         <lower>1</lower>
         <upper>36</upper>
         <divisor>3</divisor>
      </reinforcement>
      <reinforcement>
         <lower>37</lower>
         <upper>352</upper>
         <divisor>400</divisor>
      </reinforcement>
   </reinforcements>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

4.2 -Starting Positions

Postby thenobodies80 on Mon Jan 07, 2013 4:31 pm

4.2 -Starting Positions: Underlying Neutrals and Advanced Usage

We have defined here the very basic use of <positions> tag.
Now we are going to learn how to use the Starting Positions more in depth, but first, a few rules:

Rules:
  • Starting Positions are always divided evenly among the players.
  • If you have more players than positions, then starting positions are ignored.
  • When not assigned, a position is handed out as a standard region, so an eventual underlying neutral will apply.
  • Only territories can be used as starting positions <components>
  • There's no limit with the number of starting positions on a map.
  • Starting Positions can contain different number of <components>

You should keep in mind the above rules when you use the starting positions or the map will work in a different way than how expected.

This chapter is for the comprehension of an advanced usage of Starting Positions, if you're looking instead for the basic use of this feature, please take a look here.


Define the starting amount of troops with positions:
We know that the default number of troops given on a territory is 3. There could be a case in which we want to give more than 3 troops on a territory that is coded as starting position.
To achieve this we need to use the start="" identifier within the <territory> tag placed into a <position>

Look at this example:
City Mogul is a map that tries to minimize the luck factor by creating inflation in the number of armies. Bonuses and neutrals are much higher than is usual on an average map. This in turn required the mapmaker to also increase the number of starting armies per player by using the <positions> tag. This map also has starting positions with more than one territory.
Code: Select all
<!-- Starts -->
<positions>
   <position>
      <territory start="20">P4</territory>
      <territory start="30">P2</territory>
   </position>
   <position>
      <territory start="20">Y4</territory>
      <territory start="30">Y2</territory>
   </position>
   <position>
      <territory start="20">R4</territory>
      <territory start="30">R6</territory>
   </position>
   <position>
      <territory start="20">C1</territory>
      <territory start="30">C4</territory>
   </position>
   <position>
      <territory start="20">G5</territory>
      <territory start="30">G4</territory>
   </position>
   <position>
      <territory start="20">O6</territory>
      <territory start="30">O7</territory>
   </position>
   <position>
      <territory start="20">B5</territory>
      <territory start="30">B3</territory>
   </position>
   <position>
      <territory start="20">S4</territory>
      <territory start="30">S2</territory>
   </position>
</positions>


Limit the number of positions for each player:
We said that starting positions are always divided evenly between players. But there's a way to have more control on the number of starting positions that are given out at the start.
If we want to control the maximum number of positions (NOTE: not the number of components) that is given to each player, we can use the max="" options into the <positions> tag.
But look at this example for better understanding:
Kings Court map has 8 starting positions. And although games on this map will start with two positions for each player for 3- and 4-player games, the XML prevents 1v1 games from starting with 4 positions (8 divided by 2) by setting the maximum number of positions to 2.
Code: Select all
<positions max="2">
   <position>
      <territory start="2">Castle A</territory>
      <territory start="1">Noble A</territory>
   </position>
   <position>
      <territory start="2">Castle B</territory>
      <territory start="1">Noble B</territory>
   </position>
   <position>
      <territory start="2">Castle C</territory>
      <territory start="1">Noble C</territory>
   </position>
   <position>
      <territory start="2">Castle D</territory>
      <territory start="1">Noble D</territory>
   </position>
   <position>
      <territory start="2">Castle E</territory>
      <territory start="1">Noble E</territory>
   </position>
   <position>
      <territory start="2">Castle F</territory>
      <territory start="1">Noble F</territory>
   </position>
   <position>
      <territory start="2">Castle G</territory>
      <territory start="1">Noble G</territory>
   </position>
   <position>
      <territory start="2">Castle H</territory>
      <territory start="1">Noble H</territory>
   </position>
</positions>


Underlying Neutrals:
After the starting positions have been divided among the players as evenly as possible, the components of the remaining positions are treated like standard regions and given out using the standard formula: (NumRegions / NumPlayers, where, in the case of a 1v1 game, NumPlayers is set to three, setting up the "neutral player" with at least as many territories as the actual players).
But if we do not want to put the remaindered territories into the starting drop we're able to do that using the underlying neutrals

An underlying neutral is nothing more than a territory coded to start as a neutral one. If you don't know how to code a territory as neutral please read here.
Instead, if you already know how to use neutrals, just let me explain the trick:

When the game starts, starting Positions are evaluated before the territory tags. So the game engine divides the number of starting positions evenly between the players.
For this example let us consider the case where there is a remainder. We said that remaindered territories are given out using the standard formula, so such territories are no longer seen as part of a starting position but rather just like normal <territories> tags.
So before dividing them among the players, the game engine will check if some of them are coded as neutrals. If this is the case, the game will give the territories a neutral value instead of putting them into the starting pot. In fact neutrals have a priority on normal territories.

Confused? Let's use some code to show you that is not so hard to do!
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):
Code: Select all
<!-- Start Positions -->
<positions>
   <position>
      <territory>Britain</territory>
   </position>
   <position>
      <territory>France</territory>
   </position>
   <position>
      <territory>Holland</territory>
   </position>
   <position>
      <territory>Spain</territory>
   </position>
   <position>
      <territory>Portugal</territory>
   </position>
   <position>
      <territory>Inuit Homeland</territory>
   </position>
   <position>
      <territory>Comanche Homeland</territory>
   </position>
   <position>
      <territory>Aztec Homeland</territory>
   </position>
   <position>
      <territory>Mapuche Homeland</territory>
   </position>
</positions>


Let's make it so that France is not assigned with starting positions and we don't want it to be given out as a normal territory due to the autodeploy bonus (+4)
We need just to add the <neutral> tag into the territory:

Code: Select all
<!-- France -->
<territory>
  <name>France</name>
  <borders>
    <border>French Landing Point</border>
  </borders>
  <bombardments>
    <bombardment>French 1</bombardment>
   <bombardment>French 2</bombardment>
   <bombardment>French 3</bombardment>
  </bombardments>
  <coordinates>
    <smallx>545</smallx>
   <smally>167</smally>
   <largex>637</largex>
   <largey>191</largey>
  </coordinates>
  <neutral>10</neutral>
  <bonus>4</bonus>
</territory>


Positions only for particular numbers of players:

If we have a map in which numbers are perfect for, let say, 8 players but not for 3 players, we can decide to work on numbers using starting positions.
Obviously we need to use a system that has influence only on a specific number of player and not on the whole cases.

Do this is simple, we need just to code less positions than players. For games in which players are more than positions, those positions will be ignored.
But look at the example:


Thyseneal
has starting positions, but only for games with 5 players or less. This is to prevent a player from unfairly getting a bonus right from the start.

Code: Select all
<positions>
   <position>
      <territory>Dalmus</territory> <!-- position A-1 -->
      <territory>Arleus</territory> <!-- position A-2 -->
      <territory>Illania</territory> <!-- position A-3 -->
      <territory>Tuskaroja</territory> <!-- position A-4 -->
   </position>
   <position>
      <territory>Caspiar</territory> <!-- position B-1 -->
      <territory>Chunjaris</territory> <!-- position B-2 -->
      <territory>Azuran</territory> <!-- position B-3 -->
      <territory>Alus</territory> <!-- position B-4 -->
   </position>
   <position>
      <territory>Tyross</territory> <!-- position C-1 -->
      <territory>Theraland</territory> <!-- position C-2 -->
      <territory>Chancella</territory> <!-- position C-3 -->
      <territory>Cancallus Desert</territory> <!-- position C-4 -->
   </position>
   <position>
      <territory>Cratica</territory> <!-- position D-1 -->
      <territory>Sarle</territory> <!-- position D-2 -->
      <territory>Jenua</territory> <!-- position D-3 -->
      <territory>Iskul</territory> <!-- position D-4 -->
   </position>
   <position>
      <territory>Solaria</territory> <!-- position E-1 -->
      <territory>Itheria</territory> <!-- position E-2 -->
      <territory>Morovia</territory> <!-- position E-3 -->
      <territory>Narula</territory> <!-- position E-4 -->
   </position>
</positions>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

4.3 -Continents Options

Postby thenobodies80 on Mon Jan 07, 2013 4:31 pm

4.3.1 -Nested Continents and Overrides

We have described here the <continents> tag.
Now we are going to learn how to mix some continents together to create more variety in your maps.

Nested Continents:
We know that a continent is a group of regions. Usally the structure of bonuses based on zones (continents) is pretty simple and clear. But in some cases we need to create a series of continents where the components of one is a subset of (or even identical to) the components of another. Confused? Ok, look at this example:

This is a continent taken from the Cyprus map. With this bonus you need to hold at least 5 turkish territories to receive +1 troop.
Code: Select all
<continent>
<name>5 Turkish Territories</name>
   <bonus>1</bonus>
   <components>
        <territory>Rizokarpaso</territory>
        <territory>Yalousa</territory>
        <territory>Akanthou</territory>
        <territory>Lefkoniko</territory>
        <territory>Famagusta</territory>
        <territory>Kyrenia</territory>
        <territory>Karavas</territory>
        <territory>Laphitos</territory>
        <territory>Morphou</territory>
        <territory>Kythrea</territory>
        <territory>Nicosia</territory>
   </components>
   <required>5</required>
</continent>


It looks exactly like a standard bonus with the exception of the <required> tag. If you add this tag, your bonus will not given only when a player holds the whole list of territories, but instead when he holds at least the number of territories equal to the number written into the <required> tag, obviously, among those territories listed in the continent.

Now, we are going to add a second continent, this time +2 for 10 turkish territories:

Code: Select all
<continent>
<name>5 Turkish Territories</name>
   <bonus>1</bonus>
   <components>
        <territory>Rizokarpaso</territory>
        <territory>Yalousa</territory>
        <territory>Akanthou</territory>
        <territory>Lefkoniko</territory>
        <territory>Famagusta</territory>
        <territory>Kyrenia</territory>
        <territory>Karavas</territory>
        <territory>Laphitos</territory>
        <territory>Morphou</territory>
        <territory>Kythrea</territory>
        <territory>Nicosia</territory>
   </components>
   <required>5</required>
</continent>
<continent>
   <name>10 Turkish Territories</name>
   <bonus>2</bonus>
   <components>
      <territory>Rizokarpaso</territory>
      <territory>Yalousa</territory>
      <territory>Akanthou</territory>
      <territory>Lefkoniko</territory>
      <territory>Famagusta</territory>
      <territory>Kyrenia</territory>
      <territory>Karavas</territory>
      <territory>Laphitos</territory>
      <territory>Morphou</territory>
      <territory>Kythrea</territory>
      <territory>Nicosia</territory>
   </components>
   <required>10</required>
</continent>


With the above code when a player holds 10 regions, he will receive +1 troops for holding 5 turkish territories and +2 for holding 10 turkish territories, for a total of +3 troops.
But we want to give 5 territories bonus only if the player doesn't hold 10 territories. How to make this possible?
Look at the final code:

Code: Select all
<continent>
<name>5 Turkish Territories</name>
   <bonus>1</bonus>
   <components>
        <territory>Rizokarpaso</territory>
        <territory>Yalousa</territory>
        <territory>Akanthou</territory>
        <territory>Lefkoniko</territory>
        <territory>Famagusta</territory>
        <territory>Kyrenia</territory>
        <territory>Karavas</territory>
        <territory>Laphitos</territory>
        <territory>Morphou</territory>
        <territory>Kythrea</territory>
        <territory>Nicosia</territory>
   </components>
   <required>5</required>
</continent>
<continent>
   <name>10 Turkish Territories</name>
   <bonus>2</bonus>
   <components>
      <territory>Rizokarpaso</territory>
      <territory>Yalousa</territory>
      <territory>Akanthou</territory>
      <territory>Lefkoniko</territory>
      <territory>Famagusta</territory>
      <territory>Kyrenia</territory>
      <territory>Karavas</territory>
      <territory>Laphitos</territory>
      <territory>Morphou</territory>
      <territory>Kythrea</territory>
      <territory>Nicosia</territory>
   </components>
   <required>10</required>
   <overrides>
      <override>5 Turkish Territories</override>
   </overrides>
</continent>


We added the <overrides> tag. The bonus listed within this tag, as <override>, is not given when the player hold this continent. So, using our example, when a player holds 10 Turkish Territories, the +2 bonus overrides the +1 bonus for 5 Turkish Territories, and the total amount of bonus troops given is +2 (and not +3 like with the previous code).
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

Bonus Collections

Postby thenobodies80 on Mon Jan 07, 2013 4:32 pm

4.3.2 -Collections, a new way to code Continents

If you have ever used nested continents for one of your map, you certainly have experienced how long that continents list can be and how many overrides you had to use to give out bonuses correctly.
This issue can be circumvented using a different way to code your bonuses: Collections.
Essentially, it's a more flexible way to write a continent or a series of continents without having to create a long chain.

Syntax
<continent>
__<name>ConName</name>
__<bonuses>
____<bonus required="#">BonusVal</bonus>
____...
__</bonuses>
__<components>
____<territory>TerrName</territory>
____...
__</components>
<required>#</required>
</continent>


With this method we introduce the <bonuses> tag.
Into this tag we can list all the bonuses, a <bonus> tag for each bonus.
It can sound confusing but look at the code:

Code: Select all
<continent>
<name>ConName</name>
<bonuses>
<bonus required="2">1</bonus>
<bonus required="3">2</bonus>
<bonus required="4">3</bonus>
</bonuses>
<components>
<territory>TerrName1</territory>
<territory>TerrName2</territory>
<territory>TerrName3</territory>
<territory>TerrName4</territory>
</components>
<required>2</required>
</continent>


With the above code a player will receive 1 additional armies if he holds at least 2 components, 3 additional armies if he holds 3 components and 6 armies if he holds 4 components.
So with collections you can specify multiple bonuses along with the number of components required to achieve each bonus.

There some important aspects to consider while using Bonus Collections:
  • Add the <required> tag after having listed all the components is mandatory, otherwise the collection feature won't work properly. The value of the required tag must be the lower bonus of the collection.
  • If you achieve several bonuses they get added together;
  • Components can be a <territory> as well a <continent>;
  • They are NOT mandatory. The standard way to code continents still works.
  • Only <territory> components can have additional options. Refer to the dedicated section of this guide for details;
  • Even if Collections are a series of bonuses, you can specify only a single name for a Bonus Collection. The <name> tag must be unique.
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

Other Options

Postby thenobodies80 on Mon Jan 07, 2013 4:32 pm

4.3.3 - <mandatory>, <blocker> and <multiplier>

To perform some nice tricks we need to introduce 3 options that we can specify for the <territory> tags listed within the <components>.
The 3 options that can be used to specify a particular type of component, are:
  • mandatory
  • blocker
  • multiplier

Mandatory

Syntax
<continent>
__<name>ConName</name>
__<bonuses>
____<bonus required="#">BonusVal</bonus>
____...
__</bonuses>
__<components>
____<territory type="mandatory">TerrName</territory>
____...
__</components>
</continent>


The mandatory type can be used to give a bonus to a player only if the mandatory component is held.
To specify that a territory is a mandatory component, you need to add type="mandatory" into the opening territory tag: <territory type="mandatory">

For example
Code: Select all
<continent>
<bonuses>
<bonus required="5">2</bonus>
<bonus required="8">3</bonus>
<bonus required="10">5</bonus>
</bonuses>
<components>
<territory type="mandatory">country 1</territory>
<territory>country 2</territory>
<territory>country 3</territory>
<territory>country 4</territory>
<territory>country 5</territory>
<territory>country 6</territory>
<territory>country 7/territory>
<territory>country 8</territory>
<territory>country 9</territory>
</components>
</continent>


Let me explain the above code. In the first part we can see that you will receive 2 troops if you hold at least 5 territories within those listed as components, 5 if you hold 8 and 10 if you hold 10. But these additional troops are given to you only if you hold the mandatory one (country 1 in the example). In fact if you hold 9 countries (from country 2 to country 9) but you don't hold the mandatory one (country 1) you will NOT qualify for the bonus and you will receive nothing. It's simple, If you don't hold the mandatory territory you don't hold the continent. The mandatory type need not be unique, so you can have more than a single mandatory territory for a bonus.

IMPORTANT
The mandatory type can be used ONLY with <territory> components. Do NOT use it with <continent>


Blocker

Syntax
<continent>
__<name>ConName</name>
__<bonuses>
____<bonus required="#">BonusVal</bonus>
____...
__</bonuses>
__<components>
____<territory type="blocker">TerrName</territory>
____...
__</components>
</continent>


The blocker type identify a particular type of component. If you hold a blocker component you do NOT hold the continent.
To specify the blocker type for a territory you need to add type="blocker" into the opening territory tag: <territory type="blocker">

For example
Code: Select all
<continent>
    <bonuses>
    <bonus required="1">1</bonus>
    <bonus required="2">3</bonus>
    <bonus required="3">5</bonus>
    </bonuses>
    <components>
    <territory type="blocker">country 1</territory>
    <territory>country 2</territory>
    <territory>country 3</territory>
    <territory>country 4</territory>
    </components>
    </continent>


With the above code, if the player holds country 1 (it doesn't matter how many other territories he has) he doesn't hold the continent at all and that means if it was a subcontinent he doesn't hold that either, like in the example into the following spoiler:
show


IMPORTANT
The blocker type can be used ONLY with <territory> components. Do NOT use it with <continent>


Multiplier

Syntax
<continent>
__<name>ConName</name>
__<bonuses>
____<bonus required="#">BonusVal</bonus>
____...
__</bonuses>
__<components>
____<territory type="multiplier" factor="#.#">TerrName</territory>
____...
__</components>
</continent>


The multiplier type identifies another particular type of component. To set a component as multiplier, first we need to add type="multiplier" to the opening <territory> tag and immediately after the type we need to specify a factor, which must be a number.

For example
Code: Select all
<continent>
    <bonus>5</bonus>
    <components>
    <component type="multiplier" factor="1.5">multiplier country</component>
    <component>country 1</component>
    <component>country 2</component>
    <component>country 3</component>
    </components>
    </continent>


In the above example, when the player holds the multiplier country the bonus is multiplied by the factor specified, in this case, 1.5.

There are a few things to keep in mind:
  • The factor value can have decimals
  • When the multiplier is applied, the final bonus value is always rounded to the nearest integer.
  • The factor value can be 0

IMPORTANT
The multiplier type can be used ONLY with <territory> components. Do NOT use it with <continent>



Now that we've looked at all component options, we can notice that there are two ways to define a territory that you don't want to hold - either make it a blocker or make it a multiplier with factor of zero. What's the difference? Like we said before, if you have a blocker, then you don't hold the continent at all and that means if it is a subcontinent you don't hold that either. Instead, if you have a multiplier with factor=0, then even though you don't get any bonus, you technically hold the continent, so if it is a subcontinent you still hold it as a component.
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

4.4 - Territories Options

Postby thenobodies80 on Mon Jan 07, 2013 4:33 pm

We have described here the <territory> tag. Now we're going to explore more in depth which other tricks you can perform with territories.

4.4.1 -Autodeploy and Decay

Syntax
<territory>
__<name>TerName</name>
____<borders>
______<border>AdjName</border>
_________...
____</borders>
____<coordinates>
______<smallx>SXCoord</smallx>
______<smally>SYCoord</smally>
______<largex>LXCoord</largex>
______<largey>LYCoord</largey>
____</coordinates>
____<bonus>#</bonus>
</territory>


Autodeploy and Decay are two different systems to use the same tag. If we want to apply a specific bonus to a single territory, we can use the <bonus> tag. It goes always after the <coordinates> tag and it must be a number. When the number is positive we will have an autodeploy, instead if the number is negative we have a decay. It's important to remember that in both cases the bonus value is added, or subtracted, to the amount of troops held by that specific territory.
In any case, a territory can NOT have less than 1 troop on it. Therefore, once there is only one troop on a territory, a decay has no effect.

A couple of examples:

In the Feudal War map, each castle is an autodepoly. Five additional troops are deployed automatically on a castle each turn, if you hold it.

Code: Select all
<territory>
   <name>Feudal Empire Castle</name>
   <borders>
      <border>Feudal Empire 1</border>
      <border>Feudal Empire 2</border>
      <border>Feudal Empire 3</border>
   </borders>
   <bombardments>
      <bombardment>Feudal Empire 4</bombardment>
      <bombardment>Feudal Empire 5</bombardment>
      <bombardment>Feudal Empire 6</bombardment>
      <bombardment>Feudal Empire 7</bombardment>
   </bombardments>
   <coordinates>
         <smallx>21</smallx>
         <smally>164</smally>
         <largex>28</largex>
         <largey>202</largey>
   </coordinates>
   <bonus>5</bonus>
</territory>


Instead, the Dust Bowl map has several decay territories in the central part to simulate drought. If you hold on of these regions you will receive a negative bonus directly on the region. For example, if you hold Sterling, you will lose 1 troop each turn you have on that region until you find yourself with just 1 army.

Code: Select all
<territory>
   <name>Sterling</name>
   <borders>
      <border>Imperial</border>
      <border>Colby</border>
      <border>Lamar</border>
      <border>Denver</border>
   </borders>
   <coordinates>
      <smallx>331</smallx>
      <smally>121</smally>
      <largex>423</largex>
      <largey>159</largey>
   </coordinates>
   <bonus>-1</bonus>
</territory>


So, you can simply change a number to make one region (or more) a powerful source of additional troops or a deadly spot on which to start your turn.
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

Neutral Territories

Postby thenobodies80 on Mon Jan 07, 2013 4:33 pm

4.4.2 -Starting Neutrals and Killer Neutrals

Starting Neutral

There are some cases in which we want to have more control of the starting drop in a game. One of these cases is when we don't want to have someone who starts with a specific territory. The best system to achieve this result is to code that territory to start always as neutral.

For example the Luxemburg map has Luxemburg City coded as neutral, that region will start with 3 neutral troops on it in any game.

Code: Select all
   <territory>
      <name>Luxembourg City</name>
      <borders>
         <border>Capellen</border>
         <border>Bourglinster</border>
         <border>Remich</border>
         <border>Esch</border>
         <border>Bous</border>
         <border>Dudelange</border>
         <border>Frisange</border>
      </borders>
      <coordinates>
         <smallx>177</smallx>
         <smally>474</smally>
         <largex>207</largex>
         <largey>550</largey>
      </coordinates>
      <neutral>3</neutral>
   </territory>


So, to code a neutral territory as starting neutral, you need only to add the <neutral> tag before the closing </territory one. The number of starting troops for that territory is specified within the tag.

Syntax
<territory>
__<name>TerName</name>
____<borders>
______<border>AdjName</border>
_________...
____</borders>
____<coordinates>
______<smallx>SXCoord</smallx>
______<smally>SYCoord</smally>
______<largex>LXCoord</largex>
______<largey>LYCoord</largey>
____</coordinates>
____<neutral>#</neutral>
</territory>


Killer Neutrals

There's an additional behaviour that we can assign to a neutral territory. We can make it a Killer Neutral.
Killer neutral works exactly like a normal neutral territory, but with an important difference:
If you take a neutral territory during a game, it will be yours until someone else conquers it. However, a killer neutral region, if you hold it, will revert back to a predefined number of neutral troops at the start of the next turn!

For example in the Arms Race! Map, the player that will take a missile launch, will lose it to 15 neutral armies, at the start of the next turn.

Code: Select all
<territory>
  <name>Titan II MISSLE LAUNCH</name>
  <borders>
  </borders>
  <bombardments>
  <bombardment>SS-18 Launch Platform</bombardment>
  <bombardment>SS-18 Stage 1</bombardment>
  <bombardment>SS-18 Stage 2</bombardment>
  <bombardment>SS-18 Stage 3</bombardment>
  <bombardment>SS-18 Stage 4</bombardment>
  <bombardment>SS-18 Stage 5</bombardment>
  <bombardment>SS-18 Warhead</bombardment>
  <bombardment>USSR Spy 1</bombardment>
  <bombardment>Leningrad</bombardment>
  <bombardment>USSR Premier</bombardment>
  <bombardment>Mendeleyev</bombardment>
  <bombardment>Moscow</bombardment>
  <bombardment>Samara</bombardment>
  <bombardment>USSR Uranium 1</bombardment>
  <bombardment>USSR Bunker 1</bombardment>
  <bombardment>Yekaterinburg</bombardment>
  <bombardment>Novosibirsk</bombardment>
  <bombardment>Noril'sk</bombardment>
  <bombardment>USSR Uranium 2</bombardment>
  <bombardment>USSR Bunker 2</bombardment>
  <bombardment>Frenkel</bombardment>
  <bombardment>Chitba</bombardment>
  <bombardment>USSR Uranium 3</bombardment>
  <bombardment>Magadan</bombardment>
  <bombardment>USSR Launch Code</bombardment>
  <bombardment>USSR Spy 2</bombardment>
  <bombardment>Sakharov</bombardment>
  <bombardment>Yakutsk</bombardment>
  <bombardment>USSR Silo 1</bombardment>
  <bombardment>USSR Silo 2</bombardment>
  </bombardments>
 <coordinates>
         <smallx>37</smallx>
         <smally>180</smally>
         <largex>51</largex>
         <largey>232</largey>
 </coordinates>
   <neutral killer="yes">15</neutral>
</territory>


To switch a neutral territory to a killer neutral, you have to add the killer="yes" option to the <neutral> tag. The territory will revert back always to the number of troops specified within the neutral tag.

Syntax
<territory>
__<name>TerName</name>
____<borders>
______<border>AdjName</border>
_________...
____</borders>
____<coordinates>
______<smallx>SXCoord</smallx>
______<smally>SYCoord</smally>
______<largex>LXCoord</largex>
______<largey>LYCoord</largey>
____</coordinates>
____<neutral killer="yes">#</neutral>
</territory>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

One Way borders and Ranged Attacks

Postby thenobodies80 on Mon Jan 07, 2013 4:34 pm

4.4.3 -One Way and Ranged Attacks

Optional tags for territories are great, but there are a few features that we can use without adding a single line of code.

One Way Borders

A standard territory has a list of borders. Usually Territory A borders with Territory B and vice versa. But if we want to make it possible to attack only from Territory A to Territory B and not the reverse?
It's simple! The solution is to list only the territory that can be attacked as a border of the territory that cannot be attacked.

An example is the British Isles Map, in which we can see that Northumberland can one way attack Lothian & Borders.

This is the code:
Code: Select all
   <territory>
      <name>Northumberland</name>
      <borders>
         <border>Lothian &amp; Borders</border>
         <border>Cumberland</border>
         <border>Durham</border>
      </borders>
      <coordinates>
         <smallx>355</smallx>
         <smally>269</smally>
         <largex>457</largex>
         <largey>351</largey>
      </coordinates>
   </territory>
...
<territory>
      <name>Lothian &amp; Borders</name>
      <borders>
         <border>Dumfries &amp; Galloway</border>
         <border>Strathclyde</border>
         <border>Tayside</border>
      </borders>
      <coordinates>
         <smallx>342</smallx>
         <smally>224</smally>
         <largex>444</largex>
         <largey>286</largey>
      </coordinates>
   </territory>


If a player decides to move troops from the attacking region to the other (advancing after conquering), he won't be able to reinforce them back, the connection being one-way, unless he has another route and the reinforcement option for the game is something other than Adjacent.

Using the same technique, we can allow a territory to attack another even if on the map the two do not border, for example a distant territory. It's the Ranged Attack feature. Remember, the map image does not determine how the game is played -- the XML does.
Ranged attacks and one way borders can be mixed together without problems. In most cases, the ranged attacks are visually supported on the map and there's no additional code required. Tt is mentioned in this guide just because it's considered by the community as a distinct map feature.

An example of ranged attacks (and also one way in this case) are the plane-parachute in the D-Day:Omaha Beach! Map
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

Bombardments

Postby thenobodies80 on Mon Jan 07, 2013 4:34 pm

4.4.4 -Bombardments

Attack is not the only way to take away a territory from your opponent(s). With the additional <bombardments> tag we can list a territory (or a series) that can be "bombarded" to become neutral. When all opponent's troops are defeated, the troop count of a bombarded territory reverts to one neutral, and the attacker isn't able to advance his troops into that region or reinforce into or through it after ending the attack phase of a turn.

Syntax
<territory>
__<name>TerName</name>
____<borders>
______<border>AdjName</border>
_________...
____</borders>
____<bombardments>
______<bombardment>BombName</bombardment>
_________...
____</bombardments>
____<coordinates>
______<smallx>SXCoord</smallx>
______<smally>SYCoord</smally>
______<largex>LXCoord</largex>
______<largey>LYCoord</largey>
____</coordinates>
</territory>


A classic example of bombardments can be found on the Berlin 1961 map, where Hohenschonhausen (the tank) can bombard the 3 western checkpoints:

Code: Select all
<territory>
      <name>Hohensch&#x00F6;nhausen</name>
      <borders>
         <border>Marzahn</border>
         <border>Lichtenberg</border>
         <border>Prenzlauer Berg</border>
         <border>Wei&#x00DF;ensee</border>
      </borders>
      <bombardments>
         <bombardment>Wedding</bombardment>
         <bombardment>Moabit</bombardment>
         <bombardment>Kreuzberg</bombardment>
      </bombardments>
      <coordinates>
         <smallx>380</smallx>
         <smally>196</smally>
         <largex>476</largex>
         <largey>240</largey>
     </coordinates>
     <neutral>3</neutral>
   </territory>
User avatar
Sergeant 1st Class thenobodies80
 
Posts: 5400
Joined: Wed Sep 05, 2007 4:30 am
Location: Milan

Next

Return to Tools & Guides

Who is online

Users browsing this forum: No registered users