Table of contents

PCGen to kLoOge.Werks export template and postprocessing utility

by Cador <cador [at] tabularum.dk>

Version: 0.8.1 - March 2005

Main webpage with latest version
(the same page as this page if there is no newer version)

Changelog

Changes in 0.8.1

Changes in 0.8

Changes in 0.7

Changes in 0.6

What this thingy is

A PCGen export template in Werks' xml format, and a small java application for postprocessing PCGen's output.

And why the need for postprocessing? Although you can do quite a lot with character data in PCGen export templates, there are some limitations that can't be overcome. One is that PCGen exports apostrophes and quotation marks and other special symbols as HTML entities, which Werks ignores. So these need to be cleaned up and converted. Another limitation is that PCGen can't reference external files when exporting characters. Thus PCGen is unable to check if a spell name matches a sound file name in Werks' sound directory, and add the sound file as a custom spell sound in the character sheet. And a finally it is difficult for PCGen to add placeholders to the character sheet, such as converting 1d8+4 melee weapon damage to 1d8+2$S if the character has a +2 strength bonus.

But all this can be done with the PCGentoWerks-clean-o-matic™ postprocessing java utility (patent pending), which can be run from the command prompt, or automatically every time you export a character in PCGen with the Werks template.

Postprocessing isn't required; you can export a character from PCGen with the kLoOge.Werks template and import it into Werks without going through the PCGentoWerks-clean-o-matic™ postprocessing java utility (patent pending). But then you will have to live with a few missing apostrophes and empty fields, and none of the nifty placeholders.

How to use this thingy

To get PCGen to run PCGentoWerks when you export a character:

  1. Unpack the .zip file and copy csheet_kLoOge.Werks.xml to PCGen's outputsheets\d20\fantasy\htmlxml directory.
  2. Copy PCGentoWerks.class somewhere you can remember (like the PCGen root directory).
  3. Go to "Settings" and "Preferences" in PCGen and select the "output" node.
  4. Find and select csheet_kLoOge.Werks.xml as "Default HTML Output Sheet."
  5. Type the following in PCGen's "Post Export Command" field:

    java -cp d:\pcgen PCGentoWerks "%"

    where d:\pcgen is the directory where PCGentoWerks.class is located.

And that's it. PCGentoWerks will now process any file you export with the csheet_kLoOge.Werks.xml template. It will ignore files created with other templates.

There are a few command-line options available to PCGentoWerks:

-o [OUTPUTDIR]
Put the processed file in OUTPUTDIR.
-d
Delete original file after processing (OUTPUTDIR must be set).
-f
Force processing of files that aren't created with the Werks template (if for some reason you need that).
-p
Add placeholders where possible.
-s [WERKSDIR]
Add spell sounds from .ogg, .mp3 or .wav files in [WERKSDIR]/sounds.
-nobooks
Don't output spellbooks.
-nosaves
Don't output spell saving throw information.
-nospelllevelnames
Don't add class names to spell levels.

So to get PCGentoWerks to copy processed files to your kLoOge.Werks char_sheets directory, deleting the original files, adding placeholders where possible, and adding spell sounds:

java -cp d:\pcgen PCGentoWerks -o d:\Werks\char_sheets -d -p -s d:\Werks "%"

Where d:\pcgen is the location of PCGentoWerks.class, and d:\Werks is the directory where kLoOge.Werks is installed.

Options explained

-p

One of Werks' strengths is its support of placeholders, e.g. $S as a placeholder for the Strength modifier. The d20 system uses ability score modifiers in lots of calculations, so heaps of values can change if a single ability score modifier changes. E.g. if buff spells or drunkenness causes your character's Dexterity bonus to change, then his AC changes, his ranged attack bonus changes, his Reflex Save changes, his initiative modifier changes, his Dexterity-based skills change, etc. etc. In pen-and-paper d20, there will be times where you need to do enough re-calculations to make your nose bleed.

Fortunately, Werks supports placeholders in the character sheet, e.g. +5$D for Reflex Save, where $D is your Dexterity modifier and any temporary adjustments, which can save you some of the bother of re-calculating everything in the sheet. And to make things even easier, you don't even need to manually add $D and $S and such in most of the character sheet, as PCGentoWerks can insert placeholders when exporting a character, if you use the -p option.

When adding placeholders to weapon attack and damage values, PCGentoWerks only tries to apply the basic rules for melee weapons, and ranged and thrown weapons. If the character has weapons with special rules governing their attack and damage values, PCGentoWerks is not likely to add placeholders correctly. So always check the results manually.

If the character has Weapon Finesse ([weaponnames]), the $D placeholder is used in melee attacks with any weapons whose names include any of the listed [weaponnames].

For mighty composite bows, PCGentoWerks will only recognise them as such if the weapon name contains "Mighty" and "Composite", and the name has an indication of the maximum strength bonus in the form of "+2 Str" or "+2 Mighty".

Placeholders are also added to saving throws, skill checks and spell descriptions.

