by James McP
This document assumes you are familiar with the RPG Third Edition and the SRD rule set. In particular, it follows the System Reference Document (SRD) for 3E, which varies in some ways from the 3E books. It was also written based on PCGen version 5 data files, located in the \data\d20ogl\srd\ directory of PCGen.
We will be discussing the format of LSTs and PCC files and how they expect to encounter tags. Refer to the documentation for details on implementing specific tags as they can, and do, change.
PCGen interprets data files using tabs and line returns. Note that a return (hitting the "enter" or "return" key) is different from word-wrap. You are advised to use a true text editor like the basic windows Notepad or one of the free editing programs like UltraEdit. Regardless, turn word-wrap off.
In these examples I will be using extra lines that are indented rather than tabs and blank lines to indicate separate lines.
So this:
Bob | 1 | 2 |
Alice | 3 | 4 |
Will be portrayed as:
Bob | |
1 | |
2 |
Alice | |
3 | |
4 |
A PCC file is the only way PCGen can see a LST file. Perhaps the most common problem people have creating their first home brew LST file is failing to create a PCC that references it.
While most users will only use PCCs as little more than a list of LSTs for their home brew campaigns, when converting a published source to PCGen the PCC file is an expression of the legal system in the form of the Open Gaming License (OGL). Only through these, or other licenses, can PCGen distribute data from published sources without violating copyrights. This can make the PCC the most important part in distributing copyrighted data.
For a completely original campaign, you are the owner of your material and the copyrights. You should still declare all the copyright information just in case your data files are somehow distributed. Keep in mind that a PCC is the sole way for PCGen to identify a LST and that the structure of PCC files is primarily to fulfill that purpose. The copyright information is for legal compliance, not program functionality.
Really not hard. The PCC consists of the header block; used to fulfill the legal obligations and provide information used in prioritizing the data and knowing which types of games it is compatible with (e.g. Fantasy RPGs, Sci-Fi RPGs, etc), and a list of LSTs to include. Each entry has a separate line in the PCC.
Typically PCC files are kept within the \data directory of your PCGen installation. They can be in a subdirectory as PCGen will find all PCCs within \data.
Another source for PCC files is the "Vendor Data" directory, specified in the Settings, Preferences, PCGen, Location dialogue.
PCC files can also be loaded off the internet by checking the "Allow sources to be loaded from web links" checkbox in the Settings, Preferences, PCGen, Sources dialogue. Then you can load sources from a Webpage from the "Source Material" Main Tab.
See the \data\d20ogl\srd\srd.pcc for an example of the layout of a PCC. Here are the tags in the order they are typically found. The order is not important, but following conventions will help others help you if you make a mistake. For legal reasons, few of the header tags should ever be omitted. See the .pcc Files tags documentation for a complete listing on Source and Header Information Tags
CAMPAIGN: |
Name of Campaign Displayed in data load window. |
RANK: 1 |
Rank indicates priority in sorting. |
GAMEMODE:3e |
Designates the Game Mode. Default RPG is 3e. |
GENRE: |
This tells PCGen what genre this is, used to filter sources. |
TYPE:Dominant Game Publisher.SRD |
Type will be used for sorting. |
SOURCELONG:The Full Name of the Source |
Long title (used in some displays). |
SOURCESHORT:Source |
Short title (used in some displays). |
SOURCEWEB:http://www.mywebsite.com |
Website for the source (typically the publisher's general site). |
ISOGL:YES |
If the source uses the open gaming license (OGL) See OGL FAQ. |
COPYRIGHT:Open Game License v 1.0a Copyright 2000, Your Name |
Copyright Terms. |
COPYRIGHT:The Full Name of the Source Copyright 2003, Company Name ; Authors Bob Writer |
Copyright Owner. |
[LST Type]:[LST Name] |
Call a LST file. |
The minimum LST files that have to be loaded to be able to create a new character are the following:
LST files are specialized, containing only a single type of data. PCC files must specify the type of LST file but each PCC can contain multiple LSTs of the same type.
Types of LST:
You can also call other PCC files from within a PCC file, for example:
PCC:myPCC.pcc
.
For a complete listing see: Main Body Tags which are used to load the specific LST files which make up the dataset.
So to call a class LST named "myfirstclass.lst" you would have the following in the PCC:
CLASS:myfirstclass.lst
This assumes the file myfirstclass.lst is in the same directory as the PCC. So if you wanted this PCC to load the file srdspells stored in pcgen\data\d20ogl\srd you would use the following line:
SPELL:@/d20ogl/srd/srdspells.lst
The "@" symbol tells PCGen to start at the top of the data directory and then follow the path down. See the documentation for more information.
CLASS:&/complete_monkey/complete_monkey_classes.lst
The "&" symbol tells PCGen to start at the top of the vendor data directory and then follow the path down. See the documentation for more information.
You can include/exclude specific information from any LST file by using the INCLUDE/EXCLUDE Tags.
Examples:
CLASS:myfirstclass.lst|@/d20ogl/srd/srdclassesbase.lst|(INCLUDE:Fighter)
Would load the classes in myclass.lst and only include the Fighter class from the SRD classes.
CLASS:myfirstclass.lst|(EXCLUDE:Monk|SorcererFoowarf)|@/d20ogl/srd/srdclassesbase.lst
Would load all classes in myclass.lst and all the SRD classes, except the Monk and the Sorcerer.
See further information on "Other .pcc file tags" which are used to provide additional functionality.
Because LSTs are called from PCC files they have little in the way of a header, just a SOURCExxx tag which provide information used on character sheets and displays.
LSTs can be complicated in the whole, but are typically quite simple. Here, in the author's opinion, are the LSTs sorted by complexity. I will be detailing the assembly of key LSTs at various levels of complexity.
The basic construction of a LST is a simple header block followed by a list of entries and their respective tags. With the exception of the name the order of tags is flexible but it is best to follow conventions. Tags are separated by tabs (hit the tab key on your keyboard) or whitespace. Most entries are on separate lines.
Remember, in these examples I will be using extra lines with indention's to reflect the tags rather than tabs for readability. Blank lines will separate entries.
This is as basic as it gets. Entries in a language LST are displayed in the language selection box. It consists of the header and a list of languages and their type. Let's consider two hypothetical languages, the spoken language Simian and the written only language Peel.
Here is the header block:
SOURCELONG:PCGen Documentation <tab> SOURCESHORT:P-Doc <tab> SOURCEWEB:http://www.pcgen.org
Here the header tells us in detail where the information came from, a short name for use in cramped locations, and the website of the source.
Then comes the actual code. In order we list the language name and type. Most LSTs have more options so with the exception of the name the order of tags is flexible but it is best to follow conventions. Tags are separated by tabs (hit the tab key on your keyboard) or whitespace. Entries are on separate lines.
And here are the two working tags:
Simian |
|
TYPE:Spoken |
Peel |
|
TYPE:Written |
You can refer to the srdlanguages.lst for a working example.
Custom equipment is often one of the first things that a GM needs to create. We'll start with something simple, like a Mighty Sling.
First, the header block:
SOURCELONG:PCGen Documentation <tab> SOURCESHORT:P-Doc <tab> SOURCEWEB:http://www.pcgen.org
Then comes the actual code. In order we list the item's name, type, cost, weight, sourcepage, proficiency used, crit multiplier, critical range (i.e. 1 for a 20, 2 for 19-20, etc), damage, range (if ranged weapon), size, and any bonuses and special abilities. Other than the name the order is flexible but it is best to follow conventions.
If you create a wholly new weapon with a new proficiency, you will need to create a proficiency LST that references your new weapon and then have your PCC load it.
Here is what we end up with, separating each tag into a separate line
Sling (+1 Mighty) |
|
TYPE:Weapon.Simple.Ranged.Standard.Bludgeoning |
|
COST:0 |
|
WT:0 |
|
PROFICIENCY:Sling |
|
CRITMULT:x2 |
|
CRITRANGE:1 |
|
DAMAGE:1d4 |
|
RANGE:50 |
|
SIZE:S |
|
BONUS:WEAPON|DAMAGE|STRMIN1 |
Looking at this you might notice the source page tag is missing. Yup, it's optional and since this is a "home made" item without a sourcebook, I left it off.
The TYPE tag is fairly easy to read, but you will likely need to refer to the documentation and srdequip(something).lst for examples.
The BONUS tag is a very, very, very feature rich tag. You will need to read the docs very carefully. This particular implementation indicates that it applies only to a weapon, modifies the damage dealt, and adds +1 strength damage to the weapon as long as the user has a strength bonus of at least +1. A mighty +2 sling would be identical except for the tag
BONUS:WEAPON|DAMAGE|STRMIN2 |
Now lets do something a bit more and create some magical armor. Red Dragon Armor will be plate +2 that provides fire resistance +5 and makes the wearer immune to Red Dragon fear. We'll start by copying the plate armor from the srdequiparmorshields.lst file.
Full Plate |
|
TYPE:Armor.Heavy.Suit.Standard.Metal |
|
COST:1500 |
|
WT:50 |
|
ACCHECK:-6 |
|
MAXDEX:1 |
|
MOVE:20,15 |
|
SOURCEPAGE:Chap.7, Armor |
|
SPELLFAILURE:35 |
|
BONUS:COMBAT|AC|8|TYPE=Armor.REPLACE |
Looking at it you can see how its tags work and how similar it is to the weapons. Name, type, cost, weight, armor check penalty, maximum dex bonus, movement restrictions (if any), source page, percent chance of spell failure, and the armor class bonus, set up as a replace to ensure only one set of armor is used.
For our custom version we'll be adding some other features. Other examples can be pulled from the srdequiparmorsheildspecific.lst
Red Dragon Armor |
|
PROFICIENCY:Full Plate |
|
TYPE:Magic.Armor.Heavy.Standard.Suit.Specific |
|
COST:16650 |
|
WT:50 |
|
ACCHECK:-5 |
|
MAXDEX:1 |
|
MOVE:20,15 |
|
SPELLFAILURE:35 |
|
BONUS:COMBAT|AC|10|TYPE=Armor.REPLACE |
|
SA: Fire Resistance +5 |
|
SA: Immune to Red Dragon Fear |
Notice the changes?
First we added a PROFICIENCY tag - Very important as it informs PCGen which characters can use the armor since the name no longer matches any of the armor use proficiencies.
The TYPE also changes to include Magic and Specific. Magic will always be flagged first, the Specific tells it that it is a named item.
Then there's the reduced ACCHECK rating. Why? Well, all magic items are masterwork, and masterwork armor has a reduced armor check penalty.
Last, the AC bonus was increased by 2 in the BONUS tag. The cost is my personal evaluation of the cost of this armor.
For armor found in a horde you may be tempted to set it to 0 so they can buy it without hitting the "buy for free" tag, but it is recommended to set the cost so you can use the "owned wealth" calculation to make sure your PCs have as much, or as little, as you think they should.
Last come the SA tags. SA stands for Special Ability and reflects a text string that is displayed on the character sheet. SAs have no affect on PCGen's operation. SAs can be used as requirements and can perform calculations (like displaying uses per level). SAs are almost, but not quite, as feature rich as BONUS. Remember citizen, the docs are your friends.
For completeness I have included a proficiency.lst below with the most complicated proficiency in the basic game; the bastard sword.
From your reading you should be aware that by the Martial Weapon proficiency, a person can use the sword two handed if medium sized, or 1 handed if they are a Large (or bigger) creature. Only someone who has the Exotic Weapon Proficiency: Bastard Sword can use it one handed.
Cannibalizing the srdweaponprof.lst file we get:
SOURCELONG:PCGen Documentation <tab> SOURCESHORT:P-Doc <tab> SOURCEWEB:http://www.pcgen.org
Sword (Bastard/Martial) |
|
TYPE:Martial |
|
HANDS:1IFLARGERTHANWEAPON |
Sword (Bastard/Exotic) |
|
TYPE:Exotic |
So you see the weapon's name, the type, and the number of hands required to use the weapon. If you don't specify the number of hands, PCGen's sizing system automatically fires up, assigning weapons of same or smaller size to 1 hand use, and weapons sized larger than the character to 2 hand use.
In this case, the Martial version of the proficiency does NOT allow a medium creature to use the medium sized Bastard Sword one-handed and overrides the default.
The Exotic version follows the standard PCGen sizing system which works as the rules require.
Refer to the HANDS tag docs for more details.
Feats are handy things. They have a lot of power, but are really fairly simple. We'll start at the beginning of the srdfeats.lst and pull alertness.
Alertness |
|
TYPE:General |
|
DESC:See Text |
|
BONUS:SKILL|Listen,Spot|2 |
|
SOURCEPAGE:Chap.5, Feat Descriptions |
So we have the name, type, description, a bonus of +2 to listen and spot, and sourcepage. Really the name, type and description are the only things you need. Some feats provide features that are not handled in PCGen because they are conditional or just not addressed.
We'll move on to something meatier.
Weapon Specialization |
|
TYPE:Special.Fighter |
|
PREFEAT:1,Weapon Focus |
|
PREVARGTEQ:WeapSpecQualify,1 |
|
DESC:See Text |
|
MULT:YES |
|
CHOOSE:FEAT=Weapon Focus|1 |
|
BONUS:WEAPONPROF=%LIST|DAMAGE|2|TYPE=NotRanged |
|
BONUS:WEAPONPROF=%LIST|DAMAGE-SHORTRANGE|2 |
|
SOURCEPAGE:Chap.5, Feat Descriptions |
A bit different, but not much. Besides the normal stuff, we see that Weapon Specialization requires the character to already have the feat Weapon Focus and have a variable called WeaponSpecQualify with a value of 1. We'll see WeaponSpecQualify later in the CLASS section where it will be covered in more detail. It can be chosen MULTiple times but only once per weapon, a feature inherent in PCGen. You CHOOSE a weapon that you already have Weapon Focus and it receives a +2 to damage.
Races are a step up the complexity list from feats. We'll first examine one of the most complex standard races, at least by PCGen standards, the Elf. This, and other examples, can be found in the srdracesphb.lst file.
Elf |
|
FAVCLASS:Wizard |
|
STARTFEATS:1 |
|
SIZE:M |
|
MOVE:Walk,30 |
|
REACH:5 |
|
VISION:Low-light |
|
LANGAUTO:Common,Elven |
|
LANGBONUS:Draconic,Gnoll,Gnome,Goblin,Orc,Sylvan |
|
WEAPONAUTO:Shortbow|Longbow|Longbow (Composite)|Shortbow (Composite) |
|
WEAPONBONUS:Rapier|Longsword |
|
BONUS:SKILL|Listen,Search,Spot|2|TYPE=Racial |
|
BONUS:STAT|DEX|2 |
|
BONUS:STAT|CON|-2 |
|
SA:Immunity to magic sleep spells and effects |
|
SA:+2 racial saving throw bonus against Enchantment spells or effects |
|
SA:An elf who merely passes within 5 feet of a secret or concealed door is entitled
to a Search check to notice it as if she were actively looking for the door |
|
TYPE:Humanoid |
|
SOURCEPAGE:Chap.2, Elves |
What we find is the race name, favored class, number of starting feats, size, movement types and speeds, reach, special vision types, automatic languages, the list of available bonus languages, automatic weapon proficiencies, a bonus proficiency that is chosen in the race window, racial adjustments to skills and stats (note the Con penalty applied as a negative bonus), followed by special abilities, the creature type and source page. Notice the SAs with nice, descriptive tags.
Since SAs have no affect on PCGen, you should make sure the relevant data is in the SAs. (Unless the copyright owner says not to. You'll find lots of things with an SA of "Super Power: see text p.xx" because the publisher doesn't want Super Power defined outside their books. It's their book, it's their right and we respect that. Do what you want for your own creations.)
The required entries are name, size, movement, reach, and creature type. Everything else is optional and there are many, many more racial tags available for use.
Our example race will be a Silverback, a strong and intelligent creature (+2 strength, +1 intelligence) but somewhat inflexible (dexterity -1), they are Large creatures with a 10' reach, 60' darkvision, bonuses to handle animal, diplomacy and sense motive (+2 each), immune to charm spells, with a preferred class of ranger. They automatically speak Simian and Common and have an elf-like list of bonus languages. Like most races, they only receive 1 feat at first level. Silverbacks have no automatic weapon proficiencies but they do get two claw attacks doing 1d6 damage. Silverbacks do not receive any bonus hit dice or have monster classes.
Building our race.lst file from scratch we put our standard header.
SOURCELONG:PCGen Documentation <tab> SOURCESHORT:P-Doc <tab>
SOURCEWEB:http://www.pcgen.org/
Silverback |
|
FAVCLASS:Ranger |
|
STARTFEATS:1 |
|
SIZE:L |
|
MOVE:Walk,30 |
|
REACH:10 |
|
VISION:Darkvision (60') |
|
LANGAUTO:Common,Simian |
|
LANGBONUS:Draconic,Gnoll,Gnome,Goblin,Orc,Sylvan,Elven |
|
BONUS:SKILL|Handle Animal,Diplomacy,Sense Motive|2|TYPE=Racial |
|
BONUS:STAT|STR|2 |
|
BONUS:STAT|INT|1 |
|
BONUS:STAT|DEX|-1 |
|
NATURALATTACKS:Claw,Weapon.Natural.Melee.Piercing.Slashing,*2,1d6 |
|
SA:Immunity to charm |
|
TYPE:Humanoid |
The differences between this and the Elf are primarily the missing weapon bonuses and the new NATURALATTACKS tag. NATURALATTACKS do not need a proficiency specified so no worries there. You can see it is called Claw, is a natural melee piercing/slashing weapon and there are two of them.
More complex races abound in the SRD directory. Consider examining the srdracesXXX.lst files. Srdracesst.lst includes tritonss, troglodytes and trolls which are good examples for player character races.
After custom equipment, classes are the most popular new LST. They are also perhaps the most complicated and difficult to master. Mastery takes time, but most people can achieve sufficiency in a very short period of time. And sufficiency is, well, sufficient.
The first barrier to overcome is that class LSTs do not follow the one line per entry system that all the other LSTs follow. Classes are too complicated to do that. So you have three sections to a class entry: a combat definition, a skill set definition, and the level-specific events.
Some will have more sections to cover special functions, but these are the standards. Once you start the level-specific block you can put entries in whatever order you want or have multiple entries for the same level. All those entries will apply until it finds a new definition block.
We'll begin simple and look at the Warrior, your basic muscle. Like the other examples, blank lines indicate a new line and the indentions list the tags that fall on that line.
CLASS:Warrior |
|
CLASS:Warrior |
|
HD:8 |
|
TYPE:NPC |
|
ABB:War |
|
SOURCEPAGE:Chap.2, Classes, NPC Classes |
|
BONUS:CHECKS|BASE.Fortitude|CL/2+2 |
|
BONUS:CHECKS|BASE.Reflex,BASE.Willpower|CL/3 |
|
BONUS:COMBAT|BAB|CL |
CLASS:Warrior |
|
STARTSKILLPTS:2 |
|
CSKILL:Climb|Handle Animal|Intimidate|Jump|Ride|Swim |
|
1 |
|
WEAPONAUTO:SIMPLE|MARTIAL |
|
FEATAUTO:Simple Weapon Proficiency|Armor Proficiency (Light)|Armor Proficiency (Medium)|Armor Proficiency
(Heavy)|Shield Proficiency|Martial Weapon Proficiency |
In the combat definition we find hit dice, class type (base, prestige, NPC, monster, etc), abbreviation to be used, source page, saving throws and base attack bonus.
The skill set block covers class skills and skill points per level. The skill names in the block need to match the entries in the skill LST file.
The level specific block only addresses first level where we see the warrior receives all simple and martial weapon proficiencies and all armor and shield proficiencies.
Notice that all the definition blocks start with CLASS:. This is the keyword used by PCGen. Leave that out and bad things will happen.
To make a warrior into a fighter we'd change the hit die and add some more level-specific abilities, specifically feats. Here is the level specific block for the fighter from the srdbaseclasses.lst file:
1
ADD:FEAT(TYPE=Fighter)
WEAPONAUTO:SIMPLE|MARTIAL
FEATAUTO:Armor Proficiency (Light)|Armor Proficiency (Medium)|Armor
Proficiency (Heavy)|Shield Proficiency|Simple Weapon Proficiency
2
ADD:FEAT(TYPE=Fighter)
4
DEFINE:WeapSpecQualify|1
ADD:FEAT(TYPE=Fighter)
6
ADD:FEAT(TYPE=Fighter)
8
ADD:FEAT(TYPE=Fighter)
10
ADD:FEAT(TYPE=Fighter)
12
ADD:FEAT(TYPE=Fighter)
14
ADD:FEAT(TYPE=Fighter)
16
ADD:FEAT(TYPE=Fighter)
18
ADD:FEAT(TYPE=Fighter)
20
ADD:FEAT(TYPE=Fighter)
Pretty simple. Only the 4th level DEFINE statement should require explanation. The DEFINE statement is used to initialize a variable, in this case WeapSpecQualify, and set it to 1. This is the prerequisite for the Weapon Specialization feat we saw earlier.
Let's look at something more magical, like a bard.
CLASS:Bard
HD:6
SPELLSTAT:CHA
SPELLTYPE:Arcane
TYPE:Base.PC
ABB:Brd
MEMORIZE:NO
SOURCEPAGE:Chap.3, Bard
LANGAUTO:Literacy
BONUS:CHECKS|BASE.Fortitude|CL/3
BONUS:CHECKS|BASE.Reflex,BASE.Willpower|CL/2+2
BONUS:COMBAT|BAB|CL*3/4
Standard combat definition block, but for the Bard it indicates the class can cast arcane spells using Charisma as the prime stat without memorizing spells.
CLASS:Bard
PREALIGN:3,4,5,6,7,8
Bards have an alignment restriction of "non-lawful". The numbers 0-9 correspond to the alignments with the omitted 1, 2, and 9 being lawful good, lawful neutral and lawful evil respectively.
CLASS:Bard
STARTSKILLPTS:4
CSKILL:Alchemy|Appraise|Balance|Bluff|Climb|Concentration|TYPE.Craft|
Decipher Script|Diplomacy|Disguise|Escape Artist|Gather Information|Hide|
Intuit Direction|Jump|TYPE.Knowledge|Listen|Move Silently|Perform|Pick Pocket|
TYPE.Profession|Scry|Sense Motive|Speak Language|Spellcraft|Swim|Tumble|Use Magic Device
Standard skill set. Nothing to see here, move along.
1
CAST:2
KNOWN:4
SA:Bardic music %/day|BardicMusic
SA:Bardic knowledge (+%)|BardicKnowledge
BONUS:VAR|BardicMusic|CL=Bard
BONUS:VAR|BardicKnowledge|CL=Bard+INT
DEFINE:BardicKnowledge|0
DEFINE:BardicMusic|0
WEAPONAUTO:SIMPLE
WEAPONBONUS:Longbow|Longbow(Composite)|Longsword|Rapier|Sap|Shortbow (Composite)|Sword
(Short)|Shortbow|Whip
FEATAUTO:Armor Proficiency (Light)|Armor Proficiency (Medium)|Shield Proficiency|Simple Weapon Proficiency
Now we see some new things other than the standard proficiencies and feats. A first level Bard can cast 2 1st level spells and knows four of them. He has the special ability to use Bardic Music a number of times equal to his class level (CL) which is handled by an SA entry (with % being used to display the value of the BardicMusic variable), a DEFINE and a BONUS to set the variable to the Bard class level. The same is done with the Bardic Knowledge bonus.
2
CAST:3,0
KNOWN:5,2
Bards can now cast 2nd level spells (if they have any bonus spells from their spell-stat Charisma) and know 2 of them.
3
CAST:3,1
KNOWN:6,3
4
CAST:3,2,0
KNOWN:6,3,2
...
...
20
CAST:4,4,4,4,4,4,4
KNOWN:6,5,5,5,5,5,4
SOURCELONG:PCGen Documentation <tab> SOURCESHORT:P-Doc <tab> SOURCEWEB:http://www.pcgen.org