[RPG] How to make the Pathfinder Trait ‘Heirloom Weapon’ function in PCGen

By looking into the inner workings of PCGen, I have manage to cobble something together that seems to do the trick. However, this answer is in no way comprehensive, but meant to serve as a guide on how to patch your own homebrew stuff. For more information about working with Homebrew files, I suggest looking into the documentation (Help -> Documentation, F1), under the "List Files" heading (Sadly, I cannot link to specific pages of the documentation here).

Quick Example

The following is an explanation on how to add a Combat Trait called "Homebrew Trait" to the game, which adds two claw attacks dealing 1d4 points of damage. This is achieved mostly by combining an existing Combat Trait with the claw attacks granted by the Maw or Claw Tiefling Alternate Racial trait, found in [PCGen]/data/pathfinder/paizo/roleplaying_game/advanced_players_guide/apg_abilities.lst and advanced_race_guide/arg_abilities_race.lst, respectively.

1. Open up [PCGen]/data/pathfinder/homebrew/my_homebrew. This is the pre-installed Homebrew Campaign Thingy, which will do just fine for this purpose.

2. Traits are internally handled as "abilities". Using a good text editor (Notepad++ or similar), open up my_abilities.lst. Under #insert your data here, add the following line

Homebrew Trait      KEY:Trait ~ Homebrew Trait      CATEGORY:Special Ability    TYPE:Trait.BasicTrait.CombatTrait   PREMULT:1,[PREABILITY:1,CATEGORY=Special Ability,Trait ~ Homebrew Trait],[!PREABILITY:1,CATEGORY=Special Ability,TYPE.CombatTrait]      DESC:You have studied the workings of PCGen and managed to claw your way into creating a homebrew trait|PRERULE:1,DisplayFullAbility        NATURALATTACKS:Claw,Natural.Weapon.Melee.Finesseable.Piercing,*2,1d4

3. Once you have your ability to your liking, save the file and open up PCGen. Go To Sources -> Select Sources (CtrlL), and go to the Advanced tab. In the dropdown list at the top, select Pathfinder RPG as your Game. On the right side, you should now see "Pathfinder RPG for Players", as well as "My Pathfinder Campaign". Click on Load. Your homebrew trait should now be available to choose from the list of traits.

Code explanation

Of course, a trait called "Homebrew Trait" is not very appealing, but again, a full explanation is absolutely beyond the scope of this answer. However, I'd like to provide an overview on what the above code does, and why it does that. Let's break it into lines.

Homebrew Trait
  KEY:Trait ~ Homebrew Trait
  CATEGORY:Special Ability
  TYPE:Trait.BasicTrait.CombatTrait
  PREMULT:1,[PREABILITY:1,CATEGORY=Special Ability,Trait ~ Homebrew Trait],[!PREABILITY:1,CATEGORY=Special Ability,TYPE.CombatTrait]
  DESC:You have studied the workings of PCGen and managed to claw your way into creating a homebrew trait.|PRERULE:1,DisplayFullAbility
  NATURALATTACKS:Claw,Natural.Weapon.Melee.Finesseable.Piercing,*2,1d4

1. It starts off with the name of the ability, "Homebrew Trait"
2. Next up is the KEY keyword, followed by the internal name of the trait, allowing you to use this trait in other homebrew things, as a prerequisite for a feat, for example. I followed the naming convention I found in other *abilities.lst files.
3. The CATEGORY tag is there to list this under Special Abilities, nothing much to say here.
4. The TYPE tag is more involved. This is a dot-separated list of subcategories this Special Ability falls under. In this case, we have a trait which is a basic trait, and which is a combat trait. You can change the latter to what you like, but you'll have to change the prerequisites as well.
5. The line starting with PRExxx denotes prerequisites. PREMULT:1 states that only one of the following prerequisites need to be fulfilled. The prerequisites are given in square brackets.
   • PREABILITY:1,CATEGORY=Special Ability,Trait ~ Homebrew Trait means that you qualify for this trait when you have this trait. In particular, it means 1 prerequisite ability from the Special Ability category, which is "Trait ~ Homebrew Trait". This is needed because of the second prerequisite.
   • !PREABILITY:1,CATEGORY=Special Ability,TYPE.CombatTrait means "Not 1 Special Ability pf the CombatTrait type, as per the trait rules. Without the first prerequisite, this would make the trait disallow itself.
6. DESC is followed by the full description of the trait. Not sure what the PRERULE part does, just keep it there.
7. Finally, NATURALATTACKS adds the crunch. I copied this part from a Tiefling Alternate Racial Trait. It adds an attack called "Claw", lists the applicable types (see above), makes it 2 attacks, and sets the damage to 1d4. Instead of this (or in addition to!), you could have a BONUS tag, as many other abilities do.

Sacred Weapon stacks with other weapon bonuses. A warpriest simply cannot raise the enhancement bonus above +5, regardless of the sources of that enhancement, so if a weapon has some enhancement already before using Sacred Weapon, normally some bonuses would be lost. However, instead of increasing the enhancement bonus further, you can bestow special abilities upon the weapon, that replace some of the enhacement bonus you might have had, including the amounts that would go over the maximum allowed +5.

1. Precisely, but you don't have to spend them on abilities. You can simply lose them if you prefer. Why would you like that is anyone's guess.

2. No. You can only replace bonus that would be the result of Sacred Weapon. You cannot replace an enhancement bonus that has some other source. While this is not explicitly stated in RAW, there is a passage saying

   The enhancement bonus and special abilities are determined the first time the ability is used each day, and cannot be changed until the next day.

   That means you choose your enhancement bonus and special abilities without regard to existing bonuses and abilities on the target weapon. You might even choose ones that you have from some other source (spells, weapon enchantments, other player's abilities) and in that situation the enhancement bonus will stack but not exceed +5 in total and the doubled special abilities will not stack. If you decide to use the ability on a different weapon, you have to use the same choice of bonuses and abilities and resolve the final effect independently

3. This fragment means that when Sacred Weapon ability takes effect the enhancement bonus is considered first. In a situation where the weapon is left with no net enhancement bonus, no further special abilities will be added.