Difference between revisions of "Data LST Standards"

From PCGen Wiki
Jump to: navigation, search
(PCC Stuff)
 
Line 77: Line 77:
 
Our old Standard was to do variables for Classes in the class file. This is no longer optimal for the existing sets. All Classes that need to use 'CL' will replace 'CL' with '<ClassNameLVL>' and then move the Variable formula to the Ability it applies too.
 
Our old Standard was to do variables for Classes in the class file. This is no longer optimal for the existing sets. All Classes that need to use 'CL' will replace 'CL' with '<ClassNameLVL>' and then move the Variable formula to the Ability it applies too.
  
===General EQMOD Naming Standards===
+
===PROPOSED General EQMOD Naming Standards===
  
 +
EQMOD keys will adopt a standard format similar to Equipment Objects. Format will be "Modifier Name (Group/Subgroup)"
 +
 +
Full Name, no abbreviations. It should match how the publisher publishes it. If in doubt, ask the Silverback or Data 2nd for clarification.
 +
 +
For Example:
 +
* Adamantine, which can be used on Armor or Weapons and has different effects/cost depending would be done as such:
 +
 +
  Adamantine  KEY:Adamantine (Ammunition) TYPE:BaseMaterial.MasterworkQuality.Ammunition COST:60 VISIBLE:QUALIFY ...
 +
  Adamantine  KEY:Adamantine (Armor/Light) TYPE:BaseMaterial.MasterworkQuality.Armor COST:5000 VISIBLE:QUALIFY ...
 +
  Adamantine  KEY:Adamantine (Armor/Medium) TYPE:BaseMaterial.MasterworkQuality.Armor COST:10000 VISIBLE:QUALIFY ...
 +
  Adamantine  KEY:Adamantine (Armor/Heavy) TYPE:BaseMaterial.MasterworkQuality.Armor COST:15000 VISIBLE:QUALIFY ...
 +
  Adamantine  KEY:Adamantine (Weapon) TYPE:BaseMaterial.MasterworkQuality.Weapon COST:3000 VISIBLE:QUALIFY ...
 +
  Bane KEY:Bane TYPE:Weapon CHOOSE:STRING|Aberrations|Humanoids|TYPE=Bane Selection  ...
 +
  Flaming Burst KEY:Flaming Burst TYPE:Weapon ...
 +
 +
 +
Then we invoke these keys as typical from the EQMOD tag:
 +
  EQMOD:Bane|Aberrations
 +
  EQMOD:Adamantine (Armor/Light)
 +
  EQMOD:Flaming Burst
 +
 +
 +
 +
====OLD METHOD FOR HISTORICAL====
 
EQMOD keys 'KEY:EQMOD_NAME' are to be in all capital letters and may only contain letters, numbers and underscores ("_").
 
EQMOD keys 'KEY:EQMOD_NAME' are to be in all capital letters and may only contain letters, numbers and underscores ("_").
  
Line 100: Line 124:
  
 
===Special Usages===
 
===Special Usages===
 +
 +
OLD:
 +
* Adamantine KEY:ADAMANT_AMMO
 +
* Adamantine KEY:ADAMANT_ARMR_LT
 +
* Adamantine KEY:ADAMANT_ARMR_MED
 +
* Adamantine KEY:ADAMANT_ARMR_HVY
 +
* Adamantine KEY:ADAMANT_WEAP
 +
  
 
KEY use should follow the following format
 
KEY use should follow the following format
Line 297: Line 329:
  
 
[[Pathfinder RPG]]
 
[[Pathfinder RPG]]
 +
 +
 +
 +
===Blank lst code templates available to be used:===
 +
 +
yyy = Object Proper Name
 +
xxx = Originating Object granting / Group
 +
 +
* ABILITY FILE
 +
Class Feature
 +
  yyy KEY:xxx ~ yyy CATEGORY:Special Ability TYPE:xxx Class Feature.SpecialQuality SOURCEPAGE:p. DESC:
 +
 +
