XML Tutorial

[yeti_c]

Courtesy of Lack we have this very useful topic that should be of great benefit to many.

XML Tutorial


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"?>

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


Territories

Next we specify the territories on your map. Inside the map tag, include one pair of <territory> tags for each 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 this one is adjacent to. Coordinates is a list of the X and Y coordinates (in pixels) where the armies should be printed on the small and large maps. So a basic territory looks like this:

Code: Select all

<territory>
   <name>Alberta</name>
   <borders>
      <border>Alaska</border>
      <border>Northwest Territory</border>
      <border>Ontario</border>
      <border>Western United States</border>
   </borders>
   <coordinates>
      <smallx>90</smallx>
      <smally>90</smally>
      <largex>120</largex>
      <largey>111</largey>
   </coordinates>
</territory>

To define one way borders, like Inner Mongolia -> Mongolia, only list the territory that can be attacked as a border of the territory that cannot be attacked.

Code: Select all

<territory>
<name>Inner Mongolia</name>
<borders>
<border>Mongolia</border>
</borders>
</territory>

Autodeploy and Starting Neutrals

You can also add some optional tags to a territory. If you want an 'autodeploy' bonus to be added to that territory each round, add a <bonus> tag. If you want the territory to be initialized with a certain number of neutral armies, add a <neutral> tag. The Neutral tag should come after the <coordinates> tag for the XML validator to check it correctly. This XML will make Alberta start off with 10 neutrals but you'll get a territorial bonus of 3 if you conquer and hold it:

Code: Select all

<territory>
   <name>Alberta</name>
   <borders>
      <border>Alaska</border>
      <border>Northwest Territory</border>
      <border>Ontario</border>
      <border>Western United States</border>
   </borders>
   <coordinates>
      <smallx>90</smallx>
      <smally>90</smally>
      <largex>120</largex>
      <largey>111</largey>
   </coordinates>
   <neutral>10</neutral>
   <bonus>3</bonus>
</territory>

Killer Neutrals

If you want you can make these neutrals come back after someone takes the territory. We call these killer neutrals, which revert to neutral at the beginning of the occupying players turn. To make Alberta a killer neutral so that it goes back to being 10 after someone takes it you just change the neutral tag like so:

Code: Select all

<territory>
   <name>Alberta</name>
   <borders>
      <border>Alaska</border>
      <border>Northwest Territory</border>
      <border>Ontario</border>
      <border>Western United States</border>
   </borders>
   <coordinates>
      <smallx>90</smallx>
      <smally>90</smally>
      <largex>120</largex>
      <largey>111</largey>
   </coordinates>
   <neutral killer="yes">10</neutral>
   <bonus>3</bonus>
</territory>

(Of course in this example - the bonus will never be given)

To mimic long-range warfare, you can additionally give a territory a <bombardments> tag. Bombardments is a list of <bombardment> tags containing exact names of other territories that this one can attack. Bombardments differ from borders in that you cannot fortify to bombardments, and a successful attack leaves 1 neutral army in the opposing territory. For example, imagine that Great Britain had inter-continental ballistic missiles pointed at Australia:

Code: Select all

<territory>
   <name>Great Britain</name>
   <borders>
      <border>Iceland</border>
      <border>Scandinavia</border>
      <border>Northern Europe</border>
      <border>Western Europe</border>
   </borders>
   <bombardments>
      <bombardment>Indonesia</bombardment>
      <bombardment>New Guinea</bombardment>
      <bombardment>Western Australia</bombardment>
      <bombardment>Eastern Australia</bombardment>
   </bombardments>
   <coordinates>
      <smallx>267</smallx>
      <smally>84</smally>
      <largex>356</largex>
      <largey>104</largey>
   </coordinates>
</territory>

Continents

Next we must specify the continents on your map. Inside the map tag, before the territories, include one pair of <continent> tags for each continent. For each continent you'll also need to specify <name>, <bonus> and <components>. Components is a list of <territory> and <continent> tags containing exact names of territories and continents making up the continent. Usually you won't have continents inside continents so a basic continent looks like this:

Code: Select all

<continent>
   <name>Oceania</name>
   <bonus>2</bonus>
   <components>
      <territory>Indonesia</territory>
      <territory>New Guinea</territory>
      <territory>Western Australia</territory>
      <territory>Eastern Australia</territory>
   </components>
</continent>

