Const Kit

CONSTRUCTION KIT V2.
2B
Copyright 1998-2001 by Lone Wolf Development, Inc. All rights reserved.
Notice This software product is the property of Lone Wolf Development and is protected by copyright laws and international copyright treaties. The software is NOT sold, it is licensed. This license grants the licensee to use the software on a single computer workstation and to make a single copy of the software for archival purposes only. This software is provided as is without warranty of any kind, express or implied, including, but not limited to, the implied warranties of merchantability and of fitness for any purpose. The user assumes the full risk of using the software. While reasonable efforts have been made to ensure the correct operation of this software, Lone Wolf Development does not warrant the accuracy, performance, or results you may encounter by using this software. In no event will Lone Wolf Development be liable for direct, indirect, special, incidental, or consequential damages resulting from the use of this software or any defect within the software, even if Lone Wolf Development has been advised of the possibility of such damages. Any liability of Lone Wolf Development will be limited to the refund of the purchase price. Duplication Prohibited This software and documentation are copyrighted materials. Making unauthorized copies is prohibited by law. No part of the software or documentation may be reproduced, transmitted, transcribed, stored in a retrieval system or translated into any human or computer language without prior written permission of Lone Wolf Development, except as outlined in the following paragraph. The Construction Kit software and documentation may be redistributed, as long as this is done without charge and with the exact set of files distributed by Lone Wolf Development, without any changes being introduced whatsoever. Trademarks Army Builder is copyright 1997-2001 by Lone Wolf Development, Inc. All rights reserved. Army Builder is a trademark of Lone Wolf Development, Inc. Windows is a registered trademarks of Microsoft Corporation. Warhammer and Games Workshop are trademarks of Games Workshop, Ltd. Chronopia and Warzone are trademarks of Target Games AB. Clan War is a trademark of Wizards of the Coast. Other brand or product names are trademarks or registered trademarks of their respective holders. These trademarks are used without permission and no challenge to the status of these trademarks is intended by their use. Acrobat Reader copyright 1987-1999 Adobe Systems Incorporated. All rights reserved. Adobe and Acrobat are trademarks of Adobe Systems Incorporated. Contact Information Lone Wolf Development, Inc. Web: www.wolflair.com Email: support@wolflair.com Forum: www.egroups.com/group/armybuilder
Construction Kit V2.2b
Copyright 1998-2001 by Lone Wolf Development, Inc.
Table of Contents
Notice.................................................................................................................................1 Duplication Prohibited........................................................................................................1 Trademarks........................................................................................................................1 Contact Information............................................................................................................1 Introduction........................................................................................................................5 Overview......................................................................................................................5 Program Requirements................................................................................................5 Product Installation......................................................................................................5 Accessing the Manual..................................................................................................6 Service and Support....................................................................................................6 Upgrading Considerations..................................................................................................7 Backwards Compatability............................................................................................7 Converting Definition Files from V1.4 to V2.x..............................................................7 Converting Data Files from V1.4 to V2.x......................................................................7 Dynamic Interaction of Options....................................................................................7 Fundamental Concepts......................................................................................................9 Definition and Data Files..............................................................................................9 Basic Components and Terminology...........................................................................9 Unique Identifiers.......................................................................................................11 Validation Rules.........................................................................................................12 Composition Rule Sets..............................................................................................12 Conflict Groups..........................................................................................................12 Type Names..............................................................................................................13 Modes and Scenarios................................................................................................13 Augmentations...........................................................................................................13 Text Files vs. Run-Time Files....................................................................................14 Definition Files..................................................................................................................15 Overview....................................................................................................................15 File Syntax.................................................................................................................15 General Definitions....................................................................................................15 Publishing Specifications...........................................................................................17 Stat Definitions...........................................................................................................18 Composition Group Definitions..................................................................................22 Unit Category Definitions...........................................................................................23 Option Category Definitions.......................................................................................23 Conflict Group Definitions..........................................................................................24 Tweak Category Definitions.......................................................................................25 Stat Set Definitions....................................................................................................26 Item Category Definitions..........................................................................................27 Terminating the Definition File...................................................................................29 Generating a Run-Time Definition File.......................................................................29 Data Files.........................................................................................................................30 Overview....................................................................................................................30 Races........................................................................................................................31 Units..........................................................................................................................33 Options......................................................................................................................35 Links..........................................................................................................................36 Items..........................................................................................................................37 Elements....................................................................................................................37 Tweaks......................................................................................................................38 Custom Validation Messages....................................................................................39 Augmentations...........................................................................................................40 Version Information....................................................................................................40 Validation of Data Files..............................................................................................41 File Syntax.................................................................................................................41 Core Data File Concepts..................................................................................................44
Construction Kit V2.2b Copyright 1998-2001 by Lone Wolf Development, Inc.
Overview....................................................................................................................44 Boolean Expressions.................................................................................................44 Calculated Expressions.............................................................................................44 Rounding and Clipping of Stat Adjustments..............................................................45 Race and Mode Restrictions......................................................................................45 Complex Legality Tests.............................................................................................46 Inheritance of Attributes.............................................................................................47 Inheritance of Options................................................................................................47 Obsolete Mechanisms...............................................................................................47 Attributes In General........................................................................................................48 Overview....................................................................................................................48 Attribute Syntax.........................................................................................................48 Conditional Restrictions.............................................................................................48 Single-Instance vs. Multi-Instance.............................................................................49 Sequencing................................................................................................................49 Validation Attributes...................................................................................................50 Use In Augmentations...............................................................................................50 Multi-Stat Capability...................................................................................................50 Using skip for Testing..............................................................................................50 Support for Army Builder Lite.....................................................................................50 Global Race Attributes...............................................................................................51 Local Versus External Unit Attributes........................................................................51 Complete Attribute Documentation is in ABCreator...................................................51 Attribute Summaries.........................................................................................................52 Race Attributes..........................................................................................................52 External Unit Attributes..............................................................................................53 Local Unit Attributes...................................................................................................54 Option Attributes........................................................................................................56 Item Attributes............................................................................................................59 Element Attributes.....................................................................................................60 Tweak Attributes........................................................................................................61 Designing Files For Army Builder.....................................................................................63 Overview....................................................................................................................63 The Definition File......................................................................................................63 Data Files..................................................................................................................63 Incremental Creation.................................................................................................64 Iterative Evolution of Files..........................................................................................64 Inserting Placeholders...............................................................................................65 Leveraging Inheritance..............................................................................................66 Augmentation Data Files...........................................................................................66 Debugging Aids.........................................................................................................66 Including User Documentation...................................................................................67 Distributing Data Files................................................................................................67 Importance of Version Numbers................................................................................68 Adding Release Notes...............................................................................................68 Required Version of Army Builder..............................................................................68 Tell Us About Your Files!...........................................................................................68 ABCreator........................................................................................................................69 Overview....................................................................................................................69 Getting Started...........................................................................................................69 The Main Menu..........................................................................................................69 The Overall Interface.................................................................................................71 Tab-Specific Details...................................................................................................72 Creating New Records and Copying Existing Records..............................................73 Adding Comments To Your Data Files......................................................................74 Command Line Usage Features................................................................................74 Other Tools......................................................................................................................75 Command-Line Tools................................................................................................75 The ABDef Tool.........................................................................................................75
Construction Kit V2.2b Copyright 1998-2001 by Lone Wolf Development, Inc.
The ABData Tool.......................................................................................................75 The ABExport Tool....................................................................................................76 The ABUndef Tool.....................................................................................................77 The ABVersion Tool...................................................................................................78 Public XML File Format....................................................................................................79 Custom Output Extensions...............................................................................................80 Overview....................................................................................................................80 Creating an Extension...............................................................................................80 Integrating Extensions...............................................................................................80 Packaging for Deployment with Data Files................................................................81 Packaging for Independent Deployment....................................................................81 Appendix..........................................................................................................................82 Internal Limits............................................................................................................82
INTRODUCTION
Overview If you are reading this document, you have probably become comfortable with using Army Builder and are now interested in creating your own data files for your favorite game system or tailoring existing data files for you own purposes. Since only a small percentage of users will want to exploit this capability, the Construction Kit is provided as a separate component from Army Builder itself. The Construction Kit must be installed separately, and it requires a modicum of technical savvy in order to use it. If you want to really make use of all of the power and flexibility of the Construction Kit, you should plan on spending a fair bit of time mastering all of the subtle capabilities of the toolset. However, you can begin creating simple units and their options in reasonably short order. The Construction Kit provides the means for you to create your own definition and data files for use with Army Builder. Whether you want to create a complete set of data files for a new game or merely add a few custom extensions to an existing set of data files, you will need to use the Construction Kit. The Construction Kit consists of a suite of tools that you use to create and/or edit the special files that Army Builder uses at run-time. The process of creating these files can range from relatively simple to extremely complex, depending on the level of sophistication you want to provide within your data files and the requirements of the particular game system you want to model. Probably the most important tool of the Construction Kit is ABCreator. This tool provides a relatively simple-touse interface for creating and editing data files. For most users, this is the tool where nearly all of your time will be spent. A tutorial for ABCreator is available that should get most users productive very quickly. You will need to become familiar with the contents of this document first at a minimum the concepts and terminology but the tutorial should make the learning curve much shorter. Please refer to the section on ABCreator for more details on this tutorial. Program Requirements In order to use the Construction Kit, your computer system will need to meet the following minimum requirements: PC running Windows 95, Windows 98, Windows ME, Windows NT, or Windows 2000. 16MB RAM memory. 3MB free hard disk space. This is over and above the requirements for Army Builder. Mouse or other pointing device Army Builder must already be installed on your system. Product Installation Installing the Construction Kit entails running the installation program and following the instructions it presents. Be sure that you have Army Builder properly installed on your system when you start to install the Construction Kit. To launch the installer, please follow these instructions: Click on the Start menu in the lower left corner of the display. Select Run.... Click on the Browse button. Navigate to the location where the installation program is located. If you are installing from a floppy, this will likely be the a: drive. If you downloaded the program, this will be the location you saved the file to. If you are installing from the CD-ROM, this is the CD-ROM drive. Double-click on the kit22.exe file containing the Construction Kit installer. Follow the instructions presented by the installation program. Note! For proper operation of the toolset, you must install the Construction Kit in the same location
Construction Kit V2.2b Copyright 1998-2001 by Lone Wolf Development, Inc. 5
where you installed the Army Builder. This should be the default location presented. Once the toolset has been installed, you can run the various tools as described elsewhere in this document. Accessing the Manual The manual for the Construction Kit will be found in the file constkit.rtf (placed in the installation directory). This file is in the Rich Text Format, which is a standard format that can be read by nearly all word processors. You can also read the file into WordPad, which ships with Windows, although some of the formatting will not be preserved fully by WordPad. A copy of the manual in Adobe's PDF format is also available (the file is constkit.pdf). If you downloaded Army Builder from the web-site (www.wolflair.com), then this file can also be downloaded from the web-site. If you purchased the CD-ROM version of the Army Builder, this file is included on the CD. The Adobe Acrobat Reader software, which is needed to view this file, can be obtained via the web-site. It is also included on the CD. For Acrobat installation instructions, please see the Army Builder manual. Service and Support User support for the Construction Kit is the same as for the Army Builder product. Please refer to the documentation for Army Builder regarding how to obtain support.
UPGRADING CONSIDERATIONS
If you have existing data files created with V1.x of Army Builder and are upgrading to V2.x, there are a number of things that have changed which you should be aware of. These are outlined in the following sections. Backwards Compatability Army Builder V2.x is intended to be fully backwards compatible with the preceeding version of the product. As such, you should be able to read in any set of data files that work with V1.4 and use them without any problems. Using data files from previous versions should be automatic and transparent to the user. Army Builder should present older data files exactly like new data files and should have no different behaviors between the two. All of the Construction Kit tools should also operate equally on both old and new definition and data files. For older files, appropriate defaults are assumed that should result in the same behavior in V2.x as was encountered in V1.4. Converting Definition Files from V1.4 to V2.x The syntax of V2.x definition files is quite different from previous versions. However, converting definition files to the new syntax should be an extremely simple step. All that is required is that the V2.x ABUndef tool be used to decompile the existing run-time definition file. This should generate a file with default values in place for all the new sections and fields. Once this is completed, the new ABDef tool can be used to recompile the definition file appropriately. Conversion of definition files should typically be performed before the conversion of data files is begun. Converting Data Files from V1.4 to V2.x The system of V2.x data files has also changed significantly from previous versions. Fortunately, converting data files to the new format should be extremely easy, too. Each data file should simply be loaded into the V2.x ABCreator, edited in some innocuous way (e.g. add a space to a record and then delete that space, saving the changed record), and then saved. If you need to convert data files to the new text format, then you should utilize the new ABCreator to save the files as text and use the new ABData tool to generate the compiled run-time version of the file. Dynamic Interaction of Options The internal handling of options has been overhauled to provide full recursive handling in response to dynamic initialization and changes to choices for units. In V1.x, use of the "more" attribute simplified a lot of things, but it wouldnt work properly in some situations. The reason for this was that the handling of attribute effects tied to chained options had some major holes. This handling has been completely reworked to provide full recursive processing of options and their effects, even when it pertains to the dynamic changing of option enablements (e.g. the "over" and "elim" attributes). Examples of some of the new behaviors that are supported include: Example #1. If OptionA uses "more:OptionB=auto" and OptionB uses "take", the "take" attribute should be properly triggered. Example #2. OptionA uses "more:OptionB=auto" and OptionB uses "over:OptionC=delete". If OptionA is attached via "cost" and OptionC via "auto", selecting OptionA should delete OptionC properly. Example #3. Same as #2, except that OptionB also uses "more:OptionD=incl" and OptionD enables OptionE via "over:OptionE=enable". If OptionE is designated as "dsab" by default, selecting OptionA should enable OptionE. Example #4. OptionC uses "over:OptionB=delete" and is linked via "cost". OptionB is linked via "incl". OptionA uses
"over:OptionC=deselect" and is linked via "cost". When OptionC is selected alone, OptionB should disappear. When OptionA AND OptionC are selected, OptionB should be available. Note the order of OptionA/OptionC, since they are sorted alphabetically and priority can sometimes be important here. Note! This change is fundamental to the engine. As such, the behavior of existing data files MAY HAVE CHANGED. If your data files exploited any of the limitations and/or incorrect behaviors of V1.x when handling options (whether intentionally or unintentionally), then those data files could now behave differently. Please check the behavior of your files for any problems that may have emerged.
FUNDAMENTAL CONCEPTS
Warning! If you are not at least somewhat technically savvy, it is quite possible that you will find the process of using the Construction Kit a daunting task. Even if you are comfortable with the idea of creating your own files, it can be a time-consuming process, depending on the scope of work you intend to tackle. Before you embark on creating your own data files, you may want to see if someone else has already created files for your favorite game system. There are a number of excellent resources for this, and they are described in the Army Builder manual. Definition and Data Files At the heart of everything for Army Builder, there are the definition files and the data files. These two types of files are described briefly in the main Army Builder manual, but you will need to understand them in much greater detail in order to create and/or edit these files appropriately. Since the objective of the Construction Kit is to enable you to create and maintain these files, the bulk of this document is dedicated to describing every nuance of these files. To sum up the basics, there are two types of files. The first of these, called the definition file, specifies all the details of the mechanics of a particular game system. This file is named datadef.*. The file extension can be anything you want, but it is limited to a maximum of nine characters (three is standard). The other type of file is simply called a data file. The data file contains the information about different races, units, options, and items that exist within the game system. You can have multiple data files for a given game system, with the information from all related data files being pooled together into one large body of data from which you can build your army. All data files for a particular game system must have the same file extension as the definition file that they correspond to. For example, if you named your definition file datadef.xxx, then all of the data files for that game system can have any base filename you want, but the file extension must be .xxx to associate them properly with the definition file. All of the data files used by Army Builder must reside in the data subdirectory beneath the location where Army Builder is installed. Basic Components and Terminology There are quite a number of different ways in which various game systems describe the rules for army construction. Army Builder has attempted to distill these various methods into a collection of components that can model all of these variations. This set of components forms the basis of the Army Builder engine, and represents the set of building blocks which are used to model a particular game system. Each of these basic components is described below, along with a few additional terms used within the Army Builder engine. Most of these are described in complete detail elsewhere within this document, but a brief description is provided below in order to introduce each concept at the outset. Race: A race is the organizational group for which an army roster is constructed. The actual term varies from one game system to another (e.g. race, clan, force, nationality, etc.). For each race, there is a selection of units which can be chosen from to build your army. Units are the components which make up an army roster. Each unit represents a combat group that has a unique set of skills and abilities on the battlefield. A unit might represent a horde of troops or a single heroic character, depending on the game system. Within Army Builder, you choose from among a set of available units to create an army. Many units will have equipment or skills that may come for free with the unit or can be optionally purchased for the unit. In some game systems, options might represent armor and weapons, while another game system might use options for the purchasing of skills and other equipment. The same option can often be given to more than one unit in a roster, so a link provides the connection between a given unit and a given option. When an option can be taken by a unit, a link will exist between the two.
Copyright 1998-2001 by Lone Wolf Development, Inc. 9
Unit:
Option:
Link:
Special Item:
Constructed Element:
Tweak:
Stat:
Composition Rule:
Composition Groups:
Unit Categories:
Option Categories:
Item Categories: Tweak Categories: Conflict Groups:
Most game systems have the concept of special weapons, protections, powers, spells, talents, and other things that can be purchased for certain units. These are generically referred to as special items (or simply items). Some game systems allow the user to construct their own special items, and constructed elements (or simply elements) represent the pieces these items are built out of. For example, if a game system allows you to create the spellbook for a wizard, the individual spells would be defined as elements within Army Builder. Aside from the special rules for construction, constructed items are treated pretty much the same as traditional special items. Some game systems allow individual equipment options to be customized during army construction. The mechanism used to support this is called tweaks within Army Builder. These tweaks are very similar in behavior to options, although tweaks allow individual special items to be customized instead of units. A stat is the term used for a units skill level in a particular area. For each game system, a set of stats is defined, covering a units combat strength, defense, movement, etc. Every game system has a framework which defines how an army is to be constructed. The composition rule set is the formal definition of this framework, which is comprised of one or more individual composition rules. Each composition rule reflects the restrictions upon one grouping of units. Each game system has one or more composition rules which must be enforced. Invariably, this translates into a number of broad groupings of units and limitations upon their relative levels of representation within an army. Each of these groups is referred to as a composition group, and every unit is assigned to a particular composition group so that Army Builder can determine if the armys actual composition satisfies the defined rules. Units can be broken down into multiple categories for a given game system. Sometimes, these categories will directly correspond to the set of composition groups, but typically this list will provide more granularity. For example, the Hero composition group might comprise the two unit categories of Hero and Wizard. Unit categories are used to restrict access to special items and a number of other things. There are usually numerous options available for units within a game system. As such, there needs to be some way to organize these options into meaningful groups, so that Army Builder can present them in an organized way (e.g. weapons, armor, etc.). This is the primary purpose of option categories. Just like options, there are usually many different special items for a game system, so these are divided into meaningful categories as well. Similar to option categories, tweak categories represent the various classifications that can be assigned to tweaks. A conflict group represents a collection to which multiple options and/or special items can be assigned. The purpose of a conflict group is to establish a limit upon a set of related options/items. For example, a unit should not be allowed to take two different types of armor at the same time. In order to enable Army Builder to preclude the user from selecting such conflicting options/items at the same time, they can be assigned to appropriate conflict groups.
10
Stat Sets:
Unique Id: Type:
Attribute:
Augmentation:
Validation Rule:
Validation Message:
Mode (or Scenario):
Unit stats are typically listed in a standard grid format. However, there are sometimes units that have a completely different set of characteristics than normal units (e.g. vehicles vs. infantry). To accommodate this, Army Builder allows you to define custom sets of stats that you can selectively use for special units. Virtually every record within Army Builder is assigned a unique identifier (unique id), via which it can be referenced by any other record. Units can be assigned types, which can be used to enable customized handling and tracking of units in very powerful ways. A unit may be assigned multiple types, each of which is simply a text value. Attributes provide the mechanism by which Army Builder can be customized and tailored to support the complexities of virtually all game systems. Attributes are assigned to records and those attributes are processed to implement special handling rules at run-time. Many users will want to use existing data files for most purposes and still be able to include their own customizations to these files. Similarly, users will want to construct data files which enhance the functionality defined in other data files, building on the existing files. If the original files must be edited, then it makes it much harder for updates to the original files to be distributed. Augmentations allow one data file to modify and enhance records that exist in another data file. This way, different data files can be created and maintained by various people without conflicting with one another. Validation rules are special rules which Army Builder evaluates whenever the roster is changed. Validation rules typically govern the relative composition of the army, spanning multiple units in their scope. For example, if the roster contains Unit A, the need for the roster to also contain Unit B would be defined as a validation rule. When a validation rule is specified, Army Builder will automatically synthesize an error message if the rule is not satisfied. However, there are significant limits to the quality of messages that are automatically generated by a program. Thats why Army Builder allows you to define your own custom messages that you can display instead of the automatic messges. A mode is a special context wherein a user constructs an army. Within a given mode, special rules and behaviors can be defined that will modify the standard ways in which an army is constructed. For example, a particular mode could be defined that imposes special restrictions that are unique to a particular tournament, enabling the tournament players to construct armies that are ensured to be legal relative to the tournament rules.
Unique Identifiers Data files are essentially a database of information. Within a data file, units will be linked to options, options may result in other units or special items being added, etc. Consequently, it is critical that most pieces of data in the data file have a unique identifier so that all of these references can be specified properly. Most tools that require these types of identifiers require you to assign everything a number, so you end up spending the majority of your time memorizing and/or looking up numbers. Numbers are important for program performance, since looking up long name strings is much slower when the program is running. However, the Construction Kit uses a method that provides a balance between the two. Every unique identifier that the Construction Kit uses for records is allowed to be an 8-character name, consisting of alphanumeric characters and the _ character. This allows you to come up with names that are meaningful and easy to remember (e.g. twohand for a two-handed weapon option). By restricting the size to 8 characters, the Construction Kit is still able to translate these names into numbers that are used internally by Army Builder so
that performance is retained. There are some instances where additional rules are imposed upon the naming of unique identifiers, but this method of allowing 8-character names will hopefully make the effort of creating and maintaining data files a little less daunting. Warning! Unique identifiers are case-specific, so be careful when mixing upper and lower case characters. For simplicity, it is recommended that all identifies use a common case (upper or lower). Validation Rules Validation rules are described at a high level within the Army Builder manual. However, you will need to understand the details of validation rules when writing data files. Manual validation is actually quite easy, since the user is in control of when the validation is performed. Automatic validation works much differently. In this case, every time the user makes a change to the roster, a special flag is set internally within the Army Builder engine. As soon as the user stops making changes, this flag indicates that the updated roster needs to be revalidated. At this time, the entire roster is scanned to recompute whether each validation rule is currently complied with, and the user-interface is updated to indicate whether the roster is valid or not. This method ensures that the user is not forced to wait for validation to finish between actions when multiple actions are taken in rapid sequence (e.g. clicking on the + button repeatedly to increase the size of a unit). Validation is not performed until the sequence of actions has completed and the user pauses for a moment. Validation rules are typically defined via attributes. Further details on validation rules and attributes can be found elsewhere in this manual. Note! Whenever you have the opportunity to decide whether to utilize an enforced rule (where the data file implementation precludes the user from taking an action) or a validation rule, there is one important question to ask yourself. This question is whether the rule is an absolute requirement or if some gaming groups will possibly choose to relax or modify the rule as part of their house rules. If the latter is the answer, be sure to use a validation rule. This way, a gaming group that doesnt observe the rules the same way as the data file can simply ignore the validation message for their armies. Note! Only top-level regiments are typically processed by validation rules. If you wish to include child units in the validation processing scan, be sure to assign the forc attribute to all such children. Composition Rule Sets The nature of composition rule sets and their importance is described within the Army Builder manual. For the Construction Kit, however, it is important to be able to translate a game systems framework into an appropriate set of composition rules. When reading the rules for a game system, there is always a clear statement of how many units can be taken from a particular group, or how large a percentage of the army can consist of units from a particular group, or the relative ratio that must be maintained between two groups. These game rules form the basis for defining the proper composition rules, and each group translates directly to a composition group. Most game systems use a single method consistently, typically basing their composition model on either a percentage-based model (up to X% of the armys total points may be spent on units of type Y) or on a countbased model (between 2 and 4 units of type Y can be in a valid roster). These are both easily modeled within Army Builder. However, a few game systems have introduced a hybrid approach, wherein some restrictions are count-based and other restrictions are percentage-based. Army Builder is also able to support these more complex models. as well. Full details on the mechanics for this are described in the section on Definition Files. Conflict Groups The Army Builder manual introduces the notion of conflicts and contrasts hard conflicts to soft conflicts. The mechanism which makes all of this possible is conflict groups. Conflict groups govern items that cannot be taken at the same time. For example, a unit cant be equipped with two types of armor at the same time, so both types of armor would be assigned to the same conflict group, resulting in only one of the two being selectable at a time. Conflict resolution is not only performed between options, though. It is also performed between options and special items, including constructed items that contain elements. Therefore, if an option is selected that possesses
the same conflict group as a special item, that special item will not be able to be selected by the user, and vice versa. For example, a Hero with magical armor cannot also take normal armor at the same time. The key facet of conflict groups which must be understood is the way they can interact with each other. The nature of conflict groups is that each group can be specified to manifest a hard conflict, a soft conflict, or no conflict with any other conflict groups that exist. Consequently, you dont have to have a single conflict group that includes all melee weapons, missile weapons, and shields. This method wouldnt model the situation properly. Instead, you can create separate conflict groups for single-handed weapons, double-handed weapons, single-handed missile weapons, double-handed missile weapons, and shields. For each of these groups, you can then specify which other groups need to be conflicted with. This means that you can stipulate that only the double-handed weapons and missile weapons conflict with the shield, while all single- and double-handed weapons of the same type conflict with each other. The net result is an accurate modeling of how the equipment should (and should not) conflict with each other. The specifics of conflict groups are described elsewhere in this manual. Type Names Each unit can be optionally assigned a type name (or simply type) as part of its definition. At run-time, units can be assigned multiple types via many different means. A type is any string of alphanumeric text, up to a maximum of 10 characters. Type names can be used to perform special testing upon units, as many of the various validation rules can be restricted to only apply to units which have been assigned a particular type. The mechanisms which test and compare these types have a special convention. When a type is specified for comparison purposes, it is allowed to end with a ? if you wish, which is treated as a wildcard. If a wildcard is specified, then the type value to be compared will be considered a match with any type that matches up to the ?. For example, a type value of orc? will match orc, orcsavage, and orcblack, but it will not match orange. This allows a group of related units to be assigned similar type names that are actually distinct from one another. When you want to match a specific type, use the complete type name. When you want to match the group of similar units, specify the type with a wildcard at the point where the names are allowed to differ. Warning! Unit type names are case-specific. Be very careful with your naming, else you will not get the results you want. Warning! Unit type names are not an abundant resource and are somwhat expensive to process at run-time. Each unit can be assigned a maximum of 25 type names at any one time via any means. If more than 25 types are assigned to a unit, the excess are simply ignored. Also, since type names are text values, the use of numerous type names across many units could have a noticeable effect upon the speed at which your data files run within Army Builder. For these reasons, please use type names judiciously. Modes and Scenarios The concept of modes (also called scenarios) is rather simple. Defining a new mode allows you to specify customized rules for army construction that are only applicable when the user selects that mode. In other words, if you dont want a particular set of rules enforced within the standard data files, you can define a mode that allows the user to choose that set of rules when he wants them. Once you define such a mode, the next thing to do is define all of the rules that are specific to that mode. The key distinction here is that each of these rules must be defined to be active only when the new mode is selected. Virtually all records can be restricted to be available only when a particular mode is selected, so restricting special units and options to a mode is easy. Similarly, numerous attributes can be restricted to be applicable only for a particular mode. With careful construction of your data file, you can ensure that the rules you want to associate with the new mode are only enabled when the mode is selected. Augmentations One of the most powerful features of Army Builder is its ability to load and merge multiple data files for a single game system. This enables the data files to be created in pieces. It also makes it possible to add enhancements to existing data files without directly changing those data files. Instead, the enhancements are defined in a separate
data file and then merged by Army Builder when the files are loaded. This process is called augmentation. At a more detailed level, augmentation actually involves the modification of records stored in one data file via information stored in another data file. The mechanism used is purely additive, hence the choice of the term augmentation. The way the mechanism works is that a special type of record (an augmentation record) is defined that actually appends one or more attributes to another existing record. Once these attributes are appended to the other record, the augmentation record on its own is useless and is thrown out by Army Builder. The advantages of using augmentation records can be seen in many ways, thanks to there no longer being any need to modify an existing data file directly. First of all, this means that it is possible to obtain an updated version of a data file from someone else and not lose the changes that you made. Since the changes are all made via augmentation records, they will usually work perfectly well with the newly updated data file. Secondly, using augmentation, users can create supplemental data files that augment a core set of data files to include new units and options (either their own of those that appear in a published rules supplement). And, lastly, augmentation records enable a data file to be written that is purely a set of augmentation records. This makes it possible for a tournament coordinator to write a data file which specifies all of the special rules for the tournament via augmentation records. Text Files vs. Run-Time Files For most of the tools associated with the Construction Kit, a distinction is made between text files and run-time files. Run-time files are the files that are loaded and used by Army Builder when the user selects a game system. These files are stored in a special format that is typically not suitable for editing. Consequently, many of the Construction Kit tools make use of text files as well. The text files contain the same information that is in the runtime file, except that the information is perfectly suitable for editing. The text files are created and/or maintained so that they contain the proper information, and then those files are converted to the corresponding run-time files for use within Army Builder. The contents of the run-time files are of no concern to you, since you will never have to manipulate their contents directly. However, the contents of the text files is very important. All of the text files used in conjunction with the Construction Kit have a specific syntax that must be adhered to. This syntax is described separately for each of the text files in other sections of this manual. To create and maintain the text files that are required by the Construction Kit, you will need to have access to a text editor that supports tabs and does not append extraneous characters at the end of the file. Most common editors satisfy these requirements, including the Notepad editor which ships with Windows. Using text files ensures that virtually everyone can readily create their own files, as Windows itself includes a text editor that serves this purpose.
14
DEFINITION FILES
Overview At the core of everything is the definition file. The definition file delineates all of the fundamental details of a particular game system. This includes the name of the game system, the set of stats that each unit possesses, the various categories of unit and options, etc. The definition file must be created first, since all of the data files for the game system reference the definition file extensively. This chapter describes the contents of the definition file in complete detail to enable you to create your own definition files. Some of the descriptions provided below will probably not be incredibly clear. It is sometimes very difficult to put a concept into clear words, so an example definition file is analyzed as part of this chapter. This example is the sample definition file that is installed with the Construction Kit (tutordef.txt). This is the text version of the same definition file that is installed with Army Builder as the Tutorial Game System (datadef.tut). While sections of this text file are reproduced in the following sections, you may also want to view this file in an editor or print it out for reference while you read this chapter. File Syntax The definition file is a simple text file that lists all of the pertinent information in a specified format, using an explicit syntax. Each line within the file identifies a piece of information, and information is not allowed to span multiple lines within the file. If a line is expected to contain multiple bits of data, then each piece of data is separated by the vertical bar character (|). The text file is broken up into sections, each with an appropriate header to introduce the section. These sections must appear in the specified sequence, and all sections must appear, even if there are no entries for a given section (in which case, it is simply left empty). Each section header must start within the leftmost column of the text file, while all of the lines containing data for that section must begin with at least one white-space character (either a space or a tab). If you wish to insert a comment into the text file, simply insert the character ~, and all text following it will be ignored, up to the end of the line. Because of this comment format, you cannot embed comments within the data on a given line. Comments can only appear at the end of a line or the comment can be the entire line by placing the ~ at the start of the line. As mentioned above, the definition file is comprised of sections, each with its own header. There are a total of ten sections, and each is described in the following pages. Each section has a name, and that name must appear, leftjustified, at the start of the section within the text file. General Definitions The first section is the general section. This section identifies general bits of information about the game system, including its name. Each piece of information appears on its own line beneath the section header, and each must be prefaced with a label at the start of the line. The label must be followed by an equal sign (=), which must be immediately followed by the value to be assigned. The list of settings must appearing in the order given below (with the label given in the lefthand colum): Game MinSize Items Name of the game system (maximum of 30 characters). Minimum army size that the user is required to specify (integer value). Name to be used throughout Army Builder to identify special items (e.g. Magic Item, Spell, etc.) (maximum of 15 characters). If this name is given as none (any case), then special items are not accessible for the game system, with all associated buttons and menu items being disabled automatically. Term to be used for all special Leader units (e.g. Warlord) (maximum of 25 characters).
LdrName
LdrAbbrev Basis
Scale
Cost
Decimal
Round
Orient
TweakAbbrevs
Army
Scenario
Abbreviation to be used for special Leader units (e.g. Ldr) (maximum of 5 characters). [Obsolete] Either the word count or the word points to indicate whether the default composition rules for the game system are based on a unit count model or a point-based model. Width of the Options column in the roster display, given as a percentage of the default width (value in the range of 1-250%). For example, if a value of 50 is given, the Options column will be half of its default width, while a value of 200 will double the width of the column. If a value of '0' is specified, no Options column will be displayed at all. This behavior only applies to files created with V2.2 and later. Previous data files use the value zero to indicate a default scale of 100. Note: If you attempt to specify small numbers for this value, it may APPEAR to have zero net effect on the column sizes. The reason for this is that the Options column is inherently given priority for the allocation of extra horizontal space. If each of the stat columns has a fixed width and the total width of all columns leaves extra space unallocated, then the Options column will be assigned a large portion of that extra space, even if it was specified to be extremely small. This will yield the appearance that small values are being ignored by Army Builder. The solution to this is to either (a) specifically widen some of the stat columns so that there is no extra space to be allocated or (b) use the x:y format for the width of various stat columns, telling Army Builder to widen those stat columns if there is additional space available. The latter method is usually the ideal solution. Width of the Cost column throughout all displays. This value is given as a number of character cells, where a width of 4 would imply 4 digits of cost. The Cost column in the roster display is automatically increased by one character in width, and additional space is automatically added, for each decimal digit to be displayed. Number of decimals to display in all costs. For example, a value of 2 would result in all costs being displayed in the format 5.00. For whole numbers only, specify a value of zero. Rounding method to be utilized in all cost calculations, which must be given as one of the following values: normal standard arithmetic rounding (e.g. 1.49 -> 1 and 1.50 -> 2) up all fractions are rounded up (e.g. 1.01 -> 2) down all fractions are rounded down (e.g. 1.99 -> 1) none no rounding is performed whatsoever Required paper orientation for roster printouts. This can be one of: portrait, landscape, or any. If roster printouts must be in a particular orientation for some reason, you can specify the orientation and it will always be enforced, regardless of the users selection. If there is no requirement, specify any so that the user can control this. Whether abbreviations for tweaks should be shown in the Options column of the roster or hidden. This must be either the value hide or show. If tweak abbreviations are shown, then the item description is truncated at the start of the Options column of the roster, instead of its normal behavior of spanning to the Cost column. Term to be used throughout Army Builder to reference the standard military force being constructed for the game system. Examples include: Clan, Warband, Gang, Team, Army, etc. (maximum of 12 characters) Term to be used within Army Builder to reference the scenario/mode mechanism, assuming the mechanism is used by the game system. (maximum 15 characters)
16
PtsSingle
PtsPlural PtsAbbrev
Term to be used within Army Builder to reference the unit of measure for points within the game system. This must be the singular form of the word. Examples include: Point, Koku, Gold Crown, etc. (maximum of 12 characters) Same as the above, except that this must be plural form of the word, such as Points, Koku, Gold Crowns, etc. (maximum of 12 characters) Same as the above, except that this must be the abbreviation to use for points, such as Pts, Koku, GC, etc. (maximum of 4 characters)
Lets take a look at how the first section in the tutorial definition file is laid out (shown below). The first two lines are simply comments, as the ~ character appears in the very first column. The very first non-comment line contains the name of the section, General. A comment appears at the end of this line, too. Beneath the General section heading, each line within the section begins with at least one white-space character to indicate that this line is part of the section. Each line contains the label string, followed by the = character, followed by the actual value for the field. The values shown for these fields should be clear, given the descriptions above.
~Tutorial Definition File ~-----------------------General ~general settings for the game system Game=Tutorial Game System MinSize=500 Items=Magic Item LdrName=Warlord LdrAbbrev=Ldr Basis=points Scale=100 Cost=4 Decimal=0 Round=normal Orient=any TweakAbbrevs=hide Army=Army Scenario=Scenario PtsSingle=Point PtsPlural=Points PtsAbbrev=Pts
Publishing Specifications The second section is the publish section and identifies all the details associated with the publishing (i.e. release) of the data files. This section specifies the version for the set of files, as well as author information and an optional password. The syntax for this section is identical to the General section above. Each piece of information appears on its own line beneath the section header, and each must be prefaced with a label at the start of the line. The label must be followed by an equal sign (=), which must be immediately followed by the value to be assigned. The list of settings must appearing in the order given below (with the label given in the lefthand colum): VersionMajor The primary (major) component of the version assigned to the current release of the data files (positive integer value). A complete version number consists of a major and a minor component, such as 3.2, where the major version is 3 and the minor version is 2. Minor changes to files usually entail an increase to the minor version component, while major changes increase the major version component. Version 4.1 is always considered newer than version 3.8, since the major component always takes precedence. The secondary (minor) component of the version assigned to the current release of the data files (non-negative integer value). For details, please see the description of VersionMajor above.
VersionMinor
PatchRequired
AuthorName AuthorEmail
LockCode
Patch level of Army Builder required to use the data files (none or the letter corresponding to the needed patch level). Once in awhile, the enhancement of data files will uncover a critical bug within Army Builder. That bug will usually be quickly fixed, but many users will still attempt to use the buggy version of the product with the data files. This field allows you to specify that a particular bug fix release is required to properly use the data files, which eliminates a lot of unnecessary confusion and frustration for users, plus it eliminates all the attendant support questions for you. The patch level requirement is only applicable within the version the files are released for. For example, if you create your data files with V2.1c and specify a required patch level of c, users with V2.1a will be notified. However, if the user loads the files with V2.2a, he will not be notified, since it is assumed the bug is fixed in V2.2 if it was fixed in V2.1c. Please do not use this feature unnecessarily. It is intended for use only when a fundamental problem is encountered that undermines the proper functioning of your data files. Name of the author of the data files (maximum of 40 characters). This name is displayed to users within Army Builder to give credit to the author. Email address where the author of the files can be contacted (maximum of 70 characters). This email address is displayed within Army Builder so users know how to contact you with bug fixes and the like that they encounter. Text to be used as a password for locking the file (maximum of 8 characters or none). This password can consist of any combination of printable characters, other than the space (i.e. ASCII codes greater than 32 and less than 127 are legal). If a password is specified, it is encrypted and stored in the run-time definition file. A password-secured definition file can only be converted to a text file via ABUndef if the proper password is provided by the user. If no password is desired, the value none must be specified any other value is treated as a password.
The following shows an example of how the Publish section of a definition file might look within a typical file:
Publish ~ release details for the data files VersionMajor=3 VersionMinor=0 PatchRequired=none AuthorName=Lone Wolf Development AuthorEmail=support@wolflair.com LockCode=none
Stat Definitions The third section is the stats section. This section specifies all of the stats (a.k.a. characteristics) that each unit within the game system will possess. Each stat is listed on its own line, along with all of the pertinent information for that stat. There are a total of seven fields specified for each stat, and those fields are described in the order they must appear below: Abbreviation: Abbreviation to be used for the stat (maximum of 5 characters). For example, a Strength stat might be abbreviated at St or Str. Only alphanumeric characters should be used for stat abbreviations (i.e. letters and digits).
18
Width:
Include in Base?
Minimum Value:
Maximum Value:
Character width to be used for this stat when displaying it within Army Builder (integer value). This width must include space for both the pre- and post-adjustment values, such as in the display of a value like 3/5. For some game systems, the field width shown on the display is wide enough for army construction purposes, but not wide enough for all situations (such as in roster printouts). In such cases, roster printouts need to allow for more space within certain stat fields. To accommodate this need, an optional print width can be specified after the basic field width, using the syntax :xx, where xx designates the width to use for all roster output. If no print width is specified, the basic field width is used for all output. For example, 5:8 indicates that the display field width should be 5 characters and the print width should be 8 characters. Whether to incorporate automatically included options within the base stat value that is shown for a unit (integer value of 1 for yes and 0 for no). Within Army Builder, stat values are shown as two values, separated by a /, when options modify the stat value. This field indicates whether options affecting this field should be folded into the base value or shown as part of the adjusted value. Only options that are automatically included for the unit are folded into the base stat value; options that are purchased are always part of the adjusted value, unless explicitly directed otherwise within the option. Minimum value for the stat (floating point value). This field has a special format of value{=character}. A simple value can be specified for the minimum, or the stat can be defined to substitute a different character when a stat possesses the minimum value. For example, 0=X implies that the minimum value is 0 and any values of 0 or less are replaced with an X when displayed. If the mapping character is given as a ., then no text is output for the stat when the minimum value is reached, allowing this stat to be used as a checkbox (e.g. 1=X for the maximum and 0=. for the minimum). The mapping character can also be given as a _ to always leave the stat blank when the minimum value is reached. Maximum value for the stat (floating point value). This field has a special format of value{=character}. A simple value can be specified for the maximum, or the stat can be defined to substitute a different character when a stat possesses the maximum value. For example, 7=* implies that the maximum value is 7 and any values of 7 or more are replaced with an * when displayed. If the mapping character is given as a ., then no text is output for the stat when the maximum value is reached. The mapping character can also be given as a _ to always leave the stat blank when the minimum value is reached.
19
Visibility:
Is Dice Syntax?
Is Signed?
Decimals:
Separator:
Whether this stat value is hidden from view within the interactive displays and/or roster output of Army Builder (integer value). Also, an optional specification of how the stat should be displayed to the user. There are four visibility levels (0-3). A value of 0 indicates that the stat is always visible. A value of 1 indicates that the stat is hidden from the user within the Army Builder UI. In this case, the information for the stat will ONLY be included in roster output (e.g. printouts). It will also be included with the full information for a unit when that unit is right-clicked within the main roster. This is useful for stats that are not pertinent to roster construction but are useful during game play. When a value of 2 is specified, the stat value is never shown at any time. This is very useful in situations where intermediate derived stats are needed (e.g. calculated expressions), as they can be completely hidden from the user, yet still provide valuable leverage in modeling a particular game system. A value of 3 designates the stat as being visible only on the screen within Army Builder. Roster output of any type will NOT include this stat. This is useful for stats that track resources available during roster construction, where the user needs to view these resources to know how many are left while creating the roster, but they are not needed within the final roster output. Stat values have two components to them. There is a base value and an adjusted value, and these values can be modified separately by data files. If both values are the same, then only a single value is displayed. However, if the values differ, then both values are displayed, typically separated by a / between them. In some cases, you may prefer to only have the final adjusted value displayed to the user, with the base value being suppressed. To accomplish this, specify the letter X (either upper or lower case) after the visibility level. For example, 0x would indicate a visibility level of 0 (always visible) with only the adjusted value ever being shown for the stat. By default, both values are shown, so only the exception must be specified. Whether this stat value uses standard dice syntax for its contents (integer value of 1 for yes and 0 for no). For example, a field whose values are always of the form 2d6+1d4 would utilize dice syntax. When this flag is enabled, the final contents of the stat are processed to consolidate the dice expression into its simplest form. This means that an expression like 2d6+1d4-1d6 would be reduced to 1d6+1d4. If there is other text within the stat value besides the proper dice syntax text, that text is parsed out and appended at the end of the reduced text. Whether the stat value is always output as a signed value (integer value of 1 for yes and 0 for no, with a value of 2 having special meaning). Some game systems have stats that are actually used as modifiers. In this case, the value can range from a positive value to a negative value, and the sign is important. When this flag is specified as 1 or 2, a positive stat value is always prepended with a +. Values of zero for a stat are not prefixed with any notation when a value of 1 is specified, but a value of 2 will always prepend a + to a zero stat. Numbers of decimal digits to be displayed for the stat. This value cannot be larger than 3, which would output all stat values in format 5.000. A value of zero results in whole numbers being output only, with no decimal point being included. All stat values are tracked as floating point numbers internally, until such time as they are output for roster display. Rounding is always performed to the number of decimal digits specified for a given stat. Character to be used as the separator if multi-stat support is leveraged (via the strm attribute). This must be a single character and should be specified as a period (.) if not utilized. For more information on multi-stat capability, please see the strm attribute elsewhere in this document.
20
Prefix/Suffix:
Derived Syntax:
The text to be used as the prefix or suffix of every instance of the stat (maximum of 4 prefix/suffix characters). If no prefix or suffix is desired, then this field should be specified as a period (.). If a prefix is desired, the < character should be followed by the actual text to use as the prefix. For example, to prefix the stat with a d, use the format <d. Adding a suffix is indicated by the > character followed by the actual suffix text to be used. For example, to suffix a stat with a %, use the format >%. If you need to embed a blank space within the prefix/suffix, use the _ character. For example, to append a suffix of thr, specify _thr. Some game systems have stats that should always indicate special notations (e.g. a d prefix for die types, a % suffix for percentages, etc.), and this method allows them to be specified without resorting to the constant use of the stxt attribute and its kin. The formula to be used to calculate the value of this stat at run-time. If this stat is to be assigned a non-calculated value for each unit (which is normally the case), then this field should be specified as a period (.). In some game systems, some stats may actually be computed based on the values of other stats. When this is the case, the syntax for computing the proper stat value must be defined here. The syntax for this field is reasonably flexible, so it is described in the paragraphs below.
If you need to define a stat value that is calculated at run-time based on other stat values, then you will need to specify the derived syntax field. This field allows you to define an arithmetic expression that Army Builder will evaluate to generate the net value for the stat. The expression can consist of up to four terms, and each term can be another stat value, a literal value, or the current model/item count of the unit. The set of valid operators is listed below: + * / ^ @ simple addition simple subtraction simple multiplication simple division (division by zero results in a value of 9999999 as infinity) raises x to the power of y (e.g. x^y) calculates the nth root (e.g. x@3 indicates the cube root of x) Literal floating point value, with an optional sign and/or decimal point (e.g. 3.141) The # character, indicating that the model count for the unit should be used in the calculation The % character, indicating that the item count for the unit should be used in the calculation The abbreviation of a stat value. This abbreviation must be prefixed with either the $ character or the & character. The $ character indicates that the base value of the stat should be used, including only adjustments that specifically are merged into the base stat value. The & character indicates that the adjusted value of the stat should be used, after the effects of all options or items are applied. The stat value selected must already be defined for units, appearing prior to this stat within the list. Since Army Builder performs all stat calculation in sequence, it is illegal for a derived stat to be based upon a stat that appears after it, unless the stat depended upon is not a calculated stat. Multiplies the adjusted value of the Wou stat by 0.75 Multiplies the current model count by 0.25 Adds the base value of the Int stat to the adjusted value of the Wis stat
The syntax for each term in the expression must be one of the following:

