Version 2 (modified by ibboard, 11 years ago) (diff)

--

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. There is also a WarFoundry file format using XML and Zip files that is the "native" file format for the WarFoundry army builder. The following is a description of that format and how it works together.

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, although that isn't enforced at loading time and any file that looks like a Game System file will be attempted to be loaded. The method used to identify a file format is a modification of the "magic number" that checks the comment section of the Zip file for a required string. Each file must then contain at least a specific file with data for the file type specified by the comment string for it to be loaded.

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.

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

Army File Definition