Racial Trait (For Race Granted Traits)
 +
  yyy KEY:xxx ~ yyy CATEGORY:Special Ability TYPE:xxx Racial Trait.SpecialQuality SOURCEPAGE:p. DESC:
 +
 +
 +
Example:
 +
  Rage KEY:Barbarian ~ Rage CATEGORY:Special Ability TYPE:Barbarian Class Feature.SpecialQuality SOURCEPAGE:p.12 DESC:The barbarian can rage
 +
 +
* ABILITYCATEGORY FILE
 +
  ABILITYCATEGORY:xxx Class Feature CATEGORY:Special Ability TYPE:xxx Class Feature PLURAL:xxx Class Features EDITABLE:NO EDITPOOL:NO VISIBLE:QUALIFY DISPLAYLOCATION:Class Features
 +
 +
  ABILITYCATEGORY:xxx Racial Trait CATEGORY:Special Ability TYPE:xxx Racial Trait PLURAL:xxx Racial Traits EDITABLE:NO EDITPOOL:NO VISIBLE:QUALIFY DISPLAYLOCATION:Racial Traits
 +
 +
 +
 +
More blanks will be added to the zen test. Note the templates for Class will be re-ordered if PrettyLST is used. The Templates are to make data entry easier.

Latest revision as of 21:15, 30 January 2015

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 (~).

The following alpha characters shall not be used in object names: Comma (,), Pipe (|), Backslashe (\), Colon (:), Semicolon (;), Period (.), Bracket ([]), Percent (%), Asterisk (*) and Equals (=).

Two words separated by a dash should both be capitalized. (Example: Low-Light Vision)

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. If the name has a Comma (,) the section after shall use Parenthesis in the KEY. Example: Beast Totem, Greater becomes Beast Totem (Greater).


Ability Naming Standard:

PublisherAbilityName <TAB> KEY:Granting Object ~ NameOfAbility

Example: Barbarian Class has 'Rage' as a Class Feature we would do it as such -

Rage <TAB> KEY:Barbarian ~ Rage

Objects Belonging to a Group of Selections should use the Originating Ability Name as the Granting Object to follow this pattern. Example: Rage Powers from Barbarian would be done 'Barbarian ~ Rage Powers' and then the powers themselves would be 'Rage Powers ~ Name of Power'

  Rage Powers ~ Beast Totem (Greater)
  Rage Powers ~ Beast Totem (Lesser)
  Rage Powers ~ Brawler

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". Further restrictions discovered: 'THROWN', 'RANGED', 'WEAPON'. << Need to clarify with code if we can override this.


General Variable Naming Standards

Variables syntax should start with a letter and should be composed of only letters, underscores (_) and numbers. Do not use Hyphens, Dashes or Emdashs (-) as the program will think the Variable is a formula 'XYZ-ABC'. Our standard is to use only letters, and capitalizing individual words for readability.

Examples:

 'SneakAttackDice'
 'UncannyDodgeFlankingLVL'
 'AnimalCompanionLVL'
 'PoisonDC'


  Variables should be Full Words and end in what they are doing. Listed below are the standard Ends for our Variable Names. Each one indicates a certain function:
 LVL <-- Short for Level (Used with Classes and Progressions)
 Dice <-- Number of Dice in a xdy format, with Dice being the X.
 DieSize <-- Die Size in a xdy format, with DieSize being the Y.
 Bonus <-- Used for '+x' formats, class features that have "Ability +1"
 Count <-- This means counting involved, used for Feat Pools, or Selections. Example: How many Fighter Feats do you have.
 DC <-- Used for items that have a 'DC x' format.
 Times <-- Used for items that use 'x/day' style format
 Duration <-- Used for items that have a Duration 

Examples of this naming:

 ClassNameLVL
 SneakAttackDice
 SneakAttackDieSize
 FighterBonusFeatCount
 AssassinSaveBonus
 DeathAttackDC

