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.

Each of the following file formats is designed to be extensible. This means that it should be possible to add extensions for future use or even embed entirely new elements for completely separate applications that also support the WarFoundry file formats.

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, notes, and additional data. Attributes of the <unit> tag are:

• id: the unique (to the race) ID of the unit type
• typeName: the name of the unit type that will be shown in unit selection lists
• cat: the ID of the category that the unit belongs to - this can be used for single categories, or <unitCategories> can be used when a unit can be a member of multiple categories
• minSize/maxSize: limits on the number of troops in a single unit
• minNum/maxNum: limits on the number of times the unit type can be taken
• basePoints: the base cost for the unit - some units (e.g. Dogs of War in Warhammer) may have a base cost for a set number of troopers
• baseSize: the base size of the unit - these are the troopers that are accounted for in the unitPoints (normally zero)
• points: the point cost per additional trooper above the baseSize

<stats> and <stat>

The <stats> tag is a container for <stat> tags. The <stats> tag has one optional attribute called "statSet" that provides the ID of the stats set to use. If it isn't defined then the stats are assumed to be for the Game System's default stat set, allowing most game systems to create races without ever using the statSet attribute. Each <stat> then references the name of the stat in the set that it represents (e.g. "M", "WS", "BS", etc) and contains the string value for that stat. Although many systems use numeric values, stats are treated as plain text because there is always an exception or two to the "stats are numbers" rule. As of the later v0.1 beta releases this element has become optional and can be replaced with <unitMember> elements that are defined later.

<equipmentSlots> and <equipmentSlot>

A new feature that was released in v0.1b4. Equipment slots represent the additional limited "special equipment" slots that a unit has, such as heavy weapons in Warhammer 40,000 (e.g. "may have up to three heavy guns, assault guns or flamers, or any combination thereof"). These slots define limited groups of equipment at a finer level of granularity than mutex groups and can be combined with mutex groups for even more powerful combinations/restrictions. Equipment slots can also be used with standard equipment limits for more detailed combinations (e.g. the slot may allow up to five items, but if there are three types of equipment in that slot with an item limit of three then the unit can take up to three of one item and two of another, or three of one item and one each of the other two, two of two items and one of the third, or any other combination that doesn't exceed three for each item and five in total).

The <equipmentSlots> tag is a container for <equipmentSlot> tags. equipmentSlot tags contain a <maxLimit> tag, which just acts as a container for one of the specific limit tags.

Limits

Equipment slots can currently have one of four limit types, some of which are more useful than others for equipment slots. Note that as these limits are centrally defined then an extra namespace is required and all limits must be prefixed with the namespace (see the example files).

• <percentageLimit> defines percentage limit and a rounding direction (up or down) relative to the size of a unit
• <sizeConstrainedLimit> defines an upper limit that is also constrained by the unit size (i.e. if a unit has a unit size of 5 to 20 and can take ten of a weapon but no more than one weapon per trooper then the sizeConstrainedLimit will be the smaller of the unit size or the 10, the equipment limit)
• <absoluteLimit> defines a fixed numeric limit that isn't constrained by the unit size (i.e. in the example above a unit of 5 troopers would still be able to take 10 of the item)
• <unitSizeLimit> a shortcut for "all of the unit" (i.e. a 100% percentage limit)

<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. Each unit equipment item can also contain minimum and maximum limit tags.

• 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)
• exclusivityGroups - a multi-valued string, split on comma (","). Defines a number of "groups" where only one item from the group can be taken at once
• 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)

<minLimit> and <maxLimit>

Defines a minimum and maximum limit for equipment, which can be used in combination with equipment slot limits. See the equipment slot limits above for the allowed values of the limit tags. The default, if none is defined, is to use a unitSizeLimit (the default "equip all of the unit" behaviour of most game systems). If only a minimum limit or a maximum limit is defined then the other limit is set to the same value.

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

The requirements define data that is used to trigger requirement calculations. Currently 3 requirements exist.

• RequiresNoMoreThanNUnits - limits the number of specified unit(s) defined by their unit ids when taking one or more of this unit
• RequiresNUnitsForMUnits - specifies a number N of unit(s) that must be taken to take M of this unit
• RequiresAtLeastNUnits - the unit in question requires a specified number of unit(s) defined by their unit ids.

<contains> and <containedUnit>

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.

• containedID - the ID of the child unit.

<extraData> and <data>

Currently unused, but useful for a variety of purposes. May contain data used by requirement calculations.

As an example, if the army has a "max units per category" restriction using a custom restriction plugin but a unit doesn't count towards the restriction then the unit may have a <data> tag with an ID of "units-per-category-count" and contain the value "0". This could then be parsed by the army restriction module and the unit wouldn't be counted towards the limit. Note: This differs from <requirements> because the <requirement> tag defines the requirements that apply to units of this type (e.g. "can only take three per unit of X"), where as the requirement in the example is on the army itself.

<notes>

Currently loaded but not yet displayed in all GUIs. Notes are a single block of text containing additional "design notes" that help people when selecting units but which aren't shown in the final exported army.

<unitMembers> and <unitMember>

A new addition in the later v0.1 beta releases, the <unitMember> elements let file writers re-use stat lines by referring to a typeID that is defined later. These member types may also be used in future for more advanced functionality. If some unit members are defined and a stat line is defined the the unit will reference the member type but the stat line shown will be the one declared in the <stats> element for the unit type. You must include a <stats> block OR one or more <unitMember> elements for each unit.

<unitCategories> and <unitCategory>

A new addition in the later v0.1 beta releases, the <unitCategory> elements override the category attribute of the main <unit> and provide a way of adding one unit to multiple categories. The catID must refer to a category from the race's System or from the Race.

<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 gaming source, but a <description> tag is provided for additional detail (currently unused/not displayed).

<memberTypes> and <memberType>

These elements were added along with the <unitMember> elements as the central store of different types of unit member. The idea is that common unit types (e.g. "Human") will have identical stat lines whether they're part of a Swordsmen, Crossbowmen or Mounted Squires unit. If that's the case then the <unitMember> defines the type with an id that will be referenced and a name that will be used in stat lines, plus the <stats> themselves. The layout of the stats element matches that defined earlier in the <unit> and is an optional replacement for the stat line per unit type layout.

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.