The following are a few sample derived stats to give you an idea of what you can accomplish: &Wou*0.75 0.25*# #Int+&Wis
Note! Calculated expressions are evaluated in simple, left-to-right order. Evaluation ignores all standard rules for operator precedence (and parentheses are not supported). Because of this non-standard convention, data file writers must define their formulae carefully. When rendering the proper contents for stats, Army Builder will try to be intelligent about the process. If a stat is at its minimum or maximum and mapping text is specified for the limit value and both the base and adjusted values of the stat are equal, then no prefix/suffix/sign will be included for the stat. This way, ugly output such as
+ or % can be avoided. The stats section for the tutorial definition file is shown below. As a helpful reminder, the section title has a comment following it that lists each of the fields required for a stat definition. In this file, all of the stats have very similar characteristics, but there are a few interesting things to point out. First, scanning down the columns, you will notice that the Ar (armor) stat is the only one which enables the Include in Base? field. This means that all stats except for Ar will show the modifications from included options on the right side of the / within the roster. However, the Ar stat will incorporate those modifications into the base value. For example, if a unit with a base St stat of 3 includes a weapon that increases its St stat by 1, the roster would show it as 3/4. In contrast, a unit with a base Ar stat of 3 that includes an option that increases its Ar by 1 would show it as simply 4, folding the change directly into the base stat value. The next interesting item is again a difference between the Ar stat and all others. All other stats have a minimum value of 0, and, any time that a stat value happens to be 0, the stat value is shown as - instead. In contrast, the minimum value for Ar is 1, and no special handling is performed for such values. The use of the - when when the value is 0 works perfectly for indicating that a particular stat is inappropriate to a particular unit. A value of * might be used to indicate a special condition that arises in a given game system. In the column of maximum values, each stat has its own appropriate limit specified. However, the Ar stat has a maximum value that is handled specially. Whenever an Ar stat is of a value of 7 or more, the stat value is replaced with an X in the roster display.
Stats ~(abbr,width,base?,min,max,hide?,dice?,sign?,frac?,sep,pre/suff,calc) Mv | 3 | 0 | 0=- | 24 | 0 | 0 | 0 | 0 | . | . | . CC | 3 | 0 | 0=- | 10 | 0 | 0 | 0 | 0 | . | . | . MW | 3 | 0 | 0=- | 10 | 0 | 0 | 0 | 0 | . | . | . St | 3 | 0 | 0=- | 10 | 0 | 0 | 0 | 0 | . | . | . To | 3 | 0 | 0=- | 10 | 0 | 0 | 0 | 0 | . | . | . Wo | 3 | 0 | 0=- | 99 | 0 | 0 | 0 | 0 | . | . | . Sp | 3 | 0 | 0=- | 10 | 0 | 0 | 0 | 0 | . | . | . At | 3 | 0 | 0=- | 99 | 0 | 0 | 0 | 0 | . | . | . Ld | 3 | 0 | 0=- | 10 | 0 | 0 | 0 | 0 | . | . | . Ar | 3 | 1 | 1 | 7=X | 0 | 0 | 0 | 0 | . | . | .
Composition Group Definitions The fourth section is the compositions section. This section specifies all of the composition groups to which units can be assigned for this game system. A special composition group named N/A is always created and reserved for use with units whose points either dont matter or should always be inherited by a parent unit (e.g. machine crew, steeds, etc.). Each composition group definition is listed on its own line, consisting of the following fields each: Group Name: Abbreviation: Name of the composition group (maximum of 10 characters). This value is used in the composition report, among other things, in Army Builder. Abbreviation for the composition group (maximum of 4 characters). This value is shown within each of the Filter Buttons in Army Builder.
The list of composition groups within the tutorial definition file is rather short and is shown below. As can be seen, each group consists of its name and abbreviation. The abbreviations will be familiar from when you ran through the tutorial in the Army Builder manual (you did do the tutorial, didnt you? J).
Compositions Hero Troops Machine Allies ~(name, abbrev) | Hero | Trps | Mach | Ally ~(special slot not directly assigned to units)
22
Unit Category Definitions The fifth section is the units section. This section outlines all of the valid categories that units can be assigned to. Each category is listed on its own line, and there are three fields for each category, as described below: Name: Name of the unit category (maximum of 20 characters). The category name is only shown to the user of Army Builder when the category is filtered via the menu. Otherwise, the name is only used within data files. Abbreviation of the unit category (maximum of 3 characters). Whether units belonging to this category should be filtered via the menu (integer value of 1 for yes and 0 for no). If this field is non-zero, then all units which belong to this category are, by default, not shown in the list of Available Units within the Army Builder. Instead, a menu item is appended to the Settings menu which controls whether these units are shown or not.
Abbreviation: Is Filtered?:
As can be seen from the units section of the tutorial definition file (shown below), the set of unit categories introduces a little bit finer granularity than is required for composition groups. There are three different unit categories that we will map to the Hero composition group, namely Hero, Leader, and Wizard. In addition, a special category is defined that enables us to write necessary rules in the data file. As the comment indicates, the Mount category is defined so that we can define the rules that will cause the combination of two options (heavy armor and shield) to adjust a child mounts Mv stat).
Units ~(name, Hero Leader Regiment Wizard Machine Mount N/A abbrev, | her | | ldr | | reg | | wiz | | mac | | mnt | | n/a | filter?) 0 0 0 0 0 0 ~(enables hvyarmor & shd to adjust child's Mv) 0
Option Category Definitions The sixth section is the options section. This section specifies the list of categories to which all options must be assigned. Each option category appears on its own line, and there is only one field for each category: the name. The critical thing about this section is that the list of option categories must be defined in a particular sequence. The categories must appear in the order they are to be prioritized by Army Builder. At run-time within Army Builder, all options are sorted in the order specified in this section (i.e. the first one listed is the first in the sorted order), and then the options are processed. This enables the data file creator to control the order in which options are processed, which is critical to the evaluation of certain options (see the documentation on the data file contents for more information). The sequence of option categories is also used as the order in which available options are shown for a unit in the Options Panel within Army Builder. By grouping all of the related options together and in a consistent order, it makes things easier for the user when creating an army. Name: Name of the option category (maximum of 10 characters). The category name is only used within data files.
The list of option categories defined by the tutorial definition file is extremely simple, but there are a few interesting points to note. In the middle of the list, all of the typical categories are defined, but special categories are included at the end of the list. There is a category simply named First that appears at the very start of the list, plus an additional category near the end that is named Last. These categories provide the means for ensuring that a particular option appears at the start or end of all processing (and at the top or bottom of the list of options shown to the user). The category N/A, at the very bottom, is defined as a special category that unimportant options can be assigned to. For example, the crew of a war machine are attached to the machine via an option, but the option is hidden from the user and there is no special processing that needs to be worried about with respect to the crew. So, the crew option can simply be assigned to the category N/A.
Options ~(categories in sorted order) First ~(option always appears first in list) Standard Weapon Missile Armor Shield Mount Barding Leader Crew Special ~(catch-all just in case something else is needed) Last ~(option always appears last in list) N/A
Conflict Group Definitions The seventh section is the conflicts section, and it delineates all of the valid conflict groups to which options and items can be assigned. A special conflict group named N/A is always created and reserved for use with options and items that dont conflict with anything else (e.g. machine crew). Each conflict group is defined on its own line, consisting of the following fields: Abbreviation: Maximum Count: Abbreviation to be used for the conflict group (maximum of 3 characters). This value is only used within the data files. Maximum number of options/items that may be chosen within this conflict group (positive integer value). As long as this number has not been reached, additional members of this conflict group can be chosen for a unit. The one caveat to this rule is that, when conflict resolution is performed between options and special items, the maximum count is always treated as 1, regardless of its setting. Therefore, maximum count values of greater than one should only be utilized within options, where the count is properly recognized and handled. List of other conflict groups that are implied to also be conflicted by this group. This is a comma-separated list of conflict group abbreviations. When you specify implied conflicts, symmetry is not automatically guaranteed, so you must be sure that all conflicting groups properly identify each other, else the user will experience inconsistent behavior for conflict resolution. For example, in some systems, a single weapon option can be taken, regardless of whether it is one-handed or two-handed. In this case, each of the two groups would need to imply the other group. List of other conflict groups with which this conflict group has a soft conflict. This is a comma-separated list of conflict group abbreviations. A soft conflict is one that deserves a warning but is technically legal (e.g. shields and two-handed weapons).
Implied Groups:
Soft Conflicts:
To help illustrate how conflict groups work and why they are necessary in data files, well start with a few examples. First, two simple examples. If a model is able to select armor, it's only going to be able to select 1 type of armor at a time. So, a conflict group called "Arm" could be defined that all types of armor are assigned to. The maximum number for this conflict group would be set to 1. Wtihin Army Builder, whenever the user selects a type of armor for a model, all other types would be disabled. This way, the user can only ever select 1 type of armor at a time. Some game systems allow models to select up to 2 different weapons at the same time. In this situation, you would have a conflict group that might be named "Wep" and give it a value of 2. All such weapons would be assigned this conflict group. When the user selected weapon options for the model, only a maximum of 2 could be selected at a time. After that, the others would be disabled. Conflict groups get a bit more complicated when you need to make use of the equivalence mechanism. As an example, let's look at the scenario where a model can either have 2 single-handed weapon option or only 1 double-handed weapon option. In this case, there would need to be 2 different conflict groups: one-handed
weapons with a maximum limit of 2 and two-handed weapons with a maximum value of 1. However, we also need to be sure that model with a two-handed weapon can't also be given one-handed weapons. This is accomplished via the equivalence mechanism. If each one-handed weapon is also considered to be a twohanded weapon, then selecting any one-handed weapon should automatically disable selection of any two-handed weapons. This is because the one-handed weapon precludes the selection of two-handed weapons. Similarly, selecting any two-handed weapon should disable all of the one-handed weapons, because the one-handed weapons count as two-handed weapons and no more of them can be taken after a single two-handed weapon is chosen. Getting back to the tutorial definition file, the conflict group definitions are where things really get interesting (shown below). As you can see, these conflict groups make significant use of the hard and soft conflict mechanism. Well focus only on the groups which make use of these conflicts. Weapons in the tutorial can take the form of single-handed or two-handed weapons, so conflict groups are defined for both (Wep and 2Hd). Similarly, there are two groups for magic weapons (MWp and M2H) and two groups for ranged/missile weapons (Rg1 and Rng). In each of these instances, it is not valid to take both a single-handed and two-handed weapon option, so the two conflict groups in each pairing specify a hard conflict with their counterpart. Now, lets look at the soft conflicts. In our simulated game system, it is valid to select more than one weapon or magical weapon for a unit. The only restriction is that it is not possible to use more than one at the same time. Therefore, each weapon group has a soft conflict specified for each of the other weapon groups. Shields are another factor, and they are the reason that a distinction was made between one-handed and twohanded weapons. Each two-handed weapon is defined to have a soft conflict with the shield group, and the exact opposite set of relationships is defined for the shield group. This ensures that any unit which has both a shield and a two-handed weapon is flagged with the proper warning. The final soft conflict is from the group Alt. This group is present in order to support units which have an upgrade option for their bows. The upgrade option itself must NOT belong to the normal group for bows (Rng), because it would then be automatically disabled due to the existing selection of the lesser bow (which belongs to the same group). So, the upgrade option must be assigned to a group that will not conflict with the existing bow selection and that will conflict with the shield. To accomplish this, a special group is defined.
Conflicts Std | Wep | 2Hd | Lnc | MWp | M2H | Rng | Rg1 | Brd | Mnt | Arm | Shd | One | Oth | Alt | ~(abbrev, 1 | | 1 | 2Hd | 1 | Wep | 1 | | 1 | M2H | 1 | MWp | 1 | Rg1 | 1 | Rng | 1 | | 1 | | 1 | | 1 | | 1 | | 1 | | 1 | | max # chosen, implies, soft conflict) ~(standard) MWp,M2H,Lnc ~(normal weapons) Shd,MWp,M2H,Lnc ~(two-handed weapons) MWp,M2H,2Hd,Wep ~(lance) 2Hd,Wep,Lnc ~(magic weapons) Shd,2Hd,Wep,Lnc ~(magic two-handed weapons) Shd ~(ranged/missile weapons w/ 2 hands) ~(ranged/missile weapons w/ 1 hand) ~(barding) ~(mount) ~(armor) 2Hd,M2H,Rng ~(shield) ~(when unit may only have ONE of...) ~(other - catch-all just in case) Shd ~(for upgrade conflicts with shield)
Tweak Category Definitions The eighth section is the tweaks section. Much like the Option Category section (above), this section lists the categories to which all tweaks must be assigned. Each tweak category appears on its own line, and there is only one field for each category: the name. Just like the option categories, the list of option categories must be defined in the sequence in which they are to be prioritized by Army Builder. At run-time within Army Builder, all tweaks are sorted in the order specified in this section (i.e. the first one listed is the first in the sorted order), and then they are processed. This lets data file authors control the order in which tweaks are processed, which is critical to the evaluation of certain tweaks. The sequence of tweak categories is also used as the order in which available tweaks
are shown for an item in the Options Panel within Army Builder. Name: Name of the tweak category (maximum of 10 characters). The category name is only used within data files.
The list of tweak categories defined by the tutorial definition file is empty, as they are not used in the tutorial files. They consist solely of the section heading, which is required within the definition file.
Tweaks ~(categories in sorted order)
Stat Set Definitions The ninth section defines the groupings for custom stat lines used in the data files, which are called stat sets. The advantage of stat sets is that special units (e.g. vehicles, war machines, etc.) can have their own set of stats that are specific to the unit. There is no longer a requirement that one size fits all for unit stats. Stat sets allow nonapplicable stats to be simply omitted, with extra stats being conveniently added. For example, consider an army that consists mostly of standard troops. These troops all have the same set of a dozen stats, and these are the stats that are typically displayed in columns within a roster. The army also contains a small number of special vehicles (e.g. tanks), and these units have a completely different set of stats that pertain to them. While there might be some overlap, there are also additional stats specific to these special units and some standard stats that simply dont apply. A stat set can be defined that consists solely of the set of stats specific to the special unit (including additional stats and omitting others). When the special unit is displayed to the user, the set of stats particular to that unit is displayed instead of the standard set. Any unit which makes use of a stat set will be displayed specially. The typical column-based output is not generated when a stat set is used, since the columns do not necessarily correspond appropriately to the number and/or contents of the stat set. Instead of columnar format, the stats are displayed simply as a text string at runtime (both in the on-screen roster display and in roster output). The contents of each stat in the set are concatenated together, in the sequence defined for the set. Preceeding each stat is a name that is specified for each stat in the set. For example, if the stat set consisted of the three stats Move, Attack, and Defense, the roster output might look like Move: 6 Attack: 5 Defense: 7. Each stat set represents a logical grouping of one or more stats. Each stat set is assigned a name, which is how it is thereafter referenced and used by units at run-time. Each of these stat sets can then define up to ten (10) logical stats that comprise the set. Each logical stat in a stat set specifies a name to be displayed to the user and the actual stat that it maps to. The logical stat is displayed to the user with the assigned name and is manipulated internally within Army Builder via the stat that it is mapped to (i.e. with attributes like "stat", "base", etc.). For example, a stat set could define a logical stat named Armor and have that stat map internally to the actual stat entitled Save within the list of stats. All modifications to the Save stat for the unit would be displayed to the user as an Armor stat. For each logical stat in a stat set, there are three (3) fields that must be specified: the abbreviation of the stat mapped to, the display name, and the visibility of the stat. The abbreviation is the standard stat abbreviation for the physical stat that is being referenced. The display name is the text that is used to prefix the stat contents when it is output. The visibility specifies whether the stat is only visible in roster output (e.g. printouts) or always shown. This section is identied by the section name Sets. Within the section, any number of stat sets can be defined. Each set is introduced by the line set: name, where name is replaced with the name to be assigned to the stat set. Each individual logical stat within the set is then defined on separate lines beneath the introduction line, with the set being terminated by a line containing *end* and nothing else. For each logical stat, there are three fields that must be specified. As per convention within definition files, these fields must be separated by the | character. The first field is the abbreviation assigned to the physical stat that is referenced. This abbreviation must be the same abbreviation used in the first column of the Stats section for the desired stat. The second field is the name that will be used to prefix the stat contents when displayed to the user. It can be any alphanumeric string. The third field must be zero (0) if the stat is to always be displayed to the user both on-screen and within roster output (e.g. printouts). A non-zero value indicates that the stat should only be included within roster output.
A sample stat set section of a definition file might look like the example shown below. In this example, the physical stats Mv, At, Ar, and Ld are referenced. In addition, the Lead stat is designated as only being included in roster output.
Sets Set: Example Mv | Move At | Attack Ar | Armor Ld | Lead *end*
| | | |
0 0 0 1
The list of stat sets defined by the tutorial definition file is empty, as they are not used in the tutorial files. They consist solely of the section heading, which is required within the definition file.
Sets ~(stat sets)
Item Category Definitions The tenth and final section is the items section, governing the various categories that special items can be assigned to. Each item category is defined on its own line and consists of the fields described below. The order in which special item categories appear in the list is important. The order they appear within the definition file is the same order in which they will be listed to the user within Army Builder. When a user brings up the Special Items screen within Army Builder, the drop-down list of available item categories is populated in the order specified, so care should be taken that the list is defined in an appropriate order for the user to view. Name: Abbreviation: Equivalent: Name of the special item category (maximum of 20 characters). This name is shown to the user within the drop-down list of item categories in Army Builder. Abbreviation of the special item category (maximum of 4 characters). Abbreviation of a special item category which this category is to be considered equivalent to. For most item categories, this field will simply contain the abbreviation for this same category. However, sometimes a category must be treated the same as another for conflict purposes. This usually occurs when a selected item category and a constructed item category are considered to be effectively the same category. In this case, one or both of the categories must specify the abbreviation of the other category within this field. Whether only one item of the category can be taken by a given unit (integer value of 1 for yes and 0 for no). If this value is zero, a unit may take as many items from this category as it wants (up to the maximum number it is allowed, of course). Otherwise, the unit may only ever take one item from this category. For example, Heroes might be limited to only one magic weapon, while Wizards might be able to select any number of spells. Whether this item category is made available to all races by default (integer value of 1 for yes and 0 for no). If this value is non-zero, then the item category will be available to all races, although it will only be available to units that can possess this item category. If the value is zero, then no race will have access to this type of item unless they specifically are granted access within the race definition (given in the data file). List of the unit categories which can access this item category (maximum of 30 characters). This is a comma-separated list of the unit category abbreviations which can select this type of item. The list can contain one or numerous unit categories, but only the listed categories can select the item. If no categories are listed, then none can select this category by default. If the literal value *hide* is specified, then this item category is hidden and behaves specially (see below for details).
Is Only One?:
Is Available?:
Units List:
27
Available Slots:
Are Combos Unique?:
Items Charged:
Maximum number of constructed element slots which can be placed upon this item (integer value). This field serves a double purpose, since it also identifies whether the item category represents constructed items or selected items. If the value of this field is 0, then there are no elements and the category governs selected items only. Otherwise, the value specifies the number of constructed element slots that can be placed on each item. For details on how this value is used, please refer to the section detailing Constructed Elements within data files. Whether constructed items within this category must be created with globally unique combinations (integer value of 1 for yes and 0 for no). If this field is 0, then constructed items in this category do not have to have unique combinations of elements. If this field is non-zero, then the combinations must be unique within the army. For item categories that use selected items, this field is irrelevant and should be set to 0. Number of special items that a unit is charged when an item from this category is added to the unit (integer value). Typically, each special item will cost one available slot out of the special items that a unit is allowed to take, so this field will usually be 1. However, there are some instances where items from a particular special item category will cost a unit 2 (or more) of those available slots. There might also be certain categories that are not charged for, in which case the category would be assigned a value of zero for this field.
If the literal value *hide* is specified in the column for valid unit categories, this item category is treated as hidden. A hidden item category is automatically made available to ALL units of all categories but is never shown to the user in the special items display. When designated as hidden, the category automatically sets the is only one field to 0 (unrestricted count) and is available to 1 (all races can access the category). These values override any value specified within the definition file. This mechanism is extremely useful for items that are attached via options purely so that the item can be user-adjusted via tweaks (i.e. the item is never meant for selection via the special items screen). Items that belong to a hidden category are NOT shown to the user anywhere except for the roster grid. If the unit is also able to have regular special items selected for it (via other categories), this functionality will work normally, however the hidden items will not be visible. When the user brings up the special items dialog to edit the items for the unit, no hidden items will be shown, eliminating any confusion that might be caused by having non-removable items appearing in the list. An example where this would be useful is a space fleet game where all ships have their equipment selected via options. The selection of missile bays needs to also specify which types of missiles are available, so the purchase of missile bays uses the take attribute to add an item for missile bays. This item uses tweaks to select the composition of the missile payload. The user does not select any special items for the unit at all it all happens purely via options and tweaks although the item is used to allow for tailoring the equipment. The section which defines special item categories for the tutorial game system has a number of interesting facets. Lets look at each column to see where the different categories vary. The first column of interest indicates whether only a single item can be selected from the category. In this case, only two categories can have more than one item selected from them (Enchanted Items and Wizard Items). If you attempt to select two or more items from one of the other categories, you will be issued a message that says you arent allowed. The next column of interest is the units list. The first two categories of item are made available to Heroes, Unit Leaders, and Wizards. Enchanted Items, though, are not made available to Unit Leaders. The remaining categories are each restricted to a specific type of unit. The ability to differentiate between Heroes, Unit Leaders, and Wizards is critical to implement the proper rules for our special item categories. This is the primary reason that each of these unit categories was defined in the earlier section (instead of lumping them all into a single Heroes category). The next column to the right is also of interest to us. All of the first 5 special item categories specify that there are 0 available slots. This means that each of these categories consists of individual items that the user can select
from. If you remember back to the tutorial, each of these categories presented a simple list of items. The data files will contain numerous items that are identified as belonging to each category, and those are the items that will be displayed to the user. The final category specifies that up to 2 slots can be selected. This indicates that an item of this category is constructed by the user from an assortment of elements. The value of 2 dictates that the maximum number of elements that the user can include in one of these items is 2 elements. Similar to normal items, the set of elements to be displayed is retrieved from the data files and consists of those elements which belong to this category. The rightmost column contains the final noteworthy component of the definition file. All categories have a cost of 1 item, except for the Wizard Spells. This means that each item selected from these categories deducts 1 from the total number of items that a particular unit can be given. The Wizard Spells has a value of 0 in this field, meaning that the user could select as many of these as he wanted. Fortunately, this category is also specified to allow only one item to be chosen from it, so we dont have to worry about this problem. In addition, the category is only available to Wizards. The reason that this category has a value of 0 for this field is that every Wizard gets a single spellbook, independent of whether or not they also select other magic items. If an item was charged for selecting a spellbook, then the Wizard would need to be allowed to take another item, and that item could potentially be used to take an item other than the spellbook.
Items ~(categories sorted Weapon | weap Armor | armr Enchanted Item | ench Wizard Items | wzrd Banner | stnd Wizard Spells | spel name, abbrev, equiv, only one?, show?, | weap | 1 | 1 | her,ldr,wiz | 0 | 0 | | armr | 1 | 1 | her,ldr,wiz | 0 | 0 | | ench | 0 | 1 | her,wiz | 0 | 0 | | wzrd | 0 | 1 | wiz | 0 | 0 | | stnd | 1 | 1 | reg | 0 | 0 | | spel | 1 | 1 | wiz | 2 | 0 | units, 1 1 1 1 1 0
Terminating the Definition File At the end of the definition file, an additional section header must be added that is simply named end. This identifies the end of the file and informs the conversion tool that the file has been successfully completed. No data is allowed to follow the end header, not even comments. If you wish to have any end-of-file comments within your definition file, place them immediately before this symbol in the data file. This is definitely the least interesting part of the tutorial definition file (see below).
End
Generating a Run-Time Definition File Now that you have a reasonable idea of how to create your definition text file, you need to know how to actually convert it into a proper run-time definition file for use within Army Builder. This is accomplished by using the tool ABDef, which is described elsewhere in this document.
29
DATA FILES
Overview Unquestionably, the most complex part of the Construction Kit is the data file. For any given game system, it is the set of data files which describes all of the races, units, options, links, special items, constructed elements, and augmentations that the user can select from. Not only do the data files define each of these components, but they also define all of the subtle inter-relationships between these components. It is through the data files that all of the army composition rules are implemented, as well as all of the exceptions to those rules. There are basically two ways to create run-time data files for use with Army Builder. The first option is to write text files and convert them into the corresponding run-time version via the use of the ABData tool. The other alternative is to use the ABCreator tool instead. Most users prefer using ABCreator, since ABCreator eliminates the need for you to carefully monitor the syntax of potentially large and cumbersome text data files. However, ABData is invaluable in special circumstances where text files must be utilized. The details of each of these tools is described elsewhere in this manual. This chapter describes the details of each component in a data file. Before we launch into that, though, an initial overview of the components and how they are related to one another is necessary. Each of the ten fundamental components is outlined below: Version Info: Version tracking information is included in data files as an optional facility for data file authors. This information allows authors to identify themselves within the files. It also enables users to readily verify whether they are using the latest version of a given data file and quickly determine when they need to acquire a new file. A race represents the basic grouping used by the game system for building armies. The actual term used by a game system might be different (e.g. Clan, Force, Nationality, etc.). These are the combat elements with which a user build his army. An option is something that can be given to a unit, whether it be a weapon, armor, banners, a related unit (e.g. leaders), or anything else. Items represent the special equipment which is available to units within a given game system. These might be magic items, spells, skills, or anything else that is appropriate to a particular game system. Some game systems provide the means to construct a special item from a set of components, each having an individual cost. When an item can be constructed, the pieces it is constructed from are called elements. Links provide the connection between units and options. Both units and options exist independently of one another, and links establish that a particular unit has a particular option available to it. Links can also be defined within the context of a specific unit, which is how they are managed within ABCreator. A tweak is similar to an option, except that it is assigned to items. Tweaks are usually used to let the user customize an item that has been selected. Tweaks are assigned to items in the same way that options are assigned to units. A link nature must be specified to dictate how the tweak is applied to the item, with all of the same link natures being available as for options. The key difference is that tweak assignments are not managed in a separate pool (like links provide), so it is not possible to define new tweak assignments for an item from another data file. Since individual items are not expected to change like units and options do, this ought to be a reasonable restriction.
Races:
Units: Options: Items:
Elements:
Links:
Tweaks:
30
Messages:
Augmentations:
Messages are used in conjunctions with validation rules. Army Builder will generate a validation message for the user when a validation rule is not satisfied, but there are limits to the usefulness of computer-generated messages. Custom validation messages can be defined that are presented to the user in place of the messages generated by Army Builder. It is possible that the need will arise to augment an existing record within another data file in order to fully implement a new data file. For example, a unit (such as a monster) is defined in the main data file for a game system, and that unit is restricted to a small number of races within that main data file. You are creating a new race, and you need to make sure that the monster is available to your race as well, but that would normally require you to modify the main data file. This means that your changes are not decoupled from the main data file. To eliminate this problem, you can augment the attributes of an existing record to include new attributes. For example, you could define an augmentation record for the monster that simply makes it available to the new race, and that augmentation is defined within the new data file. When the data files are all loaded, the augmentation record effectively acts as an extension to the original record, appending its information to the end of that record. Everything is properly encapsulated this way.
In the record descriptions provided in the following sections, each field will typically have its syntax specified. In some instances, the syntax indicated will only be applicable when creating text files and using the ABData tool to convert those files. If you use ABCreator to generate your data files, some of these fields will be presented in a more appropriate visual manner. For example, if the syntax for a field states that it contains an integer value of 1 for yes and 0 for no, then it is obviously a Boolean field and ABCreator will present this as a checkbox. It is left to your good judgement to determine how to handle the translation in cases like this. Races Each race is comprised of nine fields, as described in the table below: Name: Abbreviation: Full name of the race (maximum of 40 characters). Two-character abbreviation that identifies the race. The abbreviation must consist of alphabetic characters (a z) and can NOT start with the letter x (for reasons explained in the documentation on Units). Whether the units within the race should be listed as an independent race or shared as part of other races (integer value of 1 for yes and 0 for no). For example, Monsters in some systems are common to all races and are therefore shared. List of the races which can be chosen as allies for this race. This list is a commaseparated sequence of the abbreviations for each allied race. If this race uses a special composition group to collect the points for allied units, the full name of that composition group should be specified here. Otherwise, this field should be left blank. If you specify a group here, it must appear in the list of groups in the next field. This field describes the set of composition breakdown groups that apply to this race, with each group designated by its abbreviation. The groups are given as a commaseparated list, with each entry complying with specific syntax requirements. The specifics for the valid formats are detailed in the paragraphs following this table. List of the special item categories that are specifically made available to this race. The categories are given as a comma-separated list of the abbreviations for each category. Only the special item categories that are not available by default need to be specified here. List of the special attributes which pertain to this race. This field is formatted as specified for all attributes, and the specific attributes that are available for races are described in another section.
Is Shared?: Allies: Ally Group:
Breakdown List:
Items Allowed:
Attributes:
User Comments:
Arbitrary comments entered by the data file author. Typically, this field is used for reminders and advisory information about how the record is devised and why it is specified the way it is. This field is never seen by the end-user.
As mentioned above, the syntax utilized for defining the composition breakdown of a race requires that each group be separated by a comma. Each individual group must be defined as the group abbreviation, followed by a : character. Thereafter, any number of terms may follow, in any order, with multiple terms being separated by the '&' character. Each term may take one of the following forms: any This form specifies the literal string any as the term contents, and it indicates that the contents of this group can be anything. ?min=XY/Z@S or ?max=XY/Z@S This form for the term allows you to specify a minimum or maximum limitation for the group. The ? specifies which facet of the group will be restricted, and it must be one of: p (total points spent on composition group), % (percentage of roster allocated to group), u (number of units allocated to group), or m (number of total models allocated to group). The min or max simply identifies whether a minimum or maximum restriction is being defined. The value X indicates the basic limit value to impose, and the Y/Z@S is completely optional. If the limit value varies based on the size of the roster, then the adjustment portion of the formula should be utilized. The value Y specifies an adjustment to X, while Z specifies the points interval over which this adjustment should be applied. For example, the term %max=50 indicates that the group cannot exceed 50% of the total army size. The term mmax=1+1/1000 would limit the number of models in the army to 1 in a 500 point game, 2 at 1000 points, 3 at 2000 points, etc. The @S portion is still another optional component, identifying the starting roster size at which the interval should begin being applied. For example, the term mmax=1+1/1000@1000 would trigger the interval to begin when the roster size reached 1000 points, so the limit would be 1 model at 1000 points, 2 models at 2000 points, 3 models at 3000 points, etc. This last term could also have been written as mmax=0+1/1000, but the start value is important if the interval is not equal to the start value. Note! If a group has no size restriction explicitly imposed, then there will be no size restrictions applicable to that group. ?rel?*expr This form allows you to define a comparison relationship between the current composition group and some other set of conditions, possibly including other groups. Both of the ? characters must be one of p, %, u, or m (as described above for the preceeding form). The first ? dictates which value to use for the current group, while the second ? dictates which value to use for any groups specified in the expression (e.g. the model count of one group could be compared to the total points of another group). The * specifies the nature of the comparison and must be one of <, <=, =, >=, or >. The overall expression can consist of up to four (4) arithmetic terms, with these terms combined via +, -, *, or /. Each arithmetic term may be replaced with the abbreviation for a different composition group, and the proper value from that group will be used in the expression. For example, the term urelm>=hero*2 would indicate that the total units for the current group (indicated by the u) must be greater than or equal to the total models (the m) for the Hero group times 2. show=u or show=m This term specifies that the count column in the composition report should show the total number of units (u) or models (m) assigned to the composition group. Note! The default is always to show the total number of units within the composition report, unless specified otherwise. Consequently, you must use the show=m form to explicitly instruct Army Builder to display the model count if that is desired. Note! If you need to modify the composition limits and/or consumption under certain circumstances, you can use
the acmp and allw option attributes for this purpose. Note! The total count of models calculated by Army Builder is not just the total of all models within the roster (or composition group). The model count distinguishes between two types of units within the roster: standard and auxilliary. The total model count accumulated by Army Builder is the total number of standard (i.e. nonauxilliary) models in the roster. An auxilliary model belongs to a unit that is assigned a unique id beginning with 'x', while standard models consist of all other units. Alternately, a standard model can be considered to be any model that is assigned explicitly to a race via its unique id, while auxilliary models are not inherently associated with any particular race. The advantage of this distinction is that Army Builder can properly handle games wherein mounts are separate units for the purposes of stat lines but are not treated as separate models for model counting. By simply specifying the mounts as an auxilliary unit, they are not counted in the totals. Units Units are the largest record type, and they consist of 16 base fields. In addition to these 16 fields, each unit must also specify the initial values for each of the stats identified in the definition file. Unique Id: Unique identifier that is specific to this unit and adheres to the rules specified previously for unique ids. The unique id for a unit must comply with one additional special rule. This rule requires that the first two characters of a units unique id be the two-letter abbreviation of the race to which the unit belongs. This leaves an additional 6 characters for you to define a meaningful identifier. For example, an Elf unit of Heavy Infantry might be assigned the unique id elhvyinf. There is one exception to this rule, which is described later on in this section. Name of the unit (maximum of 40 characters). Abbreviation for the unit that is displayed in parentheses if the unit is given a special name by the user (maximum of 5 characters). Name of the composition group to which this unit belongs. The group you specify must be one of the groups listed for the race that this unit belongs to. If not, then the points for this unit will be treated either as ally points or ignored, depending on various other conditions within Army Builder. There are often units for which there is no appropriate composition group to assign (e.g. war machine crew, horses, etc.). Any points for these units should automatically be assigned to the parent unit that the secondary units are associated with. For this reason, the special group N/A can be assigned to your unit and the points for the unit will be automatically transferred. Note! It is illegal to specify the group N/A for a top-level unit. It is also illegal to specify the group N/A for a unit to which you wish to assign special items. If you attempt either of these, then you will likely encounter erroneous run-time results within Army Builder. Name of the unit category to which this unit belongs. This category is used to determine which special item categories the unit can gain access to, as indicated within the definition file. Name of the unit type to which this unit belongs. This is a simple text field that will be empty for most units. A custom type name can be entered here for use in conjunction with some of the special attributes. This type value allows multiple units to be assigned to a common grouping, enabling those groups to be referenced and operated upon for various purposes.
Name: Abbreviation: Composition:
Category:
Type:
33
Size:
Cost: Item Count: Local Attributes:
External Attributes:
Links:
Notes:
Report:
Comments:
Description of the size characteristics of the unit. This field has up to three separate components, although only one is required. The complete format of this field is minimum{:maximum{:increment}}, representing the minimum (and initial) number of models in the unit, the maximum number of models, and the number of models to increment by when the user presses the + or - buttons within Army Builder. Each of these components is separated by a colon, but only the minimum/initial size is required. A regiment that must have 5 models in it and has no maximum size would be listed simply as 5, since the maximum size is unbounded and the increment size is 1 model (both the default interpretations). For a hero that there can only be one of, the size would be 1:1. A unit that can only be taken in pairs would be listed as 5:0:2, where the 0 indicates that there is no maximum size and the 2 indicates the increment size. Base cost of the unit (positive floating point value), exclusive of any and all options for the unit. Maximum number of special items that the unit may possess at one time. List of the local special attributes which pertain to this unit. Local attributes are those that operate within the context of the unit, effecting options and child units (like a horse). This field is formatted as specified for all attributes, and the specific set of local unit attributes is described in another section. List of the external special attributes which pertain to this unit. External attributes are those that operate outside the context of the unit, having an effect upon other units (like a requirement that another unit must be in the army in order for this one to be included). This field is formatted as specified for all attributes, and the specific set of external unit attributes is described in another section. List of the options that are directly linked to this unit. This field contains a commaseparated list of the options and the nature of the link. The syntax for each option is option=nature, consisting of the unique identifier of the option, followed by an =, followed by a valid code for the link nature (one of: cost, incl, auto, free, hide, or appl). The options linked to the unit can be defined here or they can be defined via a separate set of links records within the data file, at your discretion. For more information about links, please refer to the documentation on Link records. Description of the unit that you want to appear in all output regarding the unit, whether it be to the screen or a printout. If there are multiple notes for the unit, the convention is that each individual note is separated by a semi-color and a space. When displaying notes on the screen, line breaks are automatically inserted when the ; pair is encountered. Description of the unit that you want to only have appear within printouts. As with the Notes field, the convention is to separate individual statements via the ; pair. Sometimes, descriptive text for a unit is quite lengthy, being too long to show on the screen. There are also times where it just isnt appropriate to include all the extra text on the screen. In these cases, that data can be placed within this field and it will only appear in reports. If Notes text is also specified for this unit, the Report text is appended after the Notes text. Description of the unit that will only appear on the screen, also using the ; separator between statements. This field is perfect for reminders that are useful during the creation of an army but irrelevant at game-time. For example, adding a reminder that this unit requires another unit within the army is only applicable at the time the army is built and would be perfectly suited here. If Notes text is also specified for this unit, the Comments text is displayed prior to the Notes text.
34
User Comments:
Stat Value:
Arbitrary comments entered by the data file author. Typically, this field is used for reminders and advisory information about how the record is devised and why it is specified the way it is. This field is never seen by the end-user. The initial value must be specified for each stat that exists for the unit. The number of stat values and their sequence is given in the definition file. Each stat field must contain a floating point value, representing the initial value of the stat for the unit.
As mentioned above, there is a special case where units do not have to be named with the prefix of the race they belong to. This applies to units that are considered auxiliary units, which are those units that are support units to other units and have little or no strategic importance when constructing an army. Typically, these will consist of units like war machine crew and horses, where the primary unit is the important consideration. You can define an auxiliary unit by assigning the first letter of its unique id as the letter x (lowercase). Auxiliary units are never displayed to the user, except when specifically referenced via options for other units. This is a convention supported by Army Builder which eliminates the need for using the hide attribute on numerous units (described later). Note! If a unit is to be assigned any special items, then it must begin with the proper prefix for the race that it belongs to. Auxiliary units are not allowed to possess special items. Note! If a unit is assigned an item limit of 99 or greater and the unit is also assigned a point limit on items possessed (via the ipts attribute), then Army Builder will display the number of remaining points of items that may be assigned to the unit instead of the number of items. Note! If a unit is assigned an item limit of 999 or greater and the unit has no point limitation imposed (see above), then Army Builder will not display any mention about the number of items allowed to the unit. Options An option record consists of the fields outlined below: Unique Id: Name: Unique identifier that is specific to this option and adheres to the rules specified previously for unique ids. Name of the option (maximum of 30 characters). This field is output in all reports to identify the option before its description is given. If you want to only print the description and not print the name of the option, then assign this field an empty name or the value Empty. Abbreviation for the option (maximum of 5 characters). This abbreviation is shown within the Options column when the option is selected for a unit. It is not required that an option have an abbreviation. In fact, there are many instances where you may want the option to not have an abbreviation. If an option is assigned an abbreviation, then the contents of its Notes field is always rendered when the option is output. However, if the option does not have an abbreviation, then the Notes field will not be output. An example of an option that does not need an abbreviation is an option to add a leader to a unit. The leader is listed beneath the unit, so no option needs to be redundantly identified. Name of the option category to which this option belongs. This category governs the sort order of all options and the order in which options are processed for a unit. List of the conflict groups to which this option belongs. This is a comma-separated list of the applicable conflict group abbreviations. If you need to specify a different set of conflicts for an option under certain circumstances, you can do so with the xcon attribute. Cost of the option (floating point value, positive or negative). List of the special attributes which pertain to this option. This field is formatted as specified for all attributes, and the specific set of option attributes is described in another section.
Abbreviation:
Category: Conflicts:
Cost: Attributes:
Comments:
Notes:
Report:
User Comments:
Description of the option that you want to appear only in output to the screen. The convention is that multiple notes are separated by a semi-color and a space. If Notes text is also specified for this option, the Comments text appears prior to the Notes text. Description of the option that you want to appear in all output, whether it be to the screen or a printout. The convention is that multiple notes are separated by a semicolor and a space. Description of the option that you want to appear in all printouts pertaining to the option. The convention is that multiple notes are separated by a semi-color and a space. If Notes text is also specified for this option, the Report text is appended after the Notes text. Arbitrary comments entered by the data file author. Typically, this field is used for reminders and advisory information about how the record is devised and why it is specified the way it is. This field is never seen by the end-user.
Links The content of each link record consists of the following three fields: Unit Id: Option Id: Link Nature: Unique identifier of the unit to which the option is associated. Unique identifier of the option which is associated with the unit. The nature of the association between the unit and the option. This value must be one of the following values: cost: Option is selectable by the user and costs points when selected; free: Option is selectable by the user and does not cost points when selected; auto: Option is automatically selected for unit and costs points; incl: Option is automatically selected for unit and is free of charge; hide: Option is hidden by default, is selectable by the user, and costs points. appl: Same as incl, except that any adjustments made to the base value of stats by the option are assumed to already be included in the stats for the unit and are not reapplied non-base adjustments are applied normally.
The first four link natures are pretty simple and self-explanatory, as they cover the four standard situations that need to be modeled within data files (i.e. whether the option is user-selectable and whether the cost of option needs to be charged). The last two link natures, though, have special uses that could benefit from a more detailed explanation. The hide link nature is really just a combination of the cost link nature and the hide option attribute. Using this link nature eliminates the need to designate the option itself as hidden, since a particular option may need to be hidden sometimes and visible at other times. The appl link nature is very similar to the incl link nature, with one very important distinction. When appl is specified, all adjustments of base stat values by the option are ignored, as they are assumed to already have been applied to the base stat values of the unit. All other adjustments made by the option are applied normally. The advantage of this link nature is that you can adjust the armor value (or some other stat value) directly into the base stat value for a unit, yet still attach the proper option for its description and side effects. Without this appl link nature, the incl nature must be used, and a unit that comes with armor that adjusts is defense value must be defined without the effects of the armor included in its stats. Using incl, when the unit is added to the roster and the armor is added to the unit, the armor adjustments are applied, so the basic unit must be listed without including this adjustment. This can lead to confusion for the user, since the unit information in the list of Available Units is not what he expects. By using the appl attribute, the adjustments for the armor can be built into the basic stat values for the unit, and they will not be re-applied when the unit is added to the roster.
36
Items Each special item record consists of the fields defined below: Unique Id: Name: Category: Conflicts: Cost: # Available: Unique identifier that is specific to this special item and adheres to the rules specified previously for unique ids. Name of the special item (maximum of 50 characters). Abbreviation of the special item category to which this item belongs. List of the conflict groups to which this special item belongs. This is a commaseparated list of the conflict group abbreviations. Cost of the special item (positive floating point value). Total number of instances of this item that can be chosen within a single army at the same time. As soon as this number is reached, the item can no longer be added to units without triggering a validation error. List of the special attributes which pertain to this special item. This field is formatted as specified for all attributes, and the specific set of special item attributes is described in another section. Description of the special item that is to be displayed within the Roster in Army Builder when the item has been assigned to a unit. Description of the special item that is to be displayed when the special item is highlighted on the Special Items screen in Army Builder. This field can also incorporate the contents of the Comments field as a convenience, if desired (see below). Description of the special item that is to be output when the special item is printed in reports by Army Builder. This field can also incorporate the contents of the Notes field as a convenience, if desired (see below). Arbitrary comments entered by the data file author. Typically, this field is used for reminders and advisory information about how the record is devised and why it is specified the way it is. This field is never seen by the end-user.
Attributes:
Comments: Notes:
Report:
User Comments:
For the units and options records, the contents of multiple fields are often automatically appended to each other when being output (i.e. comments are included in notes, comments and notes are included in report). In contrast, the Special Item fields Comments, Notes, and Report are completely independent of each other, with only one being rendered at the appropriate time. However, it is possible to selectively include the contents of one of these three fields into another. If the ^ character appears anywhere within the Notes field, the contents of the Comments field is inserted into the Notes field at that point. Similarly, if the ^ character appears anywhere within the Roster field, the contents of the Notes field is inserted into the Report field at that point. This process cascades, so both the Roster and Notes fields can contain a ^, in which case the contents of the Comments field will appear within the Roster field. The advantage of this mechanism is that lengthy descriptions can incorporate shorter descriptions for the same item without requiring that the same data be reentered for each field. When a single short description is sufficient for all fields, it can be entered into the Comments field and then the other two fields can simply inherit the contents. Elements Element records comprise fourteen fields, each of which is described below: Unique Id: Name: Abbreviation: Category: Unique identifier that is specific to this element and adheres to the rules specified previously for unique ids. Name of the constructed element (maximum of 50 characters). Abbreviation for the element (maximum of 5 characters). Abbreviation of the special item category for which this element can be chosen as a component of an item.
Conflicts: Cost: Max # Taken:
Slots Used: Is Unique?: Attributes:
Comments: Report: Min # Taken:
User Comments:
List of the conflict groups to which this element belongs (and, therefore, to which the item will belong). This is a comma-separated list of the conflict group abbreviations. Cost of the element (positive floating point value). Maximum number of times that this element can be chosen on a single item (integer value). If this slot is specified as 0, then the element will automatically be assigned a maximum value equal to the total number of slots that are available for the item category. Number of available slots consumed each time that the element is chosen for an item (integer value). For a description of how this works, see below. Whether this element must be globally unique, only being able to be taken on a single item within the army (integer value of 1 for yes and 0 for no). List of the special attributes which pertain to this element. This field is formatted as specified for all attributes, and the specific set of element attributes is described in another section. Very brief description of the element that is used when a description of the containing item is shown in the Roster display in Army Builder. Full description of the element that is used when element is printed out in a roster by Army Builder. Minimum number of times that this element can be chosen on a single item (integer value). If this slot is specified as non-zero, then the element is required to be included on every constructed item for which it is available. Arbitrary comments entered by the data file author. Typically, this field is used for reminders and advisory information about how the record is devised and why it is specified the way it is. This field is never seen by the end-user.
Constructed items dont have a name, since each item is defined by the combination of elements that comprise it. However, some sort of name is required when the item is listed beneath the unit which to which it is assigned within Army Builder. To accommodate this, a name is synthesized by Army Builder, consisting of the abbreviations for the elements on the item and the number of times each element appears on the item. Take this into consideration when deciding upon the abbreviation you assign to each element. When the user creates a constructed item, there are three important values that all work together to determine what constitutes a valid item. These values determine whether the button to create an item within Army Builder is enabled or not. The three values are the Max # Taken and Slots Used fields for an element and the Available Slots fields for the item category being constructed. The Available Slots value determines the total number of slots that constitute a legal item. As long as at least one slot is used and the number of slots used is less than or equal to the total number of Available Slots, the item is considered valid and can be created. When an element is selected for an item, the number of slots it uses up is equal to the number of Slots Used for the element multiplied by the number of times the element appears on the item. For example, if an element uses up 3 slots and is chosen 2 times for an item, a total of 6 slots are consumed within that item. Tweaks An tweak record is almost identical to an option record and consists of the fields outlined below: Unique Id: Name: Unique identifier that is specific to this tweak and adheres to the rules specified previously for unique ids. Name of the tweak (maximum of 25 characters). This field is output in all reports to identify the tweak before its description is given. If you want to only print the description and not print the name of the tweak, then assign this field an empty name or the value Empty.
38
Abbreviation:
Category: Conflicts:
Cost:
Attributes:
Comments:
Notes:
Report:
User Comments:
Abbreviation for the tweak (maximum of 3 characters). This abbreviation is shown within the Options column when the tweak is selected for an item. It is not required that a tweak have an abbreviation. In fact, there are many instances where you may want the tweak to not have an abbreviation. If a tweak is assigned an abbreviation, then the contents of its Notes field is always rendered when the tweak is output. However, if the tweak does not have an abbreviation, then the Notes field will not be output. Name of the tweak category to which this tweakbelongs. This category governs the sort order of all tweak and the order in which tweaks are processed for an item. List of the conflict groups to which this tweak belongs. This is a comma-separated list of the applicable conflict group abbreviations. Conflict resolution for tweak is completely decoupled from options, so the same conflict groups can be used between the two and no conflicts will be recognized between them. Cost of the tweak (floating point value, positive or negative). The cost characteristics of a tweak contribute to the cost of the item, with the net item cost being treated normally for the unit. List of the special attributes which pertain to this tweak. This field is formatted as specified for all attributes, and the specific set of tweak attributes is described in another section. Description of the tweak that you want to appear only in output to the screen. The convention is that multiple notes are separated by a semi-color and a space. If Notes text is also specified for this tweak, the Comments text appears prior to the Notes text. Description of the tweak that you want to appear in all output, whether it be to the screen or a printout. The convention is that multiple notes are separated by a semicolor and a space. Description of the tweak that you want to appear in all printouts pertaining to the option. The convention is that multiple notes are separated by a semi-color and a space. If Notes text is also specified for this tweak, the Report text is appended after the Notes text. Arbitrary comments entered by the data file author. Typically, this field is used for reminders and advisory information about how the record is devised and why it is specified the way it is. This field is never seen by the end-user.
Custom Validation Messages The fields of a custom validation message record are described below: Unique Id: Name: Message: Unique identifier that is specific to this message and adheres to the rules specified previously for unique ids. Name of the message (maximum of 30 characters). This field is only used as a visual reference within the data files and ABCreator. The actual message text to be displayed to the user, which can be up to 500 characters in length.
The message text for a custom validation message will typically just be a string of text that is displayed to the user. However, there are certain validation attributes that are generalized in nature and may trigger for a range of situations. An excellent example is the scmp attribute that verifies that the stats for a unit observe a particular relationship. The scmp attribute will be performed for all units, so the validation message should identify which specific units actually failed to comply with the rule. Custom messages allow you to insert the non-compliant unit name into the message that is displayed to the user. To achieve this, simply specify the two characters ^ and u (or U), and Army Builder will perform the correct insertion for you when the validation fails. Only a portion of validation attributes utilize this special field, and any
use of a field that isnt applicable for a validation message will result in an empty string being inserted. Each validation attribute that defines this special field value will be flagged as such within its description. An example of a custom message for the scmp attribute would be Unit ^u failed stat comparison. Augmentations The fields of an augmentation record are described below: Augmentation Type: An augmentation record always modifies an existing record, which must be one of the other record types, excluding links. Since augmentations specify new attributes to be assigned to the record, separate augmentations must be defined for the external and local attributes of a unit. Consequently, there are seven valid types for an augmentation record: race: Augments a race record external: Augments the external attributes for a unit record local: Augments the local attributes for a unit record option: Augments an option record item: Augments an item record element: Augments an element record tweak: Augments a tweak record Unique Identifier: The augmentation record modifies a single record, so the record itself must be uniquely identified. If the type indicates a race record, this field must give the unique prefix for the race to be augmented. For any other type of record, this field must contain the unique id for the record. When the data file is loaded by Army Builder, if a record with the specified type and unique identifier does not exist, an error is reported. List of the special attributes to be appended for the specified record. The attributes Attributes: that are given must be valid for the augmentation type being performed (e.g. only race attributes are valid for a race augmentation record), else an error is reported. If you need to augment both the local and external attributes for a unit, then you will need to create two separate augmentation records. It is valid to list multiple attributes within an augmentation record, just like a normal attribute specification for a given record type. User Comments: Arbitrary comments entered by the data file author. Typically, this field is used for reminders and advisory information about how the record is devised and why it is specified the way it is. This field is never seen by the end-user. Version Information Data files will be periodically enhanced and/or have corrections introduced. This is especially true if data files for complex game systems are created and shared by numerous users (e.g. across the Internet community). Consequently, it is important to have some way of attaching version information to a data file, as this gives users everywhere the ability to ascertain whether they are using the latest version and/or need to acquire new files. To facilitate version tracking of data files, there are a total of five information fields that are stored within a given data file, as described below: Description: Version: Author: This field provides a brief description of the data file, which can contain any single line of text. This field designates a version number of some sort for the data file. This version number is a simple text string, so any versioning syntax may be used by the author. This field defines the name of the data files author. The name given may be anything desired (a real name, a handle, etc.).
40
Lock:
Comments:
This field specifies whether the authoring information in this data file is to be locked from modification. If ABCreator is used to edit this data file, the user will be unable to change the authoring information or save the file as text, although all other facets of the data file can be edited and changed. Locking the data file is optional, so this state may be enabled or not. Beginning with V2.1 of Army Builder, most author information now resides in the definition file, so there is little reason to lock data files anymore. However, this functionality is still present in case you want to use it. The version information can contain a very long block of text that serves as the comments for the data file. The comments may contain carriage returns. This section is ideal for placing notes and suggestions to users of your data file that may want to create their own files that integrate with yours.
One other piece of information is stored as part of the versioning data. This final piece is not editable in any way by the creator of the data file, as it is the date and time when the data file was last created/modified. Since the date and/or time stamp of a file can be easily changed when you copy or download it, this practice ensures that the original date/time information will always be embedded within the data file. With this additional information, users will always be able to determine whether they have a particular version of a file or not. Validation of Data Files When you are creating your data files, please remember that not all validation can be performed outside of Army Builder. The tools within the Construction Kit (i.e. ABData and ABCreator) do as much validation of the generated data files as is possible. When errors are encountered, an appropriate error message is reported so that you can make the correction. However, not all errors can be caught when creating a data file. Since multiple data files can be created to work in conjunction with one another, the contents of one data file can reference the contents of another data file. This means that the creation of one data file cannot, for example, verify that all of the referenced links properly exist, since they might exist in a separate file. Problems like this can only be caught by Army Builder itself, after it has loaded all of the data files. Only then can it properly verify that all references between components actually exist and are legal. If an error occurs, Army Builder will inform you which reference is invalid and then exit, allowing you to correct the problem in the data file and try again. File Syntax This section is only pertinent to you if you are creating your data files as text files and then converting them to run-time files using the ABData tool. Most users will utilize ABCreator for this purpose, in which case this section will serve only to make your eyes cross and then water. The syntax used for data files is completely different from the syntax for definition files. The reason for this is that the information in data files is much more extensive and complex. Data files are essentially a database stored in a text file, so they use the traditional syntax of delimiting records with carriage returns and delimiting fields with tabs. This means that each database record will appear on its own line, since a carriage return indicates the start of a new record. Within each line (or record), there will be multiple fields, and all fields on the line will have a tab between them. Tabs only appear between fields. There is no tab at the start of the line or at the end. An example set of records is shown below, with the symbol indicating a tab in the data and the symbol indicating a carriage return at the end of each line:
fieldA1 fieldA2 fieldA3 fieldA4 fieldA5 fieldA6 fieldB1 fieldB2 fieldB3 fieldB4 fieldB5 fieldB6 fieldC1 fieldC2 fieldC3 fieldC4 fieldC5 fieldC6
Data files can get quite complex at times, depending on the level of sophistication that you want to provide within the data file. Because of this, it is likely that you will want to include comments within your data files, providing reminders to yourself (or others) as to why you chose to implement certain components in a particular way. Comments use the same syntax as for definition files, using the ~ character, except that the comments in data files may only appear at the start of a line/record. If the ~ is placed anywhere on the line other than the very first character, the line is treated as a normal record. This ensures that you can make use of the ~ character within your data fields if you wish.
There are multiple types of records that appear in a data file (races, units, options, etc.), and each contains a different set of fields. Consequently, there needs to be a means of identifying where one group of records stops and the next one begins. This is accomplished by inserting a ^ character on a line all by itself (i.e. there must also be a carriage return at the end of the line). When the ABData tool encounters a record that consists only of a ^, it knows to stop reading the previous record type and start to read the next one. As just mentioned, each data file contains multiple types of records. There is a separate type of record for each of the different pieces of information within the data file, specifically: versioning, races, units, options, items, elements, tweaks, links, augmentations, and messages. The syntactic details for each of these record types is described in the following paragraphs. Within the data file, each of these record types must be included in the order just given, since that is the order expected by the ABData tool. If the records are given in any other order, or if any section is omitted, an error will occur during the parsing of the data file and you will be required to correct the problem. Since each group of records must be included, your data file will always contain eight sections. Each of these sections will be separated by a ^ character on its own line, and you must also include a separator at the end of the last group. It is quite possible that your data file wont have any records within a group of records. In this case, you will simply have no records for the group, with two separator lines in sequence. The example below shows a valid data file that contains no records of any type (it contains only comments and group delimiters):
~Version info Description: Version: Author: ^ ~Race records ^ ~Unit records ^ ~Option records ^ ~Item records ^ ~Element records ^ ~Tweak records ^ ~Link records ^ ~Augmentation records ^ ~Message records ^
The very first thing that appears in any data file is the version information section. The first line of the section contains the description. This line begins with the string Description: (case does not matter), followed by any amount of white-space, followed by the actual description text itself. The second line designates the version number. The line must begin with the string Version: (case is irrelevant), followed by any amount of whitespace and the version string itself. The third line defines the data files author, and the syntax for the line consists of the string Author: (in any case), followed by white-space and the authors name. The fourth line is optional and specifies whether the authoring information in this data file is to be locked from modification. To lock the data file, the line must contain the string Lock (in any case) and nothing else (not even any comments). If the file is not to be locked, then this line does not need to appear. The remaining lines of this section are interpreted as public comments for the data file that are embedded into the run-time data file. There can be any number of these comment lines (even zero), and the comments end when the group delimiter is encountered on its own line. These comment lines should not begin with a comment delimiter (~), as these lines are intended to be visible to users who will make use of the run-time version of the data file.
42
As an example, the following sequence of lines might constitute the version information section of a possible data file:
~This is just a comment line that is ignored. Description: Sample Data File for Use with XYZ Game System ~Another comment that is ignored. Version: V1.23a Author: Freddy Boy Lock ~optional line that specifies the authoring info should be locked This is the first line of the public comment block. ~Another comment line that is ignored and NOT included in public comments. This is the second line that is part of the public comment block. And the third (and final) line of the public comments. ^
Within the remaining seven sections, each group of records is defined using the syntax described above. The fields for each record must be listed in the order that they appear in the preceding sections of this document. The only group of records which requires special handling is the units group. In addition to the standard 15 fields, each unit must also specify the values for each of the stats identified in the definition file. For each unit record, the first fields listed must be the base fields, immediately followed by a list of the stats for the unit. The stat fields must be given in the order that they are given in the definition file. This means that each unit record for a game system with 10 stats would consist of 25 fields, with the first 15 fields being those defined earlier and the following 10 fields corresponding to the 10 stats for the record. There is one last consideration when creating text data files. Link records may be specified in two separate ways, depending upon your preference. There is an entire group of records dedicated to link records, but it is also valid to specify all of the options for a unit within the definition of the unit record. While it is possible to use both methods within the same data file, it is strongly recommended that you do not use a mixture of these two methods, since the maintenance of a mixed solution can be very problematic. Note! If you need to create an empty field within a text data file, simply have no contents for the field. This will result in two tabs in direct sequence, which will be translated by ABData as an empty field.
43
CORE DATA FILE CONCEPTS

Overview This chapter describes some of the fundamental concepts associated with data files. These mechanisms are leveraged in multiple ways by the Construction Kit, so anyone writing data files should be aware of them before proceeding. Boolean Expressions There are a number of attributes that utilize complex boolean expressions. There is no limit on the number of terms that can be specified within a boolean expression (the maximum length of an attribute serves as the only imposed limit). In addition, parentheses may be used freely within a boolean expression, being nested to any number of levels desired. Each instance where boolean expressions are used will require a different syntax for the individual terms, but the overall syntax of the expressions will always be the same. The boolean operators that are supported are listed below: & | ^ ! Logical AND Logical OR Logical XOR Logical NOT
Given the above syntactic rules, the following expression would be valid, assuming generic terms: foo&!(bar|baz) This expression would evaluate the term foo, then it would evaluate the terms bar and baz. The terms bar and baz would be ORd together, then the result would negated. This result would be ANDd with the term foo to yield a final result of either true or false. Calculated Expressions Arithmetic expressions are used extensively within attributes for calculated the necessary adjustments to stats based on other events during roster construction. The syntax for calculated expressions is the same for all attribute usage, with an expression consisting of up to four terms. Each term in the expression can be another stat value, a literal value, the current model count of the unit, or the current item count possessed by the unit. The set of valid operators that can be used is listed below: + * / ^ @ simple addition simple subtraction simple multiplication simple division (division by zero results in a value of 9999999 as infinity) raises x to the power of y (e.g. x^y) calculates the nth root (e.g. x@3 indicates the cube root of x) Literal floating point value, with an optional sign and/or decimal point (e.g. 3.141) The # character, indicating that the model count for the unit should be used in the calculation The % character, indicating that the item count for the unit should be used in the calculation The abbreviation of a stat value
The syntax for each term in the expression must be one of the following:

Note! Calculated expressions are evaluated in simple, left-to-right order. Evaluation ignores all standard rules for operator precedence (and parentheses are not supported). This means that the expression 2+3*4 will result in a value of 20 instead of the standard 14, since it will be evaluated as (2+3)*4.Because of this non-standard convention, data file writers must define their formulae carefully. Note! Calculated expressions that modify a stat value are not allowed to reference the same stat wtihin the expression.
Note! Calculated expressions that reference the number of items will actually get the number of item slots consumed by items taken by the unit. If a particular item consumes zero slots, then it will not be counted in the value used for the calculation, and items consuming multiple slots will count as more than one. Rounding and Clipping of Stat Adjustments When stats are adjusted and/or calculated via attributes, it is possible to force the adjusted value to be rounded off immediately after the adjustment. There are three rounding options available, as described below: round Performs normal rounding on the result, rounding up on a value of .5 or higher and down otherwise. Using "-round" will ensure that two separate adjustments do not combine their fractional portions into an unwanted result. For example, one adjustment of +2.3, followed by +3.4, would yield a net +5.7, which would get rounded to 6 normally. Using "-round" after each adjustment would yeild +2 and +3, for a net of +5. Ensures that the resulting value is always rounded up to the next higher value. Always rounds down to the next lower value.
roundup roundddown
If decimals have been specified for the stat being adjusted, the rounding is always performed to the number of decimals assigned to the stat. For example, an adjustment of 1.26 on a stat with 0 decimals would be rounded to 1 or 2, depending on the method chosen. That same adjustment of 1.26 on a stat with 1 decimal would be rounded to either 1.2 or 1.3, depending on the method. It is also possible to perform clipping on stat adjustments. Clipping is very similar to rounding, except that clipping is performed before the adjustment is applied to the stat. This makes for a very important difference when the stat is being multiplied or divided or if a rang attribute is being used to trigger the adjustment multiple times. The three available clipping options are described below: clip Normal rounding should be performed on the adjustment value before it is applied. The accuracy of the rounding is dictated by the number of decimals specified for the statistic. Always rounds the value upwards before it is applied. Always rounds the value down before it is applied.
clipup clipdown
To demonstrate how clipping differs from rounding, consider a situation where a calculated adjustment generates the value 1.3. Adding this value to the current stat and rounding afterwards will yield the same result of a net +1. However, consider the situation when this adjustment is attached to a "rang" attribute with a range of 0-10. If the range is chosen as 10 and normal rounding is performed AFTER the adjustment is applied, the net adjustment will be +13 (1.3 * 10). However, if clipping is used instead, the adjustment will be clipped to 1 before being applied 10 times, resulting in a net adjustment of +10. The same logic applies if the adjustment is being multiplied into the stat value without a "rang" attribute involved. Race and Mode Restrictions Most record types and numerous attributes (usually validation rules) can be restricted so that they are only applicable under specific conditions. For records, this is controlled through the legl and lglx attributes. For attributes, this is controlled via a number of special qualifiers. The various conditions that can be controlled include a combination of the following factors: The primary race matches a specified race (the primary race is the race the user is creating a roster for). The currently selected mode satisfies a defined relationship with a specified mode (the currently selected mode is the mode the user selected when the roster was created). The currently selected mode satisfies a defined timeline relationship with a specific time. Race comparisons always compare the primary race against a reference race. The primary race is always implied, and the reference race is given by its two-letter prefix. The comparison is restricted to determining if the primary race is the reference race or is not the reference race. Similarly, mode constraints always compare the current mode against a reference mode, with the current mode
always being implied. The reference mode is specified by its abbreviation and can be compared against the current mode in a number of ways. First of all, simple equality can be tested for (e.g. mode=xyz), in which case the attribute is considered valid if the current mode is equal to the one specified. It is also possible to test against the set of modes which are alphanumerically greater or less than the specified mode (using <= or >= in place of the =). When this syntax is used, all of the modes are sorted alphanumerically by their abbreviation, and case is important (so ab would be sorted after XY). If the current mode satisfies the specified relationship, then the attribute is considered valid. As a special case, the default mode is always considered to be the lowest in the sort order, so it will always be less than any other mode. To help clarify how mode comparisons work, consider a data file where there are four different modes defined, as outlined below: mode:one="This is mode #1" mode:two="Another mode" mode:THREE="Third mode" mode:four="Last mode" The user will only see the long names for these modes (given in quotes), but Army Builder uses the abbreviations internally when referencing modes. Since string comparisons of the abbreviations are used and case is important, the four abbreviations would be sorted internally in the following order: THREE, four, one, two (remember that upper case always sorts before lower case). Given this sorted sequence, a mode restriction of mode>=one would result in a valid state for the modes one and two only. It is also possible to compare modes on the basis of a timeline sequence instead of just the abbreviation. When a mode is defined, it can be specified as spanning a given time range typically a range of dates which spans an interval from X to Y. If no time range is given for a mode, then that mode is assumed to span all time periods. Using the timeline mechanism, the current mode can be compared against a specific time (usually a specific date) and can be considered valid or not based on whether the mode encompasses the date within its defined interval. Complex Legality Tests The legality of a record or attribute can be determined via complex expressions. These expressions utilize the boolean expression syntax (specified above) and simply define the syntax for individual terms within the expression. These expressions can combine comparisons of race, mode, and timeline to determine if a record should be valid or not. The valid terms for comparison are: Race=xx mode=abbr mode<=abbr mode>=abbr time=X time>=X time<=X Is the current race equal to xx, where xx is a race abbreviation Is the current mode equal to abbr, where abbr is a mode abbreviation Is the current mode <= to abbr, where abbr is a mode abbreviation Is the current mode >= to abbr, where abbr is a mode abbreviation Is X >= the current modes start time and <= the current modes end time Is X >= the current modes start time Is X <= the current modes end time
When a record is determined to be not legal based on a legality expression that record is treated as if it does not exist by Army Builder. Since the race and mode for a roster will never change, a record that is not legal can be completely discarded by Army Builder, as it will never be possible for that record to become legal again until a new roster is created. Consequently, the use of highly complex legality tests is not a performance consideration, as the expression will be evaluated once and the record will either be designated as legal or not no subsequent evaluation will occur within Army Builder. Note! The < and > syntax for comparisons is supported for backwards compatability, but any use of < or > will still be treated as a <= or >= comparison. There is no way to perform a true < or > comparison. Note! In order to perform a comparison against the default mode, specify an abbreviation of default. The default mode will always be reported as less than all other modes, regardless of their abbreviation (its a special case).
46
Inheritance of Attributes One of the more time consuming issues of data file creation is the frequent need to redundantly enter the same information for a large number of records that are similar to one another. To alleviate this, Army Builder offers a set of inheritance attributes that eliminate a great deal of duplication between these similar records. Separate attributes exist for races (inhr), units (inhl and inhx), options (inho) and tweaks (inht). All that must be specified for each of these attributes is the unique id (or race prefix) of the record to inherit from. The net effect of these attributes is that the current record (the one specifying the attribute) inherits all of the basic attributes that are defined for the referenced record (identified by its id). In the case of units, a separate attribute must be specified to inherit either the local or external attributes of the referenced record. If both local AND external attributes are to be inherited, then two separate attributes must be specified. For example, a race record with this attribute would inherit all the same attributes that are defined for the referenced race record. The inheritor record would then be treated as if all of the same attributes were directly specified for the inheritor. When the inheritor record is processed and the inherit attribute is encountered, the referenced record is retrieved and all of its attributes are appended at the END of the list of attributes for the inheritor record. This enables the inheritor record to specify attributes of its own that may override the attributes that are inherited (i.e. attributes that are not multiple in nature only recognize the first attribute encountered, so the inherited duplicate would be ignored). The set of attributes inherited is solely those attributes defined explicitly for the referenced record. If the referenced record contains either augmentations or inheritance attributes of its own, those attributes are ignored. All inherited attributes are treated as if they were specified directly for the inheriting record. A record may inherit from any number of other records, with all records being inherited from in the order that the inheritance attributes appear for the inheritor record. The biggest advantage of inheritance is that the core logic and mechanics for a game system can often be encapsulated within a small number of records especially unit records. By creating core units that act like base classes and handle all the shared behaviors for the game system, new units can be quickly defined by inheriting the behavior of the base units and only specifying the special differences. Inheritance of Options The inheritance attributes allow records to instantly mirror the attributes in other records, but there are times when units need to inherit the list of options from another unit instead (or in addition). Units are able to clone all of the option links that are defined for another unit. The referenced unit is specified by its unique id, and all options that are linked to the referenced unit are automatically linked to the current unit with the exact same set of link natures. If an option is already assigned to the current unit, then the duplicate is ignored. Unlike inheritance for attributes, inheritance of options supports multiple layers of inheritance. If unit A inherits options from unit B, and unit B inherits options from unit C, the options from both units B and C will be inherited by unit A. This behavior enables some extremely powerful capabilities that can greatly simplify the creation of data files under many circumstances. Obsolete Mechanisms For any tool that evolves, the initial implementation will fall short of the mark in some places, requiring that new mechanisms be added and/or existing mechanisms be enhanced. Army Builder is no exception. However, there are many data files out there that have been written according to the rules for the previous versions, and there would be lots of unhappy users if a new version of the product caused those files to stop working for them. The net result is that there are now a few obsolete mechanisms that remain within the data files to support these old files, yet these mechanisms should typically be avoided when writing new files. When an attribute has been replaced by something more powerful and/or flexible, the now obsolete attribute will be flagged as such. It will also identify the new attribute that has supplanted it. This does not mean that you cant use the obsolete attributes, but it does mean that you should definitely take a close look at the new attributes to see how they are most likely a better solution.
ATTRIBUTES IN GENERAL
Overview The beauty of each game system derives from all of the special nuances that it introduces, that special flavor that makes the game unique. For some systems, each unit has its own unique personality, along with its own unique set of rules. This is where life gets ugly for you, the data file creator, since you are faced with modeling these unique rules within the data file. With some game systems, special rules apply to a myriad of different game situations, which could easily result in you having to specify these unique rules in numerous different places within the data files. In an effort to keep things a bit more manageable, the Construction Kit centralizes the vast majority of these special issues into a collection of attributes. All groups of records (except links and messages) possess a field that defines the attributes of each record. All standard characteristics of each record are entered into the various fields of that record, and all of the special rules for that record are entered into the field whose sole purpose is to contain these special attributes. This ensures that all of the complexity is localized into one place. It also means that you can create your data files without all of the complexity first, and then incrementally add support for all of the complexity later. Each record type has a particular set of attributes which are applicable to it. The specifics of each of these attributes is described in the appropriate chapters that follow. If you specify an attribute that is illegal for the record you assign it to (e.g. doesnt exist for the record or has incorrect syntax), both ABCreator and ABData will report appropriate errors. Attribute Syntax Attributes describe all sorts of different game mechanics and rules, so the syntax of attributes will vary. However, all attributes have a few basic syntax rules that must be adhered to. These are: 1. All attributes possess a four-character name, which can consist of alphanumeric characters only. 2. The names of all attributes are unique, although some attributes are applicable to multiple record types (in which case, the syntax and usage will be the same for each record type). 3. If an attribute has parameters or qualifiers of any kind, then the attribute name must be followed by a :, after which all of the parameters can be listed. 4. When there are multiple attributes for a record, each attribute must be separated by a ; to indicate where one attribute ends and the next one begins. (This only applies to text files.) 5. If there are multiple attributes, the attributes are processed in the order they are listed, so there are times when the sequencing of attributes for a record can be important. Each attribute has its own internal syntax that is defined along with its description. This syntax will often include optional data. To indicate an optional piece of information, the definition of the attribute will place the optional components within curly braces { and }. Attributes may also possess parameters that can take various forms. In these cases, the set of valid forms is placed within square brackets [ and ] and each valid form is separated by a vertical bar (|). Each of these conventions is used throughout the definitions of attributes that appear within this document. Conditional Restrictions Many of the attributes available for the various record types can be restricted so that they only apply in specific situations. This is achieved through special qualifiers that are part of the standard syntax for the appropriate attributes. There are a wide range of constraints that can be applied to various attributes. Each of the standard constraints is described below. If more than one constraint is specified, the constraints must appear in the order given below, and all constraints will need to be satisfied for the attribute to be considered valid. when=type This constraint determines whether the unit being processed has the specified type defined. If the unit
does not have the type defined, then the attribute is not applied. The type may include wildcards. race=race This constraint determines whether the primary race is equal to the specified race, where race is given as a two-letter race prefix. If not, then the attribute is not applied. It is also possible to specify the syntax as race=!race to determine if the primary race is not the one specified. mode[<=|=|>=]mode This constraint allows the attribute to be restricted to the specified mode, where mode is given as a mode abbreviation. If the current mode does not satisfy the indicated relationship with the mode specified, the attribute is not applied. legal=(expr) This constraint allows you to specify a complex legality expression (described previously). If the expression yields a true result, the attribute is applied, but not if a false result is obtained. The entire expression must be enclosed within parentheses, else syntactic errors may occur. istype=type This constraint determines if the specified type is defined for any unit in the entire roster. If no unit has the type defined, then the attribute is not applied. The type may include wildcards. It is also possible to specify the syntax as istype=!type to determine if the type is not defined anywhere in the roster. Within the documentation for each attribute, the above constraints will be abbreviated. Otherwise, the specification for some attributes will extend for quite a distance. The format that will be used is {#name}, where name is replaced by the literal constraint name given above. For example {#legal} will indicate that the attribute can have the legal=(expr) constraint specified as a qualifier. Single-Instance vs. Multi-Instance If you attempt to model all of the complexities of a highly complex game system, you will likely find yourself using attributes extensively within your data files. In some cases, you may even find yourself defining a dozen attributes for a single record. Now, consider that someone else will probably want to extend or tailor your data files for a specific purpose (like supporting a supplement or a special set of rules), adding more attributes to your records via augmentation records. The number of attributes associated with some records could become quite high, and this brings up an important consideration. This consideration is whether a particular attribute is single-instance or multi-instance. If an attribute is defined to be single-instance, then Army Builder assumes that there will never be more than one such attribute ever associated with a given record. If more than one single-instance attribute is assigned to a record, then Army Builder simply uses the first one that it finds for the record and ignores any others. In contrast, when an attribute is designated as multi-instance, Army Builder expects that there could be many instances of the same attribute assigned to a record and processes them all appropriately. To ensure that there is no confusion regarding the potential usage of a particular attribute, the description of each attribute specifies whether the attribute is treated as single-instance ([Single]) or multi-instance ([Multiple]). Sequencing In general, the sequence in which attributes are attached to a record is unimportant. However, there are times when different attributes operate upon the same target records. When this occurs, it is important to consider the effects of each attribute and to ensure that the attributes are defined in the proper sequence to give you the results you want. This issue of sequencing can sometimes extend beyond the scope of a set of attributes. In some cases, attributes will be used that operate upon child units of a parent unit. There may also be other attributes that control the enabling and disabling of the child units within the roster. Different attributes are assigned to different options and units, but they all must work together to achieve the desired effect. Circumstances like this will sometimes require that you monitor the sequencing of the attributes between different options. This means that you will have to
consider the relative priorities of the options that are being processed, as the attributes assigned to an option are processed as part of the option processing. Control of option priorities is achieved through the selection of option categories for each option, which is described in more detail elsewhere in this document. Validation Attributes Quite a number of attributes are considered validation attributes. These attributes serve only to register a new validation rule with the Army Builder engine for resolution during the next validation pass. Validation attributes completely ignore issues of sequencing, so they can be added to your data files without these concerns. In general, validation rules only involve all of the top-level units within the roster, unless special steps are taken to include child units in validations (see the forc attribute for more information). All validation attributes are identified as such within their description in the following sections, being designated with the indicator [Validation]. Virtually all validation attributes have the ability to specify a custom validation message. This message will be displayed if the validation rule is not observed by the user. Default messages are provided within Army Builder, but custom messages can usually be even more helpful to the user. When a validation attribute can have a custom message specified, the optional qualifier {-msg=msg} will be given for the attribute. To specify the message you wish to have used, replace msg with the unique id of the desired message record. Custom validation messages are defined via the Messages tab within ABCreator, and they can reference information generated at run-time by Army Builder (e.g. the name of the unit that is not in compliance). If a particular validation attribute provides the unit name at run-time, then that will be indicated within the description text of the attribute. Use In Augmentations When attributes are assigned to records via augmentation records, there is no guarantee of the order in which augmentation attributes will be applied to a given record. In fact, any subtle change to a data file could cause the sequencing of augmentation attributes to change within Army Builder. This means that care must be taken within augmentation data files to either only use attributes that are not sequence dependent or make careful use of options that are priority controlled to govern the attribute sequencing. Multi-Stat Capability In most situations, a unit will have a single set of stats to represent its skills within a game system. However, there do exist game systems which will sometimes require more than one value to represent a single stat. For example, if a unit has two forms of attack and they both have different damage characteristics, the two stats will need to be represented in the roster. To accommodate this, the Construction Kit provides a mechanism to represent the two (or more) distinct stats within a single stat, provided that text values are used for the affected stats. This multi-stat mechanism requires that each individual stat be separated by a vertical bar character (|) within the text and that the unit be identified as multi-stat via the inclusion of the strm attribute. Thus, the text 1d6+1d4|2d6 would represent two distinct stat values (assuming the unit was assigned the strm attribute). If the strm attribute is not assigned, then the stat value is treated as simple text without any special meaning. Within Army Builder, whenever multi-stat text is encountered for a unit to which additional text is being grafted via the stxt attribute, the change is applied to each of the distinct stat values. Also, at the time that the final text is rendered for the stat, the vertical bar (|) is replaced with a forward slash (/). If a unit is not assigned the strm attribute, though, any stxt attribute is simply applied to the entire text as a whole. Using skip for Testing A special skip attribute exists for all record types. The skip attribute allows you to specify any text after it, with the entire attribute being ignored by Army Builder. Using the skip attribute is an excellent way to comment out attributes temporarily during testing. You are encouraged to use skip to regularly for this purpose. Support for Army Builder Lite There are many attributes that are only supported by the full version of Army Builder. Only a portion of the total
set of attributes are actually supported by Army Builder Lite. If you are interested in writing data files with concern for Army Builder Lite users, then this distinctino may be of importance to you. For this reason, attributes which are supported by Army Builder Lite are designated with the [ABLite] indicator within their descriptions. Note! Support for the lead and foll attributes within Army Builder Lite is only partial. Stat accumulation and restrictions enforced via the validation mechanism are not implemented within the Lite version. Global Race Attributes Some race attributes can be defined on a global level, applying to all races via a single specification. These race attributes are identified by the designation [Global] in their descriptions. If you wish to define a global attribute, then you need to define it via a special mechanism. You must include a race augmentation record within your data file that defines the global attribute. This augmentation record must specify the race abbreviation as xx, which is normally an illegal race abbreviation but is used specially for this case. When such an attribute is encountered within Army Builder, it is automatically assigned to all defined races. This mechanism is only supported for the specific attributes that are designated as [Global]. Local Versus External Unit Attributes The set of attributes which can be assigned to units is extremely large. In addition, there are two distinctly different contexts in which unit attributes are utilized by the Army Builder engine. Approximately half of the unit attributes are applicable toward each of the different contexts. For this reason, the two groups of unit attributes are explicitly decoupled from one another. This distinction serves two purposes. First, it tends to make things a little easier when defining a unit, as each list is a bit shorter to manage. Second, the separation improves performance of Army Builder by eliminating half of the attributes that must be waded through at any one time. The two groupings are termed local unit attributes and external unit attributes. Local unit attributes are the attributes whose effects are purely local to the unit and its children. This is in contrast to external unit attributes, which have ramifications upon other units within the roster (e.g. inter-unit relationships like required units). Complete Attribute Documentation is in ABCreator Since its introduction, ABCreator has been the preferred tool for all data file authors. The use of ABData has been relegated to those few special situations where it is needed. Since ABCreator includes the full syntax and documentation for all attributes, it is redundant to provide the full details here in this manual, too. However, there are many users who enjoy having a complete manual that can be printed out and read through. A compromise has been enacted, wherein this document contains a summary of each attribute, but not every little detail. This will allow users to get a good idea of what functionality is available from the manual, and it will keep all the gory details located within ABCreator, which is where youll want them as you write your data files.
51
ATTRIBUTE SUMMARIES
This chapter provides a brief summary of all of the attributes available within Army Builder. The attributes are grouped by record type and presented alphabetically for convenient reference. Full details on the nuances and syntax of each attribute will be found within ABCreator, since thats where youll be needing those details. This summary will give you a good idea of what functionality is available and how you might be able to exploit it. Race Attributes accu Accumulate the value of a specified stat for the entire roster, generating a single total for all regiments in the roster. Within Army Builder, all totals are displayed in the composition report dialog and included in the accumulated stat display region immediately above the Options Panel. The cost of all allied units that are added to the roster is multiplied by a specified value. The multiplier can be limited to only apply to a single allied race. Add an additional race to the list of allies for the current race. Obsolete Do not use. Specify a FAQ entry for inclusion in the FAQ that Army Builder will generate for this game system. Built-in user documentation for the data files. Require racial diversity within the roster. Units from at least a minimum number of distinct races must exist within the roster.
acst ally crcr dfaq dvrs
gmap Map a composition group to a completely different name and abbreviation for the current race. This is useful when a new race requires a custom composition group that does not exist in the definition file, as you can simply reuse an existing group and change the name shown to the user. gmul Designate the race as having composition breakdown rules that can be multiplied. For a game system that uses relative unit compositions, larger armies multiply the basic group sizes, which Army Builder flags as illegal. This attribute tells Army Builder to allow multiples without reporting them as invalid. Hide this race from the user. This is useful for races that are intended solely for use as base class races that other races will inherit from. Restrict the set of special items that can be selected for this race to a fixed limit. The limitation can be based on a percentage of the roster size, an explicit point total, a total count of items, or an individual item limit. Specify a block of message text that the user will always be shown within the UI and/or within roster output regarding this race. This is useful for race-specific reminders to the user. Inherit all attributes defined for a specified race, treating them all as if specified for this race. Restrict the points that can be spent on special items for all units of the race. The total item cost can be limited and/or the maximum cost of individual items can be limited. Establish minimum requirements for the special items taken within the army. Specific items and/or item categories can have requirements established. Define a message that will always be displayed to the user whenever these data files are loaded into Army Builder for use. This is a ideal mechanism for providing reminders to users about the data files you are creating.
hide ilmt
info inhr ipts ireq lnch
mode Define a mode (or scenario) that will be available for this race. Modes are selectable by the user when a roster is created, and most records can be restricted to only be available for certain modes. Modes are excellent for introducing separate rule-sets and/or handling time periods within historical game systems. need Establish a minimum requirement for a class of unit that must appear within the roster. Units can be grouped by unique id, category, or type.
none olmt prim
Specify the name to be displayed for the default mode/scenario for this race. Constrain the number of units/models that can possess a specific option. Specify the name to be used for the primary composition breakdown rule-set. This name replaces the default name of Primary.
pnam Define an alternate name to be used in roster output for this race.
scmp Perform comparison between two stat expressions, verifying that the two expressions satisfy an arithmetic relationship. If the relationship is not satisfied, a validation error is generated. sglb skip Verify that one or more units in the roster possess the highest or lowest value for a specific stat among all units in the roster. This attribute can contain anything and will be ignored by Army Builder. It provides an excellent means of temporarily commenting out attributes during development and testing.
smap Map a numeric value for a stat to a corresponding text value, using a lookup table to determine the mapping. This is ideal for easily handling stats that must contain a text value from a pre-defined set of possible values. Numeric values can be used within Army Builder and then mapped automatically to the proper text values. tlmt Constrain the set of units in the roster that possess a common type. Units can be constrained to a particular percentage of the roster size, model count, or unit count. Both minimum and maximum limits can be imposed. Establish a minimum relationship that must be maintained between units of two different types within the roster. The relationship can compare the respective number of models, units, or points for the two types of units. Specify a relationship that must be maintained between leaders and their individual sets of followers. This is a companion to the leader/follower mechanism that is implemented via the lead and foll unit attributes. Establish a minimum or maximum requirement upon all units which share a common characteristic within the roster. Units can be constrained based on points, model count, or unit count. The common element between the units can be a type name, composition group, or unit category. All units of the specified type have their total cost multiplied by a specified value. Create an alternate composition breakdown rule-set that users can select for this race. This is useful for supporting multiple scenarios with different army composition requirements for each. Integrate an external program into Army Builder that takes an XML file generated by the product as input and prepares customized roster output (e.g. a game-specific, graphical roster sheet).
trat
uldr
ulmt
umul xbrk xmlx
External Unit Attributes clmt Establish a constraint on the special items that may be possesses by this unit from a set of special item categories. The constraint may be based on total points of items, item slots used, or a simple count of the items. The cost of the unit is discounted by a specified multiplier based on other units in the roster that are depended upon to grant the discount. Ensure that all top-level regiments that are comprised of this unit must contain approximately equal model counts to each other. The rules for the size constraints can be specified. Designate this unit as a follower and specify the restrictions used when allowing the user to select a leader for this unit.
disc equl foll
53
forc
Force this unit to always be included within validation processing, even if this unit is not a top-level unit in the roster. By default, validation processing only includes top-level units, and this attribute overrides that behavior. Hide this unit from the list of Available Units shown within Army Builder. When hidden, a unit cannot be selected directly by the user via any means. The unit can only be added into a roster via an option or item. Inherit all external attributes defined for a specified unit, treating them all as if specified for this unit. Perform comparison between two stat expressions, verifying that the two expressions satisfy an arithmetic relationship. If the relationship is not satisfied, a validation error is generated. Designate this unit as a leader and specify the relationship it must maintain with its followers. This unit will be able to be selected as a leader by any unit with the foll attribute, provided that the constraints imposed by the leader and the follower dont preclude it. Obsolete Use lglx instead. Determine if the record satisfies criteria for inclusion in the roster. Define a boolean expression that must evaluate to true in order for this record to be included for use within the current roster. The expression can be based on a combination constraints that are based on the race and mode of the current roster. If failed, the record is ignored by Army Builder. Specify that an option or category of options must satisfy certain selection criteria for this individual unit. Specify that a set of option categories must satisfy certain selection criteria for appropriate units within the current context. This attribute allows you to define rules that control how many of which options can be taken by this unit and other units that are children of the same top-level regiment (including the top-level regiment itself). Make this unit available to additional races for selection. This unit appears in standard unit lists for those races, just as if it was a part of those other races. Establish a dependency relationship of this unit upon another unit or class of units in the roster. The dependency must satisfy a pre-defined relationship, else a validation error is reported. This attribute can contain anything and will be ignored by Army Builder. It provides an excellent means of temporarily commenting out attributes during development and testing. Limit the number of instances of this unit that may select a special item. Establish a minimum relationship that must be maintained between units of two different types within the context of a single top-level regiment. The relationship can compare the respective number of models, units, or points for the two types of units. Test that the unit satisfies specific type requirements, including the interaction of multiple types within the unit. Sepcify a minimum restriction upon the number of models/units that may appear in a roster.
hide
inhx lcmp lead
legl lglx
must ocat
race reqd skip slmt tcon
tloc
umax Sepcify a maximum restriction upon the number of models/units that may appear in a roster. umin
Local Unit Attributes attr auto bcst boun Replace a specific stat value with literal text. When this unit is added to the roster, options for this unit that are also shared by its parent and selected for the parent are automatically selected as their initial state for this unit. The total cost for this unit is bounded to a specified minimum and/or maximum value. Specify bounding rules for adjustments to stat values of this unit. Minimums, maximums, and maximum deltas can be specified.
calc
Calculate the value of a particular stat for this unit based on an arithmetic expression. This expression can be based on other stats, literal values, the model count of the unit, and/or the items possesses by the unit. Designate this unit as belonging to an additional unit category, conferring the corresponding access and limitations associated with that category. Clone all of the option links that exist for a specified unit, establishing equivalent links to the same options from this unit. Add the total count for this unit into the overall total count for any parent regiment. Designate a specific option that must be selected as its initial state when this unit is added to the roster. Controls whether the unit is visible to the user and under what condition. For example, you can specify that a unit is only visible during roster creation and not included in any roster output. Delete all types that are currently assigned to this unit and that match the type name specified. The type may include a wildcard, allowing it to match multiple types. Change the cost behavior of items for this unit, causing all of them to be charged on a per-model basis instead of a single cost for the entire unit. Exert explicit control over the options for a child unit, forcing the child unit to be automatically assigned a specific option. Inherit all local unit attributes defined for a specified unit, treating them all as if specified explicitly for this unit. Restrict the points that can be spent on special items for this unit. Both a total point limit and a maximum item cost can be imposed upon the unit. Force this unit to cause the points for all child units to be tallied up as part of the composition group to which this unit belongs, even if the child units belong to other composition groups. Designate an option possessed by this unit that must always maintain the exact same selection state as the parent unit. Specify a cost multiplier that will be applied to the costs of all items and/or options for this unit. Augment and/or clear the notes field for the record. Only allow a specified option to be available for this unit if the option is also possessed by the parent unit. Define a special unit size relationship that must be maintained between this unit and its parent. The relationship can be a minimum ratio, maximum ratio, fixed ratio, or absolute range. Designate an option category and a child option that will receive all unallocated selections for the category. This option is intended for use with ranged options, where the total number of selections for two or more ranged options must equal a specific number. By designating one option to catch the remainder, user adjustments to the other options result in the designated option always being assigned whatever number is left over. Override the size characteristics for the unit with a custom minimum, maximum, and interval. This attribute can contain anything and will be ignored by Army Builder. It provides an excellent means of temporarily commenting out attributes during development and testing. Control the availability of a specified special item category for the unit.
catg clon
comm Augment and/or clear the comments field for the record. coun dflt disp dtyp icst incl inhl ipts mgnt mirr mult note only ratp rmdr
name Override the name of this unit, assigning it a new name.
show Make a specified option visible to the user. size skip spec
sraw sset strm take
Specify one or more stats for this unit that must be output in raw format. All special formatting for these stats is bypassed by Army Builder. Assign a specific stat-set to the unit for use when displaying the unit. Designate this unit as possessing stat values that may contain "multi-stat" information. Whenever this unit is added to the roster, the unit must always automatically take a specified special item. This item can be optionally designated as free to the unit, plus it can be designated as permanent or removable by the user. Specify that this units model count be adjusted by a specified multiplier whenever that count is accessed by the trat or tlmt attributes. This allows the unit to behave specially when it is utilized in validation rules with those attributes. Assign a specific type to this unit, its parent, or its children.
tmul
type
xcmp Treat this unit as belonging to a different composition group from its normal one. All composition details for this unit are assigned to the new composition group instead. xcst xmpt zero Override the cost of the unit. Exempt this unit from certain rules that are normally enforced by Army Builder. Allow the size of this unit to go to zero. Normally, units cannot drop below a size of one, but this attribute exempts the unit from that restriction.
Option Attributes The order of processing for options is often critical, so an important thing to remember is that the attributes for an option are evaluated when the option is processed. Within the descriptions below (and within ABCreator), whenever the parent unit is mentioned, the text is referring to the unit to which the option is assigned. acmp Adjust the composition group allocations for the unit. The adjustment can be applied to the same composition group that the unit belongs to or a different group, enabling a unit to consume multiple allocation slots. Use of this attribute changes the number of instances USED within the roster. allw Adjust the composition group allowances for the unit. The adjustment can be applied to the same composition group that the unit belongs to or a different group, enabling a unit to affect the allowed roster contents in any way. This attribute changes the number of instances ALLOWED in the roster. Force the notes that are normally output for this option to be output separately from the unit. They can either be appended at the bottom of the unit or placed in the footnotes at the bottom of the entire roster. When options are used as footnotes at the end of the roster, all duplicates are eliminated, so a single list of all unique options is output (unique by both id and name). Modify the base value of a specified stat. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. Append specified text to a stat such that it can leverage the multi-stat mechanism (also see the strm local unit attribute). Designate this unit as belonging to an additional unit category, conferring the corresponding access and limitations associated with that category. Modify the value of a specified stat for all child units that match a given type. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count.
apnd
base bttl catg chld
comm Augment and/or clear the comments field for the record. comp The cost of all child options (via more) and child units (via unit) of this option are always assigned to a specified composition group that may differ from that of the parent unit. This attribute exempts the option from the effects of the mgmt attribute if it is assigned to the unit.
cost csiz dsab
Calculate the cost of this option via one of a number of special formulae. Adjust the size of a specified child unit by a given amount. Designate this option as being initially disabled, which means that the option is visible to the user but greyed out and not adjustable by the user. The option will need to be enabled before it can be manipulated by the user. Delete all types that are currently assigned to this unit and that match the type name specified. The type may include a wildcard, allowing it to match multiple types. Forcibly control the state of an option within a specified child unit. The option can be deleted, deselected, or disabled. Enable an option within a specified child unit. The option can then be manipulated by the user. Assign this option to every single unit that exists in the loaded set of data, attaching it with with the specified link nature. Hide this option from the user as its initial state. Charge a specified point cost against the total number of special item points allowed for the unit. This attribute is useful for treating an option as if it is an item. Inherit all attributes defined for a specified option, treating them all as if specified explicitly for this option. Control the visibility of this option to a finer level than is normally provided. Adjust the number of special items allowed to the unit. Obsolete Use lglx instead. Determine if the record satisfies criteria for inclusion in the roster. Define a boolean expression that must evaluate to true in order for this record to be included for use within the current roster. The expression can be based on a combination constraints that are based on the race and mode of the current roster. If failed, the record is ignored by Army Builder. Present the user with a dialog containing a list of available units to select from, attaching the selected unit as a child of the parent unit. The set of units included within the dialog can be controlled through various rules. Immediately adjust the model count of the parent unit upwards or downwards. Chain to another specified option. The chained option is automatically included in or excluded from processing as a part of this option. The more attribute is extremely useful in creating groups of options that are enabled and disabled together via control of the one option that chains to them. Augment and/or clear the notes field for the record. Control whether this option is considered legal based on the characteristcs of the parent unit to which it is being attached. Override the current state of a specified peer option. The option can be disabled, deselected, deleted, or enabled. Control whether this option actually operates for the parent unit, basing the determination on whether or not the parent unit has a parent unit of its own. Overrides the default minimum and/or maximum size of the parent unit. Modify the value of a specified stat within the grandparent unit. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count.
dtyp elim enab glob hide ichg inho invs item legl lglx
list
modl more
name Override the name of this option, assigning it a new name. note olgl
onam Change the name of the option when the option is in the selected state. over preq prng prnt
rang rept
Designate this option as a range-based option. As such, the option is displayed with +/ buttons and can be adjusted between a specified range of values by the user. Allow the user to add a repeating sequence of a specified unit to the roster as children of the parent unit. This mechanism allows the user to add an arbitrary number of the same unit, customizing the options and items for each unit separately. Control whether this option actually operates for the parent unit, basing the determination on the overall roster size of the entire army. Obsolete - Use the mapping feature of the local unit attribute \"only\" instead. This attribute can contain anything and will be ignored by Army Builder. It provides an excellent means of temporarily commenting out attributes during development and testing. Force a specified option to be automatically selected for the parent unit, overriding the normal link nature assigned to the option. Control the availability of a specified special item category for the unit. Modify the value of a specified stat. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. Append, prepend, or overwrite literal text to a specified stat of the parent unit. Designate this option as a table-based option. As such, the option allows the user to cycle through a list of valid choices for the option. The user must select one of the choices. Whenever this unit is added to the roster, the unit must always automatically take a specified special item. This item can be optionally designated as free to the unit, plus it can be designated as permanent or removable by the user. Displays a text value as the cost of the option instead of the standard numeric value. This is ideal when the cost is a calculation of some sort. Assign a specific type to this unit, its parent, or its children. Control whether this option actually operates for the parent unit, basing the determination on whether or not the parent unit is attached to another unit (via the link button withn Army Builder).
rsiz same skip slct spec stat stxt tabl take
show Make a specified option visible to the user.
tcst type uatt
ucmp Control whether this option is enabled for the parent unit, basing the decision on which composition group the unit belongs to. ucst uexp Apply cost multipliers to the parent units cost. The multipliers can take a number of different forms and be based on various criteria. Control whether this option is enabled for the parent unit, basing the decision on a boolean expression that combines one or more stat comparisons (e.g. strength less than 5 and defense greater than 4). Attach a specified unit as a child of the parent unit. The child unit can be added with a number of different size relationships, including a fixed ratio with the parent, an absolute number of models, or a variable size that is dictated by the child unit itself. Control whether this option actually operates for the parent unit, basing the determination on the model count of the parent unit. Control whether this option is enabled for the parent unit, basing the decision on a comparison between a specific stat value and a separate arithmetic expression that is calculated based on other stat values. Control whether this option actually operates for the parent unit, basing the determination on whether the unit satisfies a boolean type expression.
unam Modify the unit name of the parent unit. unit
usiz usta utyp
vwst
Display the final value for a stat within the Options Panel.
xcmp Treat this unit as belonging to a different composition group from its normal one. All composition details for this unit are assigned to the new composition group instead. xcon xcst xlat Override the conflict groups assigned to the option. Override the cost of the option. Translate the value of one stat of the parent unit to a new value for another stat in the parent unit, using a lookup table to perform the mapping.
Item Attributes Within the descriptions below (and within ABCreator), references to the parent unit are referring to the unit to which the item belongs. asop base bcst bttl catg Render this item just like an option in all roster output, appending the item name and notes to the unit notes instead of listing the item on a separate line. Modify the base value of a specified stat. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. The total cost for this item is bounded to a specified minimum and/or maximum value. Append specified text to a stat such that it can leverage the multi-stat mechanism (also see the strm local unit attribute). Designate this unit as belonging to an additional unit category, conferring the corresponding access and limitations associated with that category. Designate a specific tweak that must be selected as its initial state when this item is added to the roster. Delete all types that are currently assigned to this unit and that match the type name specified. The type may include a wildcard, allowing it to match multiple types. Specify an element (as in constructed element) that is always included as part of this item. Restrict the number of times this item may be taken by a single unit. Obsolete - Use the corresponding field of the item record instead. Inherit all attributes defined for a specified item, treating them all as if specified explicitly for this item. Specify the evaluation priority to be used by this item. Items are normally processed in the order specified by the sequence in which the user arranges them. However, priorities allow detailed control over the sequence used, ignoring the order given by the user. Obsolete - Please use itst instead. Obsolete - Please use itst instead. Designate this item as selectable in multiples, along with the selection count minimum and maximum to be used. The item can then be adjusted by the user via the +/ buttons on the Special Items form instead of requiring separate selection for each instance. This mechanism is ideal for constructing spellbooks and the like. Control whether this item is made available for selection to a given unit, basing the determination on whether the unit satisfies a boolean expression that can check the units race, category, and type. Obsolete - Please use itst instead. Obsolete Use lglx instead. Determine if the record satisfies criteria for inclusion in the roster.
comm Augment and/or clear the comments field for the record. dtwk dtyp elem icnt imax inhi ipri
irac ireg irng
itst ityp legl
59
lglx
Define a boolean expression that must evaluate to true in order for this record to be included for use within the current roster. The expression can be based on a combination constraints that are based on the race and mode of the current roster. If failed, the record is ignored by Army Builder. Augment and/or clear the notes field for the record. Modify the value of a specified stat within the grandparent unit. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. This attribute can contain anything and will be ignored by Army Builder. It provides an excellent means of temporarily commenting out attributes during development and testing. Control the availability of a specified special item category for the unit. Modify the value of a specified stat. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. Append, prepend, or overwrite literal text to a specified stat of the parent unit. Displays a text value as the cost of the item instead of the standard numeric value. This is ideal when the cost is a calculation of some sort. Assign a specific type to this unit, its parent, or its children. Attach a specified unit as a child of this item. Specify that this item requires a user-defined cost adjustment. The user is then allowed to edit the appropriate cost adjustment for inclusion in the roster cost calculations. Override the cost of the item. Designate this item as being excluded from the total item calculation for the roster. Clone all of the tweaks that exist for a specified item, establishing equivalent links to the same tweaks from this item.
name Override the name of this option, assigning it a new name. note prnt skip spec stat stxt tcst type uadd user xcst xtot zcln
Element Attributes Within the descriptions below (and within ABCreator), references to the parent unit are referring to the unit to which the item belongs. base bttl dtyp dupl irac ireg itst ityp Modify the base value of a specified stat. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. Append specified text to a stat such that it can leverage the multi-stat mechanism (also see the strm local unit attribute). Delete all types that are currently assigned to this unit and that match the type name specified. The type may include a wildcard, allowing it to match multiple types. Designate this element as exempt from the standard uniqueness rule, allowing the element to be dupilcated freely within items. Control whether this item is made available for selection to a given unit, basing the determination on whether the unit belongs to a specific race. Control whether this item is made available for selection to a given unit, basing the determination on the units unique id. Control whether this element is made available for selection to a given unit, basing the determination on whether the unit satisfies a boolean expression that can check the units race, category, and type. Control whether this item is made available for selection to a given unit, basing the determination on whether the unit has a specific type.
legl lglx
Obsolete Use lglx instead. Determine if the record satisfies criteria for inclusion in the roster. Define a boolean expression that must evaluate to true in order for this record to be included for use within the current roster. The expression can be based on a combination constraints that are based on the race and mode of the current roster. If failed, the record is ignored by Army Builder. Modify the value of a specified stat within the grandparent unit. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. This attribute can contain anything and will be ignored by Army Builder. It provides an excellent means of temporarily commenting out attributes during development and testing. Designate this element as being unable to be combined on the same item with any other element that has this same attribute. Modify the value of a specified stat. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. Append, prepend, or overwrite literal text to a specified stat of the parent unit. Displays a text value as the cost of the element instead of the standard numeric value. This is ideal when the cost is a calculation of some sort. Assign a specific type to this unit, its parent, or its children. Designate this element as belonging to an additional special item category. As such, it will be available for selection as part of multiple construction item types. Override the cost of the element.
name Override the name of this option, assigning it a new name. prnt skip solo stat stxt tcst type xcat xcst
Tweak Attributes Tweaks are very similar to options at the present time, although they often have differently named attributes (usually starting with a z). The reason for this is that future enhancements to Army Builder will likely see a divergence between the behaviors for tweaks and for options. In anticipation of this, the name have been divorced already to make future evolution easier on everyone. Within the descriptions below (and within ABCreator), references to the parent unit are referring to the unit to which the item belongs. comm Augment and/or clear the comments field for the record. inht invs legl lglx Inherit all attributes defined for a specified tweak, treating them all as if specified explicitly for this tweak. Control the visibility of this option to a finer level than is normally provided. Obsolete Use lglx instead. Determine if the record satisfies criteria for inclusion in the roster. Define a boolean expression that must evaluate to true in order for this record to be included for use within the current roster. The expression can be based on a combination constraints that are based on the race and mode of the current roster. If failed, the record is ignored by Army Builder. Augment and/or clear the notes field for the record. This attribute can contain anything and will be ignored by Army Builder. It provides an excellent means of temporarily commenting out attributes during development and testing. Displays a text value as the cost of the tweak instead of the standard numeric value. This is ideal when the cost is a calculation of some sort. Override the cost of the item.
name Override the name of this option, assigning it a new name. note skip tcst xcst
zamd Amend the comments text for the item by augmenting the displayed text.
zbas zcst zdsb
Modify the base value of a specified stat. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. Calculate the cost of this tweak via one of a number of special formulae. Designate this tweak as being initially disabled, which means that the tweak is visible to the user but greyed out and not adjustable by the user. The tweak will need to be enabled before it can be manipulated by the user. Delete all types that are currently assigned to this unit and that match the type name specified. The type may include a wildcard, allowing it to match multiple types. Specify an option that should be added as a footnote entry for the parent unit. Hide this tweak from the user as its initial state. Chain to another specified tweak. The chained tweak is automatically included in or excluded from processing as a part of this tweak. The more attribute is extremely useful in creating groups of tweak that are enabled and disabled together via control of the one tweak that chains to them. Override the current state of a specified peer tweak. The tweak can be disabled, deselected, deleted, or enabled. Modify the value of a specified stat within the grandparent unit. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. Designate this tweak as a range-based tweak. As such, the tweak is displayed with +/ buttons and can be adjusted between a specified range of values by the user. Make a specified tweak visible to the user. Control the availability of a specified special item category for the unit. Modify the value of a specified stat. An arithmetic expression can be used that allows the adjustment to be based on other stats, the model count, and/or the item count. Append, prepend, or overwrite literal text to a specified stat of the parent unit. Designate this tweak as a table-based tweak. As such, the tweak allows the user to cycle through a list of valid choices for the tweak. The user must select one of the choices. Assign a specific type to this unit, its parent, or its children. Control whether this tweak actually operates for the parent unit, basing the determination on the model count of the parent unit. Control whether this tweak actually operates for the parent unit, basing the determination on whether the unit satisfies a boolean type expression.
zdtp zfut zhid zmor
zovr zprt zrng zshw zspc zsta zstx ztbl ztyp zusz zutp
zunm Modify the unit name of the parent unit.
62
DESIGNING FILES FOR ARMY BUILDER

Overview This chapter is included to provide a little assistance when you set out to create your own data files for Army Builder. For a complex game system, the overall process can quickly become overwhelming if you dont break it up into pieces and take the process one step at a time. Hopefully, some of these ideas will prove helpful to you. The Definition File Everything starts with the definition file. If you dont have a definition file, then you cant have data files. This means that the definition file must be written first. However, the purpose of the definition file is to delineate all of the components that will be needed by the data files, which means that you have to start with the data files. Is your head hurting yet? The simple answer here is that you first need to think about what you will want to put into your data files. Sit down for a few minutes with a piece of paper and think about the game system that you are going to write files for. Write down an initial list of the various types of units and options that exist in the game system. Give some thought to which things may be best modeled as options and which things would be better suited as items. For those things that are best handled as options, think about which options might conflict with others and start to break the options up into a few basic groups. Look at the typical rules for army composition and decide on an initial set of composition groups that you will need. After you have done this, you have a pretty solid idea of what needs to go into your definition file. Write your initial definition file using the information that youve now distilled as its basis. Dont expect to write your definition file exactly right the first time. Invariably, you will run into things that youve forgotten and will need to add enhancements and/or make adjustments. Plan on this. Once your basic definition file is built, you are then ready to launch into your first data file. Warning! If you use ABCreator to build your data files and you need to modify your definition file, you will need to take special steps to ensure that the data files are kept consistent with the definition file. This is described in the Iterative Evolution of Files section. Data Files Many game systems contain a wealth of information. There is usually a wide array of armies to choose from and a large number of units and options that comprise each army. Attempting to include all of this information within a single data file would mean having a huge data file that will likely be unwieldy to maintain and extend over time. Since Army Builder supports multiple data files for a single game system, there is no reason to put yourself through such an ordeal. However, the question arises as to how you should best carve up everything into data files. Probably the easiest and most logical way to break up the data files is to have a separate data file for each army. Some game companies even sell the specifics for each army in separate books, so this approach is best. The problem with this method, though, is that there is usually a wealth of information that is shared by nearly all armies. This might include standard types of equipment (e.g. weapons, armor, etc.), units that can be selected by most armies (e.g. monsters, common allies, etc.), and special items that are available to most armies. The solution is to create a core data file. The purpose of this data file is to contain all of the basic elements that are utilized by multiple armies in the game system. This data file is effectively shared by all of the other data files and forms the foundation upon which all of the other data files are then written. Once you have a core data file, all other data files become component data files. The important thing to remember is that the core data file should contain the only information that is shared between data files. Ideally, this means that all of the component data files should be completely independent of one another and should only rely on the core data file. The easiest way to verify that you have accomplished this goal is to remove all other data files from the Army Builder data directory except for the component data file you are testing and the core
data file. If the files load and operate correctly, then the component data file is completely decoupled from the other component data files. If not, you may wish to edit your files to correct this appropriately. Note! Not all game systems can be supported this way. Some systems require extensive inter-relationships between races, in which case there is no way to keep the data file for each race truly independent. Instead, you must simply do your best to keep these dependencies manageable. Now comes the issue of how to begin writing your data files. Probably the best approach is to create two data files to start with. The first data file is the core data file for your game system, and the second data file is specific to one of the armies you want to support. Start out by adding units to the army-specific data file and by putting any shared pieces into the core data file (e.g. common options, items, etc.). Once your initial component data file is complete, you can then move onto the next component data file, continuing the process until you have all of the files created that you want. If you are using ABCreator to create your data files, there is no problem running two copies of the program at the same time. Consequently, you can use one instance of the program to edit your core data file and a second instance to edit the army-specific data file that you are working on. This way, you can quickly reference the information in the core data file and can also make changes to the core data file as you discover new components that need to be added. Note! Using the <Alt-Tab> key combination in Windows is a very effective way of switching back and forth between the multiple open copies of ABCreator. It is often much faster than using the mouse to make the switch. Incremental Creation As mentioned previously, the creation of data files for some game systems can be a daunting task. The key is to create your files in an incremental fashion. Start out simply, and slowly add the complexity that you want. The first step is to create a few units and their options, then establish the links between them. This is extremely simple, especially when you use ABCreator. Some people may even prefer to get all units and options entered into their data files and then begin the process of adding sophistication to the data files. When you set out to model the various complexities of the game system, it is best to tackle one thing at a time. Most game systems have a number of mechanisms that are used repeatedly with numerous units. Pick one of these mechanisms and get it working with one unit. Then, make the same changes to all of the other units which have this same behavior. Once you have the first mechanism working for everything, move on to the next one, and so on. Validation rules are probably best left till the very last. It is highly likely that a complex game system will require that you utilize type names in various situations to enable the proper validation rules to be written. This is something that is easily added at the end, after your units are all working properly. If you attempt to implement this early on, it is more likely that you will find yourself changing it again at the end, after other changes have broken your initial solution. Iterative Evolution of Files During the course of data file evolution, you will undoubtedly have the need to modify your definition file. This is easily done, although there can be ramifications. The definition file is referenced extensively by each data file. While everything uses names within the definition and data files, the run-time versions of the data files use numeric indices to enhance performance. Consequently, if you change your definition file, the indices stored within the data files will often be no longer valid they will typically reference incorrect information. There are a number of different solutions to this problem. The first solution is to always append new additions to the ends of sections within your definition file. For example, if you need to add a new unit category, add it at the end of the existing list of unit categories. This will leave all of the existing indices unchanged, so all of your data files will still operate properly. Sometimes, though, it is not possible to add a new entry to the end of a section in the definition file. This is especially true of option categories, where the sequence of those categories is important to the evaluation of the options at run-time. In these cases, you will have to change the indices and make sure that your data files are
properly updated. If this occurs and you are using text files and the ABData tool to construct your data files, then all you need to do is re-build your definition file with the proper changes and then re-build your data file using the updated definition file. Since the text data files use names to reference the components in the definition file, simply rebuilding the data files will ensure that the new indices are properly updated in the run-time data files. The real nuisance, though, is when you need to change your definition file and you are using ABCreator. The reason for this is that ABCreator operates directly on the run-time version of the data file. As a result, only the indices are ever used. When ABCreator shows you a list of the various names for a unit category (for example), it has retrieved those names from the definition file but only saves the corresponding index within the data file. This means that you will have to jump through a few small hoops in order to make sure that all of your data files are re-synchronized with your modified definition file. The process involves converting the run-time data file back to its corresponding text file and then converting the text file appropriately. The exact sequence of steps is outlined below: 1. Save a copy of all your data files somewhere safe. Just in case something goes wrong, you dont want to risk losing all your hard work, so a copy of everything, preferably to another directory or disk. 2. BEFORE you modify your definition file, load each data file into ABCreator and save the data file out as its corresponding text file. This is accomplished by selecting the File->Save As Text menu item and specifying the filename in which to save the file. 3. Modify the definition file appropriately. 4. Run ABDef to convert the modified text definition file into the proper run-time file. 5. For each data file that was converted to text, run the ABData tool to convert the text file back into the proper run-time data file. Once you have completed the above steps, you can then resume editing your data files with ABCreator. The reason that this process works is that the text data files contain the names of the proper values within the definition file. Thus, when you convert the text data file back into the run-time data file using ABData, the names within the text file are properly mapped to the new indices within the definition file. Inserting Placeholders Because of the above problems, a very effective technique when creating your initial definition file is to use placeholders. This amounts to inserting dummy entries (placeholders) into many of the sections of the definition file. For example, you can insert a few extra stat lines into the list of stats. Simply designate these stats as hidden (i.e. visibility of 2) and give them names that indicate they are unused (e.g. temp, junk, dummy, etc.). If you discover that you need to add a new stat value to your data files, you can simply make use of an existing placeholder and avoid having to save all files to text and then convert them back. By putting a few of these placeholders at various points in the list (not just at the end), you ensure that there will almost always be an entry available at the location you need it. This technique is also useful for most of the other sections of the definition file, such as unit and option categories, as well as conflict groups. For option categories, the placeholders would also be inserted at various points within the list. The reason for this is that the sequence is critical for option categories. If placeholders are only inserted at the end, they really arent very useful when you need to add a new category between two existing categories. For the other sections, there is always the N/A group at the end of the list, and that group will often be used within your data files. This means that you will usually be unable to just append new entries to the section. By having additional placeholders in the list, you can simply utilize one of the placeholders without having to go through the steps to re-sequence the list. Since these lists are sequence dependent, the placeholders can simply be added at the ends of the lists. Once your data files are complete, you can then do a single re-mapping of them all. At this point, you will know which entries have and have not been used in the definition file, so you can delete the unused entries and regenerate all of the data files a single time to achieve your final files. In general, though, it is easiest to simply leave these placeholder, since you may decide to add new functionality at a later date and find them very useful.
Note! If you really want to be cautious, you can insert lots of placeholders throughout the stat list and within every other list in the definition file. The impact on performance within Army Builder is negligible for unused stats and is essentially zero for all the other sections of the definition file. Leveraging Inheritance If you are somewhat familiar with object-oriented programming, you may also want to take advantage of the inheritance mechanism offered within Army Builder. Some game systems are designed around a core set of mechanics for army construction that are shared by the majority of units. By distilling out these common mechanics, you can create units (and sometimes races and options) that will implement these mechanics and serve as a base class for other units to inherit from. Instead of having to create each new unit from scratch, you can have each unit inherit the attributes and/or options from the base class unit(s). This greatly simplifies the process of completing the data files and it also makes maintenance and enhancement of the data files in the future much easier. For an excellent example of how some of this can be leveraged, take a look at the Clan War Daimyo Edition data files. These files make great use of base class units and inheritance, which makes the data files much easier to work with. Note! The maximum number of inheritance references that are allowed on any record is 100. If you are inheriting through more than 100 unique records within your data files, it will be assumed that you have an infinite recursion problem. Infinite recursion can occur if one record inherits from another, and then that record ultimately inherits back from the first record. If you have more than 100 inheritance links chained together, you probably also have a data file design problem that needs to be re-considered, since inheritance should typically involve no more than a few cascaded levels. Augmentation Data Files Augmentation data files are a special entity. Typically, an augmentation file will be created to either implement a new set of rules for a game system (e.g. published in a supplement, used for a tournament, etc.) or to supplement the set of units available for a given army (sometimes referred to as special characters). In both of these cases, the augmentation file is usually dependent on one or more component data files (not just the core data file). The various mechanics for creating an augmentation file are no different from creating a component data file. The key issue is that the complexities of creating such a file can often be greater than creating a component data file. When you set out to create an augmentation file, be very careful to think through what you intend to do before actually creating the file. Otherwise, you are likely to run into problems and/or find yourself with a substantially bigger (and more complex) augmentation file than was really required. Debugging Aids Simple data files, such as those created through the ABCreator Tutorial, wont give you any major headaches after you get the hang of creating data files. However, complex data files can sometimes become a bit confusing when you have operations going on in the background via hidden options and/or the use of types to trigger actions. To assist with this, Army Builder includes a few very valuable debugging aids. At present, there are three main debugging facilities provided. All of them are enabled via the Enable Data File Debugging selection underneath the Interface Settings sub-menu. Once debugging is enabled, you can access the debugging facilities by right-clicking on the unit of interest in the roster on the main window. When you rightclick on a unit, a popup menu appears instead of the usual roster notes. After you select the desired debug service, the unit is re-rendered and a dialog appears that lists the results that were captured. The available debugging services are:
66
Trace Types:
Trace Options:
Trace Tweaks:
Hidden Stats:
Roster Notes:
This facility performs three things: 1. The initial set of types that are inherently assigned to the unit are listed. 2. Each type change that is applied to the unit during its processing is listed. This includes both the addition of types and the deletion of types via any source (item/option/tweak and parent/self/child). The source of each change is identified, such as option foo. Most importantly, each change is identified in the sequence that the changes are applied during evaluation, enabling you to see the progression of all changes both adding and deleting types to/from the unit. 3. The final set of types that are defined for the unit are listed. This set reflects the end result of all adding and deleting of types during the units processing. This mechanism is extremely helpful in verifying which types are/aren't assigned to a unit and in identifying timing problems in the sequencing of operations on the unit. This service traces the evaluation of all options that are defined for the unit. The trace results show each option in the exact order in which it is evaluated by Army Builder. For each option, the trace identifies whether it is compliant and/or selected. Compliance indicates that the option satisfied all established requirements, such as unit size and type constraints imposed by the usiz or utyp attributes. Chained options via the more attribute are also shown in their proper evaluation sequence, so you will know exactly what options were and were not evaluation, and in what order. This display is extremely useful for verifying the assumed sequence of evaluation for a set of options. It is also valuable for confirming whether hidden options are properly compliant with specified rules/constraints. This mechanism works identically to option tracing, except that the evaluation is performed on the set of tweaks associated with all items selected for the unit. All tweaks are listed in their exact evaluation sequence, with the tweaks for each attached item being separately tracked and reported. Some game systems make use of hidden stats behind the scenes. This option generates a report of all of the stats that are hidden, along with their final values. If the unit uses a stat-set, then all stats that are not part of the stat-set are included. This choice simply displays the normal roster notes that would be shown in response to the right-click when debugging is disabled.
Including User Documentation Before you unleash you data files on the world, please take a moment to think about how users will respond to your data files. They have never seen these files before, so it is likely that there will be certain ways in which you wrote the files that wont be immediately obvious. Once users get familiar with the files, theyre going to love them, but the key is to get them familiar with the files as quickly as possible. The solution is to include a few notes to users that explain how youve designed the files to be used. This can be done with relative ease through the use of the lnch and dfaq attributes, and you are strongly encouraged to make use of these mechanisms. The lnch attribute will allow you to provide introductory notes to the user when the data files are first loaded into Army Builder. And the dfaq attribute will enable you to write up a few basic instructions to users that will help get them jumpstarted on using your new data files. Examples of these attributes being put to good use can be found in a number of data file sets that are currently available, with one of the best being the Clan War Daimyo Edition data files. Distributing Data Files After all this work, you have now completed your data files and want to make them available to other gamers who play the same game system. The way to do this is to use the ABExport tool. This tool makes life easy for the user, since installing data files that have been packaged with ABExport requires only a few mouse clicks. However, when you package up your data files with ABExport, be certain to verify that all of the necessary files are
properly included within the file. The last thing you want is for the user to install your data files, find that one of them is missing, and be unable to use them. There is one final topic to consider when distributing your data files. Please be aware than each game system is a copyrighted work, so distributing data files which contain copyrighted information may be technically illegal. Most game companies have no problem with their loyal fans putting together tools that help to foster the play of their games. In fact, many companies actively encourage such practices, as long as their copyrights are included. You are encouraged to consider this issue and to be careful when distributing your data files to a wide audience. Importance of Version Numbers The definition file must have a version number specified within it. Each time you release an update to your data files, be sure to increase the version number appropriately. Army Builder will track the version of files currently installed by a user. If you increase the version number with each new release, Army Builder will be able to assist the user in making sure that the latest version of the files are installed. If you dont increase the version number, you will be leaving the user without appropriate guidance about which set of files are more complete. This can lead to confusion and frustration for the user, which is not at all necessary. To update the version number in your files, simply use the ABVersion tool, which makes the process quick and easy. The more care you put into the management of version numbers and packaging of data files for distribution, the easier it will be for users to leverage all of your hard work and make use of your data files. Adding Release Notes Whenever you release data files, there will always be changes from the last release. Many of these changes will be important to the people who will be using your new data files. Army Builder provides a very convenient mechanism for making these changes known to users. Whenever you include a file with the extension .txt within your import file (created with ABExport), Army Builder will assume that file contains release notes for the data files. These release notes will then be displayed to the user when the data files are imported. The release notes should contain important details about what has been added and/or changed within the data files, along with any special warnings that might effect existing saved roster files. The release notes file should be a standard text file, as it will be displayed verbatim to the user without any special formatting. Note! Only one text file will be recognized by Army Builder as the release notes within an import file. If more than one text file is included, Army Builder will randomly pick one of the files and display it. This file must have a .txt file extension for Army Builder to recognize it properly. Required Version of Army Builder Whenever you create or update a definition file or a data file, the version of Army Builder you are using in encoded into that file. Those data files will not work with an older version of Army Builder than the one used to created/update the files. If only one file is updated with a newer version of Army Builder, then the ENTIRE set of data files is assumed to require the new version. Beginning with V2.2, when the user imports data files, Army Builder will warn the user if a newer version of the product is required to actually utilize the data files. This will ensure that the user knows to download the newer version of Army Builder. Note! Older versions of Army Builder will not warn the user, so this could come up as a technical support question. If data files created with V2.2 or greater of the Construction Kit are loaded into Army Builder V2.1 or older, the data files will import properly and then fail to appear within the list of available game systems. Tell Us About Your Files! After you have created your data files, please let us know about them at Lone Wolf Development. If your data files are for a new game for which data files dont yet exist, we want to know about them. If you are willing to keep the files updated, then we can set you up with the ability to automatically notify all Army Builder users whenever you release new files. Via this mechanism, you can even make your files automatically available for immediate download by all users directly from within Army Builder. Just let us know about your data files and we can help you tell the world about them.
ABCREATOR
Overview The purpose of ABCreator is to make the job of creating and editing data files much easier. It does this by presenting a point-and-click interface through which you can add, modify, and delete all of the records within a data file. Since data files are very similar to a database, the ABCreator interface is similar to a simple database program. The key difference is that ABCreator is specifically tailored for editing Army Builder data files. This enables ABCreator to include helpful reminders and extra information about data files that should minimize the need for you to refer to the documentation while creating your data files. Most users will discover that ABCreator requires a small learning curve. To get you productive as quickly as possible, a tutorial for ABCreator is provided with the Construction Kit. This tutorial can be found in the file abctutor.rtf in the directory where you installed Army Builder, and a shortcut to it can be found on the Start menu at Programs->Army Builder->Army Builder->ABCreator Tutorial. Once you have familiarized yourself with the Construction Kit manual, this tutorial should enable you to make good use of the ABCreator tool very quickly. Getting Started To launch ABCreator, go to the Start menu (in the lower left corner of your screen) and select the shortcut item Programs->Army Builder->ABCreator. When ABCreator starts, the first thing you will likely notice is that this tool is devoid of the visual aesthetics that are present within Army Builder. This is because it is intended as a simple tool that will work much like a database program for creating and editing your data files. Army Builder itself is where you will show off your data files, so there is no need for beauty in ABCreator. When the tool is first launched, no data file is initially loaded, so nothing is shown but an essentially empty window. In order to do anything useful with ABCreator, you will need to either create a new data file or load an existing one via the main menu. The Main Menu ABCreator is a standard Windows application. As with all such applications, ABCreator has a main menu that is used to initiate use of the tool. There are four menus shown across the top: File, Edit, View, Settings, and Help. A quick description of each of these menus and their menu items is provided below: File New Create a new data file. ABCreator will present you with a list of the game systems for which it has found definition files that can be used. Once you select the desired game system, an empty set of data records is created for that game system. The list of game systems is automatically rebuilt every time that this menu item is selected, so a definition file can be created while ABCreator is already running and it will be properly identified when this menu item is next chosen. Open Open an existing data file. A standard Windows dialog is presented, and you can select the data file you want to edit. Once the data file is selected, the corresponding definition file from the same directory is automatically loaded and used. All of the records within the data file are loaded into memory and you are then able to edit them as you see fit. Close Close the current data file that is being edited. This unloads the data file from memory and data records are no longer shown in the ABCreator window. Save Save all of the changes that have been made to the currently loaded data file. If the data file already exists, then the changes are saved back to the same file. If a new set of records have not yet been saved, you are prompted to specify the filename in which to save them. Note! If any individual records are dirty, you are not prompted to save them. Only records that have
already been committed are actually saved to the data file. The reason for this is that there are often times during data file creation when you want to test something out before saving the changes to the record you are working on. If you want to save all your current edits, you must commit the changes before saving the file. Save As Save the current set of data records to a new data file. This is identical to Save, except that you are always asked to specify the filename in which to save the records. Export This item brings up a sub-menu that lists a number of the different record types used by Army Builder. By selecting one of these menu items, you can export a list of all records of the selected record type to a text file. The information exported for each record consists only of the primary fields for the record type, thereby allowing you to generate a quick-reference list that you can print out and refer to. Since many attributes reference other records, you will probably find this feature to be very helpful. Save to Text Save the current set of data records to a new file, writing them in text format. ABCreator operates on the run-time data file format that is used directly by Army Builder. However, the ABData tool requires a text file as its input. This menu item allows you to save the current set of records out to a text file in a format that can be properly read and converted by the ABData tool. If you want to obtain a quick list of the options, items, or whatever that exist within a given data file, this is the best way to do it. Simply save the data as a text file and edit it quickly to extract the information you want. Note! If the currently loaded data file has had its authoring information locked by its creator, then this menu item will be greyed out and not accessible. Exit Exit ABCreator. If the current set of records has not been saved, you are prompted to save them before you exit the program. Unlike the Save menu item, pending changes to individual records are flagged so that you can properly save them before exiting. Filename #1 At the bottom of the File menu will be a list of the most recently opened data files that you have been editing. This list will contain up to 9 filenames, starting with the last file you edited. This provides a quick means of switching between multiple data files that you have been editing, instead of having to re-type the filename every time. If you have more than one copy of ABCreator open at the same time, the list within all copies will be updated simultaneously, so opening a data file in one copy of ABCreator will add the file to the top of the list in all active copies of ABCreator. Edit New Create a new record of whatever type is currently selected. The currently selected record type is always indicated by the active tab. Save Save all changes to the active record of the currently selected type. If the record has not been modified in any way, this action does nothing. If there is an error in the data for the record, the validation test will fail and you will be informed of the field in which the problem was found. Delete Delete the active record of the currently selected type. If no record has been selected, this action does nothing. You are always prompted to confirm any attempt to delete a record. Revert Revert the contents of the active record of the currently selected type. Reverting a record causes all changes to be discarded and its contents reset back to the last saved state for the record. You are prompted to confirm this action before it is performed. Copy Record Copy the active record of the currently selected type. If no record has been selected, this action does nothing. You are always prompted to confirm any attempt to copy a record. When a copy is made,
the new record has the exact same contents as the original record, except that its unique id (or prefix, for races) is assigned the same dummy value as a newly created record. Find String Search through all of the records of the currently selected type for a specified text string. If any of the text-based fields of a record contain the specified string, that record is automatically selected for editing. The search string is case-sensitive. Find Next Continue a search that was initiated via the Find String menu item. The next record which contains the established text is selected for editing. Information Edit the version information associated with the current data file. View Definition Info This item brings up a dialog that displays all of the important information from the definition file associated with the current data file. Various attributes and fields within data files make explicit reference to abbreviations and other values that are specified in the definition file. In addition, the definition file may impose constraints and/or behaviors that need to be referenced while working on the data files. This dialog provides all the information that may be needed in one convenient place. Settings Unit Sort This item brings up a sub-menu that lists the various sort methods that can be selected for units. When the Units tab is selected, the chosen sort method is used for the list of existing units. The selected sort method is saved in the registry and restored when the program is again launched. Option Sort Just like Unit Sort (above), except that this sub-menu governs the sort method for the list of existing option records. Link Sort Just like Unit Sort (above), except that this sub-menu governs the sort method for the list of existing link records. Miscellaneous This item brings up a sub-menu with miscellaneous settings options. At present, the only available option is to select an alternate color scheme for use within ABCreator. Help Visit Wolf Lair Web Site This menu item brings up a sub-menu that lists a number of locations within the Wolf Lair web-site (home of Army Builder). By clicking on any of these menu items, your web browser will be automatically launched and you will be taken to the corresponding page of the web-site. If you do not have an appropriate web browser installed, this mechanism will not operate successfully for you. Technical Support This menu item displays information about how to contact Lone Wolf Development for technical support. About Display the About Box for ABCreator. The Overall Interface The overall interface of ABCreator is best described with a visual reference. Since the ABCreator window is empty until a data file is loaded, launch ABCreator and load the tutorial data file that is shipped with Army Builder (data.tut). Once this data file is loaded, you will see a set of nine tabs across the top. There is one tab for each record type that is found within an Army Builder data file. The currently selected record type is dictated by whichever tab is currently selected. The leftmost tab (Race) is always selected when a new data file is created or loaded.
At the left is a listbox that extends nearly the height of the window. This listbox will always contain the list of existing records of whichever record type is currently selected. If you click on one of the items in this list, the contents of the corresponding record are immediately loaded into the various data fields on the right. If you click on various records, the contents shown on the right continue to change as you select new records. Beneath the list of existing records are four buttons. These buttons correspond to each of the first four options listed in the Edit menu. Clicking on one of these buttons will have the exact same result as if you clicked on the menu item or pressed the corresponding keyboard shortcut shown in the menu. At the bottom of the window is a message area. Whenever you are entering data into one of the fields on the right, help text will appear in this region to provide additional information about what needs to be entered. Normally, this will provide a sufficient reminder to eliminate the need for you to reference the documentation for each field. Tab-Specific Details To the right of the list of existing records, all of the fields for each record are shown. The set of fields shown is different for each tab, since each record type within the data file has a different set of fields associated with it. Once you click on an existing record in the listbox on the left, the fields are populated with the actual contents of the selected record. There are a total of seven different types of fields that you will be presented with, each of which is described below: Simple Text: Text fields are simple data entry fields. In some cases, rules are enforced regarding the set of valid characters that can be entered (e.g. alphanumeric characters only) and/or the special syntax for the field. Such rules will often be described in the help text at the bottom, but compliance with rules is not checked until you attempt to save a record. Checkboxes are a simple selection of yes (checked) or no (unchecked) for a specific characteristic. A multiple-selection listbox allows you to select any number of items from a single list. Clicking on an item selects the new item only. To select/deselect individual items in the listbox, hold down the <Ctrl> key when you click on each item. To select a range of items, click on the first item and then hold down the <Shift> key when you click on the item at the other end of the range. A combobox provides a simple means of selecting one of a fixed set of items. Memo fields allow you to enter free-form text of any type. Often, though, these fields must comply with special formatting rules, so be aware. These rules will typically be mentioned in the help message region at the bottom of the window. Note! The single most important thing to remember about memo fields is that they may NOT contain any carriage returns. Since ABCreator is actually a tool that encapsulates the text data file mechanism, all of the text data file rules must be adhered to, which means that an embedded carriage return is a bad thing. Consequently, ABCreator will not accept carriage returns entered into memo fields. The convention used between entries within ABCreators memo fields is the semicolon and space character combination (; ).
Checkbox: Multi-Select List:
Combobox: Memo:
72
Attribute:
Link:
An attribute field is actually a collection of a listbox and three buttons. The listbox shows each attribute that has been defined. The buttons on the right allow you to create a New attribute, Edit an existing attribute, or Delete an existing attribute. If you create a new attribute or edit an existing one, a special dialog is displayed that shows all of the available attributes, providing full documentation for each, and allows you to enter/edit the proper attribute text to be used. Doubleclicking on an attribute in the list will be interpreted as a request to edit the contents of the attribute, with the appropriate dialog appearing. Beneath the three buttons described above are two arrow buttons, one pointing up and the other down. Clicking one of these buttons will move the currently selected attribute upwards or downwards one position in the list, which can be extremely useful when manipulating order-sensitive attributes. A link field is similar to an attribute, as it also consists of a listbox and three buttons. The listbox shows each of the links, while the buttons allow you to create a New link, Edit an existing link, or Delete an existing link. If you create or edit a link, a special dialog is displayed in which you can modify the definition of the link, which consists of the linked optoins unique id and the link nature. Double-clicking on a link in the list will be interpreted as a request to edit the contents of the link, with the appropriate dialog appearing.
Whenever a record is changed, it becomes dirty until it is either saved or the changes are discarded. Only one record of a given type can ever be dirty at one time. So, if you click on a unit record, change the name, and then click on another unit record, you will be forced to decide whether to save your changes or discard them before the new unit can be selected. However, things work differently between different record types. If you want, you can make changes to a unit, then switch over to the option records and make changes there. The changes to the unit are still pending, and you can return to the unit and continue editing it if you wish. Whenever a record of a given type is dirty, the tab name is shown with asterisks (*) around it. This way, if you switch between records, you can always see at a glance which records still need to be saved. This is incredibly useful when you are modifying one record and need to know a piece of information from another record (e.g. unique id, type, etc.), which often occurs when modifying the links for a unit or an attribute of a record. The moment that a record is saved or has its changes discarded (also called reverted), the asterisk disappears from the tab name. Creating New Records and Copying Existing Records Whenever you create a new record of a given record type, a new record is physically created. This new record is assigned various default values for each of its fields and must then be modified by you. In most cases, the created record will actually be valid, however the contents will typically be of no use. Consequently, it is up to you to modify the newly created record so that it becomes useful. If you accidentally create a record that you dont want, be sure to delete it before saving the data file. Newly created records are always assigned a dummy value for their initial unique id (or the prefix for races). You will need to change this id to something meaningful after the record is created. To avoid the possibility of having multiple invalid records and/or multiple records with the same initial contents, ABCreator will check when you try to create a new record. If another record already exists that contains the default (dummy) contents for the unique id field (or the prefix field for race records), the existing record is automatically selected instead of a new record being created. This same behavior is used for records that are copied. When a record is copied, the new copy is created with the exact same contents as the original record, except that its unique id (or the prefix for races) is assigned the same dummy value as a newly created record. The duplicate record will need to be assigned an appropriate unique id before it will be useful. If you attempt to copy a record while another record with the dummy id already exists, then the copy operation will report an error, as its required id is already in use.
73
Adding Comments To Your Data Files The creation of data files can become quite complex if you attempt to utilize all the power and flexibility of Army Builder. In some relatively extreme cases, you can find yourself with a couple dozen attributes attached to a record. Also, with the capabilities of Army Builder, it is possible to create tightly interwoven relationships between multiple records. With all these details to keep track, it can become easy to forget key inter-dependencies and why they are needed. To help alleviate this problem, every record within a data file contains a user comments field into which you can enter any text you want. These user comments are stored with all the other data for the record so they are a part of the data file. Within ABCreator, the user comments field is shown at the bottom of each record tab. Simply enter notes to yourself about what you are doing and why, and then youll have instant reminders available to you when you next set out to revise and/or enhance your data files. Command Line Usage Features ABCreator will accept command line parameters if you wish to provide them. The first parameter that can be specified is the filename of the data file to be opened for editing. If this file exists, ABCreator will automatically open the file and load it for editing. It is also possible to specify a second command line parameter for ABCreator. As long as a filename is specified to be opened, ABCreator can be instructed to automatically load the data file and then generate the corresponding text data file for the file. To convert a run-time data file to a text data file via the command line, the proper syntax is:
abcreator filename /Ttextfile
The /T switch specifies the name of the text file to be generated. The above command will run ABCreator from the command line, loading in the data file filename and then generating the file textfile as the proper text version of the data file. This single command is equivalent to launching ABCreator, opening the data file filename, selecting File>Save To Text, specifying textfile as the file to generate, clicking OK, and then exiting ABCreator. The major advantage of this feature is that groups of data files can be quickly remapped to a new definition file via batch processing.
74
OTHER TOOLS
Command-Line Tools Most of the tools that comprise the Construction Kit are command-line tools. This means that you will have to use these tools from within an MS-DOS Box under Windows 95/98 or in a Command Shell window under Windows NT. These are special windows, commonly referred to as console windows, in which you can type normal DOS commands. The various tools require that you specify a number of command line parameters, identifying the files to be used and created with each tool. If you are not familiar with using command-line tools under Windows (e.g. dir, copy, etc.), then you should familiarize yourself before attempting to use these components of the Construction Kit. In order to use the tools more easily, you may want to add the Construction Kit directory to your Path within the console window. To accomplish this, simply follow the standard procedure for your operating system. Alternately, you can choose not to modify your Path and simply run all of the tools directly from within the Construction Kit directory. The ABDef Tool The ABDef tool is used to convert your text definition file into the corresponding run-time definition file for use within Army Builder. To use the ABDef tool, you will need to be running within a console window and you will need your text definition file. Invoking the ABDef tool is simple, since it takes two command line parameters and will inform you if either of the parameters is incorrect (or if you dont specify the correct number of parameters). The format of the command line used to invoke the ABDef tool is shown below:
abdef text-file def-file
The first parameter specifies the text file that contains the definition information you want converted. This file is assumed to be in the current default directory, unless you specify the path as part of the filename. The second parameter is the name of the run-time definition file that you want to create. This file will be created in the current default directory unless you specify the desired path as part of the filename. If the text file doesnt exist, an error is reported. If the run-time file already exists, it is overwritten without asking for confirmation, thereby allowing you to run the ABDef tool from within a batch file if you wish. If there are any errors parsing the text definition, an appropriate error message is output and you will need to edit the file and try again. As an example, suppose that we have created a text definition file that is named def.txt. This file is located in the data directory beneath where Army Builder is installed. To minimize confusion, well assume that no modifications have been made to the search Path on the computer, and well assume that the current default directory in the console window is the Army Builder directory. Our goal is to create a run-time definition file from the text file, and we want to use the abbreviation .xyz for our game system. This is what the command line would look like to achieve this:
abdef data\def.txt data\datadef.xyz
Since the current default directory is the Army Builder directory, the ABDef program file is in the current directory. This means that all we need to do is specify the program name. Our text definition file is located in the data directory, so we need to specify the path to the file, hence the inclusion of data\ before the filename. We need to create the run-time definition file in the data directory also, so we need to include the data\ prefix before this filename, too. Since run-time definition files must always be named datadef.* and we want our game system to use the .xyz prefix, this means that the run-time definition filename must be datadef.xyz. The ABData Tool The ABData tool is used to convert your text data file(s) into the corresponding run-time data file(s) for use within Army Builder. To use the ABData tool, you will need to be running within a console window. You will also need a valid, run-time definition file that you successfully created with the ABDef tool, since each data file makes constant references to the information within the definition file. Lastly, you will need your text data file.
Invoking the ABData tool requires three command-line parameters. The tool will notify you if there are any problems with the parameters you specify. The format of the command line used to invoke the ABData tool is shown below:
abdata def-file text-file data-file
The first parameter specifies the valid, run-time definition file for the game system that the data file is designed for. This file is assumed to be in the current default directory, unless you specify the path as part of the filename. The second parameter identifies the text file that contains the data records you want converted. This file is assumed to be in the current default directory as well, unless you specify the path as part of the filename. The third and final parameter is the name of the run-time data file that you want to create. This file will be created in the current default directory unless you specify the desired path as part of the filename. If either the definition or text file doesnt exist, an error is reported. If the run-time data file already exists, it is overwritten without asking for confirmation, thereby allowing you to run the ABData tool from within a batch file if you wish. If there are any errors parsing the text data file, then an appropriate error message is output to the console window and you will need to edit the file and try again. Continuing with the example for ABDef, lets assume that we now have a text data file named data.txt. This file is located in the data directory, too. If everything else is the same as in the previous example, the command line would be:
abdata data\datadef.xyz data\data.txt data\data.xyz
As before, the program is located in the current directory, so we need only specify the name. Since all of the files we use are located in the data directory, we need to specify the data\ prefix for each. The first parameter indicates the run-time definition file we created previously (datadef.xyz), the second parameter identifies the text data file we want to process (data.txt), and the final parameter specifies the run-time data file to create (data.xyz). Since the file extension we chose for our game system is .xyz, the created data file must also use that same extension. The ABExport Tool After a great deal of work, your data files are complete and now you want to make them available to other Army Builder users. Now what? You might consider using a compression tool like PKZip to bundle up all of your files into a single file that can be downloaded quickly over the Internet. The only problem with this approach is that users will then need to extract the files out of the compressed files and ultimately copy them into the proper location on their system manually. The user would be required to both have the necessary tools on his machine and be familiar with their use, which is not necessarily a good assumption to make. This is where the ABExport tool comes in. The ABExport tool is used to package up one or more Army Builder files into a single import file, much like PKZip would accomplish. The created file is compressed using a compression algorithm that is compatible with the one used in PKZip. The key differences are that you can include comments within your import file and that Army Builder is able to readily import one of these files automatically. This approach eliminates the need for the user to use any special tools on his computer. All that the user needs to do is download the compressed file, then go into Army Builder and import the file. The contents of the file are automatically decompressed and copied into the proper location on the users computer. The ABExport tool is a command-line tool that requires a variable number of parameters. The actual parameters that it expects depend on what you are trying to accomplish with the tool. The full command line syntax for the tool can be summarized as follows:
abexport [-v] [-x] import-file [-c"comments"] [ file1 [ file2 ... ] ]
There are basically three different ways in which you can use this tool, and each will be described separately. In all three uses, all files are assumed to be located in the current default directory, unless you specify the path as part of the filename. Additionally, the import file is assumed to have an extension of .ab unless you specify something different. Method 1 Creating an Import File
The first (and most typical) use of this tool is to create a new import file. In this case, neither the -v nor -x switches are used, and the import-file parameter specifies the new import file to be created. If you want to include any comments about the data files (e.g. date, author, game system, etc.), then those must be specified next on the command line, using the -c switch. When you use the -c switch, the comments text must immediately follow the switch and must be enclosed within double-quotes (so that you can embed spaces if you wish). The remaining command line parameters can be any number of file specifications, although there must be at least one. Each file specification must be a valid filename that you want to include in the import file. It is perfectly valid to include wildcards in these file specifications, and all matching files will be added to the import file. Once the import file is created, a summary of the contents of the import file is output to the console window so that you can see what was added to the new import file. The following command line will create an import file named bar.ab that has the text This is a comment as its comments and will include the file foo.xxx and all files matching *.yyy.
abexport bar cThis is a comment foo.xxx *.yyy
When creating import files, it is recommended that you always use the default extension of .ab, since the Army Builder import mechanism looks for files with this extension automatically. It is also valid to use the .zip extension, although it is typically a bad idea to do so. When you use a .zip extension, many users assume that they are supposed to open up the file themselves, which is precisely what the import mechanism strives to avoid. Use of the .zip extension leads to confusion for many users, so it is usually a good idea to always use the .ab extension for import files. Method 2 Querying the Contents of an Import File The second use for this tool is simply to find out the contents of a specified import file. In this case, the -v switch is used, as is the import-file. No other parameters should be given. When you use this method, the import file is opened and a summary of its contents is output to the console window. Method 3 Extracting Files from an Import File The third use of this tool is to extract the files out of a specified import file. In this case, the -x switch is used, as is the import-file. No other parameters should be given. When you use this method, the import file is opened and all of the files within it are decompressed and copied into the current default directory. If a file already exists in the current directory, it is overwritten no confirmation is requested. The ABUndef Tool There may be times when you receive a set of data files from someone else and, for one reason or another, you need to modify the definition file. To assist in this situation, a tool is included called ABUndef. This tool will effectively decompile a run-time definition file and generate the corresponding text file from which it was created (minus any comments, of course). Once you have this text file, you can then edit it and run the ABDef tool to create your updated definition file. To use the ABUndef tool, you must be running within a console window. You will also need the run-time definition file that you want to decompile. To invoke the ABUndef tool from the console window, you must specify both the run-time definition file you want to decompile and the corresponding text file that you want created as the two command-line parameters. The format of the command-line to run the ABUndef tool is given below:
abundef def-file text-file
The first parameter specifies the run-time definition file that you want to decompile. This file is assumed to be in the current default directory, unless you specify the path as part of the filename. The second parameter identifies the name of the text file that you want ABUndef to create for you. This file is also assumed to be in the default directory, unless specified otherwise. When the ABUndef tool runs, it opens the definition file and creates a text file containing the corresponding contents. You can then use the ABDef tool to re-create the definition file (probably with a few modifications first). If the text file already exists, it is automatically overwritten by this tool. If there are any problems opening or creating either of the files, an appropriate error is reported to the console
window. The ABVersion Tool Once the definition file is completed for a set of data files, there will often be only infrequent need to modify that definition file. However, with the version information stored in the definition, the definition will need to be updated every time you release a new set of your files to the world. It can become a nuisance to have to regularly open up the definition text file (possibly running ABUndef to generate it), edit the version number, save the file, and then run ABDef on the file. To alleviate this, the tool ABVersion is provided. This tool allows you to quickly update just the version number in a definition file quickly and painlessly. The ABVersion tool must be executred within a console window. The tool accepts a run-time definition filename and a major and minor version number as parameters. The definition file is opened, the versions updated, and then the file saved again. If the file is locked, then the proper password must be provided to update the version. If no new version is given, the current version information is displayed (which is convenient if you forget the current version number assigned and want to do a quick check). The format of the command line to run ABVersion is given below:
abversion def-file [major.minor [password]]
The first parameter specifies the run-time definition file that you want to update. This file is assumed to be in the current default directory, unless you specify the path as part of the filename. If all you want to do is check on the currently assigned version number, no other parameters are necessary. The second parameter identifies the new version number to be assigned, which consists of two components a major and a minor version number (described in more detail below). The third and final parameter is only required if you are specifying a new version and the definition file has been locked. If the file is locked, you must provide the proper password in order to enable ABVersion to update the contents of the file. You do NOT need the password to simply view the current version number. Version numbers consist of a major and minor value, separated by a period. For example, the version number 4.2 would indicate a major version of 4 and a minor version of 2. When you are updating your files, the major version component is typically increased whenever major changes/additions are made to the data files. In contrast, the minor number is typically increased when the changes are relatively minor. The standard convention is to reset the minor version number to zero whenever you increase the major version component. For example, version 4.0 might follow 3.2. The specific policies of when you update each value is entirely up to you, although please be sure that the overall version number always increases with each new release of data files. The contents of the definition file are directly modified by this tool, so make a backup if you are concerned about any problems arising. If there are any problems opening or updating the file, an appropriate error is reported to the console window. Only if there is an unexpected problem while trying to save the changes to the file will the definition files integrity be at risk.
78
PUBLIC XML FILE FORMAT

Version 2.x of Army Builder introduces the ability to save rosters in a publicly defined XML file format. What this means is that you can now write your own companions programs for Army Builder that take roster files and manipulate them just the way you want them. You can write your own roster printing programs that integrate custom graphics and layouts that are specific to your favorite game system. You can also write programs that let you view rosters on other computers, such as handheld computers. The Construction Kit includes complete source code that lets you read and manipulate these XML roster files. A complete sample application that converts an XML roster file into an HTML page is also included. Armed with these pieces, you can begin writing your own companion programs in no time at all. You will find all of these pieces installed in the xml directory beneath where Army Builder was installed. All of the source code is written in C++, but there should be a Windows DLL version of the code available in the future (for use with other languages like Visual Basic). Full details on the XML package can be found in the readme file that is located in the xml directory. Please start by reading this file and then give the sample source code a try.
79
CUSTOM OUTPUT EXTENSIONS

Important Note! This chapter provides an overview of what custom extensions are and how they are created. Further details on creating custom output extensions are provided within the Construction Kit, although they are separate from this manual. The Construction Kit includes a complete source code framework for quickly creating your own extension. There is even a fully operational custom extension with full source code. You will find all of these materials installed in the extension directory beneath where Army Builder has been installed. Full details on the package will be found in the readme file located in the extension directory. Overview Army Builder generates roster output (e.g. printouts) using generalized methods that work reasonably well for all game systems. However, some game systems are best served by specialized roster output that tailors the output to the particular game. An excellent example is a Mech sheet for Battletech, where the ideal printed roster contains a graphical representation of the Mech that is completely filled out. To accommodate these situations, Army Builder allows custom output extensions to be created and integrated directly into the product. These extensions are separate programs that Army Builder invokes directly, allowing the user to make use of the extensions from within Army Builder. Additional menu items are added to Army Builder that enable the user to invoke the extensions directly. Creating an Extension As just mentioned, custom extensions are separate programs from Army Builder. Each extension takes an Army Builder roster in the publicly defined XML format as its input. The extension then extracts the roster information from the XML file and uses it to generate customized output. Army Builder generates an XML file for the current roster and then invokes an extension as a separate executable, passing the program information on the command line. The first command line parameter to an extension is the filename of the XML file. Additional command line parameters can also be passed in by Army Builder as literal strings if desired, although the XML filename is the only required parameter that must be supported. A key requirement is that the name of the executable should reflect the name of the game system in some way so that extension programs for multiple game systems dont use the same names as each other (e.g. name the file b5_print.exe instead of print.exe). The key advantage of supporting extra command line parameters for an extension is that the same extension program can be re-used for different purposes. Multiple user-selectable menu items can be defined that invoke the same extension with different command line parameters. This eliminates the need for the extension to present its own user-interface to the user to obtain basic customization details (e.g. one per page), creating a clean integration with Army Builder that most users will view as seamless. It also simplifies the development of the custom extension program, since including a user-interface requires additional work. Note! When the extension is invoked, the current working directory will always be the location where Army Builder has been installed (e.g. c:\armybuilder). Integrating Extensions After a custom extension program is created, the second step is integrating it into Army Builder. When an extension is integrated, one or more custom menu items are added beneath the Output Extensions sub-menu (underneath the File menu). To define an extension, the race attribute xmlx must be utilized. This attribute allows a data file author to specify the menu name to display for the extension, the name of the extension program to be invoked, and the list of additional command line parameters to pass to the program (if any). You can specify whether Army Builder should wrap the XML filename within double quotes. This can be very useful if you have specify extra parameters on the command line. On some users computers, the absolute path of the filename can contain spaces, which makes parsing the parameter list more difficult. Wrapping the filename within double quotes guarantees that you can easily extract the filename and the additional parameters with ease. This attribute should be defined as a global augmentation to ensure that it is always recognized properly by Army
Builder when the data files are loaded. For more details on global race augmentations, please see the separate discussion of this technique elsewhere in this document. Since extensions appear to the user as fully integrated into Army Builder, the extension also needs to be documented somewhere within Army Builder. The easiest solution for this is to simply define a dfaq attribute that fully describes any special considerations in using an extension. Typically, there should be one dfaq entry for every xmlx entry in the data files. Note! A maximum of 10 custom extensions can be added for a given game system. If more are defined, any excess are simply ignored. Packaging for Deployment with Data Files Custom extensions must be placed into the Data directory where normal data files are installed, since this is where Army Builder will look for them. This enables extensions to be packaged up within a standard import file using ABExport. The separate program can be listed on the ABExport command line along with all other data files and is then imported properly when the user installs the data files on his computer. Deploying extensions this way is easy and the extension can be treated as an integral part of the data files. Packaging for Independent Deployment Sometimes you will want to create an extension that is deployed separately from the core set of data files for a game system. For example, if one person creates the data files and another writes the extension, it may be easier to release the two separately from each other. This situation can be easily handled. The key is for the author of the extension to create his own data file that will serve to integrate the extension into Army Builder. This data file must be named something different than all the core data files so that no name conflicts are encountered. Within this data file, two things must be specified. First, the xmlx attribute needs to be defined to integrate the extension into Army Builder. If the extension is used in multiple ways, then all of the necessary xmlx attributes should be defined in the same file. Second, the appropriate dfaq attributes must be defined to provide the user with full documentation on using the extension. Once the data file is created, ABExport can be used to create an import file that contains exactly two files: the extension executable and the data file. The generated import file will not contain a definition file. Therefore, Army Builder will assume that the import file augments the already installed data files, and the checkbox that automatically deletes all non-included files during the import will NOT be checked. The net result is that the extension will be properly installed in addition to the core data files that are already in place. The extension will then be available for use when the game system is next loaded.
81
APPENDIX
Internal Limits There are a number of limits imposed upon data files. These limits are shared by both the ABData and ABCreator tools. The maximum number of records that can be specified for a given data file are identified below: Maximum Races: Maximum Units: Maximum Options: Maximum Items: Maximum Elements: Maximum Tweaks: Maximum Links: Maximum Augmentations: 200 3,000 3,000 5,000 5,000 3,000 25,000 20,000
Additional internal limits also exist for the definition files that you create. The pertinent limits that you need to be aware of are given below: Max. Number of Unit Statistics: Max. Unit Categories: Max. Option Categories: Max. Item Categories: Max. Tweak Categories: Max. Conflict Groups: Max. Composition Groups (Total): Max. Composition Groups (Per Race): Max. Number of Stat Sets: 60 30 30 30 30 30 20 8 20
The maximum size allowed for a run-time definition file is 50KB, which is 5-10 times the typical size. The maximum size allowed for a run-time data file is 1MB, which is 20 times the typical size. If there is ever a need to have more data than this, it is always possible to split up a large data file into one or more smaller data files, as there is no limit to the total size of all data files at run-time (only the size of a single file). Besides, working with smaller data files is much easier when creating and maintaining the files. Additional internal limits that you might find useful include the following: Max. Data Files Per Game System: Max. Size of a Single Attribute: Max. Size of all Attributes for 1 Record: Max. Number of Attributes Per Record: Max. Size of Comments Fields: Max. Size of Notes Fields: Max. Size of Report Fields: Max. Number Entries in Table Attribute: Max. Special Items Per Unit: Max. Elements Per Constructed Item: Max. Extra Types Assigned Per Unit: Max. Tweaks Per Special Item: 500 1,000 10,000 100 1,000 1,000 1,000 50 500 10 40 100
82

Const Kit

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Const Kit

Hochgeladen von

Copyright:

Verfügbare Formate

CONSTRUCTION KIT V2.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Item Categories: Tweak Categories: Conflict Groups:

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Unique Id: Type:

Mode (or Scenario):

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Are Combos Unique?:

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Units: Options: Items:

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Is Shared?: Allies: Ally Group:

Construction Kit V2.2b

Name: Abbreviation: Composition:

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Cost: Item Count: Local Attributes:

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Conflicts: Cost: Max # Taken:

Slots Used: Is Unique?: Attributes:

Comments: Report: Min # Taken:

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

Construction Kit V2.2b

Copyright 1998-2001 by Lone Wolf Development, Inc.

CORE DATA FILE CONCEPTS

Construction Kit V2.2b