Data format for Clash of Civilizations

A specification document for the various data files in Clash of Civilizations

Table of Contents


Introduction

This document is intended as an on-line manual to allow the creation and modification of scenarios, and to allow the code developers to add to the game data files.
For scenario makers, make sure you check the very last section of this document, troubleshooting.

The term "tag" means a key word surrounded by angle brackets. For example:

<civilization>
is a tag.

Each tag is followed by data, then by a closing tag. The closing tag is identical to the opening tag except that the opening angle bracket is followed by a slash, so the closing tag for civilization is

</civilization>

Sometimes a tag has no data - the mere existence of the tag is sufficient. In this case only the opening tag is used, but with a slash at the end. An example occurs in the images file, in which

<example/>
indicates that this is an example.

The term "class" (borrowed from Java) has been used to describe the data generated by an opening and closing tag, and the data inside. If another matched set of tags occurs inside a class, it is called an inner class.

Developers please note that the correspondence between a Java class and a class as defined here as not exact. Many "classes" as defined here are actually Java primitives.

The directory structure

The base directory for the data files is the /class directory. The actual classes for the game are in the /class/game and its subdirectories.

The directories used by Clash of Civilizations are as follows:

/class/resources

This directory contains the basic files which specify the technology, military and such data, as well as containing an important list mapping image names.

The xml formats are given below.

/class/scenarios

These are the scenario files. There is an index file (scenarios.xml ) which gives basic identification information for each scenario. If a scenario is not listed in this file it will not be found by the program.

The xml formats are given below.

/class/images

This directory contains any general images used in the system. The images are button icons rather than the game specific tiles and units found in the tiles directory. Examples are locked.gif and unlocked.gif

These file are images only, there is no xml.

/class/tiles

This directory contains all the pictures used globally in the game. These are tile images (plains, mountains, and so forth), overlay images (towns, coasts, roads), resource images (mines, and similar things), and, in spite of the name of the directory, unit images.

These files are images only, the only other file is images.xml.

Inner classes

Inner classes are treated in a different manner to main classes. A main class is one whose tag is inside the <xml> ... </xml> bracketing, but not inside any other class. An inner class is one which is included inside an outer bracketing of another class (other than the xml one, which encloses everything).

Outer classes are read through an XML interface, and may have a different storage method from inner classes. The name of outer classes may be different from that of the corresponding Java class. Inner classes use the setting method of the enclosing class, which means they may be treated differently, in different outer classes, depending on what the outer class is.

As an example, the Victory class can be defined globally (in the scenario file), or it can be included as part of a civilization. The reason for this is that in a Punic Wars scenario, a victory condition like "exterminate all other civilizations" would work, however a victory condition like "occupy Rome" does not make much sense if the player is playing the Romans.

Under the files specification below, all the main classes that can be included in each file are listed. In each of the class specifications below, the inner classes allowed are specified.

Named classes

In some cases a class is specified in one place, but further information added in another place. In this case the extending specification should have an attribute naming the existing class. There are no examples in the present implementation.

General classes

Many of the class specifications in the Clash of Civilizations system can occur in more than one place. These general classes have the same format in both cases.

Location

This class defines a particular square by coordinates or by name. If both are present, it names the square and later references need the name only.

The tag is <location> for a normal square reference. In the case of a civilization the tag <start> (with the same syntax as location) defines the player's starting square if they pick that civilization.

Subtags are:
x the x coordinate of the square
y the y coordinate of the square
name possible name of the square (for example Rome). This can be used to name a square, the name can then be used to find the square. Map squares can be named in this way anywhere that coordinates are expected, and particular as outer classes in map or scenario files. This allows a square to be named (and located) once, and thereafter referred to by name, so if the location is changed while developing a scenario, the coordinates need to be changed in one place only

Where a reference to a location is made, using the name of the location, the syntax: 

<location>
  <name>actual name</name>
</location>
can be replaced by: 
<location>actual name</location>
This is purely a convenience which makes the scenario file look a little better. This abbreviation also applies to the start tag in a civilization.

Range

This class specifies the lower and upper coordinates of a rectangular range. Where this occurs, all the squares in the range will be affected (or checked).

The inner tags are:
x the first occurrence is the lower x coordinate and the second the higher x coordinate
y the first occurrence is the lower y coordinate and the second the higher y coordinate

Name list

This class defines a list of names to be used for various purposes in a scenario file.

The tag varies according to the context (see the scenario class ).

The only subtag is (with an abbreviation for the lazy):
name the name to add to the list
n this is an abbreviation for name

Scenario

Scenario data specifies the scenario specific data. Most of the data relating to a scenario is in the scenario file but as outer classes. The scenario class holds the material that does not fit well elsewhere.

The scenario (exactly one class per scenario file) has the <scenario> tag.

Inner tags are:
name the name of the scenario
description the description of the scenario
turn the start turn (calendar year) of the scenario
turnLength the length of a turn (number of calendar years) in the scenario
newnames a name list of names for new civilizations created in the course of the game
barbarians a name list of names for new barbarians created in the course of the game
visible If set, the whole map will be visible. Doesn't have a value, type <visible/>
noFogOfWar If set, there will be no fog of war. Doesn't have a value, type <noFogOfWar/>

Social Model

Social Constants

The tag is <social>

Subtags are:
minimumRiotProbability the minimum probability a riot must have before it is even considered: 0.0 means all riots will be considered, while a value of 1.0 means riots won't occur.
numberOfPoliciesBlockedTurns The number of turns during which the player can no longer change the policies after the ruler is murdered or a province capital has been conquered.
antidiscrimination Effects of anti discrimination feeling.
badpolicies Effects of bad policies feeling.
politicalchange Effects of political change (revolutionary) feeling.
poorwelfare Effects of poor welfare feeling.
replaceruler Effects of replace ruler feeling.
separatism Effects of separatism feeling.

Social effects

The tag is any one of the social effects tags. The effect of these tags is to specify for each cause which event can be triggered. If all are set to 0, no event will ever happen. Otherwise, the proportion between the various events will dictate the probability of each event happening. Note that the most likely events (first in the list below) are more likely to happen than the rarer (later) ones because of the minimumRiotProbability figure: If there is 20% of event severity and 0.1 (10%) minimum riot probability, the events are sorted and the first half of these are ignored, only the latter half has a chance of occuring.

