GDF3 File and Data Specifications for GCA4
Root FileSpec Page 		GCA Site
Home | Docs & Help Page

Directives

Directives are a kind of internal command that is processed when GCA adds an item to the character. Until the item is added to the character, the directive does nothing. Directives always begin with the # sign, so they will often be referred to as #directives.

Contents

#BuildIt
#BuildList
#Choice
#ChoiceList
#GroupList
#List
#Message

Not yet done:

#Edit
#DoNotOwn
#NoNeeds
#Codes (not a true directive)

Templates

The documentation below uses templates to demonstrate the structure of the various #directives. The templates are meant to provide a quick way to see how the directives may be formatted. Trying to do this, however, is not always easy, and we have made some formatting decisions that may take some getting used to. So here's an explanation of how things work.

 

#BuildIt
Description:

This directive prompts GCA to offer the user the Mods window, with which they can build the version of the added item they intend to use.
Template:

#buildit

Detail:

This directive has no options, and therefore has no parentheses or available tags.
Results:

The Mods window will be displayed to the user, and the Mods selected applied to the item being added to the character. This directive will be removed from the item and will not appear on the item as added to the character.

 

#BuildList
Description:

This 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] ) )
Detail:

List() is where you 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() 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.

Examples:  
Example 1:

#buildlist( list(Alpha, Bravo, Charlie), template(SK:%ListItem%=2pts) )

This example will create a list that looks like this:

SK:Alpha=2pts, SK:Bravo=2pts, SK:Charlie=2pts

Note that the %ListItem% was exactly replaced by each item in the list to create the new list.
Example 2:

#buildlist( list(Alpha, Bravo, Charlie), template(2 * "SK:%ListItem" + 1)

This example will create a list that looks like this:

2 * "SK:Alpha" + 1, 2 * "SK:Bravo" + 1, 2 * "SK:Charlie" + 1

Note that the %ListItem% was exactly replaced by each item in the list to create the new list, and that the quotes are preserved from the template.
Results:

The directive will be removed, and will not appear in the item as added to the character. A new list will be put into the position of the #BuildList directive. That list will be a comma separated list of items, each item having the appearance specified in the template() tag.

 

#Choice
Description:

This 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] ] )
Detail:

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.

Here's an example of the template using braces instead of quotes:

#Choice( {item1}[=cost1] [, ..., {itemN}[=costN] ] )
Result Variables:

%choice%
%choicecost%
Detail:

Result variables are what GCA looks for in order to insert the results of the user's selection back into the item. Any one or more of the options shown may be used. The variable name itself will be replaced by the appropriate result.

If %choice% is used, GCA will insert the user's selected option.

The %choicecost% variable is used in the same fashion, but uses the cost for the item selected by the user.

Note that the results placed into the variables by GCA will not include quotes.
Results:

This directive will be removed, and will not appear in the item as added to the character. Choices made by the user will be placed into the appropriate variables at the location of the variable, and the results of that substitution will be visible in the item as added to the character.

 

#ChoiceList
Description:

This directive allows you to provide the user with a list of options to choose from, and to specify how many of the items you want the user to choose. The results of the choice are then made available through a selection of result variables.
Template:

#ChoiceList( list("item1"[=cost1] [, ..., "itemN"[=costN] ]) [, taglist] )
Detail:

List() allows you to specify the list of options being provided to the user. At its simplest, this is just 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 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.

Here's an example of the template using braces instead of quotes:

#ChoiceList( list({item1}[=cost1] [, ..., {itemN}[=costN] ]) [, taglist] )

The optional taglist allows you to include one or more tags, as detailed below.
Tag List Option Templates:

The following tags, and their related data, are all available for use within the optional tag list section, as indicated above with the taglist placeholder. The use of any such tag is optional, but is the only way to get additional flexibility from the directive. Multiple tags used in the tag list should be separated by commas.

AliasList( "item1" [, ..., "itemN"] )
name( name )
title( title )
text( text )
default( choices )
PicksAllowed( [ { exactly | upto | atleast } ] number [, { upto | atleast } number ] )
TotalCost( [ { exactly | upto | atleast } ] cost [, { upto | atleast } cost ] )
method( { bynumber | bycost | byboth } )
Detail:

AliasList() allows you to specify a second list of options, which is *not* presented to the user. This list is formatted just as the list() tag items are, except it does not allow for cost assigments. Using AliasList() allows you to provide the user with simple choices and any costs associated with the choices, but also to have a more complex group of choices to use for other purposes if necessary. As with list(), items must be enclosed in either quotes or curly {} braces if they include commas, and if they include quotes, the braces are required.

Here's an example of the AliasList() template using braces instead of quotes:

AliasList( {item1} [, ..., {itemN}] )

Name() allows you to specify a name for this instance of the #choicelist directive. If you specify a name, then GCA will look for that name instead of the word choice in each of the cases listed in the Variables section. For example, if you used name(joe) GCA would look for %joelist% instead of %choicelist%. Do not enclose the name in quotes.

Title() allows you to specify the name of the window displayed to the user. Do not enclose the title in quotes.

Text() allows you to specify some caption text that will help prompt the user as to what to do when the window full of options appears. You may enclose the text in quotes if you wish, but GCA will not remove the quotes.

Default() allows you to specify the items, if any, selected by default when the window appears. This is a list of one or more numbers, separated by commas, where each number corresponds to the position of an item provided in the list(). No items are selected by default.

PicksAllowed() allows you to specify the number of options the user should select. Optionally, you may use: exactly to specify that the number of items chosen must be exactly as specified; upto to specify that any number of selections up to (and including) the number specified is acceptable; atleast to specify that at least the number of items specified is acceptable, but more may also be selected. By default, exactly 1 selection is required from the user.

