GCA Data File
From GCAWiki
GCA Data File (also referred to as GDF) is a file format for containing the data and directives used to populate GCA's character trait lists. GDFs are cascading, meaning a GDF may delete, replace, or update data loaded by a previously loaded GDF.
Contents
|
[edit] General format and syntax
...general format/syntax mumble...
[edit] Type Hinting Prefixes
Identifiers in GCA can, and should in most cases, include a prefix which signifies their type — this is especially important in cases where multiple traits have the same name, so GCA will know which trait you are referring to. The common type prefixes are:
Prefix Description ST: Statistics/Attributes TE: Templates AD: Advantages PE: Perks DI: Disadvantages QU: Quirks SK: Skills SP: Spells EQ: Equipment GR: Groups
Prefix Description SAMECAT: Refers to a trait of the same category as the trait being needs checked TECAT:, PACAT: Refers to a category of templates/packages ADCAT:, CA: Refers to a category of advantages DICAT:, DISADCAT: Refers to a category of disadvantages SKCAT:, SKILLCAT:, CL: Refers to a category (class) of skills SPCAT:, SPELLCAT:, CO: Refers to a category (college) of spells EQCAT:, EQUIPCAT: Refers to a category of equipment
See the list of type prefixes for a more comprehensive list.
[edit] Other concepts
[edit] Bonuses
[edit] Compound bonuses
These are bonuses that use a single bonus listing to grant a bonus to one or more possible targets, but that will *not* add the bonus more than once to any particular target, no matter how many of the listed targets it may qualify as. For example, gives(+1 to (CO:Air, CO:Water)) is a compound bonus, as it grants a bonus to both the colleges of Air and Water, but any spell that might belong to both colleges will still only get a single +1 bonus, not a +2 for belonging to both colleges. Note that if the gives() had been written gives(+1 to CO:Air, +1 to CO:Water), a spell belonging to both colleges *would* receive a +2, because it would satisfy both targets for both bonuses--this is what compound bonuses are meant to address. Note that compound bonuses do not work with target tag bonuses, or with targets of me:: or owner::. To create a compound bonus, the structure is the same as any other gives() bonus, except that the targets should be enclosed in a parens as a comma separated list. If a target name includes commas, it may be enclosed in quotes or curly braces. Since: 4b366.
[edit] Commands
[edit] #DeleteByTag <traitlist>, <commands>, <tag=value>
<traitlist> is the list to look in, such as Skills, Equipment, or All for everything.
<commands> is everything needed to specify what GCA should do with the comparison; usually, this means specifying Num or # for a numeric comparison, or $ or Text for a text comparison; this will vary by tag. You can also specify IgnoreEmpty to have GCA ignore tags that are empty (this prevents IsEmpty or IsNotEmpty from working; see below), and EchoLog if you want to fill your log with endless lines of GCA showing you what it looked at and did or didn't delete as a result.
<tag=value> is the name of the tag, the comparison to make, and the value you're looking for. The tag name should be exactly as used by GCA, and the value should be the exact text or number to compare against. Valid comparisons are >, <, =, >=, <=, or <>. Also, because comparing text for/against an empty tag can result in unexpected behavior during text comparisons (numeric comparisons convert empty tags to 0, so use IgnoreEmpty for those if 0 doesn't work for you in such cases), there are two special text comparison operators that have no "value" portion, and these are IsEmpty and IsNotEmpty. IsEmpty counts as True if the specified tag is empty, and IsNotEmpty counts as True if the tag is not empty.
Here are a couple examples:
#DeleteByTag Equipment, Num IgnoreEmpty, techlvl < 5
This command will delete any equipment items that have specified a techlvl() tag, and for which the numeric value contained in that tag is less than 5. Note, however, that Numeric comparisons convert text values to numbers, and if there's not a number as the text value, it is probably going to convert to 0. This means that in our example here, traits such as "_New Armor", that have a techlvl([techlevel]) like this, will appear to evaluate to techlvl(0), which means in our example it would be deleted. To avoid this kind of result, you'll probably need to do a Text comparison, and compare each techlvl you want to delete, like so:
#DeleteByTag Equipment, Text IgnoreEmpty, techlvl = 0 #DeleteByTag Equipment, Text IgnoreEmpty, techlvl = 1 #DeleteByTag Equipment, Text IgnoreEmpty, techlvl = 2 #DeleteByTag Equipment, Text IgnoreEmpty, techlvl = 3 #DeleteByTag Equipment, Text IgnoreEmpty, techlvl = 4
Be aware that in this particular example, there are a number of traits, such as "_New Innate Attack", that are currently marked as techlvl(0), which you probably don't really want to delete. But, for our purposes here, this set of commands would delete everything below techlvl(5), but not delete traits with other text values.
#DeleteByTag All, Text, x IsNotEmpty
This command will delete any trait where the x() tag has anything in it at all. (This would remove pretty much everything in GCA that appears with a little wrench icon next to it in the Available lists.)
#DeleteByTag for some special case "comparisons" that can be done when working with Text. <tag=value> can use the format <tag> HasInList <value> or <tag> Contains <value>. In the HasInList case, the being checked will be considered to be a comma delimited list, and the must match one of the items in that list. In the Contains case, the whole string of text in the will be looked at, and if appears anywhere in the string, it will be considered to match. Both of these are case insensitive.
#DeleteByTag supports an Unless clause, to allow for an exception to the rule. Unless supports all the same comparisons as the standard clause. You create an Unless section by including the keyword Unless followed by the comparison to be made. You may also include the same Numeric or Text designations immediately after the Unless keyword, if you want to use a different type from the base comparision. Here is an example:
#DeleteByTag Equipment, Numeric IgnoreEmpty EchoLog, techlvl >= 5 unless $ techlvl contains ^
#DeleteByTag also supports two additional special text comparison operators: IsNumeric and IsNotNumeric. These test if the tag value would qualify as a numeric value or not. While making a Numeric test, remember that non-numeric values usually evaluate to 0 (or the value of any numbers beginning the text). If testing IsNumeric, it only qualifies as true if the entire value qualifies as a number. An example:
#DeleteByTag Equipment, Numeric IgnoreEmpty EchoLog, techlvl < 5 unless $ techlvl IsNotNumeric
A numeric test of the techlvl() tag would be done, and a number of special cases would be deleted if not saved by the Unless clause, which allows for preserving those values due to the fact that they're not actually numbers, just text that were converted to 0 for the simple numeric comparison.
[edit] Directives
Directives are special commands within traits, that are acted upon by GCA when it adds a trait containing a directive to a character. As a general rule, directives will be found within the x() tag for a trait, but they may also be used within other tags when needed.
[edit] #BuildIt
The #BuildIt directive prompts GCA to offer the user the Modifiers window, with which they can build the version of the added item they intend to use.
Template: #buildit
This directive has no options, and therefore has no parentheses or available tags.
Notes: As with other directives, GCA will remove this directive from the trait when it is added to the character.
[edit] #BuildList
The #BuildList directive allows you to create a list with custom text options, building up from a list output by another directive or entered directly.
Template: #BuildList( list(item1, ..., itemN), template( [some text]%ListItem%[more text] ) )
Available Tags: list(), template()
list( item1, ..., itemN )- Allows you to specify the comma-separated list of items to be used when building the output list. Any item that includes commas must must be enclosed within quotes or curly {} braces. If an item includes quotes, you should enclose it in braces instead of more quotes. If you use braces, GCA will not attempt to also remove any quotes or doubled quotes.
template( [some text]%ListItem%[more text] )- Allows you to specify the appearance of the text for each item created in the output list. Every item in the list will be output to match the template, with the special variable %ListItem% being replaced by the item from the list that's currently being output. Text to the left and right of the %ListItem% will be used exactly as is to create the output item, so any quotes or other special characters will be used as is, and will appear in the output list. You must be careful, however, not to include single, unmatched parens, as that will mess up GCA's ability to parse things correctly.
Notes: As with other directives, GCA will remove this directive from the trait when it is added to the character. The output generated by this directive will be inserted directly in place of this directive.
[edit] #Choice
The #Choice directive allows you to provide the user with a list of options, and to obtain the one they pick. This is intended to be a quicker means of getting a simple, single choice from the user than #ChoiceList.
Template: #Choice( "item1"[=cost1] [, ..., "itemN"[=costN] ] )
This directive takes a comma separated list of items. If you also want to provide the user with costs for the items, you need to use the optional cost assignment, which is done by including the cost for each item after an equals sign following the item text.
The costs are not used for making the selection; they would be included for reference only, or if you needed the cost for the selected item later. Only a single item can be selected by the user.
The items in the list may be surrounded by quotes, as shown in the template, or by curly {} braces. You must use one or the other if the item includes commas or equals signs. Use the curly braces instead of the quotes if the item contains quotes, or even if you simply prefer them. Note that if you do use the braces, GCA will not attempt to remove any quotes or doubled-qoutes from the item names. Remember that in either case, the cost assignment would come outside the quotes or braces.
Result Variables: %choice%, %choicecost%
%choice%- GCA will insert the user's selected option in place of this variable.
One or both of the options shown may be used, and may be used more than once. GCA will make the replacements anywhere the result variables are found in the trait definition. Note that the results placed into the variables by GCA will not include quotes.
%choicecost%- GCA will insert the specified cost of the user's selected option in place of this variable.
Notes: As with other directives, GCA will remove this directive from the trait when it is added to the character. Unlike with other directives, the output generated by this directive will be inserted in place of the result variables, instead of in place of this directive.
[edit] #GroupList
The #GroupList directive allows you to include a comma separated list of items based on an existing Group. By default, the name of the items obtained from the group will include the prefix tag.
Template: #GroupList(GR:GroupName [, taglist])
GR:GroupName- The name of the Group to be used, as defined in a Group section of a data file. It may be enclosed in quotes (must be if the name includes a comma).
taglist- The optional list of tags applicable to creating the output of the #GroupList directive.
Available Tags: append(), prepend(), flags()
The flags that may be used in the
append( text )- Allows you to include a bit of text that will be added to the end of each item from the group. Do not enclose the append text in quotes, although you may use quotes as part of the append text if you wish.
prepend( text )- Allows you to include a bit of text that will be added to the front of each item from the group. Do not enclose the prepend text in quotes, although you may use quotes as part of the prepend text if you wish.
flags( flaglist )- Allows you to include flags that alter the behavior of the list generation. One or more flags may be included in the
flaglist, and if more than one, they should be separated by commas.flaglistare:
NoPrefixto prevent the inclusion of the prefix tags in the names of group items.InQuotesto enclose each list item within quotes. Any appended or prepended text will appear outside the quotes.InParensto enclose each list item within parentheses. Any appended or prepended text will appear outside the parens.InBracesto enclose each list item within curly {} braces. Any appended or prepended text will appear outside the braces.MasterQuotesto have GCA place quotes around the whole item and appended/prepended text combination.MasterBracesto have GCA place curly {} braces around the whole item and appended/prepended text combination.
Notes: As with other directives, GCA will remove this directive from the trait when it is added to the character. The output generated by this directive will be inserted directly in place of this directive.
[edit] #List
The #List directive allows for building a list from the contents of a List section in a data file, without having to include the contents of the list entirely in the trait where it is found. The #List directive will take the specified ListName and create a comma separated list, which will be inserted in place of the #List directive in the trait, before it is added to the character. This allows for building a #ChoiceList or other list-based part of a trait at the time the trait is added to the character.
Template: #List(ListName [, taglist])
ListName- The name of the List item, as defined in the List section of a data file. It may be enclosed in quotes (must be if the name includes a comma).
taglist- The optional list of tags applicable to creating the output of the #List directive.
Available Tags: append(), prepend(), flags()
The flags that may be used in the
append( text )- Allows you to include a bit of text that will be added to the end of each item from the list. Do not enclose the append text in quotes, although you may use quotes as part of the append text if you wish.
prepend( text )- Allows you to include a bit of text that will be added to the front of each item from the list. Do not enclose the prepend text in quotes, although you may use quotes as part of the prepend text if you wish.
flags( flaglist )- Allows you to include flags that alter the behavior of the list generation. One or more flags may be included in the
flaglist, and if more than one, they should be separated by commas.flaglistare:
InQuotesto enclose each list item within quotes. Any appended or prepended text will appear outside the quotes.InParensto enclose each list item within parentheses. Any appended or prepended text will appear outside the parens.InBracesto enclose each list item within curly {} braces. Any appended or prepended text will appear outside the braces.MasterQuotesto have GCA place quotes around the whole item and appended/prepended text combination.MasterBracesto have GCA place curly {} braces around the whole item and appended/prepended text combination.
Notes: As with other directives, GCA will remove this directive from the trait when it is added to the character. The output generated by this directive will be inserted directly in place of this directive.
[edit] Functions
...general function mumble...
[edit] Math functions
[edit] @IsEven(value)
Returns true if given value is an even integer, or false otherwise. Since: 4b367.
[edit] @Modulo(value1, value2)
Returns the remainder value after value1 is divided by value2. For example, @Modulo(10,2) would return 0, while @Modulo(10,6) would return 4. Since: 4b367.
[edit] @round(VALUE [, DECIMALPLACES])
VALUE may be any valid math expression or numeric value, and DECIMALPLACES specifies how many decimal places VALUE should be rounded off to. If DECIMALPLACES is omitted, an integer value is returned.
[edit] System Variables & Keywords
...general variable & keyword mumble...
[edit] Tags
[edit] Conventions
[edit] char prefix
Tags beginning with the prefix char are used for holding values calculated for specific characters based upon the values of their non-prefixed namesakes and applicable modifiers.
[edit] System Tags
All of the tags listed here can be accessed through TagItem("tagname"). Some of these tags are actually read-only, and will be noted where appropriate.
[edit] aa
Applies to: Traits
Valid values: 1
The aa() tag is used by GCA to mark active armor traits, such as those selected in the Apply Armor section of the Protection window. If aa() is not empty, the armor or shield is active, otherwise it is not. GCA will set this value to aa(1), or delete the aa() tag, as appropriate, while in the Protection window. Externally setting the aa() tag to some value is acceptable, but it will have no effect on the character until the Protection window is opened and the tags are read, allowing GCA to reconfigure the armor settings.
[edit] acc
Applies to: Traits
Valid values: x | x+y : where x and y are integer values.
The acc() tag represents the acc value as from the GURPS weapons charts. This is the default acc value, but may not be the actual acc value for the particular weapon; for that, see the characc() tag.
addmode
adds
apppoints
armordivisor
baseapppoints
basecost
basedgroup
basedon
baselevel
basemod
basepoints
baseqty
basescore
basevalue
baseweight
blockat
blocklevel
bonus
bonusbasepoints
bonuslevels
bonuslist
bonuspoints
castingcost
cat
[edit] characc
Applies to: Traits
Valid values: GCA filled
The characc() tag represents the acc value as from the GURPS weapons charts, but as it specifically applies to the particular weapon or attack containing this tag. Any bonuses or penalties applied against the trait's acc() value will be reflected in the final characc() value. GCA always calculates this value, so any changes made directly to the tag value will be lost next time GCA recalculates it.
chararmordivisor
chardamage
chardamtype
chardb
chardr
charminst
charparry
charparryscore
charradius
charrangehalfdam
charrangemax
charreach
charshots
charskillscore
charskillused
childkeylist
childof
childpoints
childrencosts
childrenweights
college
conditionallist
control_downto
control_upto
cost
costcnt
count
countasneed
creates
currentmods
damage
damagebasedon
damtype
db
default
deffrom
deffromid
deflevel
defpoints
description
disabled
disabledfrom
disabledwith
display
displaycost
displayweight
dmg
doubleinplay
down
dr
duration
extralevels
extrapoints
familiarities
features
forceformula
formula
frozencost
frozenlevel
fullname
fullnametl
gives
gms
group
hasmods
hide
hides
init
initmods
inplaymult
invalid
isparent
itemtype
keep
level
levelmult
levelnames
load
location
locked
locks
lockstep
mainwin
maxdam
maxscore
mergetags
minscore
minst
modcnt
mode
mods
multpoints
name
nameext
ndl
needs
needs*disabled*
needscheck
noresync
notes
ocount
optspec
owned
owns
page
parentkey
parentof
parry
parryat
parryatbonus
parryatmult
parrylevel
pd
pkids
pointmult
points
precountcost
precountweight
premodscost
premodspoints
premodsvalue
prereqcount
race
radius
raiseruleof
rangehalfdam
rangemax
reach
replacetags
round
roundmods
score
sd
sets
[edit] shieldarc
Applies to: Traits
Valid values: None | Left Arm | Right Arm | Back
The shieldarc() tag is used by GCA to mark specific protection arcs provided by a shield. At this time, these are represented by the specific values shown in Valid values. Additional valid values may be added in the future, but GCA will not currently understand any but those shown here. Left Arm represents the arc from the left flank through the front hexes. Right Arm represents the arc from the front hexes through the right flank. Back represents only the rear hex. GCA will set these values, or delete the tag, as appropriate, while in the Protection window. Externally setting the shieldarc() tag to a value is acceptable, but it will have no effect on the character until the Protection window is opened and the tags are read, allowing GCA to reconfigure the shield arc settings.
shortlevelnames
shortname
shots
skillused
stat
step
stepoff
symbol
sysbonus
syslevels
syspoints
taboo
taboo*disabled*
taboofailed
tabootext
tier
time
tl
type
up
upto
usernotes
value
valuenum
weight
[edit] x
Applies to: Traits
Valid values: various #Directives
The x() tag serves as a convenient place to store any directives that may be needed for a trait.
[edit] User Tags
...user/custom tag mumble...
[edit] Sections
...general section mumble...
[edit] Header
The header section is a special section which must exist, and must also be the first section in the data file. It consists of a number of required and optional variables.
[edit] Version=GDF specification version
The Version variable is required and must be the first variable in the header -- more specifically, it must also be the first line in the data file. Its value is the data file specification version to be used. All current data files should use the current version of the specification (3).
Usage example:
Version=3
[edit] Description=GDF description
The Description variable is optional, but recommended. Its value is the description of the contents/purpose of the data file. If the description is long enough that splitting it into multiple lines is desired, each line except the last must end with an underscore.
Usage example:
Description=This data file contains information taken from the GURPS Supers sourcebook. GURPS Supers is copyright _
© 1989, 1991, 1996, 2000, 2007 by Steve Jackson Games Incorporated. All rights reserved.
[edit] Program=GCA version
The Program variable is optional, but recommended. Its value is the required minimum version of GCA needed to correctly load the file. Useful for ensuring that a data file will not be used with a version of GCA older than the given version, which may not support all of the features included in the file.
Usage example:
Program=4.0.348
[edit] Requires=file1[, file2[, fileN]]
The Requires variable is optional. Its value is a comma-delimited list of data file names which must be loaded before the current file. File names should consist of the full name of the data file (without path info), and must be enclosed in quotes or braces if they contain a comma. Requires is intended for specifying files that the current file is dependent on to work correctly, not necessarily for files that should be loaded when things are being added to the character. For example, if the file includes commands that change previously loaded data definitions, Requires would be a good bet to use.
Usage example:
Requires="GURPS Basic Set 4th Ed.--Characters.gdf", "GURPS Powers 4e.gdf"
[edit] LoadAfter=file1[, file2[, fileN]]|All
The LoadAfter variable is optional. Its value is a comma-delimited list of data file names, or the special keyword All to denote all files, which should be loaded before the current file. File names should consist of the full name of the data file (without path info), and must be enclosed in quotes or braces if they contain a comma. LoadAfter is intended for specifying files that the current file should be loaded after, but is not dependent on to work correctly.
Usage examples:
LoadAfter="GURPS Ultra-Tech 4e.gdf"
LoadAfter=All
[edit] Taboo=file1[, file2[, fileN]]
The Taboo variable is optional. Its value is a comma-delimited list of data file names which must not be loaded with the current file. File names should consist of the full name of the data file (without path info), and must be enclosed in quotes or braces if they contain a comma. Taboo is intended for specifying files that the current file is incompatible with.
Usage example:
Taboo="My Custom Data File.gdf"
[edit] WorldBook=SettingName
The WorldBook variable is optional. It accepts only one value, the name of the setting covered by the file, and designates that the file is a World Book (which often contains changes to Basic Set assumptions, and therefore will almost certainly clash with other World Book files not in the same setting).
Multiple files that may all be used for the same setting may all be tagged with the same WorldBook=SettingName information, and GCA will not raise notice of a conflict. However, if any files use different WorldBook=SettingName values, GCA will raise a flag about the potential conflict.
Usage example:
WorldBook=Banestorm
[edit] Incomplete=Yes
The Incomplete variable is optional. It accepts only one value (Yes) and designates that the file is incomplete or unfinished, a work-in-progress.
Usage example:
Incomplete=Yes
[edit] [AUTHOR]
Available Tags: none
The [AUTHOR] section is fairly simple: it should consist comments, and nothing else, and all comments following the section marker, until it reaches a new section marker or the end of the file, are considered author information.
Usage example:
************************************************************************************************************************ * * GURPS(R) Character Assistant * Filename: GURPS Basic Set 4th Ed.--Characters.gdf * Created: August 24, 2004 * Requires GCA v4 or later! * * This data file contains information taken from the GURPS Basic Set: Characters sourcebook. GURPS Basic Set: * Characters is Copyright(C) 1986, 1987, 1988, 1989, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2002, 2004 by * Steve Jackson Games Incorporated. All rights reserved. * * Information in this file includes: * Attributes * Advantages, Disadvantagess, Quirks, Including Bonuses and Penalties. * Skills, Including Bonuses, Classes, Needs and Prereqs. * Spells, Including Bonuses, Colleges, Needs and Prereqs. * Equipment * Templates * ************************************************************************************************************************ * * David L. Watkins - Major work * Armin D. Sykes - Changes, Updates, Packages/Templates * Craig Roth - Equipment * Eric B. Smith - GURPS Data File Coordinator, Equipment, Updates, Corrections, Skill Categories * * If you find any errors or omissions in this file please contact the Data File Coordinator at: * eric.frogkiller@gmail.com * * Or drop a message at: * http://forums.sjgames.com * ************************************************************************************************************************ * * GURPS is a registered trademark of Steve Jackson Games Incorporated, used with GCA by permission of Steve Jackson * Games. All rights reserved. * * The GURPS game is copyright (c) 1986-1989, 1991-1994 by Steve Jackson Games Incorporated. This product includes * copyrighted material from the GURPS game, which is used by permission of Steve Jackson Games Incorporated. All * rights reserved by Steve Jackson Games Incorporated. * ************************************************************************************************************************
You are strongly encouraged to use this, or a similar format, for your [AUTHOR] section. Regardless of the format chosen, you should definitely include: the name of the data file, which version of GCA it's for, any appropriate copyright notices from the source used to create the data file (don’t forget this!), what the data file includes, and contact information so users of the file can get in touch with you if they have questions or problems.
[edit] [SKILLTYPES]
...skill type section mumble...
[edit] [BASICDAMAGE]
...basic damage section mumble...
[edit] [CONVERTDICE]
Available Tags: break(), adddice(), subtract()
This section allows you to tell GCA the method to use when converting extra damage bonus additions to damage dice instead, as per the Optional Rule: Modifying Dice + Adds (p. B269).
When GCA finds this section in a data file, it clears any previously defined [CONVERTDICE] values, even if the new section is blank. Each line defines a new [CONVERTDICE] instruction, and consists of three tags:
break(breakvalue), adddice(addvalue), subtract(subtractvalue)
If the bonus is breakvalue or more, GCA will add addvalue to the damage dice and subtract subtractvalue from the bonus value. When applied, each instruction is used, repeatedly, until its breakvalue test fails, at which point processing continues with the next instruction, if any.
Usage example:
break(7), adddice(2), subtract(7) break(4), adddice(1), subtract(4)
Which tells GCA: If there is a bonus of +7 or more, subtract 7 from it and add 2 dice to the damage. If there is a bonus of +4 or more, subtract 4 from it and add 1 die to the damage.
[edit] [ATTRIBUTES]
...attributes section mumble...
[edit] [ADVANTAGES]
...advantages section mumble...
[edit] [PERKS]
...perks section mumble...
[edit] [DISADVANTAGES]
...disadvantages section mumble...
[edit] [QUIRKS]
...quirks section mumble...
[edit] [SKILLS]
...skills section mumble...
[edit] [SPELLS]
...spells section mumble...
[edit] [EQUIPMENT]
...equipment section mumble...
[edit] [TEMPLATES]
...templates section mumble...
[edit] [GROUPS]
...groups section mumble...
[edit] [LISTS]
...lists section mumble...
[edit] [MODIFIERS]
...modifiers section mumble...
