File Formats

Table of Contents

• Tabletop Wargame Ruleset (*.twr) 2.0
  • info.xml
  • Units XMLs
  • Scripts
    • Validation Scripts
    • Display Scripts
• Tabletop Wargame Army (*.twa) 2.0
• Appendixes
  • editing XML files
  • unique ids

Tabletop Wargame Ruleset (*.twr) 2.0

Tabletop Wargame Ruleset is an open standard for storing data about armies for certain game systems. It stores units points cost, their characteristics, pictures and information about available addons. It can also contain scripts with complex validation rules and/or custom display(printing) templates.

To be flexible and to contain multimedia informations, twr files are in fact *.tar.gz archives. After changing the extension of a *.twr file or simply opening it in archiver that supports *.tar you will be able to see its contents. On UNIX like systems this can be done using command line:

This will extract all files from twr to current working directory!

Windows users can use 7zip for example.

The fastest way to learn the twr format will be to open example ruleset (or any other) and experiment changing its contents. Of course you will have to tar and gzip the contents back to one file to use it after changing anything.

info.xml

info.xml contains basic information about the Ruleset. It have to be named exactly 'info.xml' and be saved on the root of twr archive. Among other things it contains paths to other files in the twr.

Schema for this files can be found here: twr2info.xsd. See editing XML files for help on how to use it.

Complex example of this file can be found in example.twr. Below you can find detailed description of each field.

• uid - unique id of a ruleset. This will be saved in a twa file so the editing program can identify a ruleset for a saved army.
• revision - positive number that represents the version of a ruleset. This should be increased every time you are making a change in a file like adding units and/or addons. User will be warned trying to open an army using an older or newer version of a ruleset.
• name - short name describing your ruleset that will be visible on a list of installed rulesets.
• author - your name and/or email address.
• description - detailed plain text description of a ruleset.
• defaultArmyName - default name for new army. 'Horde', 'Example Army' or simple 'Army'
• defaultArmySize - default size for new army. This should be set to the most typical value. It can be of course changed by user.
• extraParams (OPTIONAL) - extra parameters possible to set when creating new army. It can be used by validator afterwards. This item is reserved and not implemented yet by any editor.
• displayFields - ordered list of default visible unit and addons fields. This fields will be displayed as a table when editing army. It will be also used by default display scripts.
  • field
    • name - name of the field displayed in a table header. It have to match the name of a unit/addon field.
    • default - default value that will be displayed if unit has this field not defined. Best choice will be to leave this empty or set it to something like '-'
• files - most important tag that contains locations of other important data files.
  • units - XML files with all units and addons data. See units XMLs for details.
    • file
      • name - describing contents of a file. For example: 'Infantry Units' or 'Cavalry Units'. This is just for clearness sake and have nothing to do with grouping units by a client program.
      • path - path to the file inside the archive.
  • media - path to a folder containing images of units.
  • validators - army validating scripts for complex rules. See Validation Scripts for details
    • default
    - path to default validator script that will be displayed as 'Default Validator'
    • file - optionally you can specify more validators for user to choose.
      • name - display name of the script like 'Tournament X Rules'
      • path - path to the script inside archive

For more information refer to ArmyCalc forums.

Units XMLs

Units XMLs are most important part of the twr file. They contain information about available army units and all its addons and properties.

Schema for this files can be found here: twr2units.xsd. See editing XML files for help on how to use it.

Best idea will be to start from browsing units XMLx in example.twr. You can find detailed description of all fields underneath.

Scripts

To extend its flexibility to maximum twr format allows you to write simple text scripts to check for very complex rules or generate custom army lists.

As twr standard will be extended it will provide choice of scripting languages and they will be identified by file extension. For now all applications can use only Lua scripts. Script files need to have *.lua extension.

Most rulesets will only need a validation script. Default display format used by ArmyCalc applications is suitable in most cases.

In both of this scripts You can use selected basic Lua functions. You can also use special interface that depends on script type.

Validation Scripts

Validation script can use special interface to read the content of an army. It can read the whole tree of units and addons.

Doing whatever is needed with given tree, validation script should output lists of Errors, Warning and Notices using special set of functions.

For tutorial on how to write validation scripts, full functions documentation and examples see Lua Validation Scripts

Display Scripts

Similar to validation scripts, display script can read the ready army tree using the same interface. But they can also get the lists form output of a validation scripts (to show validation results on army list).

As contrasted with validation scripts this scripts should use a special function to output a large piece of HTML text. It can be styled using the CSS or whatever and later on can be converted to PDF by application.

For tutorial on how to write display scripts, full functions documentation and examples see Lua Display Scripts

Tabletop Wargame Army (*.twa) 2.0

Tabletop Wargame Ruleset is an open standard for saving ready armies. This description is for developers who would like to implement the twr/twa standards in their applications. To create a ruleset you do not need to know how the armies are saved.

Schema for this files can be found here: twa2.xsd. See editing XML files for help on how to use it.

twa uses unique ids from ruleset to save the army tree. This is a simple example with army with only one unit and two addons.

<?xml version="1.0" encoding="UTF-8"?>
<army xmlns="armycalc" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="armycalc http://armycalc.com/xmls/twa2.xsd" version="2.0">
 
	<ruleset>
		<name>Example Army</name>
		<uid>example_ruleset_uid_asdnjkasd3478</uid>
		<revision>6</revision>
		<filemd5>b7907b035e2bcf8d84a45b4aec9e95e9</filemd5>
	</ruleset>
 
	<name>Army 21</name>
	<size>1000</size>
 
	<units>
		<unit>
			<uid>b7907b035e2bcf8d84a45b4aec9e95e9</uid>
			<count>11</count>
			<bonus>
				<uid>9e9702dbf7d01551394a2574fa66dfed</uid>
				<bonus>
					<uid>81f63992ca1770ec136fa45cd0639ca9</uid>
					<count>1</count>
				</bonus>
				<count>5</count>
			</bonus>
		</unit>
	</units>
</army>	

Detailed fields description follows.

• ruleset - as twa file is not usable without its ruleset in the system, this set of data helps the application to find corresponding twr file.
  • name - name of a ruleset
  • uid - unique id of a ruleset
  • revision - if no such revision can be found newest will be used and user will be issued a warning
  • filemd5 - MD5 hash of twr file
• units - list od unit tags. Each containing its uid and count and optionally one or more bonus and bonuses.

For more information refer to ArmyCalc forums.

Appendixes

editing XML files

XML files can be edited in any text editor. However it can be really handy to use dedicated XML editor like XML Copy Editor.

It will help a lot providing a syntax highlighting and keeping the opening and closing tags in proper order. When given a reference to a schema file at the beginning of an XML it can provide also quick validation for twr and twa files.

XML file with following structure::

<?xml version="1.0" encoding="UTF-8"?>
<ruleset xmlns="armycalc" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="armycalc http://armycalc.com/xmls/twr2info.xsd" version="2.0">
 
[...]
 
</ruleset>

will be checked for errors after clicking 'validate' button. This way you can be sure your file will work well even before loading it with ArmyCalc application.

unique ids

ArmyCalc applications are identifying unique rulesets, units and addons using unique string ids. This way if you change the name of the ruleset and/or units you will still be able to successfully open a twa file.

You can use any combination of alphabetic characters, digits, '_' and '-' signs as an ID. You can set an id like 'my-Ruleset12' or '7hd7883bhwb-fuwe8'. Only thing important is for it to be unique. No more than two units or two addons for one unit should have the same id.