Data LST Standards

From PCGen Wiki
Revision as of 20:56, 28 May 2012 by LegacyKing (talk | contribs)
Jump to: navigation, search

General Object Naming Standards

These are general rules for the naming of classes, feats, races and other objects.

Characters approved for use in object names are: upper and lower case letters, numbers, single spaces in between multiple words (never before or after) and the following glyphs: underscore (_), dash (-), apostrophe ('), parentheses (), slash (/), and a tilde (~).

Characters which should never be used in object names are Commas (,), Pipes (|), Backslashes (\), Colons (:), Semicolons (;), Periods (.), Brackets ([]), Percent (%), Asterisk (*) and Equals (=).

Two words separated by a dash should both be capitalized.

Within these limits the name should be as close as possible to the published source.

EXCEPTION to the Naming Convention, if you use a KEY name, the Name acts as OUTPUTNAME and may use commas. The KEY MUST ADHERE to the General rules for the naming of all objects at ALL times.


Additional Restrictions

No object may be named a valid number (even 0x45 or 1e20 could be a problem) as items with optional count can fail.

No object may be called "ANY" or "ALL" or "LIST".

No Class may be called "HIGHESTLEVELCLASS".

No Equipment may be called "Total".

No Weaponprof may be called "DEITYWEAPON".

No equipment (or eqmod ITYPE) may use the types "ADD" or "REMOVE".


General Variable Naming Standards

Variables syntax should start with a letter and should be composed of only letters, _ and numbers. The standard Convention is to use only letters, capitalizing individual words for readability.

Examples: TurnUndead, SpecialAbility, UncannyDodgeFlankingLevel.

Where it is possible to do so there should be only one DEFINE statement per variable and the DEFINE should be set at 0 with a BONUS:VAR used to adjust the value.

Variable names in all capitals are reserved for hard coded variables or variables defined within the system files.

Where it is possible to do so variables should be DEFINEd within the parent object where it is first used or encountered.

It is good practice to leave comments within the data sets LST code explaining what variables have been used in the set, what their purpose is and how they are to be used.


General EQMOD Naming Standards

EQMOD keys are to be in all capital letters and may only contain letters, numbers and underscores ("_").

Each word should be separated by an underscore character for ease in reading.

For purposes of abbreviation the letter limit on the first and second sections of the Key name is 8 and 7.

EQMODs for different item types (Weapon vs. Armor for example) will be done as separate EQMODs.

Materials which list different pricing for different item types or sub types (Light Armor vs. Medium Armor for example) will be done as separate EQMODs for each price type.


Special Usages

KEY use should follow the following format

  • For EQMODS
    • ALL UPPERCASE
    • Spaces will be underscores '_'


  • For Abilities
    • Prime Ability ~ ClassGranting
    • Grouping ~ Abilities
    • Example: Archetypes are a Grouping, 'Barbarian Archetype ~ Name of Archetype/Ability'
    • Example: Poison is an Ability, 'Poison ~ Druid'


Commenting In .lst Files Standard

In an effort to make our use of comments in .lst files more uniform (and hopefully more useful), the following standard has been adopted regarding what comments should be in the file and how they should be done.

At the top of the file the original author should enter the following (this should be in every file from the date of adoption of this standard forward):

# ORIGINAL ENTRY: <name, handle, etc.>
# ORIGINAL ENTRY DATE: <####/##/## date of original entry>

Note that the date should be in the format of YEAR/MONTH/DAY

The rest of these recommendations are to be used on an as needed basis. These types of entries should appear immediately above the item/feat/object they are referring to. For ease of reading, please restrict each line to one screen width, using multiple lines (all with the appropriate comment heading in front) if necessary. As a further aid to reading the comments and identifying what they apply to, a blank line should be left above the first of these comment lines and there should also be a blank line below the object line the comment(s) refer to (see examples below).

# NEEDS CODE WORK: <explanation of code work needed, tracker # if there is one>
# NEEDS DATA WORK: <explanation of data work needed>
# WORKAROUND: <explanation of workaround being used>
# PARTIAL WORKAROUND: <explanation of partial workaround and what is supposed to be happening but isn't>
# COMMENT: <elaboration on a difficult concept/implementation that the creator feels needs explanation (like all the barbarian rage vars)>

More than one of these could be used in concert if there were a workaround in place but a better solution was expected from code, you might have a NEEDS CODE WORK and a WORKAROUND for example.


Examples as they should appear in a .lst file:

# ORIGINAL ENTRY: Barak
## ORIGINAL ENTRY DATE: 2011/06/23

Feat 1
Feat 2
Feat 3

# NEEDS CODE WORK: Cannot track *when* feat was taken, so adding +1 hp per level after is impossible - CDOM should fix this
# WORKAROUND: Will implement the +1 hp - but it won't be correct. Basing calculation on fighter levels TL-6
Feat 4
Feat 5
Feat 6

# NEEDS CODE WORK: Need a way to tally total ranks in type.knowledge where you must have at least 3 different knowledge skills.
# NEEDS CODE WORK: Current tag can get 20, but not the three part.
# PARTIAL WORKAROUND: Coding to test for the total ranks, DM will have to monitor the total of three knowledge skills required
Feat 7
Feat 8
Feat 9
Feat 10
Feat 11
Feat 12

# COMMENT: The ExtShokQual variable will override the normal PREREQs for those classes that
# COMMENT: gain this as a class ability without having to meet the prereqs.
Feat 13


File Naming and Folder Names

  • Submitted Oct 15th, 2010
  • All titles and folders will adhere to lower case and spaces will be replaced by '_' underscores.
  • Sorted by Alpha or d20ogl > Determined if Bug Free and Stable by the Data Team
  • Publisher > All books are identified by Primary Publisher or one holding current License if known
  • Book Type > Core / Supplemental Title Group
  • Book Name
  • Files shall follow short name of book using short pub name and book name. Adhere to 3 to 5 letter book abbreviation by publisher if known. The PCC master file will be the full name of the book.
  • Example:
    • paizo
    • pathfinder_rpg
    • core_rulebook
    • core_rulebook.pcc
    • pfcr_abilities.lst
    • etc.

File Reference

  • Submitted May 28th, 2012

For Conversion Folders - when referencing a folder above the conversion folder ALWAYS use RELATIVE file paths, not absolutes, otherwise your paths will be broken and you'll be forcing fixes as the files transition between NFD, to ALPHA, To the full release folder. The only case this is not PLAUSIBLE is reference to other source books OUTSIDE the sourcebook folder, i.e. you need to reference material in another source book.

One Folder Up:

   ../<filename>.lst

Folder below:

   <folder_name>/<filename>.xxx