Subtags are:
riot Weight of the riot event (most likely and harmless event)
rebelDuke Weight of the Rebel Duke event
murder Weight of the murder ruler event
revolutionaryForces Weight of the Revolutionary Forces Formation event
guerillaForces Weight of the Guerilla Forces Formation event
armyBetrayal Weight of the army betrayal event
militaryCoup Weight of the military coup event
independance Weight of the independance event (least likely and most harmful event)

Regime

The tag is <regime>

Subtags are:
name the name of the regime, eg Athenian democracy
description the description of the regime, to be shown in Encyclopedia
attractiveness the attractiveness of the regime (0.0 - 1.0, 1.0 is more attractive)
ruler the ruler influence in this regime (0.0-1.0)
human the human influence in this regime (0.0-1.0)
capital the capital influence in this regime (0.0-1.0)
ethics the ethics influence in this regime (0.0-1.0)
warfare them warfare influence in this regime (0.0-1.0)
privateproperty the private property preference in this regime (0.0-1.0)
socialpolicy the social policy preference in this regime (0.0-1.0)

Moral Code

The tag is <moralcode>. (Note this overlaps a bit with culturalprototype)

Subtags are:
aggressiveness the aggressiveness of the moral code
ethnictolerance the ethnic tolerance of the moral code
religioustolerance the religious tolerance of the moral code
individualism the individualism of the moral code

Ethnicity

The tag is <ethnicity>

Subtags are:
name the name of the ethnicity, eg Gauls
abbreviation an abbreviation to be used in the map, eg G. This abbreviation must be unique
religion the religion
socialclasses the social classes available for this ethnicity
culture the culture of this ethnicity

Ethnic Group

Association of an ethnicity with a population - a concrete example of a population. The tag is <ethnicgroup>

Subtags are:
name the name of the ethnicity, eg Gauls
population the number of peoiple of this ethnicity

Social Classes

A set of social classes available to an ethnicity. The tag is <socialclasses>

Subtags are:
socialclass details of a specific named social class social class name

Social Class

The tag is <socialclass>

Subtags are:
name the name of the social class, eg Aristocracy
value the proportion of the population (0 - 1) in this social class

Culture

The culture of the ethnicity. The tag is <culture>

Subtags are:
nationality The name of the civilization this ethnicity would like to belong to.
culturalprototype The cultural values of this culture

Cultural Prototype

Culture moral values. The tag is <culturalprototype> (Note this overlaps a bit with moral code)

Subtags are:
traditionalism Importance of tradition
nationalism Nationalism
landConnection The importance of the (sacred) land
importanceOfReligion How important religion is in this culture
corruption corruption
aggressiveness aggressiveness
ethnicTolerance The tolerance of other ethnic groups
religiousTolerance The tolerance of other religions
asceticism asceticism
individualism individualism

Religion

The tag is <religion>

Subtags are:
name the name of the religion, eg Nature spirits
moralcode the moral code (see moral code)

Technology Model

The technology model consists of technologies and activities. Activities are used to add research points to technologies. Technologies are used to enable the building of certain things, as specified in the files.

Technology Global setting

These are global parameters which specify how the technology model behaves.

The tag is <globals>.

Inner classes are:
growthrate overall growth rate
upkeep upkeep rate

Technology

Specifies the data about a particular technology.

The tag is <technology>.

Inner classes are:
name the name of the technology
description the description of the technology
tier tier (1-3) for this technology
growthrate growth rate
upkeep upkeep rate
helper inner class for helper technology
messages inner class for messages to be displayed as the tech progresses

Helper Technology

Specifies a helper technology .

The tag is <helper>

Inner classes are:
name the name of the helper technology
requirement The knowledge level required to be helpful (more than this value helps, less hinders)
effect effect
start If the helper tech knowledge is below that level, then the helped tech is not active and cannot be researched. Defaults to 0.

Technology messages

Specifies messages to be displayed as a technology grows in level.

The tag is <messages>

The only legal inner classes are one or more >namedlevel tags:

Named levels

Named levels specify a level and the corresponding messages.

The tag is <namedlevels>

Inner classes are:
level the value the technology must reach in order to display the message
name The name of the technology, which will be displayed as a short message.
message A more detailed message which will be shown if the player clicks to get details.

Activity

Specifies an activity to receive research points.

The tag is <activity>

Inner classes are:
name the name of the activity
description a description of the activity
recipient a recipient technology

Recipient Technology

Specifies a technology to receive research points.

The tag is <recipient>

Inner classes are:
name the name of the recipient technology
proportion the proportion it is to receive. Proportions will be summed and scaled so the total of proportions of all contributed technologies is 1.

Military Model

MilitaryConstants

Constants used in fights by the military model. The tag is <militaryconstants>

Subtags are:
healAfterFight the proportion (between 0 and 1) of casualties that heal after one tick of fight.
This represents wounded units. It is applied only to non losing sides (winners and ties), wounded and fleeing losers are lost forever. A 0 value will mean deadly fights, 1 means there will be no casualties for the winner.
damageDivider Divides all damage dealt in combat by that amount.
Big means long fights, little means fast and deadly.
distanceBetweenRanges Distance between the various ranges of fight (long, medium, short, melee).
Units have different strengths at various ranges (distance/attack values). The bigger the figure, the more fights will take place at long range. Note that high mobility elements reach melee range faster (if they want to) or are harder to get close with (if they prefer to fight from afar).
maxRoundsOfFight An integer parameter indicating how many computations are made in one tick of fight.
Each tick is made of that number of rounds at most. Increasing the number will mean longer and deadlier fights. It will also mean fights will be fought longer at close range. Note that increasing this indefinitely doesn't change many things, as all losing units eventually flee. Beware when lowering to decrease distanceBetweenRanges too if you don't want fights to be reduced to ranged skirmishes with no melee.
researchDivider Divide number of research points received from combat by this factor.
engineerDivider Defense provided by in-fields fortifications is equal to (number of engineers (units capable of Build order)) / this divider. Note fortifications are built only if manoeuvering phase has been won (thus generally requires elements with Skirmish order in order to succeed).

Unit

This is a military unit, consisting of a number of elements and named image, the tag is <unit>

Subtags are:
name the name of the unit, eg Phalanx
flavorText text to be displayed in the encyclopedia
description the description of the unit, shown when the unit becomes available
image the logical name of the imahe to be used (that is, the name specified in the images.xml file). It can be either a string or a technology dependant string. For example:
<image>Archer</image> or 
<image>
  <default>Archer</default> 
  <technology>...</technology>
