# Ability Files

The Ability files are used to identify and implement the individual class/racial abilities that make up each character.

## How to Build an Ability

The first field is the Ability Name, this is a required field and does not have a tag.

## Ability File Tag Dictionary

This section is broken into three subsections. The first, the Ability File Tags subsection, lists the new ability file tags, the second subsection, Global Ability Tags, and the third subsection, Other Ability Tags, lists the tags located else where in the PCGen documentation.

### The Ability File Tags

*** Added 5.11.x

Tag Name: ADDSPELLLEVEL:x

Variables Used (x): Number (Increase in spell slot level)

What it does:

This tag is used in metamagic abilities to denote how much higher the spell levelslot requires.

Example:

`ADDSPELLLEVEL:2`

A spell with this metamagic ability applied to it takes up a slot two levels higher than the normal spell.

*** New 5.15.2

Tag Name: ASPECT:x|y|z|z

Variables Used (x): Text (Name of Aspect)

Variables Used (y): Text (Value of Aspect)

Variables Used (z): Number or Formula (Optional. Used for substitutions in y)

What it does:

- Identifies an "aspect" (see examples below) that an ability has and sets its value.
- This tag can be used multiple times within an ability but each time it must identify a new aspect.
- The text in the y variable can use %z for replacing numerical values set by the z variable, %1 is replaced by the first z, %2 is replaced by the second z, etc..
- The y text can also use other special variables, also usable in the `DESC` tag:
  - `%CHOICE` - Will replace the first associated choice in the object.
  - `%LIST` - Will substitute all choices comma separated into that parameter.
  - `%NAME` - The `OUTPUTNAME` or name of the object this `DESC` tag is in.
- `ASPECT` tags can be modified by .MODing the ability and inserting a new `ASPECT` tag. Since each aspect name can hold only one value per ability, .MODing a new `ASPECT` tag will overwrite the only value of the aspect by that name in the ability.

Example:

`ASPECT:Action Type|Standard Action`

Identifies the "Action Type" of an action performed as part of the associated ability as a "Standard Action".

`ASPECT:Attack Type|Melee weapon`

Identifies the "Attack Type" of an attack performed as part of the associated ability as a "Melee weapon" attack.

`ASPECT:Target|One creature`

Identifies the "Target" of an action performed as part of the associated ability as "One creature".

`ASPECT:Attack|Strength vs. AC`

Identifies an "Attack" performed as part of the associated ability as "Strength vs. AC".

`ASPECT:Attack Type|Ranged %1|PowerRange`

Identifies the "Attack Type" of an attack performed as part of the associated ability as a "Ranged" attack with a range equivalent to the "PowerRange" variable.

`ASPECT:Effect|Double damage to %CHOICE creatures`

Identifies the "Effect" of an action performed as part of the associated ability as "Double damage" to the creature chosen by the associated chooser.

*** Added 5.11.x

Tag Name: BENEFIT:x

Variables Used (x): Text (benefit text)

Variables Used (x): .CLEAR

Variables Used (x): .CLEAR.text (regular expression)

What it does:

- This is the benefit text of the ability from the source material.
- The included text will be displayed in the ability description field if the "Display Feat Description" checkbox in the Appearance/Display Options Preference window is unchecked. Otherwise the text from the DESC tag will be displayed.
- PRExxx tags can be used with the `BENEFIT` tag.
- Multiple `BENEFIT` tags per line are allowed with all qualifying `BENEFIT` tags being concatonated for output and separated by commas (,).
- `.CLEAR` will clear all `BENEFIT` tags.
- `.CLEAR.(regular expression match)` will clear specific instances.
- `BENEFIT` tags will take variable substitution.
  - Within the text a % followed by a number will substitute the #th variable from the variable list associated with the `BENEFIT`.
  - Variables are specified after the descriptive text and are pipe-delimited (|).
  - The special parameter %% will insert an actual % character into the text.
  - If the parameter needs to be next to a number the parameter number should be surrounded in curly brackets { }. For example, %{1000}gp.
- The following special variables are allowed within the variable list:
  - `%NAME` - The name of the object this `BENEFIT` tag is in.
  - `%FEAT` - Will substitute the descriptions of feats within the object that match the associated preqrequisites.
  - `%CHOICE` - Will replace the first associated choice in the object.
  - `%LIST` - Will substitute all choices into that parameter as a comma-delimited list.