There should be at least one, 'DEFINE' per variable and the DEFINE should be set at 0. All adjustments of the Variable will then use a BONUS:VAR statement. Per Code Silverback (James Dempsey): Define is evaluated once in the code, therefore using DEFINE to any value other than 0 can cause issues for characters. DEFINE is now required by CODE to be a value of 0, no exceptions.

Only SYSTEM hard-coded variable names are all capitals. Any Data Team created variables are restricted to Mixed Case only.

Variables should always have the DEFINE set within the originating 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. UPDATE: Hopefully, moving to using consistent naming patterns the documentation won't be as necessary.

Our old Standard was to do variables for Classes in the class file. This is no longer optimal for the existing sets. All Classes that need to use 'CL' will replace 'CL' with '<ClassNameLVL>' and then move the Variable formula to the Ability it applies too.

PROPOSED General EQMOD Naming Standards

EQMOD keys will adopt a standard format similar to Equipment Objects. Format will be "Modifier Name (Group/Subgroup)"

Full Name, no abbreviations. It should match how the publisher publishes it. If in doubt, ask the Silverback or Data 2nd for clarification.

For Example:

  • Adamantine, which can be used on Armor or Weapons and has different effects/cost depending would be done as such:
  Adamantine   	KEY:Adamantine (Ammunition)	TYPE:BaseMaterial.MasterworkQuality.Ammunition	COST:60		VISIBLE:QUALIFY	...
  Adamantine   	KEY:Adamantine (Armor/Light)	TYPE:BaseMaterial.MasterworkQuality.Armor	COST:5000	VISIBLE:QUALIFY	...
  Adamantine   	KEY:Adamantine (Armor/Medium)	TYPE:BaseMaterial.MasterworkQuality.Armor	COST:10000	VISIBLE:QUALIFY	...
  Adamantine   	KEY:Adamantine (Armor/Heavy)	TYPE:BaseMaterial.MasterworkQuality.Armor	COST:15000	VISIBLE:QUALIFY	...
  Adamantine   	KEY:Adamantine (Weapon)		TYPE:BaseMaterial.MasterworkQuality.Weapon	COST:3000	VISIBLE:QUALIFY	...
  Bane			KEY:Bane			TYPE:Weapon	CHOOSE:STRING|Aberrations|Humanoids|TYPE=Bane Selection  ...
  Flaming Burst	KEY:Flaming Burst		TYPE:Weapon ...


Then we invoke these keys as typical from the EQMOD tag:

  EQMOD:Bane|Aberrations
  EQMOD:Adamantine (Armor/Light)
  EQMOD:Flaming Burst


OLD METHOD FOR HISTORICAL

EQMOD keys 'KEY:EQMOD_NAME' 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 Naming for EQMOD Keys:

 ARMR <-- Armor
 LT <-- Light
 MED <-- Medium
 HVY <-- Heavy
 SHLD <-- Shield
 WEAP <-- Weapon


Special Usages

OLD:

  • Adamantine KEY:ADAMANT_AMMO
  • Adamantine KEY:ADAMANT_ARMR_LT
  • Adamantine KEY:ADAMANT_ARMR_MED
  • Adamantine KEY:ADAMANT_ARMR_HVY
  • Adamantine KEY:ADAMANT_WEAP


KEY use should follow the following format

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


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.
  • 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.
  • Underscore (_) before the pcc file name will keep the file at the top of the list.
  • Example:
    • paizo
    • pathfinder_rpg
    • core_rulebook
    • _core_rulebook.pcc
    • cr_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


PCC Stuff

CAMPAIGN:>book name< or 'My Pathfinder Campaign' (home brew name) or 'Pathfinder Society'
# EXAMPLE - CAMPAIGN:Advanced Players Guide
# EXAMPLE - CAMPAIGN:Curse of the Crimson Throne, Chapter 1: Edge of Anarchy
# EXAMPLE - CAMPAIGN:Inner Sea World Guide
KEY:>PCGen Key Rules Apply<
Instead of Parenthesis, we use dash (-) instead of Commas as PRECAMPAIGN will not work with Commas! # EXAMPLE - KEY:Curse of the Crimson Throne - Chapter 1