</image>
element inner class specifying an element, with two inner inner tags:
the name of an element as, say, <name>Archer</name>
the number of these elements in the unit, for example <number>9</number> 
obsolete the name of the unit which renders this unit obsolete
forceObsolete if set to true <forceobsolete/>), then the unit becomes obsolete as soon as the obsoleting unit becomes buildable, even if it is not as efficient as this one.

Element

This is a military element, the tag is <element>

Subtags are:
name the name of the element, eg Warrior
flavorText text to be displayed in the encyclopedia
default the name of another, previously specified element to be used as the default for this element.
Example: This means all values of the element are set to the default element value. For instance if BigWarrior is a better version of Warrior, instead of repeating all the Warrior values and having to change them both in Warrior and BigWarrior, you can say that BigWarrior defaults to Warrior, and then override the one or two figures you're interested in.
category must be one of: foot, horse, wheel, lightwheel, track, coastal, naval, air()
manpower a number setting the number of people in this element
attack element attribute affects the amount of damage dealt.
defense element attribute reduces the amount of damage taken.
movement element attribute affects strategic speed.
distance element attribute affects both damage at non melee range and support fire.
armor element attribute reduces damage taken, can be countered by armorpen.
armorpen element attribute reduces opponent armor.
boardspace element attribute is the amount of personnel that can be carried by one personnel of this element (used for specifying transport ships capacity).
health element attribute
morale element attribute affects the chance to flee during a fight. Also, low morale elements will disband themselves earlier when severely damaged. Morale should be in a 0-20 value range, with 10 as an average.
mobility element attribute affects speed during combat, particularly speed at which the element can close range or stay at long range.
flankereffectivity element attribute affects the efficience of the element when flanking (outnumbering) opponent. Must be at least 1.
dispersion element attribute represents the dispersion of the element, which in turns determines its frontage in fights: An element with dispersion of 2 will face two elements of dispersion 1 in clsoe combat. Dispersed elements should have better defense against area attacks (bombs...)
cost cost of the element
order Allows the unit to perform given order. The orders used include: Attack, Garrison (no effect now), Skirmish (allows better deployment of units in early combat phase), Carry (to carry other elements), Build (to be able to build field fortifications, also means this element will try to avoid close combat), Support (means the unit can perform support fire and willl try to do so rather than fight hand to hand), Scout (allows better reconnaissance, giving an edge in combat scouting phase)
civilization optional. If present, only the civilization whose name follows can build the units containing this element. You can put several civilization tags to allow building by several civilizations.

Attribute

This is an attribute of a military element, various tags (such as attack and defence) use this class.

Subtags are:
value the starting value of the attribute
technology helper technology

Cost

This specifies the building cost of a buildable entity. The tag is <cost>

Subtags are:
food the amount of food required
production the amount of production resources required
services the amount of services required
decay The rate at which food/production/services put in the building decays.
training Cost of training the element by +1 on a 0-5 scale. Training is not used as of D7.
foodmultiplier the amount of food required computed as this value times the default element food cost
productionmultiplier the amount of production resources required computed as this value times the default element food cost
servicesmultiplier the amount of services required computed as this value times the default element food cost
trainingmultiplier Cost of training the element by +1 on a 0-5 scale computed as this value times the default element food cost. Training is not used as of D7.
upkeepfactor Fraction of the total cost to be paid each turn in otder to maintain the unit. If this price is not paid, unit will be at 25% firepower.

Wall

This is a wall, or fortification, enclosing and protecting a square, definition.

Subtags are:
name the name of the wall type
defense element attribute
armor element attribute
health element attribute
cost cost of the wall. Note it should have food = 0 and production = 4 times services right now because there is a single econ category to hold all walls costs. Changing the proportion will result in waste, putting food will never get the wall built.
sightrange Sight range of the wall. This range is the range in squares that the wall unveils (no fog of war). Note that only the integer part is taken into consideration.
image name of the image

Required technology

This is a technology required in order to be able to build the element. The tag is <requirement>

Subtags are:
name the name of the technology concerned
knowledge the required knowledge

Helper technology

This is a technology modifier for an attribute. The tag is <technology>

Subtags are:
name the name of the technology concerned
baseknowledge the starting knowledge required to help
knowledgeeffect multiply effect by this amount times (knowledge - baseknowledge)

Technology dependant String

This specifies a character string whose value varies with technology levels. There is no tag for this, as it is used to valuate some subtags, like image in Unit tag.

Subtags are:
default the default value of the string
technology One or many technology tags, each having three subtags, for the technology name like <name>Military Tactics</name>, the minimum tech level for it to have an effect, like <knowledge>15.0</knowledge>, and the value of the string, like <image>Archer</image>. The image tag is used because these strings will usually refer to image names.

Civilization

Each civilization has the <civilization> tag.

Inner tags are:
name the name of the civilization, eg Merovingian Empire
noun the noun used for the civilization, eg Rome
adjective the adjective used for the civilization, eg Carthaginian
selectable no data, if <selectable/> is present, the civilization is selectable by the human player, otherwise it is computer controlled only
victorymessage the message displayed if a human player wins with this civilization
defeatmessage the message displayed if a human player loses with this civilization
recruitment the proportion of the population in a square which will be available for recruitment into a military unit
dispersion the proportion of the personnel of a disbanded unit which will wander away and not join the population of the square
government the government of the civilization
highcommand the high command of the civilization
ai the artificial intelligence of the civilization
start a location the starting square if the Player selects this civilization
city a city in this civilization

Government

The government within the civilization. The tag is <government>

Subtags are:
name the name of the government, eg SPQR
province an inner class defining a province
ruler the ruler
regimename the name of the regime

Province

This defines a province name for a civilization. The tag is <province> and must occur within a <government> class.

Inner class is: <abbreviation>. Where there is no abbreviation the shortened form using just the <province> tag for the name may be used.

Subtags:
name the name of the province, eg Gaul
abbreviation the abbreviation used in the map
capital the name of the location of the capital
port the name of the location of the main port

These names and abbreviations are used when the map is defined.

Ruler

The ruler of a civilization. The tag is <ruler>

Subtags:
name the name of the ruler, eg Scipio
age the ruler's age
preferences the preferences of the ruler

Preferences

The preferences of the ruler of a civilization. The tag is <preferences>