TotalCost() allows you to specify the total number of points worth of items the user should select. Optionally, you may use: exactly to specify that the cost of the items chosen must be exactly as specified; upto to specify that the cost of the chosen items may be up to (and including) the value specified; atleast to specify that items totaling at least the value specified is acceptable, but more may also be selected. By default, costs are ignored.

Method() allows you to specify the exact method used to pick items, whether it should be based on the number of items (ByNumber), the cost of items (ByCost), or both (ByBoth). The default option is ByNumber, so you will need to choose ByCost if you are looking for a specific total cost of items, or ByBoth if you want to use cost and number together.
Examples:  
Example 1:

#choicelist( list("Alpha", "Bravo", "Charlie") )

This is pretty much as simple as you can get. This will provide a list with three options to the user.
Example 2:

#choicelist( list("Alpha"=10, "Bravo"=20, "Charlie"=30) )

This is like Example 1, except that now we've included costs for each item. When the items are displayed to the user, they will also see the cost for each item.
Result Variables:

%choice1%, ..., %choiceN%
%choice1alias%, ..., %choiceNalias%
%choicelist%
%choicealiaslist%
%choicecost1%, ..., %choicecostN%
%choicecostlist%
%choicenotlist%
%choicealiasnotlist%
%choicecostnotlist%
Detail:

Result variables are what GCA looks for in order to insert the results of the user's selection back into the item. Any one or more of the options shown may be used. The variable name itself will be replaced by the appropriate result.

If %choice1% is used, GCA will insert the first item in the list of options the user selected; if %choice2% is used, the second choice will be inserted, and so on. If GCA sees the %choicelist% variable, it will create a comma separated list of the options selected by the user, and insert it at that point. As with the regular choice options, the alias variants serve the same purpose, except the items used to create the output correspond to the selected items from the AliasList().

The variables with cost in the name work in the same fashion as those without, but use the costs for items selected by the user instead of the options themselves.

The last three result variables listed are the 'not list' result variables. These work similarly to the other list variables, except they return the lists of items *not* chosen by the user.

If the user has specified a name using the name() tag, then the name will be used instead of the word choice in all possible variables.

Note that the results placed into the variables by GCA will not include quotes or curly {} braces.
Results:

This directive will be removed, and will not appear in the item as added to the character. Choices made by the user will be placed into the appropriate variables at the location of the variable, and the results of that substitution will be visible in the item as added to the character.

 

#GroupList
Description:

This directive allows you to include a 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] )
Detail:

The GroupName placeholder should be replaced with the name of the group desired.

The optional taglist allows you to include one or more tags, as detailed below.
Tag List Option Templates:

The following tags, and their related data, are all available for use within the optional tag list section, as indicated above with the taglist placeholder. The use of any such tag is optional, but is the only way to get additional flexibility from the directive. Multiple tags used in the tag list should be separated by commas.

append( text )
prepend( text )
flags( flaglist )

Detail:

Append() 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() 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() 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.

The flags that may be used in the flaglist are:

  • NoPrefix to prevent the inclusion of the prefix tags in the names of group items.
  • InQuotes to enclose each group list item within quotes. Any appended or prepended text will appear outside the quotes.
  • InParens to enclose each group list item within parentheses. Any appended or prepended text will appear outside the parens.
  • InBraces to enclose each group list item within curly {} braces. Any appended or prepended text will appear outside the braces.
  • MasterQuotes to have GCA place quotes around the whole item and appended text combination.
  • MasterBraces to have GCA place curly {} braces around the whole item and appended text combination.
Results:

This directive will be removed, and will not appear in the item as added to the character. This directive will be replaced by the comma separated list created by the directive, and only the list will appear in the item added to the character.

 

#List
Description:

This directive allows you to include a list of items based on an existing List. Unlike with GroupList, which is based on Groups, List items don't have prefix tags, so there's no option concerning them in #List.
Template:

#list( ListName [, taglist] )
Detail:

The ListName placeholder should be replaced with the name of the List desired.

The optional taglist allows you to include one or more tags, as detailed below.
Tag List Option Templates:

The following tags, and their related data, are all available for use within the optional tag list section, as indicated above with the taglist placeholder. The use of any such tag is optional, but is the only way to get additional flexibility from the directive. Multiple tags used in the tag list should be separated by commas.

append( text )
prepend( text )
flags( flaglist )

Detail:

Append() 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() 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() 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.

The flags that may be used in the flaglist are:

  • InQuotes to enclose each list item within quotes. Any appended or prepended text will appear outside the quotes.
  • InParens to enclose each list item within parentheses. Any appended or prepended text will appear outside the parens.
  • InBraces to enclose each list item within curly {} braces. Any appended or prepended text will appear outside the braces.
  • MasterQuotes to have GCA place quotes around the whole item and appended text combination.
  • MasterBraces to have GCA place curly {} braces around the whole item and appended text combination.
Results:

This directive will be removed, and will not appear in the item as added to the character. This directive will be replaced by the comma separated list created by the directive, and only the list will appear in the item added to the character.

 

#Message
Description:

This directive allows you to create a message that will be displayed to the user when the item containing it is added to the character.

Template:

#message( "text" [, "caption" ] )
Detail:

The text placeholder in the template should be replaced by the text you wish to display as the message to the user. This should be enclosed in quotes, as shown. If embedded quotes are included, they must be doubled.

The optional caption placeholder in the template should be replaced by the text you wish to display in the caption area of the message window. This should be enclosed in quotes, as shown. If embedded quotes are included, they must be doubled.
Results:

A message will be displayed to the user. This directive will be removed, and will not appear in the item as added to the character.

This document last updated July 22, 2008. Copyright © 2004, 2007, 2008 Armin D. Sykes. All rights reserved.