RANK:1-9
# NOTE - Follow these rules - 1 (Core Rulebook), 2 (capaign settings), 3 (supplements), 4 (web/blog), 5 (3rd party campaign settings), 6(3rd party supplements), 7(3rd party web/blog), 8 & 9 (Homebrew)
# EXAMPLE - RANK:3
# EXAMPLE - RANK:3
# EXAMPLE - RANK:2
TYPE:Paizo Publishing.>Type of book = Core Rulebook, Player Companion, Campaign Setting, Adventure Path, Web Enhancement, Paizo Blog, >Homebrew<.>campaign setting name/adventure path name<
# NOTE - Max of 3 type's only, last type is optional
# EXAMPLE - TYPE:Paizo Publishing.Supplement
# EXAMPLE - TYPE:Paizo Publishing.Adventure Path.Curse of the Crimson Throne
# EXAMPLE - TYPE:Paizo Publishing.Campaign Setting
STATUS:TESTONLY, ALPHA, BETA, RELEASE
# EXAMPLE - STATUS:RELEASE
# EXAMPLE - STATUS:BETA
# EXAMPLE - STATUS:ALPHA
BOOKTYPE:Core Rules, Supplement, Adventure, Campaign Setting, Homebrew
# EXAMPLE - BOOKTYPE:Supplement
# EXAMPLE - BOOKTYPE:Adventure
# EXAMPLE - BOOKTYPE:Campaign Setting
SETTING:Pathfinder and/or >overall setting name< and/or >setting regional name< and/or >specific location name< or Pathfinder Society or Homebrew or >campaign setting name<
# NOTE - SETTING is pipe delimited
# EXAMPLE - Pathfinder
# EXAMPLE - Pathfinder|Golarion
# EXAMPLE - Pathfinder|Golarion|Inner Sea
PRECAMPAIGN:#,BOOKTYPE=>BOOKTYPE name<
!PRECAMPAIGN:#,BOOKTYPE=>BOOKTYPE name<
# NOTE - PREMULT works in these files - ignore the prettylst message
# EXAMPLE - PRECAMPAIGN:1,BOOKTYPE=Core Rules
# EXAMPLE - !PRECAMPAIGN:1,Character Traits Web Enhancement,BOOKTYPE=Complete Core
# EXAMPLE - PREMULT:2,[PRECAMPAIGN:1,BOOKTYPE=Core Rules],[!PRECAMPAIGN:1,Character Traits Web Enhancement,BOOKTYPE=Complete Core]
PUBNAMELONG:Paizo Publishing, LLC
PUBNAMESHORT:Paizo
PUBNAMEWEB:http://paizo.com
SOURCELONG:>full book name<
# EXAMPLE - SOURCELONG:Advanced Player's Guide
# EXAMPLE - SOURCELONG:Curse of the Crimson Throne, Chapter 1: Edge of Anarchy
# EXAMPLE - SOURCELONG:Inner Sea World Guide
SOURCESHORT:>short book name<
# EXAMPLE - SOURCESHORT:APG
# EXAMPLE - SOURCESHORT:EOA
# EXAMPLE - SOURCESHORT:ISWG
SOURCEWEB:>url link to exact store location<
# EXAMPLE - SOURCEWEB:http://paizo.com/store/downloads/pathfinder/pathfinderRPG/v5748btpy8fo1
# EXAMPLE - SOURCEWEB:http://paizo.com/pathfinder/adventurePath/curseOfTheCrimsonThrone/v5748btpy81xw
# EXAMPLE - SOURCEWEB:http://paizo.com/store/games/roleplayingGames/p/pathfinderRPG/paizo/pathfinderChronicles/v5748btpy8ief
SOURCEDATE:>release date as 4 digit year dash 2 digit month (2008-08)
# EXAMPLE - SOURCEDATE:2010-08
# EXAMPLE - SOURCEDATE:2008-03
# EXAMPLE - SOURCEDATE:2011-03
ISOGL:YES