- Formulas can be parsed and the results replaced in the output by enclosing the variables and formulas within parentheses.
  - CASTERLEVEL, a variable specifically designed for this purpose, is commonly used though other variables can be used as well.
  - Because anything within parentheses is assumed to be a formula to be parsed, text containing parentheses must substitute brackets [ ] in place of parentheses.
  - Java has a Regular Expression library built in that is very similar to Perl regular expressions. Basically it allows for pattern matching in strings. You can create fairly powerful match structures using things like character groups "[a-zA-Z]" match any alphabetic character or groupings "(bat|super)man" match batman or superman and many many more. So, for example, you could clear all benefits by doing `BENEFIT:.CLEAR..*`, or clear all exceptional abilities by doing `BENEFIT:.CLEAR.\(Ex\)`, or clear everything that's non-numeric with `BENEFIT:.CLEAR.[A-Za-z]`.

Example:

`BENEFIT:This is sample text for the example purposes`

Adds ability benefit.

`BENEFIT:Kick Butt (level 3)|PRELEVEL:3`

Adds ability description only if the PC is level 3 or higher.

`BENEFIT:Assembly ~ 1 table|PREVAREQ:AssemblyTables,1
BENEFIT:Assembly ~ %1 tables|AssemblyTables|PREVARGTEQ:AssemblyTables,2`

Adds an ability description which is dependent upon the value of the variable AssemblyTables.

`BENEFIT:You get a +2 bonus on all %1 saving throws|%CHOICE`

Adds ability description and replaces %1 with the first choice made.

`BENEFIT:You get a +3 bonus on all checks involving %1|%LIST.`

Adds ability description, replacing %LIST with all choices made.

`BENEFIT:%3 Sneak Attacks per day for +%1d%2 damage|SneakAttack|SneakAttackDie|SneakAttackTimes`

Adds ability description, substituting the variables from the positions specified.

`Advanced Combat Martial Arts.MOD <tab> BENEFIT:.CLEAR <tab> BENEFIT:When the character scores a critical hit on an opponent with an unarmed strike, the character deals triple damage`

Changes the ability description, substituting the specified text.

*** Updated 5.13.6

Tag Name: CATEGORY:x

Variables Used (x): Text (Ability category)

What it does:

This is the Ability Category that the ability belongs to. The ability category is a broad group of abilities, defined in the game mode. An ability's key name need only be unique within its category.

Examples:

`CATEGORY:SpecialAttack`

This ability is part of the "SpecialAttack" ability category.

`CATEGORY:Feat`

This ability is part of the "Feat" ability category, which is a special case of abilities that can be selected as feats.

`CATEGORY=Talent|Uncanny Dodge II.MOD <tab> PRE:.CLEAR`

This ability is part of the "Talent" ability category, which is aimed at the feat of "Uncanny Dodge II" so that it can be modified by removing the PRExxx.

Tag Name: CHOOSE:SKILLSNAMEDTOCCSKILL|x

Variables Used (x): Text (Skill name)

Variables Used (x): Text% (Start of skill name)

Variables Used (x): TYPE=Text (Skill type)

Variables Used (x): ALL (Displays all skills)

Variables Used (x): CLASS (Displays all class skills)

Variables Used (x): CROSSCLASS (Displays all cross class skills)

Variables Used (x): EXCLUSIVE (Displays all exclusive skills)

What it does:

- This will produce a list of named skills.
- The selected skill will be made a cross class skill for the character.
- The SELECT tag is used in conjunction with this `CHOOSE` tag to define the number of "selections" that can be made.

Example:

`CHOOSE:SKILLSNAMEDTOCCSKILL|CLASS`

This will display a list of all the characters class skills and allow them to select a skill to be made a cross class skill.

Where it is Used:

Ability Files

Tag Name: CHOOSE:SKILLSNAMEDTOCSKILL|x

Variables Used (x): Text (Skill Name)

Variables Used (x): Text% (Start of skill name)

Variables Used (x): TYPE=Text (Skill type)

Variables Used (x): ALL (Displays all skills)

Variables Used (x): CLASS (Displays all class skills)

Variables Used (x): CROSSCLASS (Displays all cross class skills)

Variables Used (x): EXCLUSIVE (Displays all exclusive skills)

What it does:

- This will produce a list of named skills.
- The selected skill will be made a class skill for the character.
- The SELECT tag is used in conjunction with this `CHOOSE` tag to define the number of "selections" that can be made.

Example:

`CHOOSE:SKILLSNAMEDTOCSKILL|CROSSCLASS`

This will display a list of all the characters cross class skills and allow them to select a skill to be made a class skill.

Where it is Used:

Ability Files

*** Added 5.11.x

Tag Name: COST:x

Variables Used (x): Number (ability point cost)

What it does:

This is how many ability points the ability costs. A decimal value, as the example below, would mean that it only costs 1/2 an ability point.

Example:

`COST:1`

Ability costs one ability point.

`COST:.5`

Ability costs half a ability point.

