File Formats

WarFoundry is designed such that it can load any data files from any other application as long as a plugin is written than maps the other application's format to the WarFoundry format (e.g. the Rollcall plugin). There is also a WarFoundry file format using XML and Zip files that is the "native" file format for the WarFoundry army creator. The following is a high-level description of that format and how it works together. For a more detailed version, please read File Formats Explained.

XML and Zips

The main WarFoundry data files themselves are XML files contained within a Zip. The XML provides well structured and more easily human-readable data, while the Zip allows for future expansion (e.g. including race-specific icons for categories) and keeps other supporting data in the same place without cluttering up the data (e.g. readme files and credits). As an added side-effect, any WarFoundry files hosted on the Internet will always prompt the user to download a Zip, where as plain text files can sometimes be displayed in the browser.

Files

There are currently three main files in WarFoundry:

• Game System
• Race
• Army

Each has a different file extension as standard, which just involves renaming the .zip file (Windows users should note that you will need to show extensions in Explorer to do this, but this is good security practice anyway). The files were originally designed to be identified using a modification of the "​magic number" system that checked the comment section of the Zip file for a required string. After some user testing this was dropped as an unnecessary complication and so all files must now have the correct file extension.

Game System Files

Game System files define the individual "game systems" that can be loaded. Each Race must belong to a System, such as Warhammer, Warhammer 40,000, Lord of the Rings, or WarMachine. This method of having "game systems" to swap between allows WarFoundry to easily handle different armies for different games without having to have separate data folders for each system, as Rollcall used to.

The Game System file itself defines the name of the System, the categories that unit types can be in (overridable by the Race) and the format for the different stat lines in the game. It can also optionally define whether the game system support "allies" (taking units from other races) and whether the system owners allow you to warn people if they are building invalid armies.

Race Files

Race files define everything that would be in an army list/army book/codex for a single race. They define the unit types, their size, what equipment they can take, limits on numbers, restrictions on combinations of units and abilities.

Army Files

Army files store the units that someone has selected for their army, complete with custom names, unit size, champions, equipment and any other information. While Game System and Race files are the definition of what comes from the game manufacturer, Army files are the definition of what the gamer has done with that.

File Definitions

Each of the XML files has its own XML Schema to validate against. The latest versions of the schema should always be in source control, and any updates should always be backwards compatible (i.e. new tags should always be optional and new attributes should provide a default or be optional). As well as a schema for each file type, there is also currently a "categories" schema that defines common data about categories of units (used by the Game System and Race files) and a "core" schema that defines custom values that can be used in all of the other schemas.

All of the following information is correct as of r96 of the files, but all future updates should be backwards compatible as much as possible.

Game System Definition

A Game System is the simplest of the files and only needs to contain a few tags and attributes. A Game System file must have "WarFoundry_System" at the start of the Zip file's comment and contain a file called data.systemx. The .systemx file should use the system.xsd schema.

A simple Warhammer-esque game system can be defined as:

<?xml version="1.0" encoding="UTF-8"?>
<system xmlns="http://ibboard.co.uk/warfoundry/system" xmlns:cats="http://ibboard.co.uk/warfoundry/cats" id="sampleSys" name="Sample Game System" warn="false">
	<categories>
		<cats:cat id="cat1" name="Characters" minPercentage="0" maxPercentage="50" />
		<cats:cat id="cat2" name="Regiments" minPercentage="25" maxPercentage="100" />
		<cats:cat id="cat3" name="War Machines" minPercentage="0" maxPercentage="25" />
		<cats:cat id="cat4" name="Monsters" minPercentage="0" maxPercentage="25" />
		<cats:cat id="cat5" name="Allies" minPercentage="0" maxPercentage="25" />
	</categories>
	<sysStatsList defaultStats="default">
		<sysStats id="default">
			<sysStat name="M"/>
			<sysStat name="WS"/>
			<sysStat name="BS"/>
			<sysStat name="S"/>
			<sysStat name="T"/>
			<sysStat name="W"/>
			<sysStat name="I"/>
			<sysStat name="A"/>
			<sysStat name="Ld"/>
		</sysStats>
	</sysStatsList>
</system>

