# Lesson #18: .lst - Converting Feats to Abilities, The Basic Conversion

By Andrew A. Maitland (LegacyKing) and Eric C Smith (Maredudd)

File(s) Covered: *abilities.lst, *feat.lst, *.pcc, *abilitycategory.lst, miscinfo.lst

Tags used:

`CATEGORY(ability), PREABILITY, ABILITY(pcc), ABILITYCATEGORY(pcc), ABILITYCATEGORY(ability category), CATEGORY(ability category), PLURAL, EDITABLE, EDITPOOL, FRACTIONALPOOL, POOL, VISIBLE, DEFINE, TYPE, PRESKILL, PREVARLT, DESC, BONUS:VAR`

## Introduction

Beginning with PCGen 5.12, and maturing in PCGen 5.14, the Ability object has been available to the lst monkey as a more flexible tool than the existing Feat object. Though it was originally conceived as a replacement for the Feat, it will take quite some time before the Feat actually goes away, if it ever does.

This lesson will assist users in converting their existing homebrew feats to the new Ability object. To accomplish this, the lesson is broken into two sections, the Basic Conversion and the Advanced Conversion. Within each of these sections you will find discussion of each file that must be modified, and the tags required to accomplish the conversion of your homebrew feats.

NOTE: Standard practice in PCGen distributed datasets is to only use the ability object for those abilities that had been implemented as hidden feats. Feats listed in the sourcebooks as feats are implmented with the standard feat object.

What this lesson will not tell you is how to create either Feats or Abilities. Both are very similar in construction, using the same set of general tags to provide the functionality required to implement varied game rules used. The primary difference is that each "ABILITY" is assigned to a specific "CATEGORY". This means that you can have several abilities with the same name, but each will be of a separate category. The tags required to do this are covered below.

### Sample Feat

The Expert Defense hidden feat, included below, will be used as our example in this LST file class.

`Expert Defense`

`TYPE:Special`

`VISIBLE:NO`

`SAB:Expert Defense ~ Add % bonus to AC|INT`

`BONUS:COMBAT|AC|INT`

Note: This hidden feat has been created specifically for this LST File class.

### Before We Begin

#### File Names

You will see several LST files referenced within this lesson. The files names used are generic file names and do not represent what your files will need to be called. The general convention used for official datasets within PCGen can be found in the Official Release Standards. You are free to call your homebrew datasets by what name you will, though I find it helps to include the object type contained within the file in the name of the file. For the purposes of this LST File class, we will use the following file names:

my_abilities.lst file for the converted abilities.

my_abilitycategpries.lst file for the new abilities categories.

my_campaign.pcc file for the campaign pcc file.

Note: You can name your homebrew files anything you wish as long as you include them in the your homebrew PCC file.

#### LST File Class Style Guide

Because HTML formatting cannot exactly replicate what you would see in a LST file we are going to use certain conventions to convey these ideas:

1) Coding examples and PCGen tags are identified by `code` style.

2) When referencing a specific PCGen object, i.e. domain, feat, weapon, etc., I have included the name as a LST Object text, except for when the object is part of a `code` example.

3) Each new line should be considered a `<TAB>` in the actual file.

> Examples in this lesson will appear as:

> `ABILITYCATEGORY:My Special Ability Category`

> `CATEGORY:Special Ability`

> Will in the LST file appear as:

> `ABILITYCATEGORY:My Special Ability Category` <tab> `CATEGORY:Special Ability`

#### Special Note for the LST Student

Finally, for those of you that have gone through the previous LST Classes, some of the global tags will be repetitive. feel free to skip those portions if you like. These classes are being written for the new LST-Monkey, so there will be some overlap, but a student of the classes does not need to take them in order.

## The Conversion

The basic process of converting "Feats" to "Abilities" is to create a new file called my_abilities.lst and then copy the homebrew feats that you wish to convert to the new file and removing them from the my_feat.lst file. You will then need to add the appropriate `CATEGORY` tag to the copied feats, making sure that any new ability categories are properly defined in the my_abilitycategories.lst file. The next step is to modify your hombrew my_campaign.pcc file by adding the `ABILITY` and `ABILITYCATEGORY` tags. The relevant files and tags to acomplish this are explained below.