Subtags:
ruler the preference for ruler
taxrate the preferred tax rate
civilrights the preferred civilrights level
ethnicdiscrimination the preferred ethnicdiscrimination level
religiousdiscrimination the preferred religiousdiscrimination level
slavery the preferred slavery level
foreignpolicy the preferred foreignpolicy level
privateproperty the preferred privateproperty level
socialpolicy the preferred socialpolicy level

High Command

The military high command of a civilization. The tag is <highcommand>

Subtags:
plan several plans dictating the military attitudes available to the highcommand, and the repartition of task forces between them.
army several armies
wall several walls

Plan

This adds a plan to the list of plans available to the highcommand. The tag is <plan>. Plans are used by the Artificial Intelligence to decide which orders to give a given task force. A plan is a military attitude (see militaryattitude) and a proportion. By specifying several plans at high command level, it is possible to tell the ai to execute several high level tasks, like offense and defense, and how much of their resources to spend on either.

Subtags:
attitude the name of the militaryattitude
proportion the proportion of resources to be spent on this attitude. This is a relative figure, the meaningful figure being the ratio comparison with the proportion of other plans.

Wall

This adds a wall to a civilization in a scenario. The owning civilization is the owner of the square containing the wall. The tag is <wall>

Subtags:
type the type of wall or fortification
size the size of the wall - the bigger the stronger
location the name of the location of the wall

Army

This adds an army to a civilization in a scenario. It is made of one or more taskforces. The tag is <army>

Subtags:
name the name of the army
taskforce a task force in the army
attitude the attitude this army obeys. If not specified, an attitude based on the highcommand plans will be used.

Task force

This adds a task force to an army in a scenario. A task force is made of one or more units. The tag is <taskforce>

Subtags:
name the name of the task force
location the name of the location of the task force
unit a series of units within the task force. It is a series of tags containing either just the name of the unit (Legion, Phalanx, ...) or scenario unit tags.

Scenario unit
A unit with some information beyond its type.

Subtags:
name the name of the unit used.
settlers the name of the ethnicity of settlers attached to the unit.
population the amount of settlers attached to the unit.
unitethnicity the name of the ethnicity of the unit personnel. Useful when disbanding the unit and to compute whether the unit will join in riots when a given ethnic group revolts.

Artificial Intelligence

The ai associated to a civ. IT will not be used if the civ is chosen by the player. The tag is <ai>

Subtags:
buildorders the building orders that this ai will have.
allvisible if set, means this ai will have explored the whole map. Useful if you want to give map knowledge to one articial intelligence in particular.

Building orders

The orders an ai will issue to build units. This provides a profile of the desired army. Orders will try to get an active army whose proportions of units map this profile. The tag is buildorders

Subtags:
militaryProduction A number between 0 and 1: The amount of production used on military units.
unitsProfile a profile by units, describing each unit the ai wants in its army. Use this or abilityProfile instead.
abilityProfile a profile specifying abilities rather than units. This profile will find units best fit to their role rather than relying on the unit names being hardcoded in the scenario file. This means units can change with time, which is not the case with unitsProfile.

Units profile

A profile of units to be built by the ai. Note this may allow to build units that shouldn't be buildable, so it would be better to use abilityProfile instead. The tag is <unitsprofile>

Subtags:
production A list of production tags. Each tag has two inner tags, order which is the name of the Unit, and level, which is a figure. The level fives a proportion. For instance if you have two production tags with levels 1 and 2, units will be built with twice as much cash used for the second unit.

Ability profile

A profile of units to be built by the ai. This tag allows to specify unit roles rather than units themselves. The ai will automatically find which unit it can build best fits the role. It will also not waste money on units it can't build.

Important:This is the only way to make sure the ai will handle reinforcements more or less correctly.

The tag is <abilityprofile>

Subtags:
production A list of production tags. Each tag has two inner tags, ability which describes the Unit, and level, which is a figure. The level fives a proportion. For instance if you have two production tags with levels 1 and 2, units will be built with twice as much cash used for the second unit.

Ability

A description of an ability a unit must meet. All possible units are run against this ability, and the one that fits best is selected. The ability is described by the subtags it has or doesn't have: All values are 0 by default (except name). Each subtag should be valued by a figure or left blank. Figures should be in range 0-2, most probably 1 will be the best used. This value is a weight. So for isntance attack = 1 and support = 2 means you want a unit which can attack, but it is much more important for it to be able to provide support fire. The tag is <ability>

Subtags:
name Name you give to this ability. A name will automatically be generated if none is provided. This is the only value which shouldn't be a figure.
attack Whether the unit should be good at attacking.
breach Whether the unit should be able to breach walls.
cost Whether the unit should be cheap. You'll often want to include this tag in addition to others in order to provide cost-effective units.
defense Whether the unit should have good defense.
movement Whether unit should have a high strategic movement value.
support Whether the unit should be able to provide support fire.

City

This adds a city to a civilization in a scenario. The owning civilization is the owner of the square containing the city. The tag is <city>

Subtags:
name the name of the city
image the logical image to display
location the name of the location of the city
capital no data, use <capital/> if this is the capital
ethnicgroup one or more ethnic groups in the city

Diplomatic Model

There is a large variety of data that can be set within the diplomacy model. (Well, not right now, but there will be.)

Diplomatic Statuses

This allows the scenario designer to set the initial diplomatic statuses between the civilizations in this scenario.

While it is not required, it is highly recommended for the sake of clean and correct code to include all the diplomatic statuses within the <diplomaticstatuses> tag.

The tag for one diplomatic status is <diplomaticstatus>

The Inner classes are as follows:
civilization Specifies the name of a civilization involved. There should be exactly two instances of this tag. The reason being that there are two civilizations bound by any diplomatic status. If only one <civilization> tag is supplied, then the data is useless. If more than two are supplied, the status is considered to bind the first two civilizations.
strength A string representing the status, can be any one of the following three values (case independent):
  • war
  • peace
  • alliance

Example: 

<diplomaticstatus>
    <civilization>Rome</civilization>
    <civilization>Carthage</civilization>
    <strength>-1</strength>
</diplomaticstatus>

This XML construct tells the game that the diplomatic status bewteen Rome and Carthage is War.

The pairs of civilizations, for which the diplomatic status is not specified, will be assigned the default status of No Contact.

Squares

The characteristics of a square can be set using the scenario file outer tag <square>