These tags are mandatory, but you can add some optional tags to a continent. If you want the bonus to apply for partially held continents, throw in a <required> tag with the minimum number of components a player is required to hold to trigger the bonus. Furthermore, you can make one continent exclude others when a player holds them all by including <overrides> tags. Confused? Let's say you wanted to give 1 army for holding half of Oceania and 2 for the whole thing. Just having the following would give total of 3 armies when all of Oceania is held:

Code: Select all

<continent>
   <name>Oceania</name>
   <bonus>2</bonus>
   <components>
      <territory>Indonesia</territory>
      <territory>New Guinea</territory>
      <territory>Western Australia</territory>
      <territory>Eastern Australia</territory>
   </components>
</continent>
<continent>
   <name>Half of Oceania</name>
   <bonus>1</bonus>
   <components>
      <territory>Indonesia</territory>
      <territory>New Guinea</territory>
      <territory>Western Australia</territory>
      <territory>Eastern Australia</territory>
   </components>
   <required>2</required>
</continent>

We don't want the Half of Oceania to apply when the whole thing is held. So let's make Oceania override Half of Oceania:

Code: Select all

<continent>
   <name>Oceania</name>
   <bonus>2</bonus>
   <components>
      <territory>Indonesia</territory>
      <territory>New Guinea</territory>
      <territory>Western Australia</territory>
      <territory>Eastern Australia</territory>
   </components>
   <overrides>
      <override>Half of Oceania</override>
   </overrides>
</continent>
<continent>
   <name>Half of Oceania</name>
   <bonus>1</bonus>
   <components>
      <territory>Indonesia</territory>
      <territory>New Guinea</territory>
      <territory>Western Australia</territory>
      <territory>Eastern Australia</territory>
   </components>
   <required>2</required>
</continent>

A continent can have more than one pair of <override> tags inside <overrides>. You can achieve complex continent behaviours with creative use of overrides.


Objectives

Optionally, you can specify winning conditions for your map. An objective is a set of territories or continents that when held will give the player an early victory. A map can have several objectives and a held objective ends the game in both Assassin and Terminator games. In the case of a Terminator game points would be earned from all opponents who haven't been terminated. Suppose an objective is to hold Alaska, Greenland and the continent of Asia. The XML would look like this:

Code: Select all

    <objective>
       <name>Alaska & Asia</name>
       <components>
          <continent>Asia</continent>
          <territory>Alaska</territory>
          <territory>Greenland</territory>
       </components>
    </objective>


Putting it all together

Your final XML file should look something like this:

Code: Select all

<?xml version="1.0"?>
<map>
   <objectives/>
   <continents/>
   <territories/>
</map>

Random Notes

• Continent and territory bonuses can be negative.
• When multiple continents have the same name, the related log entries will be merged into one entry.
• Order is very important in xml, please follow the order in the last code snippet.

Many thanks to Lack again for whipping this up.

[yeti_c]

It's time to learn some new toys.

XML Tutorial 2

So you've played with everything in the original XML Tutorial and now you are bored? Well we've added some new toys. 2 of which I hid up in the original tutorial. The more complex ones I'm going to explain below.

Start Positions

Lets say we found that whenever someone starts with Asia they win. This isn't true and nearly impossible but just go with it. We want to make that impossible to do. One way we could do this is using the new start position tool. Start positions are contained in a tag called <positions> which contains multiple <position> tags. These position tags can contain one or more <territory> tags, like so:

Code: Select all

<positions>
   <position>
      <territory>Ural</territory>
   </position>
   <position>
      <territory>Afghanistan</territory>
   </position>
   <position>
      <territory>Middle East</territory>
   </position>
   <position>
      <territory>Siberia</territory>
   </position>
   <position>
      <territory>Irkutsk</territory>
   </position>
   <position>
      <territory>Yakutsk</territory>
   </position>
   <position>
      <territory>Kamchatka</territory>
   </position>
   <position>
      <territory>Mongolia</territory>
   </position>
   <position>
      <territory>Japan</territory>
   </position>
   <position>
      <territory>China</territory>
   </position>
   <position>
      <territory>India</territory>
   </position>
   <position>
      <territory>Siam</territory>
   </position>
</positions>

So in the above example we have 12 start positions. When the game begins these start positions will be split up randomly amongst the players. If there is a remainder, the territories of those start positions are dealt out in the same way as other territories (unless of course they are coded as neutral).

We can restrict the game engine to allocate a maximum of 2 postions per player as follows - any additional/leftover positions will be ignored and divided in the usual way:

Code: Select all

<positions max="2">
...
</positions>