### The Ability File

The my_abilities.lst file is where your converted feats will be placed. Fortunately, the tags you use in this file are very similar to those used in the feat.lst file. The major difference between these two files is that you will need to add the `CATEGORY` tag to your converted feat to make it an ability. To get an idea of how to build feats, you can look up LST File Class #12 and LST File Class #13, Feat LST Classes Parts 1 and 2. There will eventually be a LST FIle Class for Abilities so you can check back periodically to see if its been released yet.

#### <Ability Name>

Every ability line must begin with the name of the ability. You can use any name you prefer as long as it conforms to the standard requirements for feat names. For our purposes in this class, we will be using the same name we used for our sample feat. This means our new ability will be called `Expert Defense`.

Note: You can have two abilities with the same name as long as they are of different categories, i.e. the `CATEGORY` tag specifies a different category for each ability.

Example:

`Expert Defense`

Amazingly enough, our new ability has the same name as our old feat.

#### `CATEGORY:My Super Ability`

This tag identifies the 'category' in which your new ability will be placed. In the case of our example ability, we are placing it in the My Super Ability category. Any category, besides 'FEAT', must have been defined in the miscinfo.lst or abilitycategory.lst file to be valid. See "The Ability Category File" file below.

Note: While abilitiy categories can be named whatever you decide upon, when using the hardcoded FEAT category, you must use all caps as that is the way it is hardcoded within PCGen.

#### Our New Ability

All other tags in our example feat are used as is in our new ability. The final Ability object is shown below:

`Expert Defense`

`CATEGORY:My Super Ability`

`TYPE:Special`

`VISIBLE:NO`

`SAB:Expert Defense ~ Add % bonus to AC|INT`

`BONUS:COMBAT|AC|INT`

### The Ability Category File

The my_abilitycategories.lst file defines the various ability categories that an ability can be assigned to. These categories will determine where, within the PCGen user interface, the related abilities will appear. In general, they will appear in a sub-tab on the "Feats & Abilities" tag.

There are a number of ability categories built into PCGen's various datasets, all defined in either the loaded gamemode's miscinfo.lst file or the loaded dataset's abilitycategory.lst file. For Homebrews, you'll need to either use one of these existing ability categories or set up your own "Ability Category", which in turn will create a separate "pool" with which to manage your converted abilities. To demonstrate how this is done, we'll use the My Super Ability category.

#### `ABILITYCATEGORY:My Super Ability`

The first entry in the ABILITYCATEGORY line is the name of the new ability category which identifies the "ABILITYPOOL". This ability pool governs how many abilities can be taken, if they cost anything at all. The "ABILITYCATEGORY" tag is not strictly required as PCGen will take the first data entry as the name of the ability category, and thus the ability pool, but current PCGen standard practice is to include the tag.

If this ability category is defines as "visible" (See the "VISIBLE" tag below), any ability given this category will appear in the "Feats & Abilities" tab under a sub-tab of the same name as this ability category. In this case, My Super Ability.

#### `CATEGORY:Special Ability`

This is a 'super-category', or parent, to which our new ability category belongs. This tag is optional but if included must list an existing ability category that has been defined in either the miscinfo.lst or miscinfo.lst file.

#### `TYPE:Special`

This is a TYPE, or list of types, assigned to abilities of this catgory. While some types do not have an effect other than allowing additional filtering in the GUI, as is the case with the type Special, there are a number of standard ability types used within PCGen that effect PCGen in different ways. SpecialQuality and SpecialAttack are used to determine where on the Output Sheet the associated abilities will be placed. FavoredEnemy, RogueAbilities, and General effect which sub-tab the associated abilities will appear on in the PCGen GUI.

A complete list of standard feat and ability types can be found on the Global TYPE page.

#### `PLURAL:My Super Abilities`

This has to do with the internationalization. An example is: in_feats which sets the Category key to 'in_feats'. It also shows up with the 'Plural' of the name. Ex. Feat would be Feats (Feats would display in the drop down bar).

#### `EDITABLE:NO`