The inner classes for this tag are:
location the name of the location of the square
x The x coordinate of the square -don't use if you used location
y The y coordinate of the square -don't use if you used location
terrain the map terrain of the square
province the province name of the square
people an ethnicity to add to the square, inner classes are <ethnicity> (with the name of the ethnic group) and <population> (with the population)

Note that the map may overwrite these values if the map tag comes later in the scenario file. Similarly the square tag will overwrite the map it it comes after the map tag.

Map

The map is an outer tag for the scenario file. It is designed to set the various factors for the map squares. This is the format for a file which defines a map. The name of the map must be specified within each <scenario> class in the scenario file. The only outer class (apart from possible locations at the start) in this file has the tag <map> which includes all the inner classes described below. Since some inner classes are complex, each has its own heading, rather than merely a table entry.

The width, height, and, for each row in the map a row tag, are compulsory (though a terrain could be specified using the square tag for each square in the map, this is unlikely to happen).

Width

The width inner class must be at the start of the map class and specify the width of the map. Width and height may be in any order.

Height

The height inner class must be at the start of the map class and specify the height of the map. Width and height may be in any order.

Map Terrain

Each row of squares in the map must have a tag <row> which specifies the actual terrain for that row. The row is represented by a string containing terrain abbreviations, one for each square in the row.

Currently available terrain (see the terrain.xml file) are, with their abbreviations:

Map roads

This inner class defines any existing roads at the start of the scenario. The tag is <roads> , and there must be one for each map row. Each row consists of a string of characters which must be "-", where there is no road, or "r" where a square has one or more roads. Where adjacent squares both have the "r" marker, a road will be built connection them.

Map provinces

This inner class defines the owning provinces for the map squares. The tag is <province> , and there must be one for each map row, each row cosisting of a string of province abbreviations. A square which does not belong to a province should have a hyphen or minus sign (-).

Map population

This inner class defines the ethnicity and population contained in each map row. The tag is <population> , and there must be exactly one for each map row. A square which does not have a population should have four hyphens or minus signs (----) as its entry.

Otherwise the entry for a single square should be four characters:

  1. An abbreviation for an ethnicity
  2. The high order digit of the population
  3. The next digit of the population
  4. The number of zeroes to add to the population value
The length of the string is thus four times the width of the map.

This system allows only a single ethnicity per square, however, others may be added using a square tag for individual squares.

Map economic special sites

This inner class defines the economic special type (gold, tin, cloth, by first initial) and corresponding number of sites contained in each map row. The tag is <economicsite> , and there must be exactly one for each map row. A square which does not have an economic special site should have four hyphens or minus signs (----) as its entry.

Otherwise the entry for a single square should be four characters:

  1. The first character of the special name (Eventually will be able to specify the character for each special to avoid the salt or silver problem with S)
  2. The hundreds digit of the number of sites
  3. The tens digit of the number of sites
  4. The ones digit of the number of sites
The length of the string is thus four times the width of the map.

This system allows only a single economic special per square, which should be sufficient.  The delenda scenario has an example (MPE 20030108)

Feature

This adds a feature to a square. The tag is <feature>

Subtags:
name the name of the feature
image the logical name of the image to use
location the name of the location of the army

Economics Model

There are four main types of information that need to be initialized in the Clash economy

1. GoodsInfo contains basic information on the goods (Commodities) in the economy, like Food
2. SectorInfo has a number of parameters that influence production and cost of kapital in an economic sector, like the farming sector>
3. InfrastructureInfo covers infrastructure types in the economy, like how much investment there is in tools in the farming sector, or educational capabilities
4. GovtEconOrdersInfo covers orders the govt can issue to build infrastructure. It includes a hierarchy of classes like "military" for organizing orders

These four main tags are all necessary for FE handling Food, and producing it in the farm sector as shown in the substantial snippet from economics.xml below.  Not all economic aspects will have all four parts.  See the economics.xml file for some examples.

<!-- Food and Farming -- this information is required to be present, although parameters can be changed>
<goodsinfo>
  <goodname>Food</goodname>
  <basicgooditbecomes>Food</basicgooditbecomes>
  <goodconversionrate>1</goodconversionrate>
</goodsinfo>

<sectorinfo>
  <sectorname>farm</sectorname>
  <sectoroutputname>Food</sectoroutputname>
  <!-- The tech activity to which farming production RPs go >
  <techactivityname>Food</techactivityname>
  <!-- the technology upon which farm sector productivity is based, for now only a single tech useable>
  <techforproductivity>Farming</techforproductivity>
  <yieldx>1</yieldx>
  <lowtechlaborexponent>0.70</lowtechlaborexponent>
  <lowtechsitesexponent>0.20</lowtechsitesexponent>
  <lowtechkapitalexponent>0.10</lowtechkapitalexponent>
  <hightechlaborexponent>0.50</hightechlaborexponent>
  <hightechsitesexponent>0.30</hightechsitesexponent>
  <hightechkapitalexponent>0.20</hightechkapitalexponent>
  <lowtechcostf>0.30</lowtechcostf>
  <lowtechcostp>0.50</lowtechcostp>
  <lowtechcosts>0.20</lowtechcosts>
  <hightechcostf>0.30</hightechcostf>
  <hightechcostp>0.50</hightechcostp>
  <hightechcosts>0.20</hightechcosts>
</sectorinfo>

<infrastructureinfo>
  <buildableinfrastructure>
  <name>farm kapital</name>
  <cost>
   <persistent>true</persistent>
   <food>0.30</food>
   <production>0.50</production>
   <services>0.20</services>
   <decay>0.05</decay>
  </cost>
 </buildableinfrastructure>
</infrastructureinfo>

<govteconordersinfo>
  <ordertypename>farm kapital</ordertypename>
  <orderclass>kapital</orderclass>
</govteconordersinfo>

WHEN EDITING pay close attention that names match as they do above.  FE the sectoroutputname "Food" in sectorinfo must match the goodname "Food" in goodsinfo.  Also the infrastructureinfo names are the sectorinfo name with " kapital" appended.  I will introduce a more nuanced system at some point, but probably not for quite a while. 

Background on how the Clash economy works can be found on the Economy page on the Clash Web Site.

-Mark  (Feb 22, 2003)

GoodsInfo

This adds information about a type of good (commodity) like food to the economy. The tag is <goodsinfo>