Lets say now that we discovered that Middle East isn't a viable start position unless they have 5 armies and that Kamchatka is overpowered and needs to have 2. We can change the number of armies that start on a given territory as follows:

Code: Select all

   ...
   <position>
      <territory start="5">Middle East</territory>
   </position>
   ...
   <position>
      <territory start="2">Kamchatka</territory>
   </position>
   ...

If the nunber of starting positions is not evenly divisible by the number of players, the leftover territories will be dealt out in the usual way with 3 starting armies, rather than the number specified in the start position code.

I'm sure you can think of better ways to use this new code then that example.

Reinforcement Adjustment

As I'm sure all of you know, typically you get reinforcements every turn based on how many territories you own. You always get a minimum of 3 but you start to get more once you hit 12 for every 3. Now we have access to this and can change it to suit our needs. This is what Classic looks like in this xml by default:

Code: Select all

<minreinforcement>3</minreinforcement>
<reinforcements>
   <reinforcement>
      <lower>1</lower>
      <upper>42</upper>
      <divisor>3</divisor>
   </reinforcement>
</reinforcements>

Lets say we want to change it so you are only guaranteed 2. Then for the first 12 territories you gain 1 for every 2 you own. After that we want to make it so that you gain 1 for every 6. Now we can! It sounds complex but the code is easy:

Code: Select all

<minreinforcement>2</minreinforcement>
<reinforcements>
   <reinforcement>
      <lower>1</lower>
      <upper>12</upper>
      <divisor>2</divisor>
   </reinforcement>
   <reinforcement>
      <lower>13</lower>
      <upper>42</upper>
      <divisor>6</divisor>
   </reinforcement>
</reinforcements>

The minimum reinforcement must be a number greater than zero.

I hope you understood and enjoyed this explanation of the new xml. The other features hidden in the first tutorial that I added are killer neutrals, and continents inside continents. So read up on them in the previous tutorial and you'll know it all!

Random Notes

• I can't stress enough how important order is, if you have a complete xml with all the toys the tags must be in the this order:

Code: Select all

<?xml version="1.0"?>
<map>
  <minreinforcement/>
  <reinforcements/>
  <positions/>
  <objectives/>
  <continents/>
  <territories/>
</map>

• Also important is that if you put continents inside of continents you must put the inner continent by itself before the continent(s) you put it inside.

XML Testing / Mapmaker Tool

Once your XML has been finished, you can test it with finished map images using the Mapmaker Tool.

[Evil DIMwit]

Losing Conditions / Requirements
Losing conditions (technically known as 'requirements') are a form of objective that you must continue to hold in order to avoid being eliminated. If your 'requirement' objective is taken from you, then you will be instantly eliminated from the game. (You can think of this as a 'capture the flag' scenario).

Let's explain it in a bit more detail: The requirements are evaluated whenever you conquer/bombard a territory, nuke a country, or are hit by a killer neutral. So if you do not meet a requirement from the initial game drop you might have a chance to conquer it and become safe (although for the most part, the 'requirements' will be bundled up as starting positions). When you eliminate someone via requirement, it works the same as eliminating someone via nuke - you get their cards and it counts as terminator points. When you don't meet a requirement your remaining armies change to neutral.

Here are the technical details, for those that love the code:

The new <requirement> tag goes in between positions and objectives. If you have a complete xml with all the toys the tags must be in the this order:


Code: Select all

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




So, let's get on to how they work... In this example, in order to stay alive in the game you must hold 2 out of the 4 territories in Oceania:


Code: Select all

<requirement>
   <name>Two Oceanic Countries</name>
   <components>
      <territory>Jakarta</territory>
      <territory>Port Moresby</territory>
      <territory>Perth</territory>
      <territory>Sydney</territory>
   </components>
   <required>2</required>
</requirement>


It should be noted that you can include <continent> components as well <territory> components.

Similarly, lackattack has updated the game engine to respect <required> tags on objectives. For example, you can now do this:


Code: Select all

<objective>
   <name>Two Small Continents</name>
   <components>
      <continent>South America</continent>
      <continent>Africa</continent>
      <continent>Oceania</continent>
   </components>
   <required>2</required>
</objective>

When somebody is eliminated via requirement, the game log will look something like this:

MrBenn assaulted Canada from England and conquered it from lackattack
lackattack no longer holds XXX (name of the requirement)
MrBenn overthrew lackattack who has been eliminated from the game
lackattack lost 8 points
MrBenn gained 8 points