This defines whether a user can modify the abilities in the category. NO would be appropriate for class abilities which aren't chosen by the user.

#### `EDITPOOL:NO`

This defines whether a user can modify the pool number or not. Each ability has a 'cost' (Default is 1) if this option is set to 'NO' the user cannot add or subtract from the pool. For feats, the default is 'YES'.

#### `FRACTIONALPOOL:NO`

This defines whether the pool must be a whole number or can be fractions. Some abilities may have a cost less than '1' like .5 or .25. <YES / NO>

#### `POOL:0`

This tag establishes the base ability pool for the defined ability category. It will take a number, formula, or variable. If a variable is used, the variable MUST be defined by a `DEFINE` tag. For our new ability category, we will start with an ability pool of zero (0).

#### `VISIBLE:NO`

Defines whether this category is visible on the UI or hidden. Usefull for hidden abilities and class abilities that require no interaction from the user. <Options are - YES, NO, QUALIFY>

#### DISPLAYLOCATION

The `DISPLAYLOCATION` is optioonal but will identify the sub-tab upon which the associated abilities will be displayed. Examples of some standard locations defined in the RSRD data set are "Class Abilities" and "Special Qualities and Attacks". If it is not included the `PLURAL` taxt will be used instead.

We will not be including this tag in our example ability category so you can look for our converted abilities under the "My Special Abilities" sub-tab.

Well, you could if we had not included the `VISIBLE:NO` tag in our ability category entry.

#### Our New Ability Category

The new entry in my_abilitycategories.lst is shown below:

`ABILITYCATEGORY:My Super Ability`

`CATEGORY:Special Ability`

`PLURAL:My Super Abilities`

`EDITABLE:NO`

`EDITPOOL:NO`

`FRACTIONALPOOL:NO`

`POOL:0`

`VISIBLE:NO`

### The PCC File

PCGen will use our my_campaign.pcc file to identify which source files to load as well as other information about the 'campaign'. Without these files and the related information, PCGen would not be able to load any datafiles. For the purposes of this lesson, there are only two tags we need to cover: The `ABILITY:my_abilities.lst` tag and the `ABILITYCATEGORY:my_abilitycategories.lst` tag.

PCGen will look in the my_abilities.lst file for our newly converted abilities and in my_abilitycategories.lst file for any new ability categories required to define the new abilities. These file references are relative to the PCC file itself so if you provide no specific path beyond the file names, PCGen will look in the same directory in which the pcc file is contained.

There are three ways to call a file from an absolute location within the PCGen installation. These are:

1. The "at" symbol (@) will load the file from a path relative to the data folder. (Example: `ABILITY:@/d20ogl/srd35/basics/rsrd_abilities_class.lst`)
2. The ampersand (&) will load the file from a path relative to the vendor data folder. (Example: `ABILITY:&/complete_monkey/complete_monkey_abilities.lst`)
3. The asterisk (*) will load the file from a path relative to the vendor data folder and if that does not exist, uses a path relative to the data folder. (Example: `ABILITYCATEGORY:*/d20ogl/srd35/basics/rsrd_ability_categories_core.lst`)

More information about PCC files can be found in the PCC LST File Class.

## Final Thoughts

Unless you've made a new Ability Category, all feats converted to abilities will show up on the 'Feats' tab as normal. Great examples of new ability categories can be seen in the RSRD/SRD for the Fighter, Wizard and Rogue class.

Remember, miscinfo.lst is a gamemode file, to define new ability categories or subcategories you MUST create it there. There are entries about them in the docs if you want to read up on them. To call the ability file it's (as you guessed), ABILITY:ability.lst, in the .pcc file. Basically pretend that an ability.lst is a feat file as far as what tags you can use in it and you'll be ok (fair warning though, there may be exceptions to that rule of thumb).

You may continue to use PREFEAT when testing for the converted abilities as a prerequisite, as long as you use the `CATEGORY:FEAT` tag, but it is recommended that you use PREABILITY instead. If you use any other category, e.g. `CATEGORY:MySpecialAbility` you MUST use the `PREABILITY` tag to check for your new abilities as prerequisites.

Andrew
LST Chimp