Version 7 (modified by ibboard, 10 years ago) (diff)

Complete race definition

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, 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
  • 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
  • unitPoints: 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.

<equipmentSlots> and <equipmentSlot>

A new feature that is currently in development (ticket:198). Equipment slots represent the additional limited "special equipment" slots that a unit has, such as heavy weapons in Warhammer 40,000. 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.

The <equipmentSlots> tag is a container for <equipmentSlot> tags. equipmentSlot tags currently define a name, limit number and limit type. The type is either an absolute number (e.g. "3") or the numerical part of a percentage (e.g. "50" for 50% with isPercentage="true"). If isPercentage isn't defined then an absolute number is assumed.

<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)
  • 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
  • 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. 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 (ticket:196). 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 army.

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

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.