Subtags:
goodname the name of the good, FE Food
basicgooditbecomes All special goods, like gold are converted into one of the four basic goods (Food, Resources, Manufactured Goods, and Services).  This tag specifies the basic good to which a special commodity is converted.   The basic goods simply have themselves entered as  <basicgooditbecomes>.
goodconversionrate Sets the rate of conversion for a good into the basic good it becomes.  This rate is only used for small amounts of a special good, and decreases for larger amounts.  For the four basic goods this value should be set to 1.0.



SectorInfo

SectorInfo contains all possible sector types (like the farm sector, services sector) that economies in the game might have. The tag is <sectorinfo> .  SectorInfo contains the information needed to set the good that the sector produces, effects of tech upon the sector and vice versa, determine production function exponents, and the cost of buying a point of capital at various gross levels of technology.

Subtags:

sectorname the name of the sector of the economy, FE farm,
sectoroutputname the good that the sector produces, FE Food
techactivityname sets tech activity to which RPs from this sector are sent, FE Food (which shows in the econ gui as "Food Tech")
techforproductivity sets the technology that productivity in this sector is based upon.  For now each sector can only be based on a single tech.  FE Farming
yieldx yield multiplier used in the production function that determines production in the sector.  For most sectors this is one, but since production has 2x yield (because it requires another sector's output [resources in this case] as its input) this will be  2.0 for prod - perhaps others later
lowtechlaborexponent Labor exponent used in production function in this sector for a subsistence economy.  
Sum of  low tech exponents for labor, sites and kapital must = 1.0 or the production function will have odd scaling properties with size of economy that are best avoided.
lowtechsitesexponent Sites exponent used in production function in this sector for a subsistence economy.
lowtechkapitalexponent kapital exponent used in production function in this sector for a subsistence economy.  Kapital (capital) is investment put into an economic sector.  Buying tools for farms is one example of increasing kapital in the farm sector.
hightechlaborexponent Labor exponent used in production function in this sector for a modern economy.  
Sum of  high tech exponents for labor, sites and kapital must = 1.0
hightechsitesexponent sites exponent used in production function in this sector for a modern economy.
hightechkapitalexponent kapital exponent used in production function in this sector for a modern economy.
lowtechcostf Proportion of kapital (capital) cost investment for the given sector in a subsistence economy that requires Food (f)
Sum of  low tech cost for food (f), production (p) and services (s) should  = 1.0 for the system to function reasonably, although it is not as critical as for the exponents above.
FE if you have: lowtechcostf = 0.2; lowtechcostp = 0.3; and lowtechcostp = 0.5 a purchase of one unit of kapital in the sector will cost 0.2 units of food, 0.3 units of  Manufactured Goods, and 0.5 units of Services
lowtechcostp Proportion of kapital (capital) cost investment in a subsistence economy that requires Production (p) [aka Manufactured Goods]
lowtechcosts Proportion of kapital (capital) cost investment in a subsistence economy that requires Services (s)
hightechcostf
hightechcostp
hightechcosts
 Proportion of kapital (capital) cost investment for the given sector in a modern economy that requires Food (f), Production(p) or Services(s)
Sum of  low tech cost for food (f), production (p) and services (s) should  = 1.0 for the system to function reasonably, although it is not as critical as for the exponents above.
siteabbreviation Single Character that represents sites for this sector when read in from scenario file.  These are currently only needed for special goods since sites are set for basic commodities elsewhere.  Use first letter of sector when possible, but almost any character, FE '1' can be used if necessary.  Abbreviations are used in setting the Map economic special sites .


InfrastructureInfo

InfrastructureInfo contains basic information on infrastructure types: what they are called, and the information needed to determine their game function.  Infrastructure is just at its simplest a storage container.  Whether the storage is food, education, or pieces of a trireme the approach
is similar, at least as coded for now. The tag is <infrastructureinfo>

At present this tag will always contain a single BuildableInfrastructure, seen immediately below.

BuildableInfrastructure

BuildableInfrastructure implements the Buildable interface for use on infrastructure types associated with economic function, FE "farm kapital".   BuildableInfrastructure is used by InfrastructureInfo to specify if an infrastructure improvement is buildable in a particular location, and what its Cost is. It also happens that at the moment it contains all the information necessary to specify a given infrastructure type, which is why it is used in the xml. The tag is <buildableinfrastructure>

Subtags:

name Name of the BuildableInfrastructure, will also apply to the InfrastructureInfo.  FE "farm kapital"
cost The cost associated with building a point of this infrastructure.  The only parameters of cost generally used here are persistant, food, production, services and decay.  Generally food + production + services = 1.0 should be maintained, although no great stability problems will be caused if this constraint is violated.


GovtEconOrdersInfo

GovtEconOrdersInfo contains basic information on each type of  infrastructure build order, what they are called, and other orders they may mask (override).  Most of the contents are for classifying orders so that they can appear in the right context in the current and future Econ GUIs.  Also specifies whether an order type should be shown in the GUI.  The tag is <govteconordersinfo>

Subtags:
ordertypename Name of the specific order type, "Phalanx" or "farm kapital". FE salt mine kapital
orderclass High-level type of order, FE kapital.  Currently the list of high-level classes is restricted to the following.  Examples of all are available in econmics.xml.
  • military,
  • civilian,
  • kapital (investment in a sector -- technically civilian, but important enough for its own class),
  • special (investment in a special commodity sector,
  • tech activity (these are auto-generated from the tech information, so you shouldn't ever have to use this category)
  • stub (this is a utility designation that will be described below.
ordersubclass (optional) Sub-class of the order, like "army unit" is a subclass of "military" (default is "").  Look in economics.xml to see what the valid sub-classes are for each high-level class.
hidden (optional) Identifies which orders are hidden (not shown in GUI). FE true.  (default is false, meaning orders are shown)
ordertypeitmasks (optional) not implemented yet  FE "gold mining kapital" masks "Special kapital", if we invest specifically in gold mines here, then we won't apply any overall government spending in any Special commodity production areaFE Special kapital (default is false)
genericorder (optional) Generic orders are blanket orders like "invest in any Special".  They order investment of the size specified for ANY order of the same class and subclass that is valid locally.  FE see the "Specials kapital" order in economics.xml.  It invests in any special commodity sector (gold, tin, cloths, salt. . .) present.


Hiding Orders in the GUI

Normally orders are designated as hidden in the using the "hidden" tag during definition of the <govteconordersinfo> object.  However for military units and tech activites the order information is generated automatically based on the information in the respective .xml files.  These orders can be specified as hidden using tje "stub" order class.   The stub category allows for setting the "hidden" parameter (whether the order should be hidden from the player in the gui) either before or after a GovtEconOrdersInfo object is created by another part of the xml initialization.  This allows a simple way to ensure that FE a Tech Activity cannot be invested in by the player, since if it  is hidden from the GUI the order to invest in that Activity cannot be given.  Below is an xml snippet showing how to hide non-economic orders.

<!-- Order Presence in GUI>
<!-- Demonstration of a "stub" order that sets the flag for an order being hidden in gui>
<!-- In this case the order "Combat Tech" for the Combat Activity is not shown in the gui>

<govteconordersinfo>
  <ordertypename>Combat Tech</ordertypename>
  <orderclass>stub</orderclass>
  <hidden>true</hidden>
</govteconordersinfo>

Merchant

This adds a Merchant to a Location. The tag is <merchant>

The delenda scenario has an example (MPE 20030108)

Subtags:
location the name of the location for the merchant
cash the starting capital of the merchant

Event Model

Event

This specifies an event which may happen in the course of the game. The tag depends on the particular event. Any event may contain actions which are carried out when the event takes place. Any event can contain any action as an inner class. In addition, any event can contain a <centerview> tag which itself can contains a location (the location tag is not needed, the centerview class is itself a location), or a string which is the name of a location. When the event is triggered, the map view is centered on that square.

The tag depends on the actual event.

There are several classes of event. In particular there are general events, civilization events, location events (which are also civilization events). They are described in separate sections below.

In addition to the inner tags listed in these tables, every event can have <action> tags.
afterturn this has an integer parameter, and disables the event from being tested until after the turn specified by the integer
cancelcondition this has a string parameter, the name of a condition which cancels this event
cancelturn this has an integer parameter the turn on which to cancel the event
centerview this is an action which centers the view on the given <location>, it is listed here, rather than with the actions because it always occurs first, before any other actions
name this gives the event a name so some actions can refer to it
negative this reverses the sense of the event test, so that the event is fired if the condition is not met

General event

These events occur without being affected by any particular civilization or square. The tags are:
turnevent event fired at the end of the turn specified
yearevent event fired at the end of the year specified
eventjoin contains a series of inner events (any from this table), is fired if any of the inner events has occurred
eventunion contains a series of inner events (any from this table), is fired if all of the inner events has occurred
eventnegativejoin contains a series of inner events (any from this table), is fired if any of the inner events has not occurred
eventnegativeunion contains a series of inner events (any from this table), is fired if all of the inner events have not occurred

Civilization event

This type of event affects a specific civilization, though in some cases if the civilization is missing, any civilization can fire the event. In other cases the civilization is mandatory. The tag to specify the civilization is (not unexpectedly) <civilization>. This tag will be recognized by all civilization and location events. The events are:
buildunitevent event fired by building a particular type of unit.The event should have inner class <unit> (the unit archetype name). <civilization> is optional.
civilizationsizeevent event fired if the civilization reaches the <size> given in the inner tag
conditionevent event fired if the condition <condition> exists. <civilization> is optional.
destroyarmies event fired if the civilization has no armies. <civilization> is mandatory.
technologyevent event fired if the technology <technology> has reached the <level> (level is a floating point number). <civilization> is mandatory.

Location event

These events allow a civilization (unless otherwise indicated in the table) and one or more locations or ranges. There must always be at least one location for each event.
controllocation event fired if any location is controlled. If the civilization is specified, it must be the controlling civilization. If the civilization is not specified, any civilization will fire the event.
isfoggedevent event fired if any location is either hidden by the fog of war or visible (typically fired when it is first seen). The civilization is automatically that of the player. Since a unit may move 2 squares at once before events are checked, I want the event to be triggered when the location first becomes uncovered.
isvisibleevent event fired if any location is visible. The civilization is automatically that of the player.
settledevent event fired if the civilization settles any of the locations.
singlevisitevent event fired if the civilization eneters any of the locations
unitcountevent event fired if the civilization, in any of the locations, has a unit count equal to the integer parameter of the <count> tag
zeropopulationevent event fired if any of the locations zero population. Civilization is not used

Action

This specifies one of a number of possible actions triggered by an event .

The tag depends on the actual action:
activateevent activate an event. Inner classes are <event> containing the name of the event to activate, and an optional <delay> which has an integer parameter giving the number o fturns before the activation is to take effect
bulletin display a series of HTML formatted bulletins. Inner classes are:
  • <title> (the title at the top of the bulletin)
  • <message> (the text in HTML format; it must be enclosed in double quotes if it contains inner tags such as <p>)
  • <x> (optional x-coordinate of the box, default is centered)
  • <y> (optional y-coordinate of the box, default is centered)
  • <width> (optional width of the box, default is 450)
  • <height> (optional height of the box, default is 400)
  • <remove> (remove the bulletin with the given title from the list)
Each message inner class creates a new bulletin, with the most recent title, x, y, width and height
displayaction display a message immediately. The action should have inner classes <title> and <message>
enabletechnology set a technology to active. Inner class is any <technology>
eventaction set a new turn event in the future. The event can only set a named condition. Inner classes are <delay> (the number of turns to delay) and <condition> (the named condition to set)
giveresearch set a technology to active. Inner classes are any <activity> and <amount>
removeeevent remove an event. Inner class is <event> containing the name of the event to activate
removefeature remove the named feature from its square. The name of the feature to be removed should be given in an inner <feature> class
savecondition save a condition or series of conditions. Inner class is any condition. It is always a named condition
units create a new task force. Inner classes are <location>, <civilization>, this special inner class is described below, <militaryattitude> (random choice if missing), and one or more of <unit> naming the archetype to use
productionaction Changes the production orders for a civilization. Inner classes are <civilization> (name of the civilization), a list of <productionorder> giving the actual orders, and a <replace/> tag if the orders are not in addition to existing ones, nut to replace them.
addpopulationaction Changes the population in a square. Inner classes are <ethnicity> (name of the ethnicity), <population> (amount of people to add), and <location>

ProductionOrder

The productionOrder has two inner tags, both mandatory: <level> which must be between 0 and 1, is the proportion of resources to be spent, and <order> is a string giving the name of the order to be executed.

Civilization

The <civilization> inner class is different from the main <civilization> class, though it has much in common. If the parameter is a single string, that is taken as the name of a civlization previously defined (in the scenario file). If, on the other hand, it has inner inner classes, it defines a new civilization. The inner classes are:
name the name of the new civilization
adjective the adjective describing the new civilization
description description of the new civilization

Condition

This is essentially a record that an event has taken place. It is stored by a save condition action . It may be checked later for various purposes. Each civilization has its own list of conditions, and there is also an overall list. Which list a condition is posted to depends on the save condition action which created it.

Conditions are identified by their name. The name is the only characteristic it has.

The tag is <condition> and the only parameter is the name.

Victory Model

Victory conditions

This determines the victory conditions for a scenario. The class is always defined in the scenario file (only), but can be "global" (not an inner class) so it refers to all civilizations, or within specific civiliations as an inner class. The <win> inner class has the name of a condition as its parameter, as has the <lose> inner class. If the condition is met then a win or lose ending takes place. The lose condition is checked first. If exterminating all others is a victory condition, the tag <extermination> should be included.

The tag is <victory> and the <win>, <lose> and <extermination> are the only inner classes, though <civilization> is allowed.

The <victory> tag can occur inside a civilization class (in which case the <civilization> tag should be omitted). If the <victory> tag is not in a civilization class and no civilization is specified, the win or lose conditions are global.

A game is always lost if the player's civilization is wiped out.

Resource files

Each file has a different purpose and a different format. The files are: The first two are global settings, and apply to all scenarios. They relate to drawing the map and the units, and the physical characteristics of the terrain.

Scenario files are kept in the scenarios subdirectory.

Images file

This file, images.xml is located in the class/tiles directory. It assigns logical names to image file name, so, if the imafe file name changes, it needs to be changed here, not in every reference to it. All other files use the logical name, not the actual gif or jpg file name.

This file specifies the size of the tiles used, and assigns logical names to the tiles. The <mapparameters> tag specifies the size of the images used. The size includes width, height and inter tile height, the latter being typically 2/3 of height and half of width. It must have the following inner tags:
tilewidth the width of terrain images
tileheight the height of terrain images
intertileheight the height between tiles (less than the tileheight to allow pseudo 3D terrain)

This file allows a tag which assigns a logical name to an image. An image that is not listed in this file will not be recognized by the program.

One class, not used anywhere else, is used in this file. The tag is <image>. Each image code MUST have both of the following inner tags:
name the symbolic name of the image
gif the actual file name, inluding an extension of .gif or .jpg or .jpeg

Terrain file

This file, terrain.xml , is located in the class/resources directory. It specifies the terrain, and associated images, available in the game. The various caharacteristics of the different types of terrain are also specified.

A single class, not used anywhere else, is used in this file. The tag is <terrain>. Each terrain must have the following inner tags (unless marked as optional):
name the type of terrain, for example flat mandatory
abbreviation an abbreviation for the name, used in maps optional, but always present
image the symbolic name of the image to use mandatory
rougher the type of terrain, for example flat optional
movement a floating point number giving the movement multiplier for this terrain mandatory
roadcost the cost of raod building if roads are possible
mobilityMalus the malus to mobility on this terrain - also decreases attack strength. mandatory
category a troop category optional, defaults to 1.0 if missing
farms the default number of farms in the terrain optional
resources the default number of resources in the terrain optional

Category

An inner class for the terrain class. It specifies the movement multiplier for the different categories of troops. Available categories are: The tag is <category>

Inner classes are:
name the type of category, from the list above
movement a floating point number giving the movement multiplier. If this is missing the category cannot enter this terrain
mobilityMalus the mobility malus for this category on this terrain.

Military attitude file

This file specifies the different, possible, military attitudes, and the probability of each possible computer generated order for each military attitude. For each attitude the tag is <militaryattitude>

The inner tags are:
name the name of the military attitude
random weighting factor for this attitude if an attitude is randomly selected
owncapital probability of moving to own capital
owncity probability of moving to nearest own city
owncity probability of moving to nearest own square
ownarmy probability of moving to nearest own army
wait probability of doing nothing
enemycapital probability of moving to enemy capital
enemyprovince probability of moving to enemy nearest province's capital
enemycity probability of moving to nearest enemy city
enemycity probability of moving to nearest enemy square
enemyarmy probability of moving to nearest enemy army
merge probability of merging with another TaskForce in the same square, or waiting if no taskforce is available. Important for the ai to be able to do some correct attacks later.

The military attitude file also contains constant ai data, enclosed in the tag <AIConstants>
breachFactor This number represents how many times the defenders' strength the ai will try to put when attacking a besieged city. By default, worth 1.
aiConfidence This is the confidence the ai has in a single fight simulation. When the sum of confidence for simulated fights reaches 1, no more simulations are needed. The smaller te number, the more the ai will ponder. Default value is 0.4.
MaxTaskForcesInSquare Over this number, the ai will always consider mergeing idle task forces in the same square rather than giving them other orders.
moveBeforeReinforced This is a multiplier applied to the 'none' order weight to the task forces that await reinforcements.

The military attitude tag can also be placed in the scenario file.

Scenario file

This is the format for a file which defines a scenario. The name of the file is the short name of the scenario, with an extension ".xml". A number of outer classes may occur in the scenario file. In particular all the following tags are permitted as outer tags in the scenario file, the preferred order being as specified:

Gameconcepts file

This file contains a set of entries that provide help on game concepts. All entries use the tag <entry>, and have three inner tags, <name>, <description> and <flavorText> which are strings.

Default files

In each scenario, you can specify default files. These may be needed in order not to duplicate information or reinvent the wheel.
Default files will be used if specified, using a <files> tag. Note that you should be careful not to define military elements in a scenario file which default to elements defined in another file (military.xml). This is because each file is parsed in its own thread, and that can cause some problems as you have no idea in what order they will be processed.
The files tag, if used, means that either <all/> resources files are read, or only those indicated in between the opening and closing files tag.
It is also possible to provide a name to the files, instead of the default one. For instance using <military/> is actually the same as using <militaryFile>/resources/military</military>. Note that the file names should be in the base Clash directory, and file separator is a forward slash: "/", and that the file should be a .xml file corresponding to the format defined herein.
Files include:

Troubleshooting

Things may not work when running the game after modifying scenario files.
Here are a few reasons why things won't go well: