File Formats Explained

The following page will contain details of the WarFoundry XML file structure in plain English. If you just want to view the schemas then please look at the source code viewer. Details of the rest of the file format (e.g. the Zip file that contains the XML) are in the main file format page.

Game Systems

The Game System schema defines the basics for a game system.

Game System Basics

Each game system must have an ID that race definitions for a system reference, as well as a name. Game systems may or may not support allies (a future feature) and may or may not warn users about validation errors (a ​Games Workshop imposed requirement for army builder).

Categories

Each game system defines a set of categories that units must be in, with each category having a limit on either the maximum and minimum number of points or the maximum and minimum percentage of an army's total that must be taken in that category. Armies may optionally override the categories in their own definition, for example where an army has a non-standard organisation compared to the rest of the game system.

Stats

The game system defines one or more stat lines in terms of the columns the stat line contains. One stat line must be declared as the default, although multiple stat line formats can be declared.

Races

The Race schema defines the structure of the race files. Race files define the units and equipment that can be taken in an army of a given race. Each race must be part of a game system and each army must be of a race.

<race>

A race defines an id and a subid. These are used to differentiate between races definitions. The subid can be used to define sub-races, either official sub-'races' like Black Templar Space Marines (who are still Space Marines, but have their own units) or unofficial sub-races such as campaign-specific versions with additional restrictions.

Each race also defines its name, which is shown to the user, and the ID of the game system that it is part of.

<units> and <unit>

The <units> tag is a container for <unit> tags. Unit tags define everything about a unit, including equipment, statistics, limits on the number of troops in the unit (min/maxSize), limits on the number of times the unit can be taken (min/maxNum), and other additional data.

<stats> and <stat>

<unitEquipment> and <unitEquipmentItem>

The <unitEquipment> tag is a container for <unitEquipmentItem> tags. unitEquipmentItem tags define the equipment that a unit can take by referencing an equipment item in the main list.

• id - the ID of the equipment item in the main list
• required - whether the item must be taken by the unit (e.g. swords for swordsmen)
• exclusivityGroup - currently a single string, but will be multi-valued. Defines a "group" where only one item from the group can be taken at once
• minNum/maxNum - the minimum and maximum number of times an item can be taken by each instance of the unit
• minPercentage/maxPercentage - the minimum and maximum percentage of the unit who can be equiped with the item
• roundDirection - defines whether to round the number of items taken up or down if a min/maxPercentage limit for a unit doesn't reach a whole number (which is likely to be a common occurrence). Used in situations such as Lord of the Rings where "up to one third of the unit, rounding up, can take bows".
• costMultiplier - the multiplier of the base price for the equipment item. Useful to allow units to get equipment (e.g. swords) for free but charge champions the full price, or where a unit type (e.g. goblins) get the equipment for half-price.
• costRounding - how to round any fractions of prices for the total cost of the equipment (especially when multipliers are in place). Can be up, down, ​Banker's rounding (rounding to the closest whole with a bias towards the even number for halves), up to a half, down to a half, or 'Banker's half rounding' (rounding to the closest half with a bias towards the whole for quarter values)

<unitAbilities> and <unitAbility>

The <unitAbilities> tag is a container for <unitAbility> tags. unitAbility tags define which abilities/skills a unit has. As of 25th September 2009 they are loaded by the API but not used in the UI. Each unitAbility has the following attributes:

• abilityID - a reference to the ID of the ability defined later in the file
• required - a boolean that determines whether the ability is always taken by the unit (an innate ability) or whether it is optional (a training/doctrine)

<requirements>

Currently unused. The requirements will define data that is used to trigger requirement calculations.

<contains> and <containedUnit>

Currently loaded but unused. Allows a unit to define units that it "contains", either champions (who are sometimes separate entities, but are part of the unit) or to represent detachments and sub-units.

<extraData> and <data>

Currently unused, but useful for a variety of purposes. Can contain additional notes (e.g. design text) or data used by requirement calculations.

<categories>

Overrides the default categories from the game system. The definition is the same as for the game system.

<equipment> and <equipmentItem>

The <equipment> tag is a container for <equipmentItem> tags. The equipmentItem tags define the equipment available to the race as a whole. Units reference the equipment items through unitEquipmentItem tags. Attributes of the equipmentItem are:

• id - the unique ID of the equipment item
• name - the name of the equipment item
• cost - the normal points cost of the equipment item (may be modified by the unitEquipmentItem's costMultiplier)
• armourType - the type of "armour" that the equipment is. Defaults to "none", but covers all combinations of 'light' armour and 'heavy' armour (with the latter being an upgrade of the former), shields (which can be taken with armour) and mount armour or "barding". These types don't need to be taken literally, but give a way of defining what "armour" equipment can be combined together.

<abilities> and <ability>

The <abilities> tag is a container for <ability> tags. The ability tags define the abilities/skills available to the race as a whole. Units reference the abilities through unitAbility tags. Attributes of the ability are:

• id - the unique ID of the ability
• name - the name of the ability

Details of the ability should be known by the user and available in the appropriate army definition

Armies

Army files should generally be created by saving an army from the applications, but can be viewed in the same way as other data files. Armies basically define the size and name of the army that was saved, which units were in it (with name, size and reference to their unit type) as well as what equipment they had. Further details will be added later.