Default Value:

`1`

Deprectated 5.15.6 - Remove 6.0

Tag Name: MODIFYABILITYCHOICE:x

Variables Used (x):Text (ability name)

Variables Used (x):TYPE=Text (ability type)

What it does:

- This tag allows for a previous ability choice to be replaced by a new one.
- The ability called must allow choices to be a valid ability.

Example:

`MODIFYABILITYCHOICE:TYPE=NinjaMonkeySchool`

An ability with this tag will allow the selection of a new school from a list of schools of type 'NinjaMonkeySchool' to replace a previously selected one.

`MODIFYABILITYCHOICE:Ninja Monkey Primary Weapon Reselection`

Allows a ninja monkey to select a new primary weapon, replacing an earlier selected primary weapon.

*** Added 5.11.x

Tag Name: MULT:x

Variables Used (x): Boolean ('YES' or 'NO')

What it does:

This determines if an ability can be taken multiple times. If the value is set to 'YES', then you MUST also use a 'CHOOSE' tag.

Example:

`MULT:YES`

This Ability can be taken multiple times.

Default Value:

`NO`

*** Added 5.11.x

Tag Name: STACK:x

Variables Used (x): Boolean ('YES' or 'NO')

What it does:

This tells PCGen if the ability benefits may be stacked on one another.

Example:

`STACK:YES`

The benefits for this ability stack with it self if taken multiple times.

Default Value:

`NO`

Tag Name: TEMPLATE:x|x

Variables Used (x): Text (Template Name)

What it does:

This is a pipe-delimited (|) list of templates that are granted by the ability.

Example:

`TEMPLATE:Incorporeal|Undead|Celestial`

The ability applies the "Incorporeal", "Undead" and "Celestial" templates.

Tag Name: TEMPLATE:ADDCHOICE:x|x

Variables Used (x): Text (Template Name)

What it does:

- This is a pipe-delimited list of template choices that are added to the list presented by the original `TEMPLATE:CHOOSE` tag.
- When using the `TEMPLATE:ADDCOICE` tag as part of a `.MOD` of a Race object that containes multiple `TEMPLATE:CHOOSE` tags, all instances of the `TEMPLATE:CHOOSE` tag will be modified.

Example:

`TEMPLATE:ADDCHOICE:Demihuman|Beast`

The ability can choose previously defined templates plus the "Demihuman" or "Beast" templates.

Tag Name: TEMPLATE:CHOOSE:x|x

Variables Used (x): Text (Template Name)

What it does:

- Will present a popup window of the choices provided in the pipe-delimited (|) list, allowing the user to pick ONE from the list.
- Multiple `TEMPLATE:CHOOSE` tags can be used in the same LST object but PCGen's current Data Standard os to include no more that one in each LST object.

Example:

`TEMPLATE:CHOOSE:Celestial|Outsider`

The ability allows the selection of either the "Celestial" or "Outsider" template.

*** Added 5.11.x

Tag Name: VISIBLE:x

Variables Used (x): YES (Default)

Variables Used (x): NO

Variables Used (x): DISPLAY

Variables Used (x): EXPORT

What it does:

- `YES` - Shows the ability name in PCGen and on export to a character sheet.
- `NO` - Hides the ability name in PCGen and on export to a character sheet.
- `DISPLAY` - Displays the ability name in PCGen but not on the character sheet.
- `EXPORT` - Hides the ability name from PCGen but displays it on the character sheet.

Example:

`VISIBLE:YES`

Shows the ability name in PCGen and on the Output sheet.

### Global Ability Tags

- ABILITY (Global Other)

### Other Ability Tags

These are not true global tags as the tags in the previous section are. Though they occur in other files, they have an impact on abilities and are being included here to make them easier to locate and understand.

#### Game Mode Misc Info and AbilityCategory Files

- ABILITYCATEGORY (Misc Info) or ABILITYCATEGORY (Ability Category)
- CATEGORY (Misc Info)
- DISPLAYNAME (Misc Info)
- EDITABLE (Misc Info)
- EDITPOOL (Misc Info)
- FRACTIONALPOOL (Misc Info)
- PLURAL (Misc Info)
- POOL (Misc Info)
- TYPE (Misc Info)
- VISIBLE (Misc Info)

#### Game Mode - Stats and Checks File

- ABILITY:ADDSPELLLEVEL (Stats & Checks, in STATNAME Line)

#### Bonus Ability Tags

- BONUS:ABILITYPOOL (Global BONUS)

#### Starting Kit Tags

- ABILITY:CATEGORY (Starting Kit)
- ABILITY:PROMPT:FEAT (Starting Kit)

#### PCC Ability Tags

- ABILITY (PCC)