PCGentoWerks_spells.xml

PCGen's spell descriptions often contain some math for calculating various basic effects, such as "Invisibility lasts for CASTERLEVEL*10 minutes." PCGentoWerks can translate most of such text to spell expressions, e.g. "Invisibility lasts for {$WL*10} minutes", where $WL is the placeholder for the current wizard level.

However, some of PCGen's spell descriptions can't always be fully translated to spell expressions in Werks. In order to compensate for that, PCGentoWerks is able to read pre-typed spell expressions from an .xml file, which must be named PCGentoWerks_spells.xml and placed in the same directory as PCGentoWerks.class.

Please note that the PCGentoWerks_spells.xml file included in this .zip file contains 3.0 edition spells. Should anyone do a 3.5 conversion, then please mail me the file and I'll be happy to include it in the next version.

The PCGentoWerks_spells.xml file can also add effects and sounds to the exported character's spells. See the example in PCGentoWerks_spells.xml.

-s [WERKSDIR]

If you want PCGentoWerks to automatically add spell sounds to the exported character's spells, use the -s option followed by the directory where Werks is installed. PCGentoWerks will then read the contents of your [WERKSDIR]\sounds directory and subdirectories, and any .ogg, .mp3 or .wav files matching any of the exported character's spells will be added to the character sheet as custom spell sounds.

The matching algorithm is case-insensitive, and spaces in spell names will match underscores and dots in file names. E.g. the spellname Cure Light Wounds will match cure_light_wounds.ogg, Cure Light Wounds.mp3 or CuRe.LiGhT.wOuNdS.wAv.

-nobooks

In PCGen you can create "spellbooks", or rather sets of spells memorised for certain common situations (such as "City spells", "Wilderness spells", or "Party hard spells"). And with Werks you can import and export spell lists to and from .txt files. So if a character has spellbooks defined in PCGen, they will be exported to .txt files that you can later import into Werks. The .txt files will be output to the same location as the character sheet .xml file, and they will be called characterfilename_classname­spellbook_spellbookname.txt (e.g. Tybalt_Wizard­spellbook_PartyHardSpells.txt).

If you don't want the spellbook .txt files to be created, use the -nobooks option.

-nospelllevelnames

In order to support multiclass spellcasters, e.g. sorcerer/clerics and such, PCGentoWerks will add class names to spell level numbers in the character sheet. Every spell level will be listed as "Cleric 1" or "Sorcerer 2" so that it is clear which spell belongs to which class. However, since the spell level fields contain more than just a number, Werks won't be able to automatically calculate spell saving throw DCs (as Werks naturally can't add "10 + $W + Cleric 1", for example). However, there is a remedy for that - see below.

If you would rather just use plain spell level numbers, use the -nospelllevelnames option to strip class names from spell levels, leaving only the level number.

-nosaves

I have made a minor change to my version of Werks' 3rd edition definition file, so Werks no longer calculates spell saving throw DCs automatically. Werks' default formula of DC = 10 + ability modifier + spell level doesn't take into account that feats and prestige classes can raise the DC of some spells, and that muliticlass spell casters often have different ability modifiers affecting the spell save DCs of each spellcasting class.

Since PCGentoWerks appends spell saving throw information to each spell expression, Werks no longer needs to calculate save DCs automatically. When PCGentoWerks processes spell expressions, it will indicate if the spell requires a Will or Reflex or Fortitude save, what DC the save is (with placeholder for the caster's ability modifier if you use the -p option), and if a successful save negates or halves damage, etc.

But Werks will still automatically calculate spell save DCs "the old way", unless you edit Werks' definition file slightly as follows:

  1. Go to Werks' defs directory and open 3rdEdition.xml in a suitable editor (make a backup copy first, in case you make mistakes when editing the file).
  2. Near the end of the 3rdEdition.xml file, look for a line containing <post-roll>&nbsp; (DC={10${SPELL_DC}+${SPELL_LEVEL}}) <i>Spell failure check [...etc. etc.] (this is line no. 1495 in the default 3rdEdition.xml that comes with Werks 2.1.5).
  3. Delete (DC={10${SPELL_DC}+${SPELL_LEVEL}}) and save 3rdEdition.xml and restart Werks.

If you want to keep Werks' automatic DC calculation, and you don't want PCGentoWerks to append saving throw information to spells, use the -nosaves option.

"Anonymising" weapon names

When creating NPCs in PCGen and exporting them to Werks, you may want to avoid using full weapon names such as Longsword +2. The PCs shouldn't automatically know that the NPC has a nifty magical weapon (because we all know how some PCs react when they might be able to get their grubby little hands on a shiny, new magical weapon...). To avoid that, type "NPC" as the player name in PCGen, and then the character's weapon names won't be exported to Werks with +this and +that or even "masterwork" in the names. E.g. a Bastard Sword +1 will have its name changed to "Bastard Sword".

Suggestions and bug reports

Mail them to cador [at] tabularum.dk