# Place errata version/applied dates here (multi-lines as need be)
# EXAMPLE - Errata: December 4, 2012 "Monkeying Around" Article - http://paizo.com/paizo/blog/v5748dyo5le61?Monkeying-Around (Andrew Maitland)
# EXAMPLE - Errata: January 35, 2250 "274th errata update" - >weblink< - (>name of updater<)

COVER:>book cover<.jpg
LOGO:@/publisher_logos/Paizo_Publishing.png
URL:WEBSITE|http://www.paizo.com/%7CVisit Paizo Publishing!

INFOTEXT:>text<
COPYRIGHT:>text<

# Do Not Remove Comment
# EXTRAFILE:OGL.txt

# Data Files
ABILITY:>source short name<_abilities.lst
ABILITY:>source short name<_abilities_class.lst
ABILITY:>source short name<_abilities_companion.lst
ABILITY:>source short name<_abilities_equipment.lst
ABILITY:>source short name<_abilities_race.lst
ABILITY:>source short name<_abilities_template.lst
ABILITYCATEGORY:>source short name<_abilitycategories.lst
BIOSET>source short name<_biosettings.lst
CLASS:>source short name<_classes.lst
COMPANIONMOD:>source short name<_companionmods.lst
DEITY:>source short name<_deities.lst
DOMAIN:>source short name<_domains.lst
EQUIPMOD:>source short name<_equipmods.lst
EQUIPMENT:>source short name<_equip_general.lst
EQUIPMENT:>source short name<_equip_magic_items.lst
EQUIPMENT:>source short name<_equip_arms_armor.lst
FEAT:>source short name<_feats.lst
KIT:>source short name<_kits.lst
KIT:>source short name<_kits_race.lst
KIT:>source short name<_kits_companion.lst
LANGUAGE:>source short name<_languages.lst
RACE:>source short name<_races.lst
RACE:>source short name<_races_companion.lst
SKILL:>source short name<_skills.lst
SPELL:>source short name<_spells.lst
TEMPLATE:>source short name<_templates.lst
ARMORPROF:>source short name<_profs_armor.lst
SHIELDPROF:>source short name<_profs_shield.lst
WEAPONPROF:>source short name<_profs_weapon.lst

Pathfinder Specific

Pathfinder RPG


Blank lst code templates available to be used:

yyy = Object Proper Name xxx = Originating Object granting / Group

  • ABILITY FILE

Class Feature

  yyy	KEY:xxx ~ yyy	CATEGORY:Special Ability	TYPE:xxx Class Feature.SpecialQuality	SOURCEPAGE:p.	DESC:

Racial Trait (For Race Granted Traits)

  yyy	KEY:xxx ~ yyy	CATEGORY:Special Ability	TYPE:xxx Racial Trait.SpecialQuality	SOURCEPAGE:p.	DESC:


Example:

  Rage 	KEY:Barbarian ~ Rage	CATEGORY:Special Ability	TYPE:Barbarian Class Feature.SpecialQuality	SOURCEPAGE:p.12	DESC:The barbarian can rage
  • ABILITYCATEGORY FILE
  ABILITYCATEGORY:xxx Class Feature	CATEGORY:Special Ability	TYPE:xxx Class Feature	PLURAL:xxx Class Features	EDITABLE:NO	EDITPOOL:NO	VISIBLE:QUALIFY	DISPLAYLOCATION:Class Features
  ABILITYCATEGORY:xxx Racial Trait	CATEGORY:Special Ability	TYPE:xxx Racial Trait	PLURAL:xxx Racial Traits	EDITABLE:NO	EDITPOOL:NO	VISIBLE:QUALIFY	DISPLAYLOCATION:Racial Traits


More blanks will be added to the zen test. Note the templates for Class will be re-ordered if PrettyLST is used. The Templates are to make data entry easier.