Advanced XML

## Starting positions

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 starting amounts

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.

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

```
<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):

```
<!-- 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:

```
<!-- 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 number 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.

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

## Continents

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

```
<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:

```
<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:

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

## Bonus Collections

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:

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

## Special territorry types for continents

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

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:

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

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

```
<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 code:

```
<continent>
  <name>Continent A<name>
  <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>
<continent>
  <name>Continent B</name>
  <bonus>10</bonus>
  <components>
    <continent>Continent A</continent>
    <territory>country 5</territory>
  </components>
</continent>
```

Since, Continent A is component into Continent B, if you hold country 1 (the blocker), you don't hold Continent A thus you don't hold Continent B

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

### Multiplier

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

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

## Conditional borders

We all know that standard territories have fixed borders. This means that Territory A always borders with Territory B.
But now we're going to learn how to make the border conditional.
Conditional Borders allow a more flexible usage of borders and this feature makes it possible to have borders which change over the course of a game, based on the possession of territories.
Using again the same example, with conditional borders, we can have that Territory A borders with Territory B only if the player holds a Territory C. The third territory will be a sort of key: holding it satisfies the condition and so activates that border.

Syntax

```

Conditional Borders

Postby thenobodies80 on Mon Jan 07, 2013 11:35 pm
4.4.5 -Conditional Borders

We all know that standard territories have fixed borders. This means that Territory A always borders with Territory B.
But now we're going to learn how to make the border conditional.
Conditional Borders allow a more flexible usage of borders and this feature makes it possible to have borders which change over the course of a game, based on the possession of territories.
Using again the same example, with conditional borders, we can have that Territory A borders with Territory B only if the player holds a Territory C. The third territory will be a sort of key: holding it satisfies the condition and so activates that border.

Syntax
<territory>
  <name>TerName</name>
    <borders>
      <border condition="CondName">Ter2Name</border>
        ...
    </borders>
        ...
</territory>
```

So to define a conditional border you need to add the condition=" " option to the <border> tag.

There are few additional notes:

* You can specify either a territory or a continent as condition
* You must hold the territory/continent to activate the border
* If there is a territory and a continent that both match the condition's name, the territory will be used as the condition
* The conditional border is activated/disactivated immediately when you conquer or lose the condition

Here below an imaginary example of how the code looks like:

```
<territory>
  <name>Sao Paulo</name>
  <borders>
    <border>Bogota</border>
    <border>Lima</border>
    <border condition="New York">Buenos Aires</border>
    <border condition="Oceania">Dakar</border>
  </borders>
  <coordinates>
    ...
  </coordinates>
</territory>
```

Sao Paulo can attack Buenos Aires only if the same player holds New York. In addition, Sao Paulo can assault Dakar if the player holds the whole Oceania continent.
Obviously this is just a stupid example and I'm sure you can find plenty of better ways to use it.

## Transformations

The concept of Transformation includes the general ability to apply rules that transform any territory in different ways.
Transformation rules, called Tranforms, can be applied:

* to individual territories, or to every territory.
* at the start of every turn, every round, or at the start of specific rounds
* to neutral armies, player armies, opponents armies, or some combinations of these
* to set armies to fixed amounts, change by fixed increments, change by fixed percentages, or make random changes within a range

### XML Specification

In the XML, Tranforms are specified either globally or as children to a <territory> object, as follows:

```
<map>
...
<transforms>
  <transform>
    <type></type>
    <applyto></applyto>
    <inc></inc>
    <perc></perc>
    <amount></amount>
    <lower></lower>
    <upper></upper>
    <conditions>
    <formula></formula>
    <condition>
    <id></id>
    <variable></variable>
    <ownership></ownership>
    <minvalue></minvalue>
    <maxvalue></maxvalue>
    </condition>
....
    </conditions>
  </transform>
  <transform>
...
  <transform>
  </transform>
</transforms>
...
...
<territory>
...
<transforms>
...
</transforms>
...
___</territory>
</map>
```

### TYPE <type>

Controls when the tranform will execute, as follows:

T=Each Turn
R=Each Round (when first player starts)
RGN=Each Round after Round N
RLN=Each Round before ROund N

### APPLYTO <applyto>

Controls whether a tranform will be applied based on the type of occupying armies, as follows:

A=All
S=Self (the playing Player only)
N=Neutral only
P=Players only (not neutral)
OP=Other Players only (not neutral or the playing Player)
O=Others (all others, including neutral, except the playing player)

### INC <inc>

+ or - Adds/Subtracts Amount to/from Quantity,
If this is not set then the Quantity will be set to a calculated Amount independent of its current value

### UPPER/LOWER <upper>/<lower>

A upper and lower range given so that the system chooses an Amount randomly with equal probability across the range. May be fractional.

### PERC <perc>[optional]

If set to any non-zero value, use Amount as a % of the current value, instead of as a fixed value.

### CONDITIONS <conditions>[optional]

Each Conditions tag contains a set of Condition tags and optionally a Formula tag to tie them together. Currently conditions apply to territories only.

### FORMULA <formula>[optional]

formula allows construction of boolean logic rules. conditions prefixed with COND\_ (see example below). Default is to use logical AND for each condition.

### CONDITION <condition>

Each condition tag may contain ID, VARIABLE, OWNERSHIP, MINVALUE & MAXVALUE tags

### OWNERSHIP <ownership>[optional]

Test who owns the territory. See assigns\_to tag spec for the transform tag for functioning.

## Transformation process

Tranformation is the very first thing to execute on a Begin Turn action.

Go through each territory:

* Set Quantity = Initial value of armies on this territory

For the territory, execute the following process for each applicable Tranform in turn:

* Apply filters. If Tranform does not apply do nothing and skip to next tranform for this terit.
* Calulate Amount by choosing random number if range or setting as fixed amount
* if % is set, multiply Amount by Quantity/100
* If INC = "-" negate Amount
* If INC is set add Quantity to Amount
* set Quantity to Amount

After all Tranforms have executed for a territory:

* Quantity is rounded to the closest integer and set to a minimum of 1
* If Quantity has changed, set new army count and send log to game log.

Go to next Territory

### Examples

The original suggestion of neutrals that increase (or decrease by changing <inc> to "-") by 1 each turn would be specified as:

```
<transform>
<type>T</type>
<applyto>N</applyto>
<inc>+</inc>
<amount>1</amount>
</transform>
```

To modify this to make the neutrals change randomly by between -1 and 1, we would do

```
<transform>
<type>T</type>
<applyto>N</applyto>
<inc>+</inc>
<lower>-1.5</lower>
<upper>1.5</upper>
</transform>
```

Note that the range is specified as -1.5 to 1.5 to give each option -1,0,1 equal chance, since the number is rounded at the end.

The following transform makes a territory get thrown up in the air at the start of Round 20 - it will change by between -100% and 100% (note: a minimum of 1 army is always applied).

```
<transform>
<type>R20</type>
<applyto>A</applyto>
<perc>1</perc>
<amount></amount>
<lower>-100</lower>
<upper>100</upper>
</transform>
```

Conditions Example. The following Transform will only be applied if Territory 11 is Neutral OR Territory 32 is owned by the current player with an army size of 5 or more.

```
<transform>
....
<conditions>
<formula>COND_A OR COND_B</formula>
<condition>
<variable>A</variable>
<id>11</id>
<ownership>N</ownership>
</condition>
<condition>
<variable>B</variable>
<id>32</id>
<ownership>S</ownership>
<minvalue>5</minvalue>
</condition>
</conditions>
...
</transform>
```