This file defines a game system called "Sample Game System" with an ID of "sampleSys" (which all races of the system will use as their Game System ID). The game system has five categories with various percentage limits on the units in the category. It also has one stat line with nine columns, which is defined as the default (the default has to be defined in case there are multiple stat lines).

Race File Definition

A Race is the definition of the available unit types that can be used to create an army of a given faction or race. A Race file must have "WarFoundry_Race" at the start of the Zip file's comment and contain a file called data.racex. The .racex file should use the race.xsd schema.

A sample race to go with the above game system would look like:

<?xml version="1.0" encoding="UTF-8"?>
<race xmlns="http://ibboard.co.uk/warfoundry/race" id="Empire" name="Empire" system="sampleSys">
	<units>
		<unit id="Empire1" typeName="Empire General" cat="cat1" points="100" maxNum="1" maxSize="1">
			<stats>
				<stat name="M">4</stat>
				<stat name="WS">6</stat>
				<stat name="BS">6</stat>
				<stat name="S">4</stat>
				<stat name="T">4</stat>
				<stat name="W">3</stat>
				<stat name="I">6</stat>
				<stat name="A">4</stat>
				<stat name="Ld">9</stat>
			</stats>
			<unitEquipment>
				<unitEquipmentItem id="equip1" required="true" />
			</unitEquipment>
		</unit>
		<unit id="Empire2" typeName="Swordsmen" cat="cat2" points="10">
			<stats>
				<stat name="M">4</stat>
				<stat name="WS">3</stat>
				<stat name="BS">3</stat>
				<stat name="S">4</stat>
				<stat name="T">3</stat>
				<stat name="W">1</stat>
				<stat name="I">4</stat>
				<stat name="A">1</stat>
				<stat name="Ld">7</stat>
			</stats>
			<unitEquipment>
				<unitEquipmentItem id="equip1" required="true" exclusivityGroup="group1" />
				<unitEquipmentItem id="equip2"/>
				<unitEquipmentItem id="equip3" required="true" exclusivityGroup="group1" />
			</unitEquipment>
		</unit>
	</units>
	<equipment>
		<equipmentItem id="equip1" name="sword" cost="1"/>
		<equipmentItem id="equip2" name="shield" cost="1"/>
		<equipmentItem id="equip3" name="broadsword" cost="2" />
	</equipment>
</race>

This race file defines the units of the "Empire" race for the Sample System. It defines a General in the Characters category and a Swordsman unit in the Regiments category. The Swordsmen must have a sword or a broadsword, but can't take both. They can also take a shield, but don't start with it.

On top of this example, the Race file can also define abilities and which units have them, it can override the system categories (e.g. Chaos armies in Warhammer always used to have a different structure to other armies), and it can define extra data for each unit that can be used by plugins (e.g. a "Warhammer 40,000 roster" plugin may use extra data to identify units that don't count towards the minimum number of Troop squads).

Army File Definition

An Army is the collection of units and their equipment that a user has created. The Army file stores this so that the user can come back to the army in the future. A Army file must have "WarFoundry_Army" at the start of the Zip file's comment and contain a file called data.armyx. The .armyx file should use the army.xsd schema.

Army files are not currently created (as of r104, 11th April 2009) but when they are then a file should look something like the following:

<army id="12345" name="Sample Army" system="sampleSystem" race="Empire" maxPoints="500">
	<units>
		<unit id="unit1" unitType="Empire1" unitName="General Eustace" size="1">
			<equipment>
				<equipItem id="equip1" amount="1"/>
			</equipment>
		</unit>
		<unit id="unit2" unitType="Empire2" unitName="First Swordsmen" size="20">
			<equipment>
				<equipItem id="equip1" amount="1"/>
				<equipItem id="equip2" amount="1"/>
			</equipment>
		</unit>
		<unit id="unit3" unitType="Empire2" unitName="First Greatswords" size="15">
			<equipment>
				<equipItem id="equip3" amount="1"/>
			</equipment>
		</unit>
	</units>
</army>

This file would define a small Empire army in the Sample Game System with a limit of 500 points. The army contains a General with a sword, a unit of Swordsmen with sword and shield, and a unit of Swordsmen with Broadswords.