HLKitWiki - User contributions [en]

TableDef Element (Data)

2017-11-10T22:52:55Z

Colen:

{{context|Kit Reference|Data File Reference}}

==The "tabledef" Element==

Note that for a tabledef to be associated with a table or chooser portal, you must specify the id of the tabledef for the portal's "usetabledef" attribute.

:{| class="infotable"
|class="leftnormal"|id
|Id – Specifies the unique id of the tabledef.
|-
|component
|Id – Specifies the unique id of the component the tabledef is associated with. Like a table portal, only things / picks from this component will be shown in the table.
|-
|isglobal
|(Optional) Boolean – if the table is used by ALL characters for the game system, specify "yes". If this is specified, you don't need to add "allowtable" tags for this table, as it's assumed to be present on all characters. This is unlikely to be true for game systems with multiple different types of characters, like Pathfinder (NPCs, kingdoms, armies, etc), so don't specify this unless every single character for the game system will need it. Default: "no".
|-
|description
|Text – A short string intended to communicate what the table does (in very general terms, like "Adds magic weapons") to the UI developers.
|-
|errorcategory
|(Optional) Unique id – indicates that this table is only marked as invalid if picks showing in it have an error of this category. If this attribute isn't set, the table will be marked as invalid if any pick in the table has an error.
|-
|}

The "tabledef" element also possesses two child elements that define the specifics of the table. Both of these child elements are optional.

:{| class="infotable"
|class="leftnormal"|select
|Contains details about the selection of new picks for this table. If the table can't select new picks (for example, if it's a fixed table), this should be omitted.
|-
|show
|Contains details about the picks shown in this table. Can be omitted if nothing interesting needs to be specified (for example, if the table has no list expression).
|-
|-
|}

==The "select" Child Element==

:{| class="infotable"
|class="leftnormal"|choosepicks
|(Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
<ul class="sets">
<li>thing – The selectable objects are things.</li>
<li>container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The selectable objects are picks from the active actor.</li>
<li>Default: "thing".</li>
</ul>
|-
|buyaction
|(Optional) Id – indicates the id of the action for the new UI to use when purchasing items from this table. Default: Empty.
|-
|sellaction
|(Optional) Id – indicates the id of the action for the new UI to use when selling items from this table. Default: Empty.
|-
|wrapupaction
|(Optional) Id – indicates the id of the action for the new UI to use after adding items from this table. Default: Empty.
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|candidatepick
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|Candidate tag expression]] for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|candidatefield
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|secondphase
|(Optional) Id – Specifies the phase of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Empty.
|-
|secondprior
|(Optional) Number – Specifies the priority of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|existphase
|(Optional) Id – Specifies the phase of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Empty.
|-
|existprior
|(Optional) Number – Specifies the priority of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|prereqtarget
|(Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
<ul class="sets">
<li>container – The default parent container is used.</li>
<li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li>
<li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li>
<li>Default: "container".</li>
</ul>
|-
|empty
|(Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
|-
|useagentcandidate
|(Optional) Boolean – Indicates whether the agent pick should be used for the candidatepick of this table. Default: "no".
|-
|useagentlinkage
|(Optional) Boolean – Indicates whether the agent pick should be used for the linkage of this table. Default: "no".
|-
|agentautotag
|(Optional) Id – Specifies the tag group of the agent pick's identity tag which will be added to picks added to this table. Default: None.
|-
|maxchoicelimit
|(Optional) Number – How many picks can be added to this table. Default: no limit. Must be 1 for tabledefs associated with choosers.
|-
|transactiontype
|Text – a short string, typically a single word, intended to communicate what sort of "purchase" the table typically makes. For example, any table in Pathfinder that allows you to buy gear might specify "money" for this attribute, indicating that money is generally used to buy the gear it contains, while the "Vanities" table might specify "prestige" instead, to indicate that the items within are generally bought with prestige.
|-
|autothing
|(Optional) Id – Specifies the unique id of the thing to be added to the table whenever the user wants to add a pick. Use this if only a single thing can ever be added to the table.
|-
|selectnone
|(Optional) Boolean – Indicates whether it's valid to have no selection in this chooser. Default: "no".
|-
|}

The "select" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#candidate|candidate]]
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the table.
|-
|[[#restriction|restriction]]
|An optional "restriction" element may appear as defined by the given link. This element defines a [[Restriction Tag Expression]] for the table that identifies things which cannot be selected if they've already been added to this table.
|-
|[[#needtag|needtag]]
|Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#denytag|denytag]]
|Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must '''not''' exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the table.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the table.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[IgnoreRequirements Element (Data)|ignorerequirements]]
|An optional "ignorerequirements" element may appear as defined by the given link. This element specifies circumstances under which pre-reqs for things and picks in this table are ignored.
|-
|[[#change|change]]
|An optional "change" element may appear as defined by the given link. This element defines a [[Change Script]] for the table.
|-
|}

==The "show" Child Element==

:{| class="infotable"
|class="leftnormal"|allowstack
|(Optional) Boolean – Indicates whether the user is allowed to stack items within the table, subject to the restrictions imposed for each item. Default: "yes".
|-
|agentlist
|(Optional) Id – If set to a tag group id, only picks with the agent pick's identity tag from that group are shown in the table. Default: None.
|-
|allowmove
|(Optional) Boolean – Indicates whether picks in this table can be moved out of this table, if the user drags them around. Default: "yes".
|-
|listpick
|(Optional) Id – Unique id of the pick to take the table's list expression from (see listfield, below). Note that this does not work when used with portals. Default: None.
|-
|listfield
|(Optional) Id – Unique id of the field to take the table's list expression from (see listpick, above). Note that this does not work when used with portals. Default: None.
|-
|}

The "show" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the table.
|-
|}

==The "list" Element{{anchor|list}}==

The "list" element defines a [[List Tag Expression]] for the table that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this table are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the List tag expression.
|-
|}

==The "candidate" Element{{anchor|candidate}}==

The "candidate" element defines a [[Candidate Tag Expression]] for the table that limits the set of things/picks that are available for selection. If this element is omitted entirely, then the items available for selection must satisfy the List tag expression instead (above). The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|inheritlist
|(Optional) Boolean – Indicates whether the List tag expression (above) is automatically inherited into the Candidate tag expression. If inherited, all available objects must satisfy both the Candidate tag expressions and the List tag expression. This eliminates the need to redundantly maintain the same filter logic within both tag expressions. If not inherited, then the Candidate tag expression supersedes the List tag expression. Default: "no".
|-
|PCDATA
|TagExpr – Specifies the code comprising the Candidate tag expression.
|-
|}

==The "restriction" Element{{anchor|restriction}}==

The "restriction" element defines a [[Restriction Tag Expression]] for the table that further limits the set of things/picks that are available for selection. This tag expression is compared against all picks that have already been added to '''this table'''. Any object that already exists within the table is precluded from being selected again, resulting in it being omitted from the list of available choices. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Restriction tag expression.
|-
|}

==The "needtag" Element{{anchor|needtag}}==

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "denytag" Element{{anchor|denytag}}==

The "denytag" element defines a tag relationship that must '''not''' exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the table. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the table. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "change" Element{{anchor|change}}==

The "change" element defines a [[Change Script]] for the table that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Change script.
|-
|}

TableAuto Element (Data)

2017-11-10T21:35:36Z

Colen:

{{context|Kit Reference|Data File Reference|Portal Element (Data)}}

==The "table_auto" Element==

Auto tables are a special kind of dynamic table that can only ever contain a single item. As such, an auto table looks like a dynamic table until the user clicks on the "add" item at the bottom. Instead of displaying a choose form, a new instance of a specific item is added to the table. This is extremely useful for tables of journal entries and character portraits. Each auto table is defined via the use of the "table_auto" element. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|component
|Id – Specifies the unique id of the component that all shown objects must be derived from.
|-
|usetabledef
|(Optional) Id – Specifies the [[TableDef Element (Data)|TableDef]] to reference for details of this table. Default: None.
|-
|autothing
|Id – Specifies the unique id of the thing to be added to the table whenever the user clicks on the "add" item at the bottom.
|-
|showtemplate
|Id – Specifies the unique id of the template to be used for displaying the picks that have been added to the table.
|-
|showsortset
|(Optional) Id – Specifies the unique id of the sort set to be used for sequencing the items that exist within the table. If empty, all objects are sorted by name. Default: Empty.
|-
|showgaphorz
|(Optional) Integer – Specifies the gap along the horizontal axis to insert between items that exist within the table. Default: "0".
|-
|showgapvert
|(Optional) Integer – Specifies the gap along the vertical axis to insert between items that exist within the table. Default: "0".
|-
|columns
|(Optional) Integer – Specifies the number of columns of data to display within the table. Default: "1".
|-
|scrollable
|(Optional) Boolean – Indicates whether the table contents can be scrolled by the user. By default, a scroller is shown whenever the number of items exceeds the visible space, but you can disable this behavior. Default: "yes".
|-
|addtemplate
|(Optional) Id – Specifies the unique id of the template to be used for the "add" item that always appears at the bottom of the table and that users will click on to add an item to the table. This allows detailed controlled when the simple "additem" script is not sufficient. If empty, the "additem" element must be specified. Default: Empty.
|-
|addpick
|(Optional) Id – Specifies the unique id of a thing that is associated with the "add" item at the bottom of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "addtemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
|-
|addspace
|(Optional) Integer – Specifies the additional vertical space to be inserted when displaying the simple "add" item at the bottom of the table by using the "additem" script. The height of the item is based on the font height of the text shown, so this attribute allows you to insert additional padding if you wish. Default: "2".
|-
|headertemplate
|(Optional) Id – Specifies the unique id of the template to be used for a header item that appears at the top of the table. This allows you to add column headers above various pieces of information in the table. If empty, the "headertitle" element dictates whether a header is displayed above the table. Default: Empty.
|-
|headerpick
|(Optional) Id – Specifies the unique id of a thing that is associated with the header item at the top of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "headertemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
|-
|showfrozenfixed
|(Optional) Boolean – Indicates whether the table must be converted to a "fixed" table whenever the table is designated as frozen. Default: "no".
|-
|allowuserorder
|(Optional) Boolean – Indicates whether the items in the table can be re-ordered by the user. If enabled, the specified component must designate a suitable ordering field or a separate component with such a field must be specified via the "ordercomponent" attribute. Default: "no". 
{{note}}Verify that whatever sort set you use for showing the items includes the designated ordering field as its first sort key.
|-
|ordercomponent
|(Optional) Id – Specifies the unique id of an alternate component that possesses a suitable ordering field. This attribute is only applicable when the table supports user ordering. If empty, the ordering field is dictated by the component associated with the table. Default: Empty.
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|alwaysupdate
|(Optional) Boolean – Indicates whether the table must be dynamically updated after any modification to the actor so that the influence of other changes are always visually reflected to the user. Default: "no". 
{{note}}This option can significantly slow down display updates on slower computers, so only enable this if truly necessary.
|-
|}

The "table_auto" element also possesses child elements that define additional behaviors of the portal. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the portal.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the portal.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the portal.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[#headertitle|headertitle]]
|An optional "headertitle" element may appear as defined by the given link. This element defines a [[HeaderTitle Script]] for the portal.
|-
|[[#additem|additem]]
|An optional "additem" element may appear as defined by the given link. This element defines a [[AddItem Script]] for the portal.
|-
|}

==The "list" Element{{anchor|list}}==

The "list" element defines a [[List Tag Expression]] for the portal that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this portal are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the List tag expression.
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the portal. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the portal. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "headertitle" Element{{anchor|headertitle}}==

The "headertitle" element defines a [[HeaderTitle Script]] for the portal that synthesizes the text to be displayed at the top of the table as a header. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the HeaderTitle script.
|-
|}

==The "additem" Element{{anchor|additem}}==

The "additem" element defines a [[AddItem Script]] for the portal that synthesizes the text to be displayed within the "add" item at the bottom of the table, where the user will click to add a new item. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the AddItem script.
|-
|}

==Example==

The following example demonstrates what an auto table portal might look like. All default values are assumed for optional attributes.

<pre>
<portal id="peImages" style="tblNormal">
<table_auto component="UserImage"
showtemplate="peImage" autothing="mscUserImg">
<headertitle>
@text = "Gallery"
</headertitle>
<additem>
@text = "Add Another Image"
</additem>
</table_auto>
</portal>
</pre>

TableFixed Element (Data)

2017-11-10T21:34:59Z

Colen: /* The "table_fixed" Element */

{{context|Kit Reference|Data File Reference|Portal Element (Data)}}

==The "table_fixed" Element==

Fixed tables present a list of items to the user that cannot be modified by the user through the table. This is ideal for displaying a list of character attributes or a summary of the special abilities possessed by a character. Since they cannot be modified, fixed tables have only a set of behaviors for showing the selected items to the user. Each fixed table is defined via the use of the "table_fixed" element. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|component
|Id – Specifies the unique id of the component that all shown objects must be derived from.
|-
|usetabledef
|(Optional) Id – Specifies the [[TableDef Element (Data)|TableDef]] to reference for details of this table. Default: None.
|-
|showtemplate
|Id – Specifies the unique id of the template to be used for displaying the picks that have been added to the table.
|-
|showpicks
|(Optional) Set – Designates the source from which the picks shown are retrieved from. Must be one of these values:
<ul class="sets">
<li>container – The picks shown are from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The picks shown are from the active actor.</li>
<li>actor – The picks shown represent all actors in the entire portfolio.</li>
<li>lead – The picks shown represent all lead actors in the entire portfolio.</li>
<li>minion – The picks shown are all immediate minions for the active actor.</li>
<li>Default: "container".</li>
</ul>
|-
|showsortset
|(Optional) Id – Specifies the unique id of the sort set to be used for sequencing the items that exist within the table. If empty, all objects are sorted by name. Default: Empty.
|-
|showgapx
|(Optional) Integer – Specifies the gap along the X-axis to insert between items that exist within the table. Default: "0".
|-
|showgapy
|(Optional) Integer – Specifies the gap along the Y-axis to insert between items that exist within the table. Default: "0".
|-
|columns
|(Optional) Integer – Specifies the number of columns of data to display within the table. Default: "1".
|-
|scrollable
|(Optional) Boolean – Indicates whether the table contents can be scrolled by the user. By default, a scroller is shown whenever the number of items exceeds the visible space, but you can disable this behavior. Default: "yes".
|-
|headertemplate
|(Optional) Id – Specifies the unique id of the template to be used for a header item that appears at the top of the table. This allows you to add column headers above various pieces of information in the table. If empty, the "headertitle" element dictates whether a header is displayed above the table. Default: Empty.
|-
|headerpick
|(Optional) Id – Specifies the unique id of a thing that is associated with the header item at the top of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "headertemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
|-
|footertemplate
|(Optional) Id – Specifies the unique id of the template to be used for a footer at the bottom of the table. This allows you to put information at the bottom of the table that is always tied to the table for sizing and positioning purposes. If empty, no footer is displayed for the table. Default: Empty.
|-
|showfixedlast
|(Optional) Boolean – Indicates whether all non-deletable picks within the table are sorted to the end of the list of picks shown. Default: "no".
|-
|allowuserorder
|(Optional) Boolean – Indicates whether the items in the table can be re-ordered by the user. If enabled, the specified component must designate a suitable ordering field or a separate component with such a field must be specified via the "ordercomponent" attribute. Default: "no". 
{{note}}Verify that whatever sort set you use for showing the items includes the designated ordering field as its first sort key.
|-
|ordercomponent
|(Optional) Id – Specifies the unique id of an alternate component that possesses a suitable ordering field. This attribute is only applicable when the table supports user ordering. If empty, the ordering field is dictated by the component associated with the table. Default: Empty.
|-
|alwaysupdate
|(Optional) Boolean – Indicates whether the table must be dynamically updated after any modification to the actor so that the influence of other changes are always visually reflected to the user. Default: "no". 
{{note}}This option can significantly slow down display updates on slower computers, so only enable this if truly necessary.
|-
|}

The "table_fixed" element also possesses child elements that define additional behaviors of the portal. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the portal.
|-
|[[#headertitle|headertitle]]
|An optional "headertitle" element may appear as defined by the given link. This element defines a [[HeaderTitle Script]] for the portal.
|-
|}

==The "list" Element{{anchor|list}}==

The "list" element defines a [[List Tag Expression]] for the portal that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this portal are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the List tag expression.
|-
|}

==The "headertitle" Element{{anchor|headertitle}}==

The "headertitle" element defines a [[HeaderTitle Script]] for the portal that synthesizes the text to be displayed at the top of the table as a header. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the HeaderTitle script.
|-
|}

==Example==

The following example demonstrates what a fixed table portal might look like. All default values are assumed for optional attributes.

<pre>
<portal id="baAttrib" style="tblInvis">
<table_fixed component="Attribute" scrollable="no"
showtemplate="baAttrPick" showsortset="explicit">
<headertitle>
@text = "Attributes"
</headertitle>
</table_fixed>
</portal>
</pre>

ChooserTable Element (Data)

2017-11-10T21:34:40Z

Colen: /* The "chooser_table" Element */

{{context|Kit Reference|Data File Reference|Portal Element (Data)}}

==The "chooser_table" Element==

Choosers are similar to thing-based menus in some ways, as they allow the user to select one thing or pick from a list that is determined dynamically. One key difference with choosers is that any selected thing/pick is added to the container as a new pick. If a pick is selected, a new pick derived from the same thing is added. Another key difference is that the available things/picks are displayed for selection in a "choose form", allowing each object to be presented with detailed information. The "chooser" mechanism is ideal for selecting facets like race, profession, archetype, etc. Each chooser is defined via the use of the "chooser_table" element. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|component
|Id – Specifies the unique id of the component that all selectable objects must be derived from.
|-
|usetabledef
|(Optional) Id – Specifies the [[TableDef Element (Data)|TableDef]] to reference for the selection details of this chooser. Default: None.
|-
|choosetemplate
|Id – Specifies the unique id of the template to be used for displaying selectable objects.
|-
|choosepicks
|(Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
<ul class="sets">
<li>thing – The selectable objects are things.</li>
<li>container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The selectable objects are picks from the active actor.</li>
<li>actor – Same as "hero".</li>
<li>Default: "thing".</li>
|-
|choosesortset
|(Optional) Id – Specifies the unique id of the sort set to be used for sequencing all of the objects presented for selection. If empty, all objects are sorted by name. Default: Empty.
|-
|choosegapx
|(Optional) Integer – Specifies the gap along the X-axis to insert between items presented for selection. Default: "0".
|-
|choosegapy
|(Optional) Integer – Specifies the gap along the Y-axis to insert between items presented for selection. Default: "0".
|-
|descwidth
|(Optional) Integer – Specifies the width of the reserved "description" area on the right within the choose form. Some items need more width for lengthy descriptions and some do not, so you can control this as you see fit. Default: "250".
|-
|buytemplate
|(Optional) Id – Specifies the unique id of the template to be shown in the lower right corner of the choose form for controlling the details of a purchase transaction. If empty, no buy template is utilized. Default: Empty.
|-
|xactspecial
|(Optional) Integer – When a buy template is shared between two or more portals or things, the template behavior may need to be tailored based on the usage. If this need arises, this attribute specifies a unique value that identifies this particular usage. By assigning a different value to each usage and keying on it within the template's Position script, you can tailor the template appropriately. Default: "0".
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added via the chooser, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|showupdate
|(Optional) Boolean – Indicates whether the chooser needs to be dynamically updated after any modification to the actor so that the influence of other changes are always visually reflected to the user, such as through color highlighting. Default: "no". 
{{note}}This option can significantly slow down display updates on slower computers, so only enable this if truly necessary.
|-
|candidatepick
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|Candidate tag expression]] for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|candidatefield
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|prereqtarget
|(Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
<ul class="sets">
<li>container – The default parent container is used.</li>
<li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li>
<li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li>
<li>Default: "container".</li>
</ul>
|-
|empty
|(Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
|-
|showlabel
|(Optional) Boolean – (iPad only) Indicates whether the label displaying the current selection of the menu should be shown. This is used when you just want the menu control to be used as a button to make a selection which will be displayed some other way. Default: "yes".
|-
|}

{{note}}Choosers possess a "buy" template, but there is no way to properly "sell" an item selected via a chooser. The reason for this is to allow the "buy" template to be used for customization purposes instead of actually buying and selling gear. The same mechanism can be used to allow the user to configure the item selected via the chooser, such as providing an edit or menu portal to specify an important facet of the selected item.

The "chooser_table" element also possesses child elements that define additional behaviors of the portal. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#candidate|candidate]]
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the portal.
|-
|[[#needtag|needtag]]
|Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#denytag|denytag]]
|Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must '''not''' exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#xacttag|xacttag]]
|Zero or more "xacttag" elements may appear as defined by the given link. This element defines a tag that is assigned to the transaction pick while the choose form is visible.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the portal.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the portal.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[#chosen|chosen]]
|An optional "chosen" element may appear as defined by the given link. This element defines a [[Chosen Script]] for the portal.
|-
|[[#titlebar|titlebar]]
|An optional "titlebar" element may appear as defined by the given link. This element defines a [[TitleBar Script]] for the portal.
|-
|[[#description|description]]
|An optional "description" element may appear as defined by the given link. This element defines a [[Description Script]] for the portal.
|-
|[[#change|change]]
|An optional "change" element may appear as defined by the given link. This element defines a [[Change Script]] for the portal.
|-
|}

==The "candidate" Element{{anchor|candidate}}==

The "candidate" element defines a [[Candidate Tag Expression]] for the portal that limits the set of things/picks that are available for selection. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Candidate tag expression.
|-
|}

==The "needtag" Element{{anchor|needtag}}==

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "denytag" Element{{anchor|denytag}}==

The "denytag" element defines a tag relationship that must '''not''' exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "xacttag" Element{{anchor|xacttag}}==

The "xacttag" element specifies a tag that is automatically added to the transaction pick while the choose form is shown. These tags allow you to indicate contextual information about where the buy template is being used so that you can tailor the behavior appropriately. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|tag
|Id – Specifies the unique id of the tag to define within the tag group "transact".
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the portal. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the portal. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "chosen" Element{{anchor|chosen}}==

The "chosen" element defines a [[Chosen Script]] for the portal, which synthesizes the text to be displayed as the chosen item within the portal. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Chosen script.
|-
|}

==The "titlebar" Element{{anchor|titlebar}}==

The "titlebar" element defines a [[TitleBar Script]] for the portal, which synthesizes the text to be displayed at the top of the choose form. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the TitleBar script.
|-
|}

==The "description" Element{{anchor|description}}==

The "description" element defines a [[Description Script]] for the portal, which synthesizes the text to be displayed within the description region of the choose form for the currently selected item on the left. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Description script.
|-
|}

==The "change" Element{{anchor|change}}==

The "change" element defines a [[Change Script]] for the portal that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Change script.
|-
|}

==Example==

The following example demonstrates what a choosertable portal might look like. All default values are assumed for optional attributes.

<pre>
<portal id="stRace" style="chsNormal" width="110">
<chooser_table component="Race" choosetemplate="LargeItem">
<chosen><![CDATA[
if (@ispick = 0) then
@text = "{text ff0000}Select Race"
else
@text = "Race: " & field[name].text
endif
]]></chosen>
<titlebar>
@text = "Choose the race for your character"
</titlebar>
</chooser_table>
</portal>
</pre>

TableFixed Element (Data)

2017-11-10T21:34:11Z

Colen:

{{context|Kit Reference|Data File Reference|Portal Element (Data)}}

==The "table_fixed" Element==

Fixed tables present a list of items to the user that cannot be modified by the user through the table. This is ideal for displaying a list of character attributes or a summary of the special abilities possessed by a character. Since they cannot be modified, fixed tables have only a set of behaviors for showing the selected items to the user. Each fixed table is defined via the use of the "table_fixed" element. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|component
|Id – Specifies the unique id of the component that all shown objects must be derived from.
|-
|usetabledef
|(Optional) Id – Specifies the [[TableDef Element (Data)|TableDef]] to reference for selection details of this table. Default: None.
|-
|showtemplate
|Id – Specifies the unique id of the template to be used for displaying the picks that have been added to the table.
|-
|showpicks
|(Optional) Set – Designates the source from which the picks shown are retrieved from. Must be one of these values:
<ul class="sets">
<li>container – The picks shown are from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The picks shown are from the active actor.</li>
<li>actor – The picks shown represent all actors in the entire portfolio.</li>
<li>lead – The picks shown represent all lead actors in the entire portfolio.</li>
<li>minion – The picks shown are all immediate minions for the active actor.</li>
<li>Default: "container".</li>
</ul>
|-
|showsortset
|(Optional) Id – Specifies the unique id of the sort set to be used for sequencing the items that exist within the table. If empty, all objects are sorted by name. Default: Empty.
|-
|showgapx
|(Optional) Integer – Specifies the gap along the X-axis to insert between items that exist within the table. Default: "0".
|-
|showgapy
|(Optional) Integer – Specifies the gap along the Y-axis to insert between items that exist within the table. Default: "0".
|-
|columns
|(Optional) Integer – Specifies the number of columns of data to display within the table. Default: "1".
|-
|scrollable
|(Optional) Boolean – Indicates whether the table contents can be scrolled by the user. By default, a scroller is shown whenever the number of items exceeds the visible space, but you can disable this behavior. Default: "yes".
|-
|headertemplate
|(Optional) Id – Specifies the unique id of the template to be used for a header item that appears at the top of the table. This allows you to add column headers above various pieces of information in the table. If empty, the "headertitle" element dictates whether a header is displayed above the table. Default: Empty.
|-
|headerpick
|(Optional) Id – Specifies the unique id of a thing that is associated with the header item at the top of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "headertemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
|-
|footertemplate
|(Optional) Id – Specifies the unique id of the template to be used for a footer at the bottom of the table. This allows you to put information at the bottom of the table that is always tied to the table for sizing and positioning purposes. If empty, no footer is displayed for the table. Default: Empty.
|-
|showfixedlast
|(Optional) Boolean – Indicates whether all non-deletable picks within the table are sorted to the end of the list of picks shown. Default: "no".
|-
|allowuserorder
|(Optional) Boolean – Indicates whether the items in the table can be re-ordered by the user. If enabled, the specified component must designate a suitable ordering field or a separate component with such a field must be specified via the "ordercomponent" attribute. Default: "no". 
{{note}}Verify that whatever sort set you use for showing the items includes the designated ordering field as its first sort key.
|-
|ordercomponent
|(Optional) Id – Specifies the unique id of an alternate component that possesses a suitable ordering field. This attribute is only applicable when the table supports user ordering. If empty, the ordering field is dictated by the component associated with the table. Default: Empty.
|-
|alwaysupdate
|(Optional) Boolean – Indicates whether the table must be dynamically updated after any modification to the actor so that the influence of other changes are always visually reflected to the user. Default: "no". 
{{note}}This option can significantly slow down display updates on slower computers, so only enable this if truly necessary.
|-
|}

The "table_fixed" element also possesses child elements that define additional behaviors of the portal. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the portal.
|-
|[[#headertitle|headertitle]]
|An optional "headertitle" element may appear as defined by the given link. This element defines a [[HeaderTitle Script]] for the portal.
|-
|}

==The "list" Element{{anchor|list}}==

The "list" element defines a [[List Tag Expression]] for the portal that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this portal are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the List tag expression.
|-
|}

==The "headertitle" Element{{anchor|headertitle}}==

The "headertitle" element defines a [[HeaderTitle Script]] for the portal that synthesizes the text to be displayed at the top of the table as a header. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the HeaderTitle script.
|-
|}

==Example==

The following example demonstrates what a fixed table portal might look like. All default values are assumed for optional attributes.

<pre>
<portal id="baAttrib" style="tblInvis">
<table_fixed component="Attribute" scrollable="no"
showtemplate="baAttrPick" showsortset="explicit">
<headertitle>
@text = "Attributes"
</headertitle>
</table_fixed>
</portal>
</pre>

TableFixed Element (Data)

2017-11-10T21:33:56Z

Colen:

{{context|Kit Reference|Data File Reference|Portal Element (Data)}}

==The "table_fixed" Element==

Fixed tables present a list of items to the user that cannot be modified by the user through the table. This is ideal for displaying a list of character attributes or a summary of the special abilities possessed by a character. Since they cannot be modified, fixed tables have only a set of behaviors for showing the selected items to the user. Each fixed table is defined via the use of the "table_fixed" element. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|component
|Id – Specifies the unique id of the component that all shown objects must be derived from.
|-
|usetabledef
|(Optional) Id – Specifies the [[TableDef Element (Data)|TableDef]] to reference for selection details of this chooser. Default: None.
|-
|showtemplate
|Id – Specifies the unique id of the template to be used for displaying the picks that have been added to the table.
|-
|showpicks
|(Optional) Set – Designates the source from which the picks shown are retrieved from. Must be one of these values:
<ul class="sets">
<li>container – The picks shown are from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The picks shown are from the active actor.</li>
<li>actor – The picks shown represent all actors in the entire portfolio.</li>
<li>lead – The picks shown represent all lead actors in the entire portfolio.</li>
<li>minion – The picks shown are all immediate minions for the active actor.</li>
<li>Default: "container".</li>
</ul>
|-
|showsortset
|(Optional) Id – Specifies the unique id of the sort set to be used for sequencing the items that exist within the table. If empty, all objects are sorted by name. Default: Empty.
|-
|showgapx
|(Optional) Integer – Specifies the gap along the X-axis to insert between items that exist within the table. Default: "0".
|-
|showgapy
|(Optional) Integer – Specifies the gap along the Y-axis to insert between items that exist within the table. Default: "0".
|-
|columns
|(Optional) Integer – Specifies the number of columns of data to display within the table. Default: "1".
|-
|scrollable
|(Optional) Boolean – Indicates whether the table contents can be scrolled by the user. By default, a scroller is shown whenever the number of items exceeds the visible space, but you can disable this behavior. Default: "yes".
|-
|headertemplate
|(Optional) Id – Specifies the unique id of the template to be used for a header item that appears at the top of the table. This allows you to add column headers above various pieces of information in the table. If empty, the "headertitle" element dictates whether a header is displayed above the table. Default: Empty.
|-
|headerpick
|(Optional) Id – Specifies the unique id of a thing that is associated with the header item at the top of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "headertemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
|-
|footertemplate
|(Optional) Id – Specifies the unique id of the template to be used for a footer at the bottom of the table. This allows you to put information at the bottom of the table that is always tied to the table for sizing and positioning purposes. If empty, no footer is displayed for the table. Default: Empty.
|-
|showfixedlast
|(Optional) Boolean – Indicates whether all non-deletable picks within the table are sorted to the end of the list of picks shown. Default: "no".
|-
|allowuserorder
|(Optional) Boolean – Indicates whether the items in the table can be re-ordered by the user. If enabled, the specified component must designate a suitable ordering field or a separate component with such a field must be specified via the "ordercomponent" attribute. Default: "no". 
{{note}}Verify that whatever sort set you use for showing the items includes the designated ordering field as its first sort key.
|-
|ordercomponent
|(Optional) Id – Specifies the unique id of an alternate component that possesses a suitable ordering field. This attribute is only applicable when the table supports user ordering. If empty, the ordering field is dictated by the component associated with the table. Default: Empty.
|-
|alwaysupdate
|(Optional) Boolean – Indicates whether the table must be dynamically updated after any modification to the actor so that the influence of other changes are always visually reflected to the user. Default: "no". 
{{note}}This option can significantly slow down display updates on slower computers, so only enable this if truly necessary.
|-
|}

The "table_fixed" element also possesses child elements that define additional behaviors of the portal. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the portal.
|-
|[[#headertitle|headertitle]]
|An optional "headertitle" element may appear as defined by the given link. This element defines a [[HeaderTitle Script]] for the portal.
|-
|}

==The "list" Element{{anchor|list}}==

The "list" element defines a [[List Tag Expression]] for the portal that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this portal are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the List tag expression.
|-
|}

==The "headertitle" Element{{anchor|headertitle}}==

The "headertitle" element defines a [[HeaderTitle Script]] for the portal that synthesizes the text to be displayed at the top of the table as a header. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the HeaderTitle script.
|-
|}

==Example==

The following example demonstrates what a fixed table portal might look like. All default values are assumed for optional attributes.

<pre>
<portal id="baAttrib" style="tblInvis">
<table_fixed component="Attribute" scrollable="no"
showtemplate="baAttrPick" showsortset="explicit">
<headertitle>
@text = "Attributes"
</headertitle>
</table_fixed>
</portal>
</pre>

TableDynamic Element (Data)

2017-11-10T21:33:30Z

Colen: /* The "table_dynamic" Element */

{{context|Kit Reference|Data File Reference|Portal Element (Data)}}

==The "table_dynamic" Element==

Dynamic tables allow the user to select the items to be added to the table. As such, they effectively have one set of behaviors for showing the selected items and a separate set of behaviors for selecting the items. A choose form is used to present the list of available items for selection, which allows for detailed information to be shown for each item. When things are added to a table, a new pick is added to the container that is derived from the selected thing. Each dynamic table is defined via the use of the "table_dynamic" element. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|component
|Id – Specifies the unique id of the component that all objects must be derived from, both selectable and shown within the table.
|-
|usetabledef
|(Optional) Id – Specifies the [[TableDef Element (Data)|TableDef]] to reference for details of this table. Default: None.
|-
|showtemplate
|Id – Specifies the unique id of the template to be used for displaying the picks that have been added to the table.
|-
|showsortset
|(Optional) Id – Specifies the unique id of the sort set to be used for sequencing the items that exist within the table. If empty, all objects are sorted by name. Default: Empty.
|-
|showgapx
|(Optional) Integer – Specifies the gap along the X-axis to insert between items that exist within the table. Default: "0".
|-
|showgapy
|(Optional) Integer – Specifies the gap along the Y-axis to insert between items that exist within the table. Default: "0".
|-
|choosetemplate
|Id – Specifies the unique id of the template to be used for displaying available objects that the user can choose from.
|-
|choosepicks
|(Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
<ul class="sets">
<li>thing – The selectable objects are things.</li>
<li>container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The selectable objects are picks from the active actor.</li>
<li>Default: "thing".</li>
</ul>
|-
|choosesortset
|(Optional) Id – Specifies the unique id of the sort set to be used for sequencing all of the objects presented for selection. If empty, all objects are sorted by name. Default: Empty.
|-
|choosegapx
|(Optional) Integer – Specifies the gap along the X-axis to insert between items presented for selection. Default: "0".
|-
|choosegapy
|(Optional) Integer – Specifies the gap along the Y-axis to insert between items presented for selection. Default: "0".
|-
|descwidth
|(Optional) Integer – Specifies the width of the reserved "description" area on the right within the choose form. Some items need more width for lengthy descriptions and some do not, so you can control this as you see fit. Default: "250".
|-
|columns
|(Optional) Integer – Specifies the number of columns of data to display within the table. Default: "1".
|-
|scrollable
|(Optional) Boolean – Indicates whether the table contents can be scrolled by the user. By default, a scroller is shown whenever the number of items exceeds the visible space, but you can disable this behavior. Default: "yes".
|-
|ismultiadd
|(Optional) Boolean – Indicates whether the user can add multiple items at a time to the table, without leaving the choose form. Default: "yes".
|-
|allowstack
|(Optional) Boolean – Indicates whether the user is allowed to stack items within the table, subject to the restrictions imposed for each item. Default: "yes".
|-
|addtemplate
|(Optional) Id – Specifies the unique id of the template to be used for the "add" item that always appears at the bottom of a dynamic table and that users will click on to add an item to the table. This allows detailed controlled when the simple "additem" script is not sufficient. If empty, the "additem" element must be specified. Default: Empty.
|-
|addpick
|(Optional) Id – Specifies the unique id of a thing that is associated with the "add" item at the bottom of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "addtemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
|-
|addspace
|(Optional) Integer – Specifies the additional vertical space to be inserted when displaying the simple "add" item at the bottom of the table by using the "additem" script. The height of the item is based on the font height of the text shown, so this attribute allows you to insert additional padding if you wish. Default: "2".
|-
|headertemplate
|(Optional) Id – Specifies the unique id of the template to be used for a header item that appears at the top of the table. This allows you to add column headers above various pieces of information in the table. If empty, the "headertitle" element dictates whether a header is displayed above the table. Default: Empty.
|-
|headerpick
|(Optional) Id – Specifies the unique id of a thing that is associated with the header item at the top of the table. HL will retrieve any pick based on this thing that exists within the target container and use it. This allows you to control what fields can be accessed from the "headertemplate". If empty, the "actor" pick is used, except within a gizmo, where its "defaultthing" is used instead. Default: Empty.
|-
|buytemplate
|(Optional) Id – Specifies the unique id of the template to be shown in the lower right corner of the choose form for controlling the details of a purchase transaction. If empty, no buy template is utilized. Default: Empty.
|-
|xactspecial
|(Optional) Integer – When a buy template is shared between two or more portals or things, the template behavior may need to be tailored based on the usage. If this need arises, this attribute specifies a unique value that identifies this particular usage. By assigning a different value to each usage and keying on it within the template's Position script, you can tailor the template appropriately. Default: "0".
|-
|selltemplate
|(Optional) Id – Specifies the unique id of the template to be shown when the user attempts to delete an item. This allows you to enable the selling of items for money. If empty, no sell template is utilized. Default: Empty.
|-
|candidatepick
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|Candidate tag expression]] for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|candidatefield
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|prereqtarget
|(Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
<ul class="sets">
<li>container – The default parent container is used.</li>
<li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li>
<li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li>
<li>Default: "container".</li>
</ul>
|-
|empty
|(Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
|-
|showfrozenfixed
|(Optional) Boolean – Indicates whether the table must be converted to a "fixed" table whenever the table is designated as frozen. Default: "no".
|-
|showfixedlast
|(Optional) Boolean – Indicates whether all non-deletable picks within the table are sorted to the end of the list of picks shown. Default: "no".
|-
|allowuserorder
|(Optional) Boolean – Indicates whether the items in the table can be re-ordered by the user. If enabled, the specified component must designate a suitable ordering field or a separate component with such a field must be specified via the "ordercomponent" attribute. Default: "no". 
{{note}}Verify that whatever sort set you use for showing the items includes the designated ordering field as its first sort key.
|-
|ordercomponent
|(Optional) Id – Specifies the unique id of an alternate component that possesses a suitable ordering field. This attribute is only applicable when the table supports user ordering. If empty, the ordering field is dictated by the component associated with the table. Default: Empty.
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|alwaysupdate
|(Optional) Boolean – Indicates whether the table must be dynamically updated after any modification to the actor so that the influence of other changes are always visually reflected to the user. Default: "no". 
{{note}}This option can significantly slow down display updates on slower computers, so only enable this if truly necessary.
|-
|}

The "table_dynamic" element also possesses child elements that define additional behaviors of the portal. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the portal.
|-
|[[#candidate|candidate]]
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the portal.
|-
|[[#restriction|restriction]]
|An optional "restriction" element may appear as defined by the given link. This element defines a [[Restriction Tag Expression]] for the portal that identifies things which cannot be selected if they've already been added to this table.
|-
|[[#needtag|needtag]]
|Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#denytag|denytag]]
|Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must '''not''' exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#xacttag|xacttag]]
|Zero or more "xacttag" elements may appear as defined by the given link. This element defines a tag that is assigned to the transaction pick while the choose form is visible.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the portal.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the portal.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[#chosen|chosen]]
|An optional "chosen" element may appear as defined by the given link. This element defines a [[Chosen Script]] for the portal.
|-
|[[#titlebar|titlebar]]
|An optional "titlebar" element may appear as defined by the given link. This element defines a [[TitleBar Script]] for the portal.
|-
|[[#description|description]]
|An optional "description" element may appear as defined by the given link. This element defines a [[Description Script]] for the portal.
|-
|[[#headertitle|headertitle]]
|An optional "headertitle" element may appear as defined by the given link. This element defines a [[HeaderTitle Script]] for the portal.
|-
|[[#additem|additem]]
|An optional "additem" element may appear as defined by the given link. This element defines a [[AddItem Script]] for the portal.
|-
|}

==The "list" Element{{anchor|list}}==

The "list" element defines a [[List Tag Expression]] for the portal that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this portal are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the List tag expression.
|-
|}

==The "candidate" Element{{anchor|candidate}}==

The "candidate" element defines a [[Candidate Tag Expression]] for the portal that limits the set of things/picks that are available for selection. If this element is omitted entirely, then the items available for selection must satisfy the List tag expression instead (above). The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|inheritlist
|(Optional) Boolean – Indicates whether the List tag expression (above) is automatically inherited into the Candidate tag expression. If inherited, all available objects must satisfy both the Candidate tag expressions and the List tag expression. This eliminates the need to redundantly maintain the same filter logic within both tag expressions. If not inherited, then the Candidate tag expression supersedes the List tag expression. Default: "no".
|-
|PCDATA
|TagExpr – Specifies the code comprising the Candidate tag expression.
|-
|}

==The "restriction" Element{{anchor|restriction}}==

The "restriction" element defines a [[Restriction Tag Expression]] for the portal that further limits the set of things/picks that are available for selection. This tag expression is compared against all picks that have already been added to '''this table'''. Any object that already exists within the table is precluded from being selected again, resulting in it being omitted from the list of available choices. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Restriction tag expression.
|-
|}

==The "needtag" Element{{anchor|needtag}}==

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "denytag" Element{{anchor|denytag}}==

The "denytag" element defines a tag relationship that must '''not''' exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "xacttag" Element{{anchor|xacttag}}==

The "xacttag" element specifies a tag that is automatically added to the transaction pick while the choose form is shown. These tags allow you to indicate contextual information about where the buy template is being used so that you can tailor the behavior appropriately. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|tag
|Id – Specifies the unique id of the tag to define within the tag group "transact".
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the portal. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the portal. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "chosen" Element{{anchor|chosen}}==

The "chosen" element defines a [[Chosen Script]] for the portal, which synthesizes the text to be displayed as the chosen item within the portal. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Chosen script.
|-
|}

==The "titlebar" Element{{anchor|titlebar}}==

The "titlebar" element defines a [[TitleBar Script]] for the portal, which synthesizes the text to be displayed at the top of the choose form. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the TitleBar script.
|-
|}

==The "description" Element{{anchor|description}}==

The "description" element defines a [[Description Script]] for the portal, which synthesizes the text to be displayed within the description region of the choose form for the currently selected item on the left. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Description script.
|-
|}

==The "headertitle" Element{{anchor|headertitle}}==

The "headertitle" element defines a [[HeaderTitle Script]] for the portal that synthesizes the text to be displayed at the top of the table as a header. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the HeaderTitle script.
|-
|}

==The "additem" Element{{anchor|additem}}==

The "additem" element defines a [[AddItem Script]] for the portal that synthesizes the text to be displayed within the "add" item at the bottom of the table, where the user will click to add a new item. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the AddItem script.
|-
|}

==Example==

The following example demonstrates what a dynamic table portal might look like. All default values are assumed for optional attributes.

<pre>
<portal id="arMelee" style="tblNormal">
<table_dynamic component="Gear"
showtemplate="arWpnPick" choosetemplate="arWpnThing"
buytemplate="BuyCash" selltemplate="SellCash">
<list>component.WeapMelee</list>
<candidate>!Equipment.Natural</candidate>
<description/>
<headertitle>
@text = "Melee Weapons"
</headertitle>
<additem>
@text = "Add New Melee Weapons"
</additem>
</table_dynamic>
</portal>
</pre>

TableDef Element (Data)

2017-11-10T21:32:15Z

Colen:

{{context|Kit Reference|Data File Reference}}

==The "tabledef" Element==

Note that for a tabledef to be associated with a table or chooser portal, you must specify the id of the tabledef for the portal's "usetabledef" attribute.

:{| class="infotable"
|class="leftnormal"|id
|Id – Specifies the unique id of the tabledef.
|-
|component
|Id – Specifies the unique id of the component the tabledef is associated with. Like a table portal, only things / picks from this component will be shown in the table.
|-
|isglobal
|(Optional) Boolean – if the table is used by ALL characters for the game system, specify "yes". If this is specified, you don't need to add "allowtable" tags for this table, as it's assumed to be present on all characters. This is unlikely to be true for game systems with multiple different types of characters, like Pathfinder (NPCs, kingdoms, armies, etc), so don't specify this unless every single character for the game system will need it. Default: "no".
|-
|description
|Text – A short string intended to communicate what the table does (in very general terms, like "Adds magic weapons") to the UI developers.
|-
|errorcategory
|(Optional) Unique id – indicates that this table is only marked as invalid if picks showing in it have an error of this category. If this attribute isn't set, the table will be marked as invalid if any pick in the table has an error.
|-
|}

The "tabledef" element also possesses two child elements that define the specifics of the table. Both of these child elements are optional.

:{| class="infotable"
|class="leftnormal"|select
|Contains details about the selection of new picks for this table. If the table can't select new picks (for example, if it's a fixed table), this should be omitted.
|-
|show
|Contains details about the picks shown in this table. Can be omitted if nothing interesting needs to be specified (for example, if the table has no list expression).
|-
|-
|}

==The "select" Child Element==

:{| class="infotable"
|class="leftnormal"|choosepicks
|(Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
<ul class="sets">
<li>thing – The selectable objects are things.</li>
<li>container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The selectable objects are picks from the active actor.</li>
<li>Default: "thing".</li>
</ul>
|-
|buyaction
|(Optional) Id – indicates the id of the action for the new UI to use when purchasing items from this table. Default: Empty.
|-
|sellaction
|(Optional) Id – indicates the id of the action for the new UI to use when selling items from this table. Default: Empty.
|-
|wrapupaction
|(Optional) Id – indicates the id of the action for the new UI to use after adding items from this table. Default: Empty.
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|candidatepick
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|Candidate tag expression]] for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|candidatefield
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|secondphase
|(Optional) Id – Specifies the phase of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Empty.
|-
|secondprior
|(Optional) Number – Specifies the priority of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|existphase
|(Optional) Id – Specifies the phase of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Empty.
|-
|existprior
|(Optional) Number – Specifies the priority of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|prereqtarget
|(Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
<ul class="sets">
<li>container – The default parent container is used.</li>
<li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li>
<li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li>
<li>Default: "container".</li>
</ul>
|-
|empty
|(Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
|-
|useagentcandidate
|(Optional) Boolean – Indicates whether the agent pick should be used for the candidatepick of this table. Default: "no".
|-
|useagentlinkage
|(Optional) Boolean – Indicates whether the agent pick should be used for the linkage of this table. Default: "no".
|-
|agentautotag
|(Optional) Id – Specifies the tag group of the agent pick's identity tag which will be added to picks added to this table. Default: None.
|-
|maxchoicelimit
|(Optional) Number – How many picks can be added to this table. Default: no limit.
|-
|transactiontype
|Text – a short string, typically a single word, intended to communicate what sort of "purchase" the table typically makes. For example, any table in Pathfinder that allows you to buy gear might specify "money" for this attribute, indicating that money is generally used to buy the gear it contains, while the "Vanities" table might specify "prestige" instead, to indicate that the items within are generally bought with prestige.
|-
|autothing
|(Optional) Id – Specifies the unique id of the thing to be added to the table whenever the user wants to add a pick. Use this if only a single thing can ever be added to the table.
|-
|selectnone
|(Optional) Boolean – Indicates whether it's valid to have no selection in this chooser. Default: "no".
|-
|}

The "select" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#candidate|candidate]]
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the table.
|-
|[[#restriction|restriction]]
|An optional "restriction" element may appear as defined by the given link. This element defines a [[Restriction Tag Expression]] for the table that identifies things which cannot be selected if they've already been added to this table.
|-
|[[#needtag|needtag]]
|Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#denytag|denytag]]
|Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must '''not''' exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the table.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the table.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[IgnoreRequirements Element (Data)|ignorerequirements]]
|An optional "ignorerequirements" element may appear as defined by the given link. This element specifies circumstances under which pre-reqs for things and picks in this table are ignored.
|-
|[[#change|change]]
|An optional "change" element may appear as defined by the given link. This element defines a [[Change Script]] for the table.
|-
|}

==The "show" Child Element==

:{| class="infotable"
|class="leftnormal"|allowstack
|(Optional) Boolean – Indicates whether the user is allowed to stack items within the table, subject to the restrictions imposed for each item. Default: "yes".
|-
|agentlist
|(Optional) Id – If set to a tag group id, only picks with the agent pick's identity tag from that group are shown in the table. Default: None.
|-
|allowmove
|(Optional) Boolean – Indicates whether picks in this table can be moved out of this table, if the user drags them around. Default: "yes".
|-
|listpick
|(Optional) Id – Unique id of the pick to take the table's list expression from (see listfield, below). Note that this does not work when used with portals. Default: None.
|-
|listfield
|(Optional) Id – Unique id of the field to take the table's list expression from (see listpick, above). Note that this does not work when used with portals. Default: None.
|-
|}

The "show" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the table.
|-
|}

==The "list" Element{{anchor|list}}==

The "list" element defines a [[List Tag Expression]] for the table that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this table are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the List tag expression.
|-
|}

==The "candidate" Element{{anchor|candidate}}==

The "candidate" element defines a [[Candidate Tag Expression]] for the table that limits the set of things/picks that are available for selection. If this element is omitted entirely, then the items available for selection must satisfy the List tag expression instead (above). The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|inheritlist
|(Optional) Boolean – Indicates whether the List tag expression (above) is automatically inherited into the Candidate tag expression. If inherited, all available objects must satisfy both the Candidate tag expressions and the List tag expression. This eliminates the need to redundantly maintain the same filter logic within both tag expressions. If not inherited, then the Candidate tag expression supersedes the List tag expression. Default: "no".
|-
|PCDATA
|TagExpr – Specifies the code comprising the Candidate tag expression.
|-
|}

==The "restriction" Element{{anchor|restriction}}==

The "restriction" element defines a [[Restriction Tag Expression]] for the table that further limits the set of things/picks that are available for selection. This tag expression is compared against all picks that have already been added to '''this table'''. Any object that already exists within the table is precluded from being selected again, resulting in it being omitted from the list of available choices. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Restriction tag expression.
|-
|}

==The "needtag" Element{{anchor|needtag}}==

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "denytag" Element{{anchor|denytag}}==

The "denytag" element defines a tag relationship that must '''not''' exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the table. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the table. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "change" Element{{anchor|change}}==

The "change" element defines a [[Change Script]] for the table that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Change script.
|-
|}

TableDef Element (Data)

2017-11-10T21:22:02Z

Colen:

{{context|Kit Reference|Data File Reference}}

==The "tabledef" Element==

:{| class="infotable"
|class="leftnormal"|id
|Id – Specifies the unique id of the tabledef.
|-
|component
|Id – Specifies the unique id of the component the tabledef is associated with. Like a table portal, only things / picks from this component will be shown in the table.
|-
|isglobal
|(Optional) Boolean – if the table is used by ALL characters for the game system, specify "yes". If this is specified, you don't need to add "allowtable" tags for this table, as it's assumed to be present on all characters. This is unlikely to be true for game systems with multiple different types of characters, like Pathfinder (NPCs, kingdoms, armies, etc), so don't specify this unless every single character for the game system will need it. Default: "no".
|-
|description
|Text – A short string intended to communicate what the table does (in very general terms, like "Adds magic weapons") to the UI developers.
|-
|errorcategory
|(Optional) Unique id – indicates that this table is only marked as invalid if picks showing in it have an error of this category. If this attribute isn't set, the table will be marked as invalid if any pick in the table has an error.
|-
|}

The "tabledef" element also possesses two child elements that define the specifics of the table. Both of these child elements are optional.

:{| class="infotable"
|class="leftnormal"|select
|Contains details about the selection of new picks for this table. If the table can't select new picks (for example, if it's a fixed table), this should be omitted.
|-
|show
|Contains details about the picks shown in this table. Can be omitted if nothing interesting needs to be specified (for example, if the table has no list expression).
|-
|-
|}

==The "select" Child Element==

:{| class="infotable"
|class="leftnormal"|choosepicks
|(Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
<ul class="sets">
<li>thing – The selectable objects are things.</li>
<li>container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The selectable objects are picks from the active actor.</li>
<li>Default: "thing".</li>
</ul>
|-
|buyaction
|(Optional) Id – indicates the id of the action for the new UI to use when purchasing items from this table. Default: Empty.
|-
|sellaction
|(Optional) Id – indicates the id of the action for the new UI to use when selling items from this table. Default: Empty.
|-
|wrapupaction
|(Optional) Id – indicates the id of the action for the new UI to use after adding items from this table. Default: Empty.
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|candidatepick
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|Candidate tag expression]] for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|candidatefield
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|secondphase
|(Optional) Id – Specifies the phase of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Empty.
|-
|secondprior
|(Optional) Number – Specifies the priority of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|existphase
|(Optional) Id – Specifies the phase of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Empty.
|-
|existprior
|(Optional) Number – Specifies the priority of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|prereqtarget
|(Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
<ul class="sets">
<li>container – The default parent container is used.</li>
<li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li>
<li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li>
<li>Default: "container".</li>
</ul>
|-
|empty
|(Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
|-
|useagentcandidate
|(Optional) Boolean – Indicates whether the agent pick should be used for the candidatepick of this table. Default: "no".
|-
|useagentlinkage
|(Optional) Boolean – Indicates whether the agent pick should be used for the linkage of this table. Default: "no".
|-
|agentautotag
|(Optional) Id – Specifies the tag group of the agent pick's identity tag which will be added to picks added to this table. Default: None.
|-
|maxchoicelimit
|(Optional) Number – How many picks can be added to this table. Default: no limit.
|-
|transactiontype
|Text – a short string, typically a single word, intended to communicate what sort of "purchase" the table typically makes. For example, any table in Pathfinder that allows you to buy gear might specify "money" for this attribute, indicating that money is generally used to buy the gear it contains, while the "Vanities" table might specify "prestige" instead, to indicate that the items within are generally bought with prestige.
|-
|autothing
|(Optional) Id – Specifies the unique id of the thing to be added to the table whenever the user wants to add a pick. Use this if only a single thing can ever be added to the table.
|-
|selectnone
|(Optional) Boolean – Indicates whether it's valid to have no selection in this chooser. Default: "no".
|-
|}

The "select" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#candidate|candidate]]
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the table.
|-
|[[#restriction|restriction]]
|An optional "restriction" element may appear as defined by the given link. This element defines a [[Restriction Tag Expression]] for the table that identifies things which cannot be selected if they've already been added to this table.
|-
|[[#needtag|needtag]]
|Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#denytag|denytag]]
|Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must '''not''' exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the table.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the table.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[IgnoreRequirements Element (Data)|ignorerequirements]]
|An optional "ignorerequirements" element may appear as defined by the given link. This element specifies circumstances under which pre-reqs for things and picks in this table are ignored.
|-
|[[#change|change]]
|An optional "change" element may appear as defined by the given link. This element defines a [[Change Script]] for the table.
|-
|}

==The "show" Child Element==

:{| class="infotable"
|class="leftnormal"|allowstack
|(Optional) Boolean – Indicates whether the user is allowed to stack items within the table, subject to the restrictions imposed for each item. Default: "yes".
|-
|agentlist
|(Optional) Id – If set to a tag group id, only picks with the agent pick's identity tag from that group are shown in the table. Default: None.
|-
|allowmove
|(Optional) Boolean – Indicates whether picks in this table can be moved out of this table, if the user drags them around. Default: "yes".
|-
|listpick
|(Optional) Id – Unique id of the pick to take the table's list expression from (see listfield, below). Note that this does not work when used with portals. Default: None.
|-
|listfield
|(Optional) Id – Unique id of the field to take the table's list expression from (see listpick, above). Note that this does not work when used with portals. Default: None.
|-
|}

The "show" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the table.
|-
|}

==The "list" Element{{anchor|list}}==

The "list" element defines a [[List Tag Expression]] for the table that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this table are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the List tag expression.
|-
|}

==The "candidate" Element{{anchor|candidate}}==

The "candidate" element defines a [[Candidate Tag Expression]] for the table that limits the set of things/picks that are available for selection. If this element is omitted entirely, then the items available for selection must satisfy the List tag expression instead (above). The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|inheritlist
|(Optional) Boolean – Indicates whether the List tag expression (above) is automatically inherited into the Candidate tag expression. If inherited, all available objects must satisfy both the Candidate tag expressions and the List tag expression. This eliminates the need to redundantly maintain the same filter logic within both tag expressions. If not inherited, then the Candidate tag expression supersedes the List tag expression. Default: "no".
|-
|PCDATA
|TagExpr – Specifies the code comprising the Candidate tag expression.
|-
|}

==The "restriction" Element{{anchor|restriction}}==

The "restriction" element defines a [[Restriction Tag Expression]] for the table that further limits the set of things/picks that are available for selection. This tag expression is compared against all picks that have already been added to '''this table'''. Any object that already exists within the table is precluded from being selected again, resulting in it being omitted from the list of available choices. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Restriction tag expression.
|-
|}

==The "needtag" Element{{anchor|needtag}}==

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "denytag" Element{{anchor|denytag}}==

The "denytag" element defines a tag relationship that must '''not''' exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the table. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the table. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "change" Element{{anchor|change}}==

The "change" element defines a [[Change Script]] for the table that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Change script.
|-
|}

TableDef Element (Data)

2017-11-10T21:16:55Z

Colen:

{{contextmulti|Kit Reference|Data File Reference}}

==The "tabledef" Element==

:{| class="infotable"
|class="leftnormal"|id
|Id – Specifies the unique id of the tabledef.
|-
|component
|Id – Specifies the unique id of the component the tabledef is associated with. Like a table, only things / picks from this component will be shown in the table.
|-
|isglobal
|(Optional) Boolean – if the table is used by ALL characters for the game system, specify isglobal="yes". This is unlikely to be true for game systems with multiple different types of characters, like Pathfinder (NPCs, kingdoms, armies, etc), so don't specify this unless every single character of any type will need it. Default: "no".
|-
|description
|Text – A short string intended to communicate what the table does to the UI developers. This is is required for all tabledefs.
|-
|errorcategory
|(Optional) Unique id – indicates that this table is only marked as invalid if picks showing in it have an error of the appropriate category. If this attribute isn't set, the table will be marked as invalid if any pick in the table has an error. See error categories and table error reporting, below, for more details.
|-
|}

The "tabledef" element also possesses child elements that define the specifics of the table. Both of these child elements are optional.

:{| class="infotable"
|class="leftnormal"|select
|Contains details about the selection of new picks for this table. If the table can't select new picks (for example, if it's a fixed table), this should be omitted.
|-
|show
|Contains details about the picks shown in this table. Can be omitted if nothing interesting needs to be specified (for example, if the table has no list expression).
|-
|-
|}

==The "select" Child Element==

:{| class="infotable"
|class="leftnormal"|choosepicks
|(Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
<ul class="sets">
<li>thing – The selectable objects are things.</li>
<li>container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The selectable objects are picks from the active actor.</li>
<li>Default: "thing".</li>
</ul>
|-
|buyaction
|(Optional) Id – indicates the id of the action for the new UI to use when purchasing items from this table. Default: Empty.
|-
|sellaction
|(Optional) Id – indicates the id of the action for the new UI to use when selling items from this table. Default: Empty.
|-
|wrapupaction
|(Optional) Id – indicates the id of the action for the new UI to use after adding items from this table. Default: Empty.
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|candidatepick
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|Candidate tag expression]] for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|candidatefield
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|secondphase
|(Optional) Id – Specifies the phase of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Empty.
|-
|secondprior
|(Optional) Number – Specifies the priority of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|existphase
|(Optional) Id – Specifies the phase of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Empty.
|-
|existprior
|(Optional) Number – Specifies the priority of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|prereqtarget
|(Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
<ul class="sets">
<li>container – The default parent container is used.</li>
<li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li>
<li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li>
<li>Default: "container".</li>
</ul>
|-
|empty
|(Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
|-
|useagentcandidate
|(Optional) Boolean – Indicates whether the agent pick should be used for the candidatepick of this table. Default: "no".
|-
|useagentlinkage
|(Optional) Boolean – Indicates whether the agent pick should be used for the linkage of this table. Default: "no".
|-
|agentautotag
|(Optional) Id – Specifies the tag group of the agent pick's identity tag which will be added to picks added to this table. Default: None.
|-
|maxchoicelimit
|(Optional) Number – How many picks can be added to this table. Default: no limit.
|-
|transactiontype
|Text – a short string, typically a single word, intended to communicate what sort of "purchase" the table typically makes. For example, any table in Pathfinder that allows you to buy gear might specify "money" for this attribute, indicating that money is generally used to buy the gear it contains, while the "Vanities" table might specify "prestige" instead, to indicate that the items within are generally bought with prestige.
|-
|autothing
|(Optional) Id – Specifies the unique id of the thing to be added to the table whenever the user wants to add a pick. Use this if only a single thing can ever be added to the table.
|-
|selectnone
|(Optional) Boolean – Indicates whether it's valid to have no selection in this chooser. Default: "no".
|-
|}

The "select" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#candidate|candidate]]
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the table.
|-
|[[#restriction|restriction]]
|An optional "restriction" element may appear as defined by the given link. This element defines a [[Restriction Tag Expression]] for the table that identifies things which cannot be selected if they've already been added to this table.
|-
|[[#needtag|needtag]]
|Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#denytag|denytag]]
|Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must '''not''' exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the table.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the table.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[IgnoreRequirements Element (Data)|ignorerequirements]]
|An optional "ignorerequirements" element may appear as defined by the given link. This element specifies circumstances under which pre-reqs for things and picks in this table are ignored.
|-
|[[#change|change]]
|An optional "change" element may appear as defined by the given link. This element defines a [[Change Script]] for the table.
|-
|}

==The "show" Child Element==

:{| class="infotable"
|class="leftnormal"|allowstack
|(Optional) Boolean – Indicates whether the user is allowed to stack items within the table, subject to the restrictions imposed for each item. Default: "yes".
|-
|agentlist
|(Optional) Id – If set to a tag group id, only picks with the agent pick's identity tag from that group are shown in the table. Default: None.
|-
|allowmove
|(Optional) Boolean – Indicates whether picks in this table can be moved out of this table, if the user drags them around. Default: "yes".
|-
|listpick
|(Optional) Id – Unique id of the pick to take the table's list expression from (see listfield, below). Note that this does not work when used with portals. Default: None.
|-
|listfield
|(Optional) Id – Unique id of the field to take the table's list expression from (see listpick, above). Note that this does not work when used with portals. Default: None.
|-
|}

The "show" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the table.
|-
|}

==The "list" Element{{anchor|list}}==

The "list" element defines a [[List Tag Expression]] for the table that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this table are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the List tag expression.
|-
|}

==The "candidate" Element{{anchor|candidate}}==

The "candidate" element defines a [[Candidate Tag Expression]] for the table that limits the set of things/picks that are available for selection. If this element is omitted entirely, then the items available for selection must satisfy the List tag expression instead (above). The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|inheritlist
|(Optional) Boolean – Indicates whether the List tag expression (above) is automatically inherited into the Candidate tag expression. If inherited, all available objects must satisfy both the Candidate tag expressions and the List tag expression. This eliminates the need to redundantly maintain the same filter logic within both tag expressions. If not inherited, then the Candidate tag expression supersedes the List tag expression. Default: "no".
|-
|PCDATA
|TagExpr – Specifies the code comprising the Candidate tag expression.
|-
|}

==The "restriction" Element{{anchor|restriction}}==

The "restriction" element defines a [[Restriction Tag Expression]] for the table that further limits the set of things/picks that are available for selection. This tag expression is compared against all picks that have already been added to '''this table'''. Any object that already exists within the table is precluded from being selected again, resulting in it being omitted from the list of available choices. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Restriction tag expression.
|-
|}

==The "needtag" Element{{anchor|needtag}}==

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "denytag" Element{{anchor|denytag}}==

The "denytag" element defines a tag relationship that must '''not''' exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the table. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the table. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "change" Element{{anchor|change}}==

The "change" element defines a [[Change Script]] for the table that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Change script.
|-
|}

TableDef Element (Data)

2017-11-10T21:16:19Z

Colen: /* The "candidate" Element{{anchor|candidate}} */

{{contextmulti|Kit Reference|Data File Reference}}

==The "tabledef" Element==

:{| class="infotable"
|class="leftnormal"|id
|Id – Specifies the unique id of the tabledef.
|-
|component
|Id – Specifies the unique id of the component the tabledef is associated with. Like a table, only things / picks from this component will be shown in the table.
|-
|isglobal
|(Optional) Boolean – if the table is used by ALL characters for the game system, specify isglobal="yes". This is unlikely to be true for game systems with multiple different types of characters, like Pathfinder (NPCs, kingdoms, armies, etc), so don't specify this unless every single character of any type will need it. Default: "no".
|-
|description
|Text – A short string intended to communicate what the table does to the UI developers. This is is required for all tabledefs.
|-
|errorcategory
|(Optional) Unique id – indicates that this table is only marked as invalid if picks showing in it have an error of the appropriate category. If this attribute isn't set, the table will be marked as invalid if any pick in the table has an error. See error categories and table error reporting, below, for more details.
|-
|}

The "tabledef" element also possesses child elements that define the specifics of the table. Both of these child elements are optional.

:{| class="infotable"
|class="leftnormal"|select
|Contains details about the selection of new picks for this table. If the table can't select new picks (for example, if it's a fixed table), this should be omitted.
|-
|show
|Contains details about the picks shown in this table. Can be omitted if nothing interesting needs to be specified (for example, if the table has no list expression).
|-
|-
|}

==The "select" Child Element==

:{| class="infotable"
|class="leftnormal"|choosepicks
|(Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
<ul class="sets">
<li>thing – The selectable objects are things.</li>
<li>container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The selectable objects are picks from the active actor.</li>
<li>Default: "thing".</li>
</ul>
|-
|buyaction
|(Optional) Id – indicates the id of the action for the new UI to use when purchasing items from this table. Default: Empty.
|-
|sellaction
|(Optional) Id – indicates the id of the action for the new UI to use when selling items from this table. Default: Empty.
|-
|wrapupaction
|(Optional) Id – indicates the id of the action for the new UI to use after adding items from this table. Default: Empty.
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|candidatepick
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|Candidate tag expression]] for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|candidatefield
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|secondphase
|(Optional) Id – Specifies the phase of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Empty.
|-
|secondprior
|(Optional) Number – Specifies the priority of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|existphase
|(Optional) Id – Specifies the phase of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Empty.
|-
|existprior
|(Optional) Number – Specifies the priority of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|prereqtarget
|(Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
<ul class="sets">
<li>container – The default parent container is used.</li>
<li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li>
<li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li>
<li>Default: "container".</li>
</ul>
|-
|empty
|(Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
|-
|useagentcandidate
|(Optional) Boolean – Indicates whether the agent pick should be used for the candidatepick of this table. Default: "no".
|-
|useagentlinkage
|(Optional) Boolean – Indicates whether the agent pick should be used for the linkage of this table. Default: "no".
|-
|agentautotag
|(Optional) Id – Specifies the tag group of the agent pick's identity tag which will be added to picks added to this table. Default: None.
|-
|maxchoicelimit
|(Optional) Number – How many picks can be added to this table. Default: no limit.
|-
|transactiontype
|Text – a short string, typically a single word, intended to communicate what sort of "purchase" the table typically makes. For example, any table in Pathfinder that allows you to buy gear might specify "money" for this attribute, indicating that money is generally used to buy the gear it contains, while the "Vanities" table might specify "prestige" instead, to indicate that the items within are generally bought with prestige.
|-
|autothing
|(Optional) Id – Specifies the unique id of the thing to be added to the table whenever the user wants to add a pick. Use this if only a single thing can ever be added to the table.
|-
|selectnone
|(Optional) Boolean – Indicates whether it's valid to have no selection in this chooser. Default: "no".
|-
|}

The "select" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#candidate|candidate]]
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the table.
|-
|[[#restriction|restriction]]
|An optional "restriction" element may appear as defined by the given link. This element defines a [[Restriction Tag Expression]] for the table that identifies things which cannot be selected if they've already been added to this table.
|-
|[[#needtag|needtag]]
|Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#denytag|denytag]]
|Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must '''not''' exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the table.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the table.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[IgnoreRequirements Element (Data)|ignorerequirements]]
|An optional "ignorerequirements" element may appear as defined by the given link. This element specifies circumstances under which pre-reqs for things and picks in this table are ignored.
|-
|[[#change|change]]
|An optional "change" element may appear as defined by the given link. This element defines a [[Change Script]] for the table.
|-
|}

==The "show" Child Element==

:{| class="infotable"
|class="leftnormal"|allowstack
|(Optional) Boolean – Indicates whether the user is allowed to stack items within the table, subject to the restrictions imposed for each item. Default: "yes".
|-
|agentlist
|(Optional) Id – If set to a tag group id, only picks with the agent pick's identity tag from that group are shown in the table. Default: None.
|-
|allowmove
|(Optional) Boolean – Indicates whether picks in this table can be moved out of this table, if the user drags them around. Default: "yes".
|-
|listpick
|(Optional) Id – Unique id of the pick to take the table's list expression from (see listfield, below). Note that this does not work in concert with table portals. Default: None.
|-
|listfield
|(Optional) Id – Unique id of the field to take the table's list expression from (see listpick, above). Note that this does not work in concert with table portals. Default: None.
|-
|}

The "show" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the portal.
|-
|}

==The "list" Element{{anchor|list}}==

The "list" element defines a [[List Tag Expression]] for the portal that limits the set of picks that are shown. Regardless of this tag expression, all picks added via this portal are always shown within it, enabling deletion of any object added through the table. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the List tag expression.
|-
|}

==The "candidate" Element{{anchor|candidate}}==

The "candidate" element defines a [[Candidate Tag Expression]] for the table that limits the set of things/picks that are available for selection. If this element is omitted entirely, then the items available for selection must satisfy the List tag expression instead (above). The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|inheritlist
|(Optional) Boolean – Indicates whether the List tag expression (above) is automatically inherited into the Candidate tag expression. If inherited, all available objects must satisfy both the Candidate tag expressions and the List tag expression. This eliminates the need to redundantly maintain the same filter logic within both tag expressions. If not inherited, then the Candidate tag expression supersedes the List tag expression. Default: "no".
|-
|PCDATA
|TagExpr – Specifies the code comprising the Candidate tag expression.
|-
|}

==The "restriction" Element{{anchor|restriction}}==

The "restriction" element defines a [[Restriction Tag Expression]] for the table that further limits the set of things/picks that are available for selection. This tag expression is compared against all picks that have already been added to '''this table'''. Any object that already exists within the table is precluded from being selected again, resulting in it being omitted from the list of available choices. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Restriction tag expression.
|-
|}

==The "needtag" Element{{anchor|needtag}}==

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "denytag" Element{{anchor|denytag}}==

The "denytag" element defines a tag relationship that must '''not''' exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the table. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the table. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "change" Element{{anchor|change}}==

The "change" element defines a [[Change Script]] for the table that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Change script.
|-
|}

TableDef Element (Data)

2017-11-10T21:15:54Z

Colen: /* The "select" Child Element */

{{contextmulti|Kit Reference|Data File Reference}}

==The "tabledef" Element==

:{| class="infotable"
|class="leftnormal"|id
|Id – Specifies the unique id of the tabledef.
|-
|component
|Id – Specifies the unique id of the component the tabledef is associated with. Like a table, only things / picks from this component will be shown in the table.
|-
|isglobal
|(Optional) Boolean – if the table is used by ALL characters for the game system, specify isglobal="yes". This is unlikely to be true for game systems with multiple different types of characters, like Pathfinder (NPCs, kingdoms, armies, etc), so don't specify this unless every single character of any type will need it. Default: "no".
|-
|description
|Text – A short string intended to communicate what the table does to the UI developers. This is is required for all tabledefs.
|-
|errorcategory
|(Optional) Unique id – indicates that this table is only marked as invalid if picks showing in it have an error of the appropriate category. If this attribute isn't set, the table will be marked as invalid if any pick in the table has an error. See error categories and table error reporting, below, for more details.
|-
|}

The "tabledef" element also possesses child elements that define the specifics of the table. Both of these child elements are optional.

:{| class="infotable"
|class="leftnormal"|select
|Contains details about the selection of new picks for this table. If the table can't select new picks (for example, if it's a fixed table), this should be omitted.
|-
|show
|Contains details about the picks shown in this table. Can be omitted if nothing interesting needs to be specified (for example, if the table has no list expression).
|-
|-
|}

==The "select" Child Element==

:{| class="infotable"
|class="leftnormal"|choosepicks
|(Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
<ul class="sets">
<li>thing – The selectable objects are things.</li>
<li>container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The selectable objects are picks from the active actor.</li>
<li>Default: "thing".</li>
</ul>
|-
|buyaction
|(Optional) Id – indicates the id of the action for the new UI to use when purchasing items from this table. Default: Empty.
|-
|sellaction
|(Optional) Id – indicates the id of the action for the new UI to use when selling items from this table. Default: Empty.
|-
|wrapupaction
|(Optional) Id – indicates the id of the action for the new UI to use after adding items from this table. Default: Empty.
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|candidatepick
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|Candidate tag expression]] for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|candidatefield
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|secondphase
|(Optional) Id – Specifies the phase of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Empty.
|-
|secondprior
|(Optional) Number – Specifies the priority of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|existphase
|(Optional) Id – Specifies the phase of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Empty.
|-
|existprior
|(Optional) Number – Specifies the priority of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|prereqtarget
|(Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
<ul class="sets">
<li>container – The default parent container is used.</li>
<li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li>
<li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li>
<li>Default: "container".</li>
</ul>
|-
|empty
|(Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
|-
|useagentcandidate
|(Optional) Boolean – Indicates whether the agent pick should be used for the candidatepick of this table. Default: "no".
|-
|useagentlinkage
|(Optional) Boolean – Indicates whether the agent pick should be used for the linkage of this table. Default: "no".
|-
|agentautotag
|(Optional) Id – Specifies the tag group of the agent pick's identity tag which will be added to picks added to this table. Default: None.
|-
|maxchoicelimit
|(Optional) Number – How many picks can be added to this table. Default: no limit.
|-
|transactiontype
|Text – a short string, typically a single word, intended to communicate what sort of "purchase" the table typically makes. For example, any table in Pathfinder that allows you to buy gear might specify "money" for this attribute, indicating that money is generally used to buy the gear it contains, while the "Vanities" table might specify "prestige" instead, to indicate that the items within are generally bought with prestige.
|-
|autothing
|(Optional) Id – Specifies the unique id of the thing to be added to the table whenever the user wants to add a pick. Use this if only a single thing can ever be added to the table.
|-
|selectnone
|(Optional) Boolean – Indicates whether it's valid to have no selection in this chooser. Default: "no".
|-
|}

The "select" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#candidate|candidate]]
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the table.
|-
|[[#restriction|restriction]]
|An optional "restriction" element may appear as defined by the given link. This element defines a [[Restriction Tag Expression]] for the table that identifies things which cannot be selected if they've already been added to this table.
|-
|[[#needtag|needtag]]
|Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#denytag|denytag]]
|Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must '''not''' exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the table.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the table.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[IgnoreRequirements Element (Data)|ignorerequirements]]
|An optional "ignorerequirements" element may appear as defined by the given link. This element specifies circumstances under which pre-reqs for things and picks in this table are ignored.
|-
|[[#change|change]]
|An optional "change" element may appear as defined by the given link. This element defines a [[Change Script]] for the table.
|-
|}

==The "show" Child Element==

:{| class="infotable"
|class="leftnormal"|allowstack
|(Optional) Boolean – Indicates whether the user is allowed to stack items within the table, subject to the restrictions imposed for each item. Default: "yes".
|-
|agentlist
|(Optional) Id – If set to a tag group id, only picks with the agent pick's identity tag from that group are shown in the table. Default: None.
|-
|allowmove
|(Optional) Boolean – Indicates whether picks in this table can be moved out of this table, if the user drags them around. Default: "yes".
|-
|listpick
|(Optional) Id – Unique id of the pick to take the table's list expression from (see listfield, below). Note that this does not work in concert with table portals. Default: None.
|-
|listfield
|(Optional) Id – Unique id of the field to take the table's list expression from (see listpick, above). Note that this does not work in concert with table portals. Default: None.
|-
|}

The "show" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#list|list]]
|An optional "list" element may appear as defined by the given link. This element defines a [[List Tag Expression]] for the portal.
|-
|}

==The "candidate" Element{{anchor|candidate}}==

The "candidate" element defines a [[Candidate Tag Expression]] for the table that limits the set of things/picks that are available for selection. If this element is omitted entirely, then the items available for selection must satisfy the List tag expression instead (above). The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|inheritlist
|(Optional) Boolean – Indicates whether the List tag expression (above) is automatically inherited into the Candidate tag expression. If inherited, all available objects must satisfy both the Candidate tag expressions and the List tag expression. This eliminates the need to redundantly maintain the same filter logic within both tag expressions. If not inherited, then the Candidate tag expression supersedes the List tag expression. Default: "no".
|-
|PCDATA
|TagExpr – Specifies the code comprising the Candidate tag expression.
|-
|}

==The "restriction" Element{{anchor|restriction}}==

The "restriction" element defines a [[Restriction Tag Expression]] for the table that further limits the set of things/picks that are available for selection. This tag expression is compared against all picks that have already been added to '''this table'''. Any object that already exists within the table is precluded from being selected again, resulting in it being omitted from the list of available choices. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Restriction tag expression.
|-
|}

==The "needtag" Element{{anchor|needtag}}==

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "denytag" Element{{anchor|denytag}}==

The "denytag" element defines a tag relationship that must '''not''' exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the table. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the table. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "change" Element{{anchor|change}}==

The "change" element defines a [[Change Script]] for the table that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Change script.
|-
|}

TableDef Element (Data)

2017-11-10T21:11:31Z

Colen: Created page with "{{contextmulti|Kit Reference|Data File Reference}} ==The "tabledef" Element== :{| class="infotable" |class="leftnormal"|id |Id – Specifies the unique id of the tabledef. |..."

{{contextmulti|Kit Reference|Data File Reference}}

==The "tabledef" Element==

:{| class="infotable"
|class="leftnormal"|id
|Id – Specifies the unique id of the tabledef.
|-
|component
|Id – Specifies the unique id of the component the tabledef is associated with. Like a table, only things / picks from this component will be shown in the table.
|-
|isglobal
|(Optional) Boolean – if the table is used by ALL characters for the game system, specify isglobal="yes". This is unlikely to be true for game systems with multiple different types of characters, like Pathfinder (NPCs, kingdoms, armies, etc), so don't specify this unless every single character of any type will need it. Default: "no".
|-
|description
|Text – A short string intended to communicate what the table does to the UI developers. This is is required for all tabledefs.
|-
|errorcategory
|(Optional) Unique id – indicates that this table is only marked as invalid if picks showing in it have an error of the appropriate category. If this attribute isn't set, the table will be marked as invalid if any pick in the table has an error. See error categories and table error reporting, below, for more details.
|-
|}

The "tabledef" element also possesses child elements that define the specifics of the table. Both of these child elements are optional.

:{| class="infotable"
|class="leftnormal"|select
|Contains details about the selection of new picks for this table. If the table can't select new picks (for example, if it's a fixed table), this should be omitted.
|-
|show
|Contains details about the picks shown in this table. Can be omitted if nothing interesting needs to be specified (for example, if the table has no list expression).
|-
|-
|}

==The "select" Child Element==

:{| class="infotable"
|class="leftnormal"|choosepicks
|(Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
<ul class="sets">
<li>thing – The selectable objects are things.</li>
<li>container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The selectable objects are picks from the active actor.</li>
<li>Default: "thing".</li>
</ul>
|-
|buyaction
|(Optional) Id – indicates the id of the action for the new UI to use when purchasing items from this table. Default: Empty.
|-
|sellaction
|(Optional) Id – indicates the id of the action for the new UI to use when selling items from this table. Default: Empty.
|-
|wrapupaction
|(Optional) Id – indicates the id of the action for the new UI to use after adding items from this table. Default: Empty.
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added to the table, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|candidatepick
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|Candidate tag expression]] for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|candidatefield
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|secondphase
|(Optional) Id – Specifies the phase of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Empty.
|-
|secondprior
|(Optional) Number – Specifies the priority of the [[Secondary Tag Expression|Secondary tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|existphase
|(Optional) Id – Specifies the phase of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Empty.
|-
|existprior
|(Optional) Number – Specifies the priority of the [[Existence Tag Expression|Existence tag expression]] for this table, if one is present. Default: Priority specified in the game system definition file.
|-
|prereqtarget
|(Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
<ul class="sets">
<li>container – The default parent container is used.</li>
<li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li>
<li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li>
<li>Default: "container".</li>
</ul>
|-
|empty
|(Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
|-
|useagentcandidate
|(Optional) Boolean – Indicates whether the agent pick should be used for the candidatepick of this table. Default: "no".
|-
|useagentlinkage
|(Optional) Boolean – Indicates whether the agent pick should be used for the linkage of this table. Default: "no".
|-
|agentautotag
|(Optional) Id – Specifies the tag group of the agent pick's identity tag which will be added to picks added to this table. Default: None.
|-
|maxchoicelimit
|(Optional) Number – How many picks can be added to this table. Default: no limit.
|-
|transactiontype
|Text – a short string, typically a single word, intended to communicate what sort of "purchase" the table typically makes. For example, any table in Pathfinder that allows you to buy gear might specify "money" for this attribute, indicating that money is generally used to buy the gear it contains, while the "Vanities" table might specify "prestige" instead, to indicate that the items within are generally bought with prestige.
|-
|autothing
|(Optional) Id – Specifies the unique id of the thing to be added to the table whenever the user wants to add a pick. Use this if only a single thing can ever be added to the table.
|-
|selectnone
|(Optional) Boolean – Indicates whether it's valid to have no selection in this chooser. Default: "no".
|-
|}

The "select" element also possesses child elements that define additional behaviors of the table. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#candidate|candidate]]
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the table.
|-
|[[#restriction|restriction]]
|An optional "restriction" element may appear as defined by the given link. This element defines a [[Restriction Tag Expression]] for the table that identifies things which cannot be selected if they've already been added to this table.
|-
|[[#needtag|needtag]]
|Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#denytag|denytag]]
|Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must '''not''' exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the table.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the table.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[IgnoreRequirements Element (Data)|ignorerequirements]]
|An optional "ignorerequirements" element may appear as defined by the given link. This element specifies circumstances under which pre-reqs for things and picks in this table are ignored.
|-
|[[#change|change]]
|An optional "change" element may appear as defined by the given link. This element defines a [[Change Script]] for the table.
|-
|}

==The "candidate" Element{{anchor|candidate}}==

The "candidate" element defines a [[Candidate Tag Expression]] for the table that limits the set of things/picks that are available for selection. If this element is omitted entirely, then the items available for selection must satisfy the List tag expression instead (above). The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|inheritlist
|(Optional) Boolean – Indicates whether the List tag expression (above) is automatically inherited into the Candidate tag expression. If inherited, all available objects must satisfy both the Candidate tag expressions and the List tag expression. This eliminates the need to redundantly maintain the same filter logic within both tag expressions. If not inherited, then the Candidate tag expression supersedes the List tag expression. Default: "no".
|-
|PCDATA
|TagExpr – Specifies the code comprising the Candidate tag expression.
|-
|}

==The "restriction" Element{{anchor|restriction}}==

The "restriction" element defines a [[Restriction Tag Expression]] for the table that further limits the set of things/picks that are available for selection. This tag expression is compared against all picks that have already been added to '''this table'''. Any object that already exists within the table is precluded from being selected again, resulting in it being omitted from the list of available choices. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Restriction tag expression.
|-
|}

==The "needtag" Element{{anchor|needtag}}==

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "denytag" Element{{anchor|denytag}}==

The "denytag" element defines a tag relationship that must '''not''' exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the table. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the table. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "change" Element{{anchor|change}}==

The "change" element defines a [[Change Script]] for the table that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Change script.
|-
|}

Data File Reference

2017-11-10T20:47:21Z

Colen: /* Structural Composition */

{{context|Kit Reference}}

==Overview==

The data file is where you'll be defining all of the top-level elements that the user will directly control. This includes visual elements like panels, layouts, templates, and portals. It also includes game system elements like things.

All data files have the ".dat" file extension and are loaded after all of the structural files have defined the framework for the game system.

This section outlines the structure and mechanics for writing a definition file.

{{important}}This section utilizes [[Kit Reference#conventions|critical notational conventions]] that should be reviewed.

{{important}}Just because you '''can''' put numerous different elements in the same file does not mean you '''should''' do so. Keeping your data files small and focused will also keep them much more manageable, so break up all the information across files where appropriate. See the Skeleton data files for examples of this.

==Structural Composition==

The overall file structure is that of a standard XML file. The file must start with an XML version element in the form: "<?xml version="1.0"?>". Following this, the top-level XML element must be a "document" and it must have a "signature" attribute containing the explicit value "Hero Lab Data".

The following table defines the attributes for a "document" element.

:{| class="infotable"
|class="leftnormal"|signature
|Text – Must be the value "Hero Lab Data".
|-
|}

Within the document element, every data file possesses the following child elements, appearing in the sequence given and with the names specified.

:{| class="infotable"
|class="leftnormal"|{{flalt|LoadOnce Element (Data)|loadonce}}
|A single "loadonce" element may appear as defined by the given link. This element allows you to conditionally exclude files from being loaded if a similar file has already been loaded.
|-
|{{flalt|FileInfo Element (Data)|fileinfo}}
|A single "fileinfo" element may appear as defined by the given link. This element specifies information about the data file and its author.
|-
|{{flalt|FileConstants Element (Data)|fileconstants}}
|A single "fileconstants" element may appear as defined by the given link. This element specifies constant information that affects the whole data file.
|-
|{{flalt|Procedure Element (Data)|procedure}}
|Zero or more "procedure" elements may appear as defined by the given link. This element specifies a collection of procedures that may be called by scripts throughout the data files.
|-
|{{flalt|Action Element (Data)|action}}
|Zero or more "action" elements may appear as defined by the given link. This element specifies a collection of actions that may be invoked throughout the data files.
|-
|{{flalt|Thing Element (Data)|thing}}
|Zero or more "thing" elements may appear as defined by the given link. This element specifies various thing objects for use within the game system.
|-
|{{flalt|Portal Element (Data)|portal}}
|Zero or more "portal" elements may appear as defined by the given link. This element specifies an assortment of portals for use within layouts.
|-
|{{flalt|Template Element (Data)|template}}
|Zero or more "template" elements may appear as defined by the given link. This element specifies an assortment of templates for use within layouts.
|-
|{{flalt|Layout Element (Data)|layout}}
|Zero or more "layout" elements may appear as defined by the given link. This element specifies an assortment of layouts for use within panels, forms, and sheets.
|-
|{{flalt|Panel Element (Data)|panel}}
|Zero or more "panel" elements may appear as defined by the given link. This element specifies a variety of panels that will be presented to the user as part of the game system.
|-
|{{flalt|Form Element (Data)|form}}
|Zero or more "form" elements may appear as defined by the given link. This element specifies a variety of forms that will be presented to the user as part of the game system.
|-
|{{flalt|Sheet Element (Data)|sheet}}
|Zero or more "sheet" elements may appear as defined by the given link. This element specifies a variety of sheets that will be used for printouts within dossiers.
|-
|{{flalt|TableDef Element (Data)|tabledef}}
|Zero or more "tabledef" elements may appear as defined by the given link. This element specifies a variety of tables that will be used throughout the data files.
|-
|{{flalt|Dossier Element (Data)|dossier}}
|Zero or more "dossier" elements may appear as defined by the given link. This element specifies a collection of dossiers that the user can select for character output.
|-
|{{flalt|Hidden Element (Data)|hidden}}
|Zero or more "hidden" elements may appear as defined by the given link. This element identifies things that HL should remove from use within the game system.
|-
|{{flalt|Preclude Element (Data)|preclude}}
|Zero or more "preclude" elements may appear as defined by the given link. This element identifies things that HL should preclude from use if certain sources are specified.
|-
|{{flalt|Input Thing Group Element (Data)|inputthinggroup}}
|Zero or more "inputthinggroup" elements may appear as defined by the given link. This element identifies groups of input things that are shown in the editor.
|-
|{{flalt|Edit Thing Element (Data)|editthing}}
|Zero or more "editthing" elements may appear as defined by the given link. This element specifies a variety of elements that enable use of the integrated Editor for creation of things.
|-
|{{flalt|Loadmods Element (Data)|loadmods}}
|An optional "loadmods" element may appear as defined by the given link. This element specifies ways to adjust old saved portfolios to new versions of the data files.
|-
|{{flalt|FAQ Element (Data)|faq}}
|Zero or more "faq" elements may appear as defined by the given link. This element specifies various FAQ entries that will be included within the FAQ page for the game system.
|-
|{{flalt|ExtThing Element (Data)|extthing}}
|Zero or more "extthing" elements may appear as defined by the given link. This element specifies additional tags which may be added to the specified things.
|-
|}

==DTD==

To edit data files in your XML editor, you can use the [[Data File DTD|Data File DTD here]].

FileConstants Element (Data)

2017-11-06T18:56:26Z

Colen: Created page with "{{context|Kit Reference|Data File Reference}} ==The "fileconstants" Element== This element allows you to specify behaviors that apply to each thing in this file. This can be..."

{{context|Kit Reference|Data File Reference}}

==The "fileconstants" Element==

This element allows you to specify behaviors that apply to each thing in this file. This can be used to assign a tag to every thing in a file, or to verify that a certain substring appears in the unique id of every thing in a file.

The contents of the "fileconstants" element cannot be viewed in the Hero Lab editor - they can only be seen when editing the file XML in a text editor. The HL editor preserves the fileconstants element of any file loaded into it, but does not allow you to view or change it.

The fileconstants element has the following attributes:

:{| class="infotable"
|class="leftnormal"|thingidrequirement
|Specifies a substring that must be found in the unique of every element in the file, or an error is reported. For example, if you were building a file for content from the "Amazing Games" publisher, and you wanted to make sure each element included "AG" in its unique id, you would specify "AG" for this attribute. Any thing without "AG" in its unique id would then report an error when the data files were compiled.
|-
|}

The "fileconstants" element possesses the following child elements:

:{| class="infotable"
|class="leftnormal"|autotag
|Zero or more "autotag" elements may be specified, each with a group id and tag id ("group" and "tag" attributes). Each tag listed here is added to every thing in the file.
|-
|}

Example:

<pre>
<fileconstants thingidrequirement="AP">
<autotag group="SomeGroup" tag="SomeTag"/>
</fileconstants>
</pre>

Data File Reference

2017-11-03T20:07:55Z

Colen: /* Structural Composition */

{{context|Kit Reference}}

==Overview==

The data file is where you'll be defining all of the top-level elements that the user will directly control. This includes visual elements like panels, layouts, templates, and portals. It also includes game system elements like things.

All data files have the ".dat" file extension and are loaded after all of the structural files have defined the framework for the game system.

This section outlines the structure and mechanics for writing a definition file.

{{important}}This section utilizes [[Kit Reference#conventions|critical notational conventions]] that should be reviewed.

{{important}}Just because you '''can''' put numerous different elements in the same file does not mean you '''should''' do so. Keeping your data files small and focused will also keep them much more manageable, so break up all the information across files where appropriate. See the Skeleton data files for examples of this.

==Structural Composition==

The overall file structure is that of a standard XML file. The file must start with an XML version element in the form: "<?xml version="1.0"?>". Following this, the top-level XML element must be a "document" and it must have a "signature" attribute containing the explicit value "Hero Lab Data".

The following table defines the attributes for a "document" element.

:{| class="infotable"
|class="leftnormal"|signature
|Text – Must be the value "Hero Lab Data".
|-
|}

Within the document element, every data file possesses the following child elements, appearing in the sequence given and with the names specified.

:{| class="infotable"
|class="leftnormal"|{{flalt|LoadOnce Element (Data)|loadonce}}
|A single "loadonce" element may appear as defined by the given link. This element allows you to conditionally exclude files from being loaded if a similar file has already been loaded.
|-
|{{flalt|FileInfo Element (Data)|fileinfo}}
|A single "fileinfo" element may appear as defined by the given link. This element specifies information about the data file and its author.
|-
|{{flalt|FileConstants Element (Data)|fileconstants}}
|A single "fileconstants" element may appear as defined by the given link. This element specifies constant information that affects the whole data file.
|-
|{{flalt|Procedure Element (Data)|procedure}}
|Zero or more "procedure" elements may appear as defined by the given link. This element specifies a collection of procedures that may be called by scripts throughout the data files.
|-
|{{flalt|Thing Element (Data)|thing}}
|Zero or more "thing" elements may appear as defined by the given link. This element specifies various thing objects for use within the game system.
|-
|{{flalt|Portal Element (Data)|portal}}
|Zero or more "portal" elements may appear as defined by the given link. This element specifies an assortment of portals for use within layouts.
|-
|{{flalt|Template Element (Data)|template}}
|Zero or more "template" elements may appear as defined by the given link. This element specifies an assortment of templates for use within layouts.
|-
|{{flalt|Layout Element (Data)|layout}}
|Zero or more "layout" elements may appear as defined by the given link. This element specifies an assortment of layouts for use within panels, forms, and sheets.
|-
|{{flalt|Panel Element (Data)|panel}}
|Zero or more "panel" elements may appear as defined by the given link. This element specifies a variety of panels that will be presented to the user as part of the game system.
|-
|{{flalt|Form Element (Data)|form}}
|Zero or more "form" elements may appear as defined by the given link. This element specifies a variety of forms that will be presented to the user as part of the game system.
|-
|{{flalt|Sheet Element (Data)|sheet}}
|Zero or more "sheet" elements may appear as defined by the given link. This element specifies a variety of sheets that will be used for printouts within dossiers.
|-
|{{flalt|Dossier Element (Data)|dossier}}
|Zero or more "dossier" elements may appear as defined by the given link. This element specifies a collection of dossiers that the user can select for character output.
|-
|{{flalt|Hidden Element (Data)|hidden}}
|Zero or more "hidden" elements may appear as defined by the given link. This element identifies things that HL should remove from use within the game system.
|-
|{{flalt|Edit Thing Element (Data)|editthing}}
|Zero or more "editthing" elements may appear as defined by the given link. This element specifies a variety of elements that enable use of the integrated Editor for creation of things.
|-
|{{flalt|FAQ Element (Data)|faq}}
|Zero or more "faq" elements may appear as defined by the given link. This element specifies various FAQ entries that will be included within the FAQ page for the game system.
|-
|}

==DTD==

To edit data files in your XML editor, you can use the [[Data File DTD|Data File DTD here]].

Pathfinder RPG Best Practices

2017-06-07T14:45:45Z

Colen: /* Deliverable 1 - Create portfolios for every encounter and NPC in the module */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== Only use official LWD content when creating data files or portfolios ==
When building data files or entering portfolios, make sure you don't have any "third party" data files installed. Content in "third party" data files isn't available to everyone, and can cause problems with what you're entering. You can check to make sure you don't have any installed by going to Tools -> Manage Third Party Updates in Hero Lab.

If you do have third party content installed, you should either delete it before working on stuff for us, or download a separate copy of the Pathfinder game system that you use to work on stuff for us. You can do this by downloading the latest Pathfinder update from the "Find Updates" screen, then changing the folder at the bottom-left of the screen to something like "pathfinder_lwd". Make sure you edit all portfolios only with the "pathfinder_lwd" version of Pathfinder, to avoid introducing or referencing third party content.

== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the sNameMod field when bootstrapping. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a sNameMod of "self plus 50 lbs. of objects only"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Details to Check for Weapons, Armor, Magic Items, and Gear =

* If there is equipment in this book from an exotic source, like high-tech items, or stone-age items, or firearms, in the Configure Hero settings, go to the "Equipment, Weapons & Armor to show" section, and turn on the option(s) that should hide this exotic content. Then, search the various tables for content from this book, and make sure that it is hidden as intended. If not, set the appropriate tag in the "Special Groupings" list for the category.

* Did you create any new weapons that are helper items or variants of an existing weapon? If so, add the weapon focus feat, and then double-check that none of the helper weapons show up there as a selection option. (To check this, search for items from the book and make sure that nothing appears in the tables that shouldn't.)

* In each table where you've added new content, filter to only this new book, and look at what categories your new content fits in to - are they sorted under the correct headers?

* Go to the weapons, armor, magic, and gear tabs, and filter for "- no description -" (note the spaces between the - and the words). Make sure none of the content from your book is among this material - everything new should have a description.

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary. For multiple issue series, like adventure paths, the sourcebook name should include both the overarching series and the specific issue, for example "Ironfang Invasion: Siege of Stone"
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables which must be submitted before a project is completed, which should be worked on in parallel.

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Please keep the following in mind when entering portfolios:

* Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

* Portfolio name format is important! For most encounters, the format is "PAGE - SECTION/MAP AREA - ENCOUNTER NAME (OTHER INFO, CR)". Note that not all general encounters will include all elements of the format.

# PAGE is the abbreviation "p" and the page number the encounter starts on, and includes a preceding 0 when necessary to bring things to 2 digits. For example, "p07" or "p82".
# SECTION/MAP AREA is what identifies where in the module structure the encounter appears. It usually precedes the name. For example "Event 3" or "B3".
# ENCOUNTER NAME is the name of the encounter, which should be in Title Case. For example, "Trader in the Dark" or "Khardajeen's Rest".
# OTHER INFO is rarely used, most often to distinguish one version of an encounter from another. For example, "If idol is active" or "While alarm is raised".
# CR is the challenge rating of the encounter, which is usually in the AP, but may be omitted for encounters which are non-combat. It should NOT include a preceding 0 when it is below 2 digits. There should be a space between "CR" and the number.
# For example: p30 - J23 - Strategy Room (CR 5).por

* An exception to the above are encounters in a random encounter table. There, the format is "ROLL RANGE - ENCOUNTER NAME".

# ROLL RANGE is the numbers which must be rolled in order to meet this encounter. It should include preceding 0 when below 2 digits. For example, "01-05", "08-12", "33-40".
# ENCOUNTER NAME is the name of the encounter, whose case varies here. It should be in Sentence case for most of these encounters (for example "1d6 peuchen" or "1 griffon"), but special encounters (those given a writeup near the table) should be in Title Case (for example, "Scout Patrol" or "Mausoleum of Bacchus").
# For example: 95-97 - 2 deathwebs.por

* Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

* If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

* Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

* Do not forget to include the sections in the Appendix! Adventure paths reproduce star characters in the appendix, and such characters should be restored to their "fresh" state. For example, an NPC who was discovered wounded during the course of the adventure, when represented in the appendix section, would be at full hit points. Another common part of the appendix is a random encounter table, but there may be other sections with their own statblocks which need representation as well.

* When building an NPC, you'll need to reverse-engineer the Hero Lab character from the statblock. For example, the character's hit points will come from a combination of class levels, favored class bonuses, and other sources - use average hit points for the class levels (which on NPCs, alternate from one level to the next). Generally favored class bonuses will be used to add additional hit points, but not always.

* Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

* For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

* A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

* In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

* If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

* Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

* Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

* Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

* If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

# if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.
# If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

* Make sure to enter text that's relevant during combat for the NPC (usually just the "Before Combat", "Morale", and "During Combat" sections from the statblock, which should be entered on the NPC tab), but '''don't''' enter any "Character" or "Development" text that appears around the statblock. Text from those sections shouldn't be included in the Hero Lab portfolio (this is a change from what we've done in the past). Statblocks often include adjustments due to actions described in the "Before Combat" section, in which case you should go to the adjust tab and apply appropriate adjustments. If any of these preparations are from personally cast spells, go to the Spells tab and mark those off as cast.

* On the Personal tab, include any portrait of the character from the book. If you can't extract those images from the PDF using a tool like Photoshop, let us know and we can supply them. If no portrait is provided in the book, just leave it as the default portrait from the Encounter Builder.

== Deliverable 2 - Notes ==

As you work on the module, create a list of any differences between what the module shows, and what Hero Lab shows. For example, if skills are off, note that, and see if you can figure out why it happened - that might lead you to think of a different way to do them so they'll be correct. This file is important because it will be used by whoever is checking your work.

== Submission ==

Submit both pieces of the project to us - portfolios and notes file. Don't submit until the portfolios are complete and checked to make sure they're correct.

= Checking Encounter Libraries =

Once both deliverables for an encounter library have been submitted (see above), we'll a different person to check the work. If you're checking someone else's encounter libraries, you need to find places they did something wrong.

Compare the statblocks listed in the module with what's in Hero Lab - do the details in the module match what's in HL? If not, consult the notes file you got along with the portfolios and see if the author noticed the problem and provided an explanation. If there is a note about the issue, is it a good one? Can you think of a way to make the statblock match the portfolio better? If there isn't, make a note of it yourself.

In addition to checking the actual portfolios, check everything from steps #1-3 of the "testing encounter libraries" section below. Make a note of any issues.

Once you've looked over everything in the module, make your list and send it to us. We'll pass it on to the original author, who will fix things. They should get you a new version of the module once the problems are fixed - once that's done, verify the issues you noted are fixed, or that you agree with the author on why they shouldn't be fixed. If there are disagreements, contact us and we'll resolve them.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form. On the NPC tab, make sure that the creature doesn't show any "default" NPC info for the race - that doesn't apply here, and we don't want it to show up on the statblock, so delete it.

If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

If you imported a creature from the bestiary, and customized it to fit the statblock in the book, you'll likely have to delete some of the chunks of info on the NPC tab to make it match the statblock (e.g. the statblock in the book likely won't show ecology, treasure, etc if it's for a specific NPC). If you don't have to customize the creature, the book likely won't show the statblock, so don't delete the NPC info.

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do make sure it's noted down. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

PreReq Element (Data)

2017-05-21T16:12:43Z

Colen:

{{contextmulti|Kit Reference}}

==The "prereq" Element==

You can establish dependencies wherein certain things require specific conditions to be satisfied by their prospective container in order to be added. These conditions are referred to as [[Pre-Requisites]] and are always tested against the prospective container for a thing. Each pre-requisite is specified through the use of a "prereq" element. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|message
|Text – Specifies the error message displayed to the user within the validation report when the pre-requisite is not satisfied.
|-
|iserror
|(Optional) Boolean – Indicates whether the failing the pre-requisite is considered to an error or merely a warning. This only applies if the user chooses to ignore a failed pre-requisite and add the thing to the container anyways. Default: "yes".
|-
|onlyonce
|(Optional) Boolean – Indicates whether the pre-requisite should only be reported to the user a single time if it fails. This is important for situations where the pre-requisite is assigned to a thing that is added to a container multiple times, such as class levels within the d20 System. Default: "no".
|-
|issilent
|(Optional) Boolean – Indicates whether the pre-requisite should report an error message to the user if failed. In some cases, you'll simply want to properly highlight picks as invalid within the interface without reporting individual errors. In such cases, you can have the pre-requisite perform its tests and mark picks as invalid, but suppress any actual message. Default: "no".
|-
|}

The "prereq" element also possesses child elements that pertain to the handling of the requirement. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#match|match]]
|An optional "match" element may appear as defined by the given link. This element defines a [[Match Tag Expression]] that must be satisfied in order for the pre-requisite to be assigned to each thing. If omitted, the pre-requisite is applied to all derived things.
{{important}}This element is only applicable when the pre-requisite is defined within a component. In all other cases, this element may not be specified.
|-
|class="leftnormal"|[[#test|test]]
|An optional "test" element may appear as defined by the given link. This element defines a [[Container Tag Expression]] that determines whether the pre-requisite is satisfied. If omitted, the pre-requisite is assumed to satisfy this test.
|-
|class="leftnormal"|[[#validate|validate]]
|An optional "valid" element may appear as defined by the given link. This element defines a [[Validate Script]] that determines whether the pre-requisite is satisfied. If omitted, the pre-requisite is assumed to satisfy this test.
|-
|}

==The "match" Element{{anchor|match}}==

The "match" element defines the [[Match Tag Expression|Match tag expression]] that determines whether a particular thing is assigned the pre-requisite. The tag expression is applied against each thing derived from the component, and the pre-requisite is only assigned to things that satisfy the tag expression. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Match tag expression.
|-
|}

==The "test" Element{{anchor|test}}==

The "test" element defines the [[Container Tag Expression|Container tag expression]] that determines whether the pre-requisite is satisfied. The tag expression is applied against all the tags of the container, and the pre-requisite is considered valid if the tag expression is satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Container tag expression.
|-
|}

==The "validate" Element{{anchor|validate}}==

The "validate" element defines the [[Validate Script|Validate script]] that determines whether the pre-requisite is satisfied. The script is applied against the container, and the pre-requisite is considered valid if the script reports the container as valid. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Validate script.
|-
|}

==Example==

The following example demonstrates what an "prereq" element might look like. All default values are assumed for optional attributes.

<pre>
<prereq message="Requirement Failed.">
<valid>
@valid = 1
</valid>
</prereq>
</pre>

5th Edition Best Practices

2017-05-04T20:40:04Z

Colen: Created page with "List goes here!"

List goes here!

Pathfinder RPG Best Practices

2017-03-23T20:50:31Z

Colen: /* Deliverable 1 - Create portfolios for every encounter and NPC in the module */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== Only use official LWD content when creating data files or portfolios ==
When building data files or entering portfolios, make sure you don't have any "third party" data files installed. Content in "third party" data files isn't available to everyone, and can cause problems with what you're entering. You can check to make sure you don't have any installed by going to Tools -> Manage Third Party Updates in Hero Lab.

If you do have third party content installed, you should either delete it before working on stuff for us, or download a separate copy of the Pathfinder game system that you use to work on stuff for us. You can do this by downloading the latest Pathfinder update from the "Find Updates" screen, then changing the folder at the bottom-left of the screen to something like "pathfinder_lwd". Make sure you edit all portfolios only with the "pathfinder_lwd" version of Pathfinder, to avoid introducing or referencing third party content.

== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Details to Check for Weapons, Armor, Magic Items, and Gear =

* If there is equipment in this book from an exotic source, like high-tech items, or stone-age items, or firearms, in the Configure Hero settings, go to the "Equipment, Weapons & Armor to show" section, and turn on the option(s) that should hide this exotic content. Then, search the various tables for content from this book, and make sure that it is hidden as intended. If not, set the appropriate tag in the "Special Groupings" list for the category.

* Did you create any new weapons that are helper items or variants of an existing weapon? If so, add the weapon focus feat, and then double-check that none of the helper weapons show up there as a selection option. (To check this, search for items from the book and make sure that nothing appears in the tables that shouldn't.)

* In each table where you've added new content, filter to only this new book, and look at what categories your new content fits in to - are they sorted under the correct headers?

* Go to the weapons, armor, magic, and gear tabs, and filter for "- no description -" (note the spaces between the - and the words). Make sure none of the content from your book is among this material - everything new should have a description.

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables which must be submitted before a project is completed, which should be worked on in parallel.

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Please keep the following in mind when entering portfolios:

* Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

* Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

* If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

* Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

* When building an NPC, you'll need to reverse-engineer the Hero Lab character from the statblock. For example, the character's hit points will come from a combination of class levels, favored class bonuses, and other sources - use average hit points for the class levels (which on NPCs, alternate from one level to the next). Generally favored class bonuses will be used to add additional hit points, but not always.

* Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

* For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

* A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

* In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

* If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

* Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

* Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

* Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

* If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

# if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.
# If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

* Make sure to enter text that's relevant during combat for the NPC (usually just the "Morale" or "During Combat" sections from the statblock, which should be entered on the NPC tab), but '''don't''' enter any "Character" or "Development" text that appears around the statblock. Text from those sections shouldn't be included in the Hero Lab portfolio (this is a change from what we've done in the past).

* On the Personal tab, include any portrait of the character from the book. If you can't extract those images from the PDF using a tool like Photoshop, let us know and we can supply them. If no portrait is provided in the book, just leave it as the default portrait from the Encounter Builder.

== Deliverable 2 - Notes ==

As you work on the module, create a list of any differences between what the module shows, and what Hero Lab shows. For example, if skills are off, note that, and see if you can figure out why it happened - that might lead you to think of a different way to do them so they'll be correct. This file is important because it will be used by whoever is checking your work.

== Submission ==

Submit both pieces of the project to us - portfolios and notes file. Don't submit until the portfolios are complete and checked to make sure they're correct.

= Checking Encounter Libraries =

Once both deliverables for an encounter library have been submitted (see above), we'll a different person to check the work. If you're checking someone else's encounter libraries, you need to find places they did something wrong.

Compare the statblocks listed in the module with what's in Hero Lab - do the details in the module match what's in HL? If not, consult the notes file you got along with the portfolios and see if the author noticed the problem and provided an explanation. If there is a note about the issue, is it a good one? Can you think of a way to make the statblock match the portfolio better? If there isn't, make a note of it yourself.

In addition to checking the actual portfolios, check everything from steps #1-3 of the "testing encounter libraries" section below. Make a note of any issues.

Once you've looked over everything in the module, make your list and send it to us. We'll pass it on to the original author, who will fix things. They should get you a new version of the module once the problems are fixed - once that's done, verify the issues you noted are fixed, or that you agree with the author on why they shouldn't be fixed. If there are disagreements, contact us and we'll resolve them.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form. On the NPC tab, make sure that the creature doesn't show any "default" NPC info for the race - that doesn't apply here, and we don't want it to show up on the statblock, so delete it.

If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

If you imported a creature from the bestiary, and customized it to fit the statblock in the book, you'll likely have to delete some of the chunks of info on the NPC tab to make it match the statblock (e.g. the statblock in the book likely won't show ecology, treasure, etc if it's for a specific NPC). If you don't have to customize the creature, the book likely won't show the statblock, so don't delete the NPC info.

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do make sure it's noted down. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2017-02-22T17:23:51Z

Colen: /* Deliverable 1 - Create portfolios for every encounter and NPC in the module */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== Only use official LWD content when creating data files or portfolios ==
When building data files or entering portfolios, make sure you don't have any "third party" data files installed. Content in "third party" data files isn't available to everyone, and can cause problems with what you're entering. You can check to make sure you don't have any installed by going to Tools -> Manage Third Party Updates in Hero Lab.

If you do have third party content installed, you should either delete it before working on stuff for us, or download a separate copy of the Pathfinder game system that you use to work on stuff for us. You can do this by downloading the latest Pathfinder update from the "Find Updates" screen, then changing the folder at the bottom-left of the screen to something like "pathfinder_lwd". Make sure you edit all portfolios only with the "pathfinder_lwd" version of Pathfinder, to avoid introducing or referencing third party content.

== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Details to Check for Weapons, Armor, Magic Items, and Gear =

* If there is equipment in this book from an exotic source, like high-tech items, or stone-age items, or firearms, in the Configure Hero settings, go to the "Equipment, Weapons & Armor to show" section, and turn on the option(s) that should hide this exotic content. Then, search the various tables for content from this book, and make sure that it is hidden as intended. If not, set the appropriate tag in the "Special Groupings" list for the category.

* Did you create any new weapons that are helper items or variants of an existing weapon? If so, add the weapon focus feat, and then double-check that none of the helper weapons show up there as a selection option. (To check this, search for items from the book and make sure that nothing appears in the tables that shouldn't.)

* In each table where you've added new content, filter to only this new book, and look at what categories your new content fits in to - are they sorted under the correct headers?

* Go to the weapons, armor, magic, and gear tabs, and filter for "- no description -" (note the spaces between the - and the words). Make sure none of the content from your book is among this material - everything new should have a description.

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables which must be submitted before a project is completed, which should be worked on in parallel.

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Please keep the following in mind when entering portfolios:

* Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

* Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

* If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

* Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

* When building an NPC, you'll need to reverse-engineer the Hero Lab character from the statblock. For example, the character's hit points will come from a combination of class levels, favored class bonuses, and other sources - use average hit points for the class levels (which on NPCs, alternate from one level to the next). Generally favored class bonuses will be used to add additional hit points, but not always.

* Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

* For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

* A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

* In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

* If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

* Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

* Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

* Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

* If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

# if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.
# If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

* Make sure to enter text that's relevant during combat for the NPC (usually just the "Morale" or "During Combat" sections from the statblock, which should be entered on the NPC tab), but '''don't''' enter any "Character" or "Development" text that appears around the statblock. Text from those sections shouldn't be included in the Hero Lab portfolio (this is a change from what we've done in the past).

== Deliverable 2 - Notes ==

As you work on the module, create a list of any differences between what the module shows, and what Hero Lab shows. For example, if skills are off, note that, and see if you can figure out why it happened - that might lead you to think of a different way to do them so they'll be correct. This file is important because it will be used by whoever is checking your work.

== Submission ==

Submit both pieces of the project to us - portfolios and notes file. Don't submit until the portfolios are complete and checked to make sure they're correct.

= Checking Encounter Libraries =

Once both deliverables for an encounter library have been submitted (see above), we'll a different person to check the work. If you're checking someone else's encounter libraries, you need to find places they did something wrong.

Compare the statblocks listed in the module with what's in Hero Lab - do the details in the module match what's in HL? If not, consult the notes file you got along with the portfolios and see if the author noticed the problem and provided an explanation. If there is a note about the issue, is it a good one? Can you think of a way to make the statblock match the portfolio better? If there isn't, make a note of it yourself.

In addition to checking the actual portfolios, check everything from steps #1-3 of the "testing encounter libraries" section below. Make a note of any issues.

Once you've looked over everything in the module, make your list and send it to us. We'll pass it on to the original author, who will fix things. They should get you a new version of the module once the problems are fixed - once that's done, verify the issues you noted are fixed, or that you agree with the author on why they shouldn't be fixed. If there are disagreements, contact us and we'll resolve them.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form. On the NPC tab, make sure that the creature doesn't show any "default" NPC info for the race - that doesn't apply here, and we don't want it to show up on the statblock, so delete it.

If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

If you imported a creature from the bestiary, and customized it to fit the statblock in the book, you'll likely have to delete some of the chunks of info on the NPC tab to make it match the statblock (e.g. the statblock in the book likely won't show ecology, treasure, etc if it's for a specific NPC). If you don't have to customize the creature, the book likely won't show the statblock, so don't delete the NPC info.

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do make sure it's noted down. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2017-01-08T00:58:55Z

Colen: /* General Issues */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== Only use official LWD content when creating data files or portfolios ==
When building data files or entering portfolios, make sure you don't have any "third party" data files installed. Content in "third party" data files isn't available to everyone, and can cause problems with what you're entering. You can check to make sure you don't have any installed by going to Tools -> Manage Third Party Updates in Hero Lab.

If you do have third party content installed, you should either delete it before working on stuff for us, or download a separate copy of the Pathfinder game system that you use to work on stuff for us. You can do this by downloading the latest Pathfinder update from the "Find Updates" screen, then changing the folder at the bottom-left of the screen to something like "pathfinder_lwd". Make sure you edit all portfolios only with the "pathfinder_lwd" version of Pathfinder, to avoid introducing or referencing third party content.

== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Details to Check for Weapons, Armor, Magic Items, and Gear =

* If there is equipment in this book from an exotic source, like high-tech items, or stone-age items, or firearms, in the Configure Hero settings, go to the "Equipment, Weapons & Armor to show" section, and turn on the option(s) that should hide this exotic content. Then, search the various tables for content from this book, and make sure that it is hidden as intended. If not, set the appropriate tag in the "Special Groupings" list for the category.

* Did you create any new weapons that are helper items or variants of an existing weapon? If so, add the weapon focus feat, and then double-check that none of the helper weapons show up there as a selection option. (To check this, search for items from the book and make sure that nothing appears in the tables that shouldn't.)

* In each table where you've added new content, filter to only this new book, and look at what categories your new content fits in to - are they sorted under the correct headers?

* Go to the weapons, armor, magic, and gear tabs, and filter for "- no description -" (note the spaces between the - and the words). Make sure none of the content from your book is among this material - everything new should have a description.

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables which must be submitted before a project is completed, which should be worked on in parallel.

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

When building an NPC, you'll need to reverse-engineer the Hero Lab character from the statblock. For example, the character's hit points will come from a combination of class levels, favored class bonuses, and other sources - use average hit points for the class levels (which on NPCs, alternate from one level to the next). Generally favored class bonuses will be used to add additional hit points, but not always.

Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

1) if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.

2) If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

== Deliverable 2 - Notes ==

As you work on the module, create a list of any differences between what the module shows, and what Hero Lab shows. For example, if skills are off, note that, and see if you can figure out why it happened - that might lead you to think of a different way to do them so they'll be correct. This file is important because it will be used by whoever is checking your work.

== Submission ==

Submit both pieces of the project to us - portfolios and notes file. Don't submit until the portfolios are complete and checked to make sure they're correct.

= Checking Encounter Libraries =

Once both deliverables for an encounter library have been submitted (see above), we'll a different person to check the work. If you're checking someone else's encounter libraries, you need to find places they did something wrong.

Compare the statblocks listed in the module with what's in Hero Lab - do the details in the module match what's in HL? If not, consult the notes file you got along with the portfolios and see if the author noticed the problem and provided an explanation. If there is a note about the issue, is it a good one? Can you think of a way to make the statblock match the portfolio better? If there isn't, make a note of it yourself.

In addition to checking the actual portfolios, check everything from steps #1-3 of the "testing encounter libraries" section below. Make a note of any issues.

Once you've looked over everything in the module, make your list and send it to us. We'll pass it on to the original author, who will fix things. They should get you a new version of the module once the problems are fixed - once that's done, verify the issues you noted are fixed, or that you agree with the author on why they shouldn't be fixed. If there are disagreements, contact us and we'll resolve them.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form. On the NPC tab, make sure that the creature doesn't show any "default" NPC info for the race - that doesn't apply here, and we don't want it to show up on the statblock, so delete it.

If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

If you imported a creature from the bestiary, and customized it to fit the statblock in the book, you'll likely have to delete some of the chunks of info on the NPC tab to make it match the statblock (e.g. the statblock in the book likely won't show ecology, treasure, etc if it's for a specific NPC). If you don't have to customize the creature, the book likely won't show the statblock, so don't delete the NPC info.

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do make sure it's noted down. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

ChooserTable Element (Data)

2017-01-03T18:43:24Z

Colen: /* The "chooser_table" Element */

{{context|Kit Reference|Data File Reference|Portal Element (Data)}}

==The "chooser_table" Element==

Choosers are similar to thing-based menus in some ways, as they allow the user to select one thing or pick from a list that is determined dynamically. One key difference with choosers is that any selected thing/pick is added to the container as a new pick. If a pick is selected, a new pick derived from the same thing is added. Another key difference is that the available things/picks are displayed for selection in a "choose form", allowing each object to be presented with detailed information. The "chooser" mechanism is ideal for selecting facets like race, profession, archetype, etc. Each chooser is defined via the use of the "chooser_table" element. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|component
|Id – Specifies the unique id of the component that all selectable objects must be derived from.
|-
|choosetemplate
|Id – Specifies the unique id of the template to be used for displaying selectable objects.
|-
|choosepicks
|(Optional) Set – Designates whether the selectable objects consist of things or picks, and, if the latter, where the list of picks is retrieved from. Must be one of these values:
<ul class="sets">
<li>thing – The selectable objects are things.</li>
<li>container – The selectable objects are picks from the implicitly identified container. If the containing scene is a form associated with a gizmo, the gizmo is used, else the actor is used.</li>
<li>hero – The selectable objects are picks from the active actor.</li>
<li>actor – Same as "hero".</li>
<li>Default: "thing".</li>
|-
|choosesortset
|(Optional) Id – Specifies the unique id of the sort set to be used for sequencing all of the objects presented for selection. If empty, all objects are sorted by name. Default: Empty.
|-
|choosegapx
|(Optional) Integer – Specifies the gap along the X-axis to insert between items presented for selection. Default: "0".
|-
|choosegapy
|(Optional) Integer – Specifies the gap along the Y-axis to insert between items presented for selection. Default: "0".
|-
|descwidth
|(Optional) Integer – Specifies the width of the reserved "description" area on the right within the choose form. Some items need more width for lengthy descriptions and some do not, so you can control this as you see fit. Default: "250".
|-
|buytemplate
|(Optional) Id – Specifies the unique id of the template to be shown in the lower right corner of the choose form for controlling the details of a purchase transaction. If empty, no buy template is utilized. Default: Empty.
|-
|xactspecial
|(Optional) Integer – When a buy template is shared between two or more portals or things, the template behavior may need to be tailored based on the usage. If this need arises, this attribute specifies a unique value that identifies this particular usage. By assigning a different value to each usage and keying on it within the template's Position script, you can tailor the template appropriately. Default: "0".
|-
|linkage
|(Optional) Id – Specifies the unique id of a thing that will be used as a linkage. When a new pick is added via the chooser, that pick has an automatic linkage setup to any existing pick derived from the specified thing. If no derived pick exists when the new pick is added, no linkage is ever created. If empty, no linkage is established. Default: Empty.
|-
|showupdate
|(Optional) Boolean – Indicates whether the chooser needs to be dynamically updated after any modification to the actor so that the influence of other changes are always visually reflected to the user, such as through color highlighting. Default: "no". 
{{note}}This option can significantly slow down display updates on slower computers, so only enable this if truly necessary.
|-
|candidatepick
|(Optional) Id – Specifies the unique id of a pick that will contain a dynamically generated [[Candidate Tag Expression|Candidate tag expression]] for use in determining the list of available objects to choose from. If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|candidatefield
|(Optional) Id – Specifies the unique id of a text-based field that contains the [[Candidate Tag Expression|Candidate tag expression]] used to determine the list of available objects to choose from. This field must exist within the pick identified by the "candidatepick" attribute (above). If empty, the "candidate" child element defines the tag expression to use. Default: Empty.
|-
|prereqtarget
|(Optional) Set – Designates the container against which all pre-requisite tests need to be performed when determining the list of items available for selection. When displacement is utilized, pre-requisites need to be tested against the container to which the new picks will ultimately be added. Must be one of these values:
<ul class="sets">
<li>container – The default parent container is used.</li>
<li>parent – The next parent up the hierarchy is used, which parallels the corresponding displacement target.</li>
<li>hero – The top-level hero is used, which parallels the corresponding displacement target.</li>
<li>Default: "container".</li>
</ul>
|-
|empty
|(Optional) Text – Specifies the text message to be displayed if the user attempts to select an option and there are no available items to choose from. If empty, a default message is displayed. Default: Empty.
|-
|showlabel
|(Optional) Boolean – (iPad only) Indicates whether the label displaying the current selection of the menu should be shown. This is used when you just want the menu control to be used as a button to make a selection which will be displayed some other way. Default: "yes".
|-
|}

{{note}}Choosers possess a "buy" template, but there is no way to properly "sell" an item selected via a chooser. The reason for this is to allow the "buy" template to be used for customization purposes instead of actually buying and selling gear. The same mechanism can be used to allow the user to configure the item selected via the chooser, such as providing an edit or menu portal to specify an important facet of the selected item.

The "chooser_table" element also possesses child elements that define additional behaviors of the portal. The list of these child elements is below and must appear in the order shown. Click on the link to access the details for each element.

:{| class="infotable"
|class="leftnormal"|[[#candidate|candidate]]
|An optional "candidate" element may appear as defined by the given link. This element defines a [[Candidate Tag Expression]] for the portal.
|-
|[[#needtag|needtag]]
|Zero or more "needtag" elements may appear as defined by the given link. This element defines a tag relationship that must exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#denytag|denytag]]
|Zero or more "denytag" elements may appear as defined by the given link. This element defines a tag relationship that must '''not''' exist between a prospective object and the container in order to list the object among the available items.
|-
|[[#xacttag|xacttag]]
|Zero or more "xacttag" elements may appear as defined by the given link. This element defines a tag that is assigned to the transaction pick while the choose form is visible.
|-
|[[#secondary|secondary]]
|An optional "secondary" element may appear as defined by the given link. This element defines a [[Secondary Tag Expression]] that is associated with every new pick added via the portal.
|-
|[[#existence|existence]]
|An optional "existence" element may appear as defined by the given link. This element defines an [[Existence Tag Expression]] that is associated with every new pick added via the portal.
|-
|[[AutoTag Element (Data)|autotag]]
|Zero or more "autotag" elements may appear as defined by the given link. This element specifies tags that are automatically assigned to each added thing.
|-
|[[#chosen|chosen]]
|An optional "chosen" element may appear as defined by the given link. This element defines a [[Chosen Script]] for the portal.
|-
|[[#titlebar|titlebar]]
|An optional "titlebar" element may appear as defined by the given link. This element defines a [[TitleBar Script]] for the portal.
|-
|[[#description|description]]
|An optional "description" element may appear as defined by the given link. This element defines a [[Description Script]] for the portal.
|-
|[[#change|change]]
|An optional "change" element may appear as defined by the given link. This element defines a [[Change Script]] for the portal.
|-
|}

==The "candidate" Element{{anchor|candidate}}==

The "candidate" element defines a [[Candidate Tag Expression]] for the portal that limits the set of things/picks that are available for selection. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|TagExpr – Specifies the code comprising the Candidate tag expression.
|-
|}

==The "needtag" Element{{anchor|needtag}}==

The "needtag" element defines a tag relationship that must exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it has at least one matching tag with the same id in a separate tag group. If the tag is not found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "denytag" Element{{anchor|denytag}}==

The "denytag" element defines a tag relationship that must '''not''' exist between the object to be added and the prospective container. Tags from one tag group are enumerated within the container, then the object is tested to make sure that it does not possess any matching tags with the same ids in a separate tag group. If any matching tags are found, the object is not valid for selection and omitted from the available list. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|container
|Id – Specifies the unique id of the tag group to utilize within the container.
|-
|thing
|Id – Specifies the unique id of the tag group to check within the thing/pick.
|-
|usehero
|(Optional) Boolean – Indicates whether the container tags are pulled from the prospective container for the new pick or the hero. This distinction can be important when using displacement. Default: "no".
|-
|}

==The "xacttag" Element{{anchor|xacttag}}==

The "xacttag" element specifies a tag that is automatically added to the transaction pick while the choose form is shown. These tags allow you to indicate contextual information about where the buy template is being used so that you can tailor the behavior appropriately. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|tag
|Id – Specifies the unique id of the tag to define within the tag group "transact".
|-
|}

==The "secondary" Element{{anchor|secondary}}==

The "secondary" element defines a [[Secondary Tag Expression]] that is automatically associated with every new pick added via the portal. This new tag expression is treated like an additional [[Container Tag Expression]] for the pick that must also be satisfied. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "existence" Element{{anchor|existence}}==

The "existence" element defines an [[Existence Tag Expression]] that is automatically associated with every new pick added via the portal. If a pick ever fails to satisfy the tag expression during an evaluation cycle, the pick is automatically deleted. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|phase
|(Optional) Id – Specifies the unique id of the evaluation phase during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|priority
|Integer – Specifies the evaluation priority during which the tag expression is tested. If empty, the default timing is used from the definition file. Default: Empty.
|-
|PCDATA
|TagExpr – Specifies the code comprising the Secondary tag expression.
|-
|}

==The "chosen" Element{{anchor|chosen}}==

The "chosen" element defines a [[Chosen Script]] for the portal, which synthesizes the text to be displayed as the chosen item within the portal. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Chosen script.
|-
|}

==The "titlebar" Element{{anchor|titlebar}}==

The "titlebar" element defines a [[TitleBar Script]] for the portal, which synthesizes the text to be displayed at the top of the choose form. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the TitleBar script.
|-
|}

==The "description" Element{{anchor|description}}==

The "description" element defines a [[Description Script]] for the portal, which synthesizes the text to be displayed within the description region of the choose form for the currently selected item on the left. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Description script.
|-
|}

==The "change" Element{{anchor|change}}==

The "change" element defines a [[Change Script]] for the portal that is invoked whenever the user selects a new choice from the list of options. This script allows the implications of the new selection to be integrated and the display updated. The complete list of attributes for this element is below.

:{| class="infotable"
|class="leftnormal"|PCDATA
|Script – Specifies the code comprising the Change script.
|-
|}

==Example==

The following example demonstrates what a choosertable portal might look like. All default values are assumed for optional attributes.

<pre>
<portal id="stRace" style="chsNormal" width="110">
<chooser_table component="Race" choosetemplate="LargeItem">
<chosen><![CDATA[
if (@ispick = 0) then
@text = "{text ff0000}Select Race"
else
@text = "Race: " & field[name].text
endif
]]></chosen>
<titlebar>
@text = "Choose the race for your character"
</titlebar>
</chooser_table>
</portal>
</pre>

5th Edition SRD Best Practices

2016-12-14T14:59:39Z

Colen: /* First Steps */

= Unique Id Prefix =
When choosing unique ids for the things you're creating, you should include a two-letter prefix for any things from a different publisher. This helps avoid "unique id collisions" with content that users have entered themselves, because they're unlikely to have used the same prefix as a publisher does.

This prefix can be set in the editor, by going to Tools -> Set User Identifier. It should come after the "type" of the thing, so for example the id for a Kobold Press feat would start "fKP", like "fKPPowAtt" for Power Attack from Kobold Press.

Here is the current list of id prefixes for different publishers:

* FG - Frog God Games
* GR - Green Ronin Publishing
* HG - Hammerdog Games
* KP - Kobold Press
* LG - Legendary Games
* RP - Rite Publishing

Make sure the unique id prefix is set correctly for every thing you submit.

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives resistance to fire damage.

::Sample Abilities: Elven Weapon Training, Expertise

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability grants advantage on saving throws against being frightened

::Sample Abilities: Brave, Tinker

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a bonus action, this ability grants a bonus on melee weapon damage rolls for one minute.
::Sample Rage

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Feats
:Classes
:Races
:Subraces
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

= Creating Races =
Races are among the most complex, fiddly things in the 5th Edition SRD (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== First Steps ==
While there are many steps in creating a race, certain things are important to handle first, because they factor into many other things.
:Ability modifiers
:Challenge Rating/CR
:Size
:Number of Hit Dice (If a creature's Hit Dice are not the standard size for the race's size, these need to be set as well.)

An optional but highly recommended step is to turn on one of the "Show stat block" options on the configure hero screen. This will show you the race's stat block and make it easier to spot differences. Note that you will have to reload before any changes take effect, either the full dataset with the Quick Reload shortcut, Ctrl+R, or only the specific race using the Test Now button in the editor.

== Race Descriptions ==

If the race has a short description at the top of the page, like many monsters in the Tome of Beasts do (usually in italics), enter that short description text in the new "Description Text" field in the editor, instead of the main description text. This allows us to display it as summary text in front of the statblock.

== Spellcasting /Innate Spellcasting ==
If a creature has the Spellcasting or Innate Spellcasting special abilities, these helper abilites will need to be bootstrapped separately from the spells the creature can cast. A custom header can be set using the rSplHead field on the race. (If a creature has '''both''' Spellcasting and Innate Spellcasting, then separate custom headers for each ability will need to be set using the CustDesc the helper abilities.) The following substitution tokens are recognized by the script that generates the spell headers:
: #name# - Creature's name. Defaults to the race name, if something else is wanted set it in the abText field on the bootstrapped helper ability.
: #lev#" - Creature's caster level.
: #abil# - Name of the creature's spellcasting ability.
: #splstats# = The creature's spell attack and DC.
: #dc# - DC of the creature's spells.
: #atk# - Creature's spell attack bonus.
: #class# - The class a creature with Spellcasting draws its spells from.

See the Deva for an example of a creature with Innate Spellcasting.

== Substitution Tokens ==
Several substitution tokens have been set up that can be used in ability descriptions, and in on-hit effects for natural attacks.
: #StandardDC# - Substitutes the value of the abDC.
: #abSave# - Substitutes the names of any abSave tags present.
: #PassiveDC# - Substitutes a passive DC value, where the passive value of a skill is used. For example, when used in conjunction with the PassiveDC.skStealth will insert the creature's passive DC value. Most often this is used for grapple DCs, which is the higher of the passive Strength (Athletics) or Dexterity (Acrobatics) values.

5th Edition SRD Best Practices

2016-12-14T14:55:47Z

Colen: /* Testing */

= Unique Id Prefix =
When choosing unique ids for the things you're creating, you should include a two-letter prefix for any things from a different publisher. This helps avoid "unique id collisions" with content that users have entered themselves, because they're unlikely to have used the same prefix as a publisher does.

This prefix can be set in the editor, by going to Tools -> Set User Identifier. It should come after the "type" of the thing, so for example the id for a Kobold Press feat would start "fKP", like "fKPPowAtt" for Power Attack from Kobold Press.

Here is the current list of id prefixes for different publishers:

* FG - Frog God Games
* GR - Green Ronin Publishing
* HG - Hammerdog Games
* KP - Kobold Press
* LG - Legendary Games
* RP - Rite Publishing

Make sure the unique id prefix is set correctly for every thing you submit.

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives resistance to fire damage.

::Sample Abilities: Elven Weapon Training, Expertise

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability grants advantage on saving throws against being frightened

::Sample Abilities: Brave, Tinker

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a bonus action, this ability grants a bonus on melee weapon damage rolls for one minute.
::Sample Rage

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Feats
:Classes
:Races
:Subraces
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

= Creating Races =
Races are among the most complex, fiddly things in the 5th Edition SRD (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== First Steps ==
While there are many steps in creating a race, certain things are important to handle first, because they factor into many other things.
:Ability modifiers
:Challenge Rating/CR
:Size
:Number of Hit Dice (If a creature's Hit Dice are not the standard size for the race's size, these need to be set as well.)

An optional but highly recommended step is to turn on one of the "Show stat block" options on the configure hero screen. This will show you the race's stat block and make it easier to spot differences. Note that you will have to reload before any changes take effect, either the full dataset with the Quick Reload shortcut, Ctrl+R, or only the specific race using the Test Now button in the editor.

== Spellcasting /Innate Spellcasting ==
If a creature has the Spellcasting or Innate Spellcasting special abilities, these helper abilites will need to be bootstrapped separately from the spells the creature can cast. A custom header can be set using the rSplHead field on the race. (If a creature has '''both''' Spellcasting and Innate Spellcasting, then separate custom headers for each ability will need to be set using the CustDesc the helper abilities.) The following substitution tokens are recognized by the script that generates the spell headers:
: #name# - Creature's name. Defaults to the race name, if something else is wanted set it in the abText field on the bootstrapped helper ability.
: #lev#" - Creature's caster level.
: #abil# - Name of the creature's spellcasting ability.
: #splstats# = The creature's spell attack and DC.
: #dc# - DC of the creature's spells.
: #atk# - Creature's spell attack bonus.
: #class# - The class a creature with Spellcasting draws its spells from.

See the Deva for an example of a creature with Innate Spellcasting.

== Substitution Tokens ==
Several substitution tokens have been set up that can be used in ability descriptions, and in on-hit effects for natural attacks.
: #StandardDC# - Substitutes the value of the abDC.
: #abSave# - Substitutes the names of any abSave tags present.
: #PassiveDC# - Substitutes a passive DC value, where the passive value of a skill is used. For example, when used in conjunction with the PassiveDC.skStealth will insert the creature's passive DC value. Most often this is used for grapple DCs, which is the higher of the passive Strength (Athletics) or Dexterity (Acrobatics) values.

Pathfinder RPG Best Practices

2016-12-13T15:12:26Z

Colen: /* Details to check for Weapons, Armor, Magic Items, and Gear */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Details to Check for Weapons, Armor, Magic Items, and Gear =

* If there is equipment in this book from an exotic source, like high-tech items, or stone-age items, or firearms, in the Configure Hero settings, go to the "Equipment, Weapons & Armor to show" section, and turn on the option(s) that should hide this exotic content. Then, search the various tables for content from this book, and make sure that it is hidden as intended. If not, set the appropriate tag in the "Special Groupings" list for the category.

* Did you create any new weapons that are helper items or variants of an existing weapon? If so, add the weapon focus feat, and then double-check that none of the helper weapons show up there as a selection option. (To check this, search for items from the book and make sure that nothing appears in the tables that shouldn't.)

* In each table where you've added new content, filter to only this new book, and look at what categories your new content fits in to - are they sorted under the correct headers?

* Go to the weapons, armor, magic, and gear tabs, and filter for "- no description -" (note the spaces between the - and the words). Make sure none of the content from your book is among this material - everything new should have a description.

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables which must be submitted before a project is completed, which should be worked on in parallel.

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

When building an NPC, you'll need to reverse-engineer the Hero Lab character from the statblock. For example, the character's hit points will come from a combination of class levels, favored class bonuses, and other sources - use average hit points for the class levels (which on NPCs, alternate from one level to the next). Generally favored class bonuses will be used to add additional hit points, but not always.

Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

1) if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.

2) If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

== Deliverable 2 - Notes ==

As you work on the module, create a list of any differences between what the module shows, and what Hero Lab shows. For example, if skills are off, note that, and see if you can figure out why it happened - that might lead you to think of a different way to do them so they'll be correct. This file is important because it will be used by whoever is checking your work.

== Submission ==

Submit both pieces of the project to us - portfolios and notes file. Don't submit until the portfolios are complete and checked to make sure they're correct.

= Checking Encounter Libraries =

Once both deliverables for an encounter library have been submitted (see above), we'll a different person to check the work. If you're checking someone else's encounter libraries, you need to find places they did something wrong.

Compare the statblocks listed in the module with what's in Hero Lab - do the details in the module match what's in HL? If not, consult the notes file you got along with the portfolios and see if the author noticed the problem and provided an explanation. If there is a note about the issue, is it a good one? Can you think of a way to make the statblock match the portfolio better? If there isn't, make a note of it yourself.

In addition to checking the actual portfolios, check everything from steps #1-3 of the "testing encounter libraries" section below. Make a note of any issues.

Once you've looked over everything in the module, make your list and send it to us. We'll pass it on to the original author, who will fix things. They should get you a new version of the module once the problems are fixed - once that's done, verify the issues you noted are fixed, or that you agree with the author on why they shouldn't be fixed. If there are disagreements, contact us and we'll resolve them.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form. On the NPC tab, make sure that the creature doesn't show any "default" NPC info for the race - that doesn't apply here, and we don't want it to show up on the statblock, so delete it.

If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

If you imported a creature from the bestiary, and customized it to fit the statblock in the book, you'll likely have to delete some of the chunks of info on the NPC tab to make it match the statblock (e.g. the statblock in the book likely won't show ecology, treasure, etc if it's for a specific NPC). If you don't have to customize the creature, the book likely won't show the statblock, so don't delete the NPC info.

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do make sure it's noted down. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-12-13T15:12:14Z

Colen: /* Entering Stock Heroes */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Details to check for Weapons, Armor, Magic Items, and Gear =

* If there is equipment in this book from an exotic source, like high-tech items, or stone-age items, or firearms, in the Configure Hero settings, go to the "Equipment, Weapons & Armor to show" section, and turn on the option(s) that should hide this exotic content. Then, search the various tables for content from this book, and make sure that it is hidden as intended. If not, set the appropriate tag in the "Special Groupings" list for the category.

* Did you create any new weapons that are helper items or variants of an existing weapon? If so, add the weapon focus feat, and then double-check that none of the helper weapons show up there as a selection option. (To check this, search for items from the book and make sure that nothing appears in the tables that shouldn't.)

* In each table where you've added new content, filter to only this new book, and look at what categories your new content fits in to - are they sorted under the correct headers?

* Go to the weapons, armor, magic, and gear tabs, and filter for "- no description -" (note the spaces between the - and the words). Make sure none of the content from your book is among this material - everything new should have a description.

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables which must be submitted before a project is completed, which should be worked on in parallel.

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

When building an NPC, you'll need to reverse-engineer the Hero Lab character from the statblock. For example, the character's hit points will come from a combination of class levels, favored class bonuses, and other sources - use average hit points for the class levels (which on NPCs, alternate from one level to the next). Generally favored class bonuses will be used to add additional hit points, but not always.

Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

1) if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.

2) If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

== Deliverable 2 - Notes ==

As you work on the module, create a list of any differences between what the module shows, and what Hero Lab shows. For example, if skills are off, note that, and see if you can figure out why it happened - that might lead you to think of a different way to do them so they'll be correct. This file is important because it will be used by whoever is checking your work.

== Submission ==

Submit both pieces of the project to us - portfolios and notes file. Don't submit until the portfolios are complete and checked to make sure they're correct.

= Checking Encounter Libraries =

Once both deliverables for an encounter library have been submitted (see above), we'll a different person to check the work. If you're checking someone else's encounter libraries, you need to find places they did something wrong.

Compare the statblocks listed in the module with what's in Hero Lab - do the details in the module match what's in HL? If not, consult the notes file you got along with the portfolios and see if the author noticed the problem and provided an explanation. If there is a note about the issue, is it a good one? Can you think of a way to make the statblock match the portfolio better? If there isn't, make a note of it yourself.

In addition to checking the actual portfolios, check everything from steps #1-3 of the "testing encounter libraries" section below. Make a note of any issues.

Once you've looked over everything in the module, make your list and send it to us. We'll pass it on to the original author, who will fix things. They should get you a new version of the module once the problems are fixed - once that's done, verify the issues you noted are fixed, or that you agree with the author on why they shouldn't be fixed. If there are disagreements, contact us and we'll resolve them.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form. On the NPC tab, make sure that the creature doesn't show any "default" NPC info for the race - that doesn't apply here, and we don't want it to show up on the statblock, so delete it.

If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

If you imported a creature from the bestiary, and customized it to fit the statblock in the book, you'll likely have to delete some of the chunks of info on the NPC tab to make it match the statblock (e.g. the statblock in the book likely won't show ecology, treasure, etc if it's for a specific NPC). If you don't have to customize the creature, the book likely won't show the statblock, so don't delete the NPC info.

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do make sure it's noted down. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Authoring Examples

2016-12-08T22:29:07Z

Colen: /* What We Assume */

{{context}}
[[Category:Authoring Examples]]

==Overview==

The goal of this section is to provide concrete examples of how to create data files for whatever game system you choose. Although additional examples are included, there are two primary components of this section. The first is an examination of the Sample data files provided by the Kit, which also serve as the starting point for creating data files for your own game system. The second is a detailed walk-through that guides you through the evolution of fully operational data files for the Savage Worlds game system. Starting with the Skeleton data files, you'll witness how the entire process unfolds.

==What We Assume==

For all of the examples below, we assume that you've familiarized yourself with the rest of the Kit documentation and all of the core concepts. Regular references will be made to the terms, concepts, and mechanisms that are introduced by the Kit. At a minimum, you must be comfortable with the material presented in the [[Basic Concepts and Terminology]] section.

If you wish to actually modify any of the data files, you will need a text editor that allows you to edit XML files. If you are only viewing the files, more web browsers provide a reasonable solution for displaying the contents of XML files.

For editing, you can get by with the Notepad editor included with Windows. However, that editor is extremely limited in what it offers, so we recommend you use something with a little bit more functionality if at all possible. Numerous text editors are available for free online that will work well, while commercial tools are also available. A few options are listed below:

*Notepad++ - [http://notepad-plus.sourceforge.net]
*EditPad Lite - [http://www.editpadpro.com/editpadlite.html]
*Textpad.com - [http://www.textpad.com]
*XMLMarker - [http://www.symbolclick.com]
*BBEdit - [http://www.barebones.com/products/bbedit/index.html] (for mac users)

==Sample/Skeleton Data Files==

To simplify the creation of custom data files for a new game system, the Kit provides the Skeleton data files as a robust starting point. The Authoring Kit Sample game system provides a working example that builds directly on top of the Skeleton data files. The major facets of the Skeleton data files are discussed in their own section, which can be accessed via the link below.

*{{fl|Skeleton Data Files}}

==Savage Worlds Walk-Through==

As mentioned above, the Kit includes complete data files for the Savage Worlds game system from [http://www.greatwhitegames.com Great White Games]. We've written up a detailed walk-through of how we created these data files, using the Skeleton files as our starting point. This should provide an excellent guide for how to adapt the Skeleton files to whatever game system you have in mind. Click on the link below to follow the process from start to finish.

*{{fl|Savage Worlds Walk-Through}}

==Miscellaneous Examples==

*{{tbd}}

Authoring Examples

2016-12-08T22:28:35Z

Colen: /* What We Assume */

{{context}}
[[Category:Authoring Examples]]

==Overview==

The goal of this section is to provide concrete examples of how to create data files for whatever game system you choose. Although additional examples are included, there are two primary components of this section. The first is an examination of the Sample data files provided by the Kit, which also serve as the starting point for creating data files for your own game system. The second is a detailed walk-through that guides you through the evolution of fully operational data files for the Savage Worlds game system. Starting with the Skeleton data files, you'll witness how the entire process unfolds.

==What We Assume==

For all of the examples below, we assume that you've familiarized yourself with the rest of the Kit documentation and all of the core concepts. Regular references will be made to the terms, concepts, and mechanisms that are introduced by the Kit. At a minimum, you must be comfortable with the material presented in the [[Basic Concepts and Terminology]] section.

If you wish to actually modify any of the data files, you will need a text editor that allows you to edit XML files. If you are only viewing the files, more web browsers provide a reasonable solution for displaying the contents of XML files.

For editing, you can get by with the Notepad editor included with Windows. However, that editor is extremely limited in what it offers, so we recommend you use something with a little bit more functionality if at all possible. Numerous text editors are available for free online that will work well, while commercial tools are also available. A few options are listed below:

*Notepad++ - [http://notepad-plus.sourceforge.net]
*EditPad Lite - [http://www.editpadpro.com/editpadlite.html]
*Textpad.com - [http://www.textpad.com]
*XMLMarker - [http://www.symbolclick.com]
*Texpad - [https://www.texpadapp.com/osx] (for mac users)

==Sample/Skeleton Data Files==

To simplify the creation of custom data files for a new game system, the Kit provides the Skeleton data files as a robust starting point. The Authoring Kit Sample game system provides a working example that builds directly on top of the Skeleton data files. The major facets of the Skeleton data files are discussed in their own section, which can be accessed via the link below.

*{{fl|Skeleton Data Files}}

==Savage Worlds Walk-Through==

As mentioned above, the Kit includes complete data files for the Savage Worlds game system from [http://www.greatwhitegames.com Great White Games]. We've written up a detailed walk-through of how we created these data files, using the Skeleton files as our starting point. This should provide an excellent guide for how to adapt the Skeleton files to whatever game system you have in mind. Click on the link below to follow the process from start to finish.

*{{fl|Savage Worlds Walk-Through}}

==Miscellaneous Examples==

*{{tbd}}

5th Edition SRD Best Practices

2016-12-06T17:31:03Z

Colen: Created page with "(Fill in here)"

(Fill in here)

Pathfinder RPG Best Practices

2016-12-05T16:21:34Z

Colen: /* Step 2 - Check Portfolios */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables which must be submitted before a project is completed, which should be worked on in parallel.

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

When building an NPC, you'll need to reverse-engineer the Hero Lab character from the statblock. For example, the character's hit points will come from a combination of class levels, favored class bonuses, and other sources - use average hit points for the class levels (which on NPCs, alternate from one level to the next). Generally favored class bonuses will be used to add additional hit points, but not always.

Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

1) if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.

2) If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

== Deliverable 2 - Notes ==

As you work on the module, create a list of any differences between what the module shows, and what Hero Lab shows. For example, if skills are off, note that, and see if you can figure out why it happened - that might lead you to think of a different way to do them so they'll be correct. This file is important because it will be used by whoever is checking your work.

== Submission ==

Submit both pieces of the project to us - portfolios and notes file. Don't submit until the portfolios are complete and checked to make sure they're correct.

= Checking Encounter Libraries =

Once both deliverables for an encounter library have been submitted (see above), we'll a different person to check the work. If you're checking someone else's encounter libraries, you need to find places they did something wrong.

Compare the statblocks listed in the module with what's in Hero Lab - do the details in the module match what's in HL? If not, consult the notes file you got along with the portfolios and see if the author noticed the problem and provided an explanation. If there is a note about the issue, is it a good one? Can you think of a way to make the statblock match the portfolio better? If there isn't, make a note of it yourself.

In addition to checking the actual portfolios, check everything from steps #1-3 of the "testing encounter libraries" section below. Make a note of any issues.

Once you've looked over everything in the module, make your list and send it to us. We'll pass it on to the original author, who will fix things. They should get you a new version of the module once the problems are fixed - once that's done, verify the issues you noted are fixed, or that you agree with the author on why they shouldn't be fixed. If there are disagreements, contact us and we'll resolve them.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form. On the NPC tab, make sure that the creature doesn't show any "default" NPC info for the race - that doesn't apply here, and we don't want it to show up on the statblock, so delete it.

If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

If you imported a creature from the bestiary, and customized it to fit the statblock in the book, you'll likely have to delete some of the chunks of info on the NPC tab to make it match the statblock (e.g. the statblock in the book likely won't show ecology, treasure, etc if it's for a specific NPC). If you don't have to customize the creature, the book likely won't show the statblock, so don't delete the NPC info.

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do make sure it's noted down. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-12-02T18:03:15Z

Colen: /* Step 2 - Check Portfolios */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables which must be submitted before a project is completed, which should be worked on in parallel.

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

When building an NPC, you'll need to reverse-engineer the Hero Lab character from the statblock. For example, the character's hit points will come from a combination of class levels, favored class bonuses, and other sources - use average hit points for the class levels (which on NPCs, alternate from one level to the next). Generally favored class bonuses will be used to add additional hit points, but not always.

Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

1) if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.

2) If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

== Deliverable 2 - Notes ==

As you work on the module, create a list of any differences between what the module shows, and what Hero Lab shows. For example, if skills are off, note that, and see if you can figure out why it happened - that might lead you to think of a different way to do them so they'll be correct. This file is important because it will be used by whoever is checking your work.

== Submission ==

Submit both pieces of the project to us - portfolios and notes file. Don't submit until the portfolios are complete and checked to make sure they're correct.

= Checking Encounter Libraries =

Once both deliverables for an encounter library have been submitted (see above), we'll a different person to check the work. If you're checking someone else's encounter libraries, you need to find places they did something wrong.

Compare the statblocks listed in the module with what's in Hero Lab - do the details in the module match what's in HL? If not, consult the notes file you got along with the portfolios and see if the author noticed the problem and provided an explanation. If there is a note about the issue, is it a good one? Can you think of a way to make the statblock match the portfolio better? If there isn't, make a note of it yourself.

In addition to checking the actual portfolios, check everything from steps #1-3 of the "testing encounter libraries" section below. Make a note of any issues.

Once you've looked over everything in the module, make your list and send it to us. We'll pass it on to the original author, who will fix things. They should get you a new version of the module once the problems are fixed - once that's done, verify the issues you noted are fixed, or that you agree with the author on why they shouldn't be fixed. If there are disagreements, contact us and we'll resolve them.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form. On the NPC tab, make sure that the creature doesn't show any "default" NPC info for the race - that doesn't apply here, and we don't want it to show up on the statblock, so delete it.

If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do make sure it's noted down. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-12-02T17:21:32Z

Colen: /* Step 2 - Check Portfolios */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables which must be submitted before a project is completed, which should be worked on in parallel.

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

When building an NPC, you'll need to reverse-engineer the Hero Lab character from the statblock. For example, the character's hit points will come from a combination of class levels, favored class bonuses, and other sources - use average hit points for the class levels (which on NPCs, alternate from one level to the next). Generally favored class bonuses will be used to add additional hit points, but not always.

Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

1) if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.

2) If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

== Deliverable 2 - Notes ==

As you work on the module, create a list of any differences between what the module shows, and what Hero Lab shows. For example, if skills are off, note that, and see if you can figure out why it happened - that might lead you to think of a different way to do them so they'll be correct. This file is important because it will be used by whoever is checking your work.

== Submission ==

Submit both pieces of the project to us - portfolios and notes file. Don't submit until the portfolios are complete and checked to make sure they're correct.

= Checking Encounter Libraries =

Once both deliverables for an encounter library have been submitted (see above), we'll a different person to check the work. If you're checking someone else's encounter libraries, you need to find places they did something wrong.

Compare the statblocks listed in the module with what's in Hero Lab - do the details in the module match what's in HL? If not, consult the notes file you got along with the portfolios and see if the author noticed the problem and provided an explanation. If there is a note about the issue, is it a good one? Can you think of a way to make the statblock match the portfolio better? If there isn't, make a note of it yourself.

In addition to checking the actual portfolios, check everything from steps #1-3 of the "testing encounter libraries" section below. Make a note of any issues.

Once you've looked over everything in the module, make your list and send it to us. We'll pass it on to the original author, who will fix things. They should get you a new version of the module once the problems are fixed - once that's done, verify the issues you noted are fixed, or that you agree with the author on why they shouldn't be fixed. If there are disagreements, contact us and we'll resolve them.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form.

The text in the "Creatures" entry should be on the Personal tab for all heroes in the portfolio, and any "Treasure", "Story Awards", or "Development" entries should be on the NPC tab (using the Additional Info option). If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do make sure it's noted down. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-12-02T17:11:38Z

Colen: /* Entering Encounter Libraries */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables which must be submitted before a project is completed, which should be worked on in parallel.

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

When building an NPC, you'll need to reverse-engineer the Hero Lab character from the statblock. For example, the character's hit points will come from a combination of class levels, favored class bonuses, and other sources - use average hit points for the class levels (which on NPCs, alternate from one level to the next). Generally favored class bonuses will be used to add additional hit points, but not always.

Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

1) if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.

2) If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

== Deliverable 2 - Notes ==

As you work on the module, create a list of any differences between what the module shows, and what Hero Lab shows. For example, if skills are off, note that, and see if you can figure out why it happened - that might lead you to think of a different way to do them so they'll be correct. This file is important because it will be used by whoever is checking your work.

== Submission ==

Submit both pieces of the project to us - portfolios and notes file. Don't submit until the portfolios are complete and checked to make sure they're correct.

= Checking Encounter Libraries =

Once both deliverables for an encounter library have been submitted (see above), we'll a different person to check the work. If you're checking someone else's encounter libraries, you need to find places they did something wrong.

Compare the statblocks listed in the module with what's in Hero Lab - do the details in the module match what's in HL? If not, consult the notes file you got along with the portfolios and see if the author noticed the problem and provided an explanation. If there is a note about the issue, is it a good one? Can you think of a way to make the statblock match the portfolio better? If there isn't, make a note of it yourself.

In addition to checking the actual portfolios, check everything from steps #1-3 of the "testing encounter libraries" section below. Make a note of any issues.

Once you've looked over everything in the module, make your list and send it to us. We'll pass it on to the original author, who will fix things. They should get you a new version of the module once the problems are fixed - once that's done, verify the issues you noted are fixed, or that you agree with the author on why they shouldn't be fixed. If there are disagreements, contact us and we'll resolve them.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form.

The text in the "Creatures" entry should be on the Personal tab for all heroes in the portfolio, and any "Treasure", "Story Awards", or "Development" entries should be on the NPC tab (using the Additional Info option). If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do note it down to pass along to Paizo. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-12-02T16:58:45Z

Colen: /* Testing Adventure Path Encounter Libraries */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Entering Encounter Libraries =

These guidelines apply to people who are building Hero Lab encounter libraries, typically for Pathfinder Modules and adventure paths.

There are two deliverables before a project is "complete", which must be done by different people. Broadly, they're "do the work" and "check the work".

== Deliverable 1 - Create portfolios for every encounter and NPC in the module ==

Every statblock, or partial statblock, printed in the module / adventure path / whatever must have a portfolio created in Hero Lab. The portfolio filenames are what appear in the Encounter Library, so they should be chosen based on the rules in "step 1" of the "testing encounter libraries" section below.

Portfolio names '''must''' be correct before we accept this deliverable - don't submit files with names like "encounter1.por" "encounter2.por" etc, as it makes things harder to QA.

Don't create a portfolio unless there's at least a partial statblock present in the module. A partial statblock will typically show the basic stats of the monster, then refer you to a Bestiary - for those, you can import the monster from the encounter builder, and make any changes as required (for example, you might need to apply a template to it, or swap out weapons).

If an encounter includes multiple copies of an NPC, import that many copies into the portfolio. If you need to make changes (like adding templates) it will probably be easier to make one, apply any changes, then duplicate it from the Portfolio menu instead.

Some NPCs (e.g. Pavo Vos on page 18 of Fangwood Keep) will need a full Hero Lab character created for them. In those cases, create the character. Don't create statblocks for NPCs we don't have enough information about. For example, if the text mentions "Merlin (elf wizard 4) might be hanging around the sanctum", don't create an NPC for him - we can't, because we don't know anything useful about him to create the NPC with.

Make sure all characters you create in all portfolios are set to "NPC" and "enemy of the party" on the configure hero form.

For any NPC in a portfolio (either imported from the encounter builder or created by yourself), check that the statblock output matches what's shown in the "Output Hero Statblock" window (found in the File menu). If anything there is wrong, try to figure out why - is it a mistake you made, or a mistake made by the authors of the encounter?

A convenient way to check whether the statblock is correct is to turn on the "statblock summary info window" for the portfolio - you can find it about 80% of the way down the "hero settings" in the configure hero form. Turn on "show full statblock summary window" and the first info window will be replaced by the character statblock. This allows you to check things without having to go to the File menu every time.

In general, set "base values" before "derived values". For example, set the character's ability scores first, then their skills - if you change ability scores after setting their skills, the skill values will change.

If you make any tweaks to the character after checking the statblock, you need to re-check the statblock for any changes. Remember, if you change an ability score, that can affect skills, ability values, etc.

If you find differences between Hero Lab's statblock and what's in the book, try to do what the creators "meant", even if that means the character will have validation errors. Examples:

1) if the character has too many feats or skill points, that's fine - just do what the module says. The GM will see any errors when they import the portfolio, and it's up to them what to do about them.

2) If you can't get the skills to match up for an obvious reason, then don't worry about the problem. For example, a common issue is that NPCs have too much gear, so they're encumbered, so their skills in HL are lower than the portfolio says they should be - that's a case where we should leave them at the "correct" values and let the GM decide what to do. Another common issue is the creator might have forgotten that a skill is a class skill, leaving it 3 points off.

Set the "buy for free" checkbox to buy the character's gear for free, then set their "starting cash" to be any cash the portfolio indicates they have.

Many NPCs will list "longbow with 20 arrows" for gear - to make that appear correctly on the statblock, add the longbow, add the arrows, then put the arrows "into" the bow using the "gear" button (the little bag) on the arrows.

Remember to set important things like composite longbow strength bonuses, holy symbol details, etc.

= Testing Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form.

The text in the "Creatures" entry should be on the Personal tab for all heroes in the portfolio, and any "Treasure", "Story Awards", or "Development" entries should be on the NPC tab (using the Additional Info option). If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do note it down to pass along to Paizo. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-03-25T19:17:44Z

Colen: /* Testing Adventure Path Encounter Libraries */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Testing Adventure Path Encounter Libraries =

== Step 1 - Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 - Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form.

The text in the "Creatures" entry should be on the Personal tab for all heroes in the portfolio, and any "Treasure", "Story Awards", or "Development" entries should be on the NPC tab (using the Additional Info option). If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do note it down to pass along to Paizo. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 - Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 - Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 - Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 - Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 - Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-03-25T19:17:10Z

Colen: /* Step 5 Prepare Portfolios in Folder */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Testing Adventure Path Encounter Libraries =

== Step 1 Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form.

The text in the "Creatures" entry should be on the Personal tab for all heroes in the portfolio, and any "Treasure", "Story Awards", or "Development" entries should be on the NPC tab (using the Additional Info option). If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do note it down to pass along to Paizo. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 Prepare Portfolios in Folder ==

All portfolios should have the "prepare" operation run on them before being checked into Vault. The following options are available:

* Automatically enter subfolders - check this if you need HL to visit all the subfolders of the selected folder to process portfolios in them, too - this will typically be checked for modules and adventure paths
* Log errors to a file - check this and then you can see any errors generated by the process at the end, rather than part-way through.
* Select minimal sources - DO NOT select this. All "normal" sources should be selected by default, so that users of the portfolio can use whichever of them they have.
* Strip missing sources - you usually won't need to check this, but do it if some of the portfolios report "missing source" errors when loaded.
* Turn ON Shrink Images - check this to ensure that the images in the portfolio will be shrunk to the appropriate size.
* Turn OFF Shrink Images - DO NOT select this.

Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-03-25T19:13:00Z

Colen: /* Step 4 Handle Player Content */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Testing Adventure Path Encounter Libraries =

== Step 1 Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form.

The text in the "Creatures" entry should be on the Personal tab for all heroes in the portfolio, and any "Treasure", "Story Awards", or "Development" entries should be on the NPC tab (using the Additional Info option). If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do note it down to pass along to Paizo. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above). (If you're one of our data file authors, make sure to integrate these into the correct place when the content is accepted.)

== Step 5 Prepare Portfolios in Folder ==
Check the all options except "Turn Off Shrink Images". Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-03-25T19:11:55Z

Colen: /* Step 3 Handle Appendices */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Testing Adventure Path Encounter Libraries =

== Step 1 Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form.

The text in the "Creatures" entry should be on the Personal tab for all heroes in the portfolio, and any "Treasure", "Story Awards", or "Development" entries should be on the NPC tab (using the Additional Info option). If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do note it down to pass along to Paizo. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 Check Appendices ==
Most APs and some modules include a section on random encounters, which should be represented in Hero Lab in a specific way. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there is a .stock file created that includes all such races. Test them as with any race (see above), comparing the statblocks between HL and the book.

Of special note is that sourcebook information needs to be specially added on the NPC tab for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above), and then integrate them once they are finished.

== Step 5 Prepare Portfolios in Folder ==
Check the all options except "Turn Off Shrink Images". Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-03-25T19:10:22Z

Colen: /* Step 2 Check Portfolios */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Testing Adventure Path Encounter Libraries =

== Step 1 Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form.

The text in the "Creatures" entry should be on the Personal tab for all heroes in the portfolio, and any "Treasure", "Story Awards", or "Development" entries should be on the NPC tab (using the Additional Info option). If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do note it down to pass along to Paizo. To see some common discrepancies between HL and statblocks, see step 5 under [[#Testing_Created_Races|testing created races]] (especially the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure any corrections everywhere are made everywhere it's used.

Verify that any NPC who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 Handle Appendices ==
Most APs include a section on random encounters, and they have special formatting rules. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there are .stock files created for all such races. Test them as with any race (see above), comparing the statblocks between HL and the book. Of special note is that sourcebook information needs to be specially added for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above), and then integrate them once they are finished.

== Step 5 Prepare Portfolios in Folder ==
Check the all options except "Turn Off Shrink Images". Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-03-25T19:07:39Z

Colen: /* Step 1 Check Structure & File Names */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Testing Adventure Path Encounter Libraries =

== Step 1 Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form.

The text in the "Creatures" entry should be on the Personal tab for all heroes in the portfolio, and any "Treasure", "Story Awards", or "Development" entries should be on the NPC tab (using the Additional Info option). If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do note it down to pass along to Paizo. For common discrepancies between HL and statblocks, see the section on testing created races (esp the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure that you make any corrections everywhere else it was used.

Verify that any hero who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 Handle Appendices ==
Most APs include a section on random encounters, and they have special formatting rules. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there are .stock files created for all such races. Test them as with any race (see above), comparing the statblocks between HL and the book. Of special note is that sourcebook information needs to be specially added for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above), and then integrate them once they are finished.

== Step 5 Prepare Portfolios in Folder ==
Check the all options except "Turn Off Shrink Images". Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2016-03-25T19:07:15Z

Colen: /* Testing Adventure Path Encounter Libraries */

= Testing =
It's up to you to ensure that content you submit meets a minimum level of quality before sending it to us. Here are the basics you need to hit before submitting:

*Description text should match the book, without any extra line breaks or incorrect characters
*Any things should have their appropriate effects when added to the hero. If the thing has multiple different effects under different circumstances (for example, different effects at different character levels), make sure to test every one of those circumstances to ensure it works correctly.
*No things you create should report script errors when added to the hero, even if it's in a situation it wasn't designed for (for example, adding a class-specific feat shouldn't report errors if the class isn't present). If a thing has different effects under different circumstances, make sure none of those circumstances cause errors to reported.
*Statblocks for monsters should match the book, unless Hero Lab is "right" and the book is "wrong". Hero Lab should display special abilities in the same categories as the book does, and should correctly display other stats.

The only way to test most of these is to test each item individually. For a class ability, add the ability, make sure it has the right effects, and if it's level dependent, increase or decrease the class level to make sure it doesn't report any issues. For races, turn on the statblock summary window, and compare the statblock in Hero Lab to what's shown in the book - you'll be able to see any differences immediately.

The Quick Reload shortcut, Ctrl+R should let you test these quickly. To increase the speed at which you can reload the data files, you can disable packages you don't rely on via the Develop menu -> Choose Supplement Packages.

= General Issues =
== What content from an Adventure Path issue should be added? ==
Add any content which could be used by a player during the course of the AP. This usually means all magic items in the Treasures section, or any feats/traits listed in the first issue of the AP. In most cases, the bestiary section does not need to be entered, unless one of the monsters within can be used as a familiar or animal companion to a PC. Another exception is that some Construct races may have information on the cost to buy them, and in that case the race and the minion object should both be created.

Some APs have sections which contain a deity entry, with special spells and items related to that faith which need entering.

== Reusing Content ==
It is absolutely encouraged that content be reused. In fact we've been making efforts to enable more variable abilities to be a single, moddable special rather than having to create a new version each time. This is especially evident in things like the "Gaze", for which there are many many different versions. Why is it important that you re-use an old ability rather than creating a new one?

;Reasons
:1. It reduces clutter when folks are using the editor, which means they are less likely to bootstrap the wrong thing.
:2. If we need to update something about an ability (such as how it interacts with another ability), we only need to do it once
:3. When using pre-requisites that search for that ability, you need only check for one thing.

=== Generalizing Content ===
This may lead to some slight wording awkwardness where the re-used ability refers to its original race or class name. While this isn't that big of a deal, it's best to "generalize" the description of the re-used ability, removing references to specific origins. For example:

"As a standard action, Paladins of the Holy Son can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 Paladin level + Charisma modifier)."

Could become:

"As a standard action, members of this class can blind evil-doers in 100 ft for 1 minute (DC 10 + 1/2 class level + Charisma modifier)."

=== Helpful Tools ===
*The #appenddesc macro modifies the description of a certain thing, to add extra text onto the end. It has the advantage of even showing this modification before a thing is added to the hero, and it applies to all copies of that thing. The fact that it must apply to all copies is a disadvantage as well, as it may hit others to which it doesn't apply. Text added with the macro is placed after the normal description text, but before text from DescAppend (see below).

#appenddesc[UniqueID,"{b}Modification from ABILITY NAME{/b}: Added Text"]

*A more targetted option is the DescAppend field, which allows a non-unique special to be bootstrapped from several different sources with a custom description each time. This is useful for many racial specials such as Poison, Disease, Gaze, Breath Weapon, or Immunity to Magic, which share a common name and mechanic but can vary wildly in effects.

*In some cases the content you may want to reuse is unavailable because it is normally added to a different table on the hero. This is especially the case when an archetype grants access to a different class' Custom Special Abilities (Rage Powers, Rogue Talents, etc), but they would normally go in a table the archetyped class is already using for its own custom special abilities. In this case, you need to override the candidate expression for one of your class's empty custom special ability tables, to use the new sort of ability.

:For example, a Magus is already using his Primary Custom Special Ability table for Magus Arcana. With the Hexcrafter archetype, he gains access to Witch Hexes (which are Primary abilities for the witch), but since they don't draw upon the same pool of selection he can't just lump them into the same table. Thus he overrides his secondary table's candidate expression to use primary witch abilities like so:

::linkage[varies].field[cCstS2Expr].text = "(SpecSource.cHelpWit) & !Helper.Secondary & !Helper.Tertiary & !Helper.Quaternary & !Helper.Quintenary"

== What should be shown on the Specials Tab? ==
;Examples
:Case 1 If the ability has a constant, calculated bonus '''only''' then it is '''not''' shown on the specials tab or character sheet because its effects are already accounted for.

::I.E: This ability gives +2 to Acrobatics.

::Sample Abilities: Keen Senses, Armor Training

:Case 2 If it has a bonus which applies in certain situations, but doesn't require the character to take an action, then it gets a situational applied to the target ability and is shown on the specials tab/character sheet.

::I.E: This ability gives a +2 to Acrobatics to jump

::Sample Abilities: Elven Magic, Favored Enemy

:Case 3 If the ability has a limited duration and requires some action to begin (even a free action), then it should be shown on the specials tab/character sheet and have an activation on the In-Play tab

::I.E: As a swift action, this ability gives +2 to Acrobatics for a number of rounds equal to your dexterity modifier (minimum 1 rd).

::Sample Abilities: Smite Evil

Some abilities have multiple elements, each of which may fall into a different case above. For example an ability could grant a +2 bonus to Spellcraft checks (case 1), and could be activated to add your Int modifier to Use Magic Device checks for 1 minute (case 3). As long as the ability has at least 1 part which should be on the Specials tab, show it. Anything shown on the Specials tab should have a summary (see Constructing a Summary for tips).

== What should be sourced? ==
Any thing which the user chooses from a menu and adds to their character should be sourced. Any thing which is not added by the user (usually because it is bootstrapped to something else and brought along with its root), should '''NOT''' have a source.

;The following types of things are usually sourced
:Custom Special Abilities
:Custom Racial Abilities
:Custom Race traits
:Archetypes
:Feats
:Traits
:Classes
:Races
:Magic Items

;The following types of things are usually '''NOT''' sourced:
:Racial Specials
:Generic Abilities
:Class Abilities

== Constructing a Summary ==
The purpose of a summary is for the user to be able to tell at a glance what a thing does mechanically. It's a hard thing to do, making summaries both small enough to fit in the limited space, yet keeping their information good. Foremost in your mind should be "What elements need to be conveyed?", and "How can they be conveyed most efficiently?"

;Common Elements (in order)
:Action required ("as a swift action", "over 1 min", "as imm. action")
:Limiting Situations ("on a hit", "when crit", "if foe is flat-footed", "when underground")
:Ability range/area/targets ("foe in 100 ft", "allies in 30 ft", "100 ft line")
:Ability effect ("dazed", "10d6 fire", "gain +2 morale bonus to AC")
:Ability duration ("for 1 rd", "until your next turn", "until atonement")
:Resisting the ability ("(Will neg)", "ignores DR")

The order above is the preferred order. For example "As a swift action when underground, foe in 30 ft has -2 to AC for 1 rd (Will neg)."

Not all abilities will have all these elements, and some will have far more content than you'd like. One trick is that information in the abilities livename does not need to be in the summary, so if you are short on space you may be able to shift info like duration or damage into there. Usage info ("X/day") and DC is already shown in the livename automatically, so those should almost never be shown in the summary. Also keep in mind that you don't need to follow proper grammer if space is tight, nor should you fear abbreviations as long as your information is still clear. The human brain is remarkably adept at filling in the blanks.

;Common Abbreviations
:Memorized -> mem
:Caster Level -> CL
:Weapon -> wep
:Critical -> crit
:Metamagic -> MM
:Round(s) -> rd(s)
:Minute -> min
:Bonus -> bon (often omitted entirely)

For example, here is a "decompressed" version of the Wild Arcana mythic ability's summary.

As a swift action, use 1 mythic power to cast any arcane spell from your class lists with a +2 bonus to caster level. The spell doesn't need need to be known or memorized.

And here is the shortened form

Use 1 power, cast an arcane spell from your class list at +2 CL (doesn't need to be known/mem).

'''A Warning'''

Constant, calculated bonuses should never be mentioned in a summary. That runs the risk of confusing the user and resulting in adding the calculated bonus again. For example, an ability which added 1/2 your class level to Perception checks and the same amount to your Survival in the desert, the Summary would mention the bonus to survival, but not mention the perception bonus.

== Situational vs Activation? ==
In general, if something is always present and active with no action required by you, but only affects you under specific circumstances, use a situational. An example of this is Trap Sense, you don't need to do anything to benefit from it and are always benefitting from it, even though the circumstance in which it matters (when you are being attacked by a trap) is relatively rare.

If something requires an action by you (even a free one), and then affects you for a limited duration thereafter, use an activation. An example of this would be Smite Evil, you activate it and then it gives you a bonus until that foe is defeated.

= Creating Races =
Races are among the most complex, fiddly things in pathfinder (especially high CR), but also one of the most important to do well. Since they are so complex there is little general procedure that can be outlined, and thorough testing is the most reliable way to get things done.

== Racial Variants ==
If you can avoid it, do not create two versions of the same race. It is better that a racial variant be indicated by the addition of a Racial Custom Special ability than by creating a whole new race which only varies in a few abilities. Racial Custom Specials are capable of replacing and disabling existing racial specials, just like Alternate Racial Traits do, and that combined with eval scripts on the RCS to manipulate the race's fields, plus bootstrapping new abilities will usually get you where you need to go.

How should you decide whether a variant warrants being split off into its own race? There isn't a hard or fast rule, but a good indicator is whether the variant has a full statblock spelled out where it is described. If the variant is simply described in a bit of text about how it differs from the base, then you're better off adding a RCS for it.

Note that we haven't always been the best at enforcing this, but it is the standard nonetheless.

== PC Races vs. Monster Races ==
A "PC Race", for our discussion, is any race which has no racial hit dice and is thus solely defined by its class levels. Halflings and orcs would both be PC races, even though orcs are usually antagonists and unlikely to be played as a PC.

A "Monster Race" is any race with racial hit dice, regardless of the likelyhood of their taking class levels. Giant Ants are mindless and would almost never have class levels; Ropers are at least intelligent and might rarely have class levels; Gnolls are humanoids and are quite likely to advance in class levels, but all three have racial HD and are considered monster races.

== Racial Spell-Like Abilities ==
SLA's appear frequently for monster races, and less so for PC races. There are several things to keep in mind when bootstrapping a SLA.

=== Marking PC Race Spell-Like Abilities ===
Any spell like ability bootstrapped to a PC race should have the Helper.RacSpAbil tag added to the bootstrap. PC race SLA and Monster race SLAs have a different format in the official paizo statblock, and are shown in different tables, and this tag is thus necessary for proper formatting.

Other than that, you may want to add further tags to mark them for this specific race (which is usually done either with a Custom or SpecSource tag). This is commonly seen in cases where the PC race only gains the SLA if they meet a certain minimum attribute (such as the Gnome race needing Charisma of at least 11 to use its SLAs). Bootstrap conditions cannot be used to enforce this because attribute values are determined so late. Instead an eval script must detect the attribute, and if necessary seek out the marked SLAs to hide them with a Hide.Spell tag. Marking the target SLA prevents the eval script from accidentally affecting other spell like abilities gained from feats or other sources.

=== Spell-Like Ability Name ===
Many spell like abilities have limitations or modifications in how they work, and these should be recorded in the livename field when bootstrapping, within parenthesis after the name. For example, many outsiders have the ability to use greater teleport as a SLA, but only on themselves and 50 lbs of gear, so this spell like ability would be bootstrapped with a livename of "Teleport, Greater (self plus 50 lbs. of objects only)"

''Warning''
The hero lab engine has automatic logic to rearrange the comma in between the spell names when generating a statblock name (to make "teleport, greater" -> "greater teleport"), but this will also catch any comma in the mod text. For this reason, you should try to avoid placing a comma in the parenthesis if you can. If you do not avoid that, you should set the sbName field specially when bootstrapping, which will prevent the automatic logic from running.

=== Spell-Like Ability DC ===
Unless specified otherwise, SLAs are assumed to calculate their DC as 10 + Spell Level (Sor/Wiz/Clr version) + Charisma modifier.

;What if the DC listed isn't the DC I want for this monster?
*Check the level of the spell you have bootstrapped. Is there a version which is of higher or lower level which will correct the descrepancy? Keep in mind that a SLA's level is assumed to be either the Sor/Wiz or Clr level version of the spell. If the Slow spell you bootstrapped has a DC 1 lower than you expected, perhaps you mistakenly bootstrapped the Summoner's 2nd level version (instead of the 3rd level sorcerer version). DO NOT switch from the assumed version to a wacky other class's spell in order to fix a DC issue.
*Check to see if the monster uses a different mental attribute for its spell like abilities than Charisma. This is probably something which should be stated somewhere in the monster's description, and if it isn't you should check among all its listed SLAs with a DC. This association grows stronger the more abilities that support it, and the wider the difference between the attribute modifiers. If there are 6 different SLAs, and all of them are off by the difference between the Wisdom and Charisma modifier then I would be comfortable making that call. If there is only 1 SLA with a DC shown, even if the difference fit, I would hesitate to make this change. Furthermore, if the DC difference is only 1, then it is more likely that an early version of the monster had a slightly higher Charisma which got adjusted down and the editors forgot to lower the SLA DCs appropriately.
::If you need to adjust the associated attribute to something else, you can bootstrap the SLA with a StandardDC tag for the new attribute. For example, StandardDC.aINT will make the DC be calculated by Intelligence rather than Charisma. This is on a bootstrap by bootstrap basis, so doing it in one place will only affect that one SLA.
*If the DC is 2 points low, check to see if the monster has Ability Focus for this SLA. If so, does your current version have that and has it selected the right target?
*Check if the monster has some other racial ability which could be increasing the DC of spells of a certain school or type. Is that functioning or not?
*At this point, you can probably assume it is a mistake on the part of the book's creators, note it down for reporting, and move on.
::I do not recommend ever doing so, but you can also add a flat bonus or penalty to a bootstrapped SLA's DC by placing a value in the sDC field when bootstrapping.

=== Spell-Like Ability CL ===
In most cases the CL of a SLA will be automatically calculated. For those bootstrapped to a race the assumption is that they will be based on the value of the rSpCastLev field (which can be set specially but defaults to the number of racial HD). There are several tags which can be applied when bootstrapping to change that. All of these must be combined with the Helper.SpellLike tag on all SLAs.

*Helper.ClsCastLev makes the CL of the spell like ability calculated based on total class level rather than the rSpCastLev field on the race. It is used for many of the ARG races that have spell like abilities (such as the Ifrit and the Aasimar).
*Helper.HDCastLev makes the CL of the spell like ability calculated based on total hit dice (both racial and class) rather than the rSpCastLev field on the race. HDCastLev overrides ClsCastLev. It is used for some spell like abilities from feats in the ARG (such as Magical Tail).
*Helper.TrCastLev makes the CL of the spell like ability calculated based on mythic tier. TrCastLev overrides both ClsCastLev and ClsCastLev. It is used for some path abilities from Mythic Adventures (such as Commune with Power).

== Testing Created Races ==
Testing should be carried out in a branch of the pathfinder files free of .user files, to prevent errors on load when someone else opens any prepared stock portfolio.

Step 1: Open a new portfolio and on the configure hero form set the character type to "NPC" and the alliance to "Enemy of Party". If this is a PC race with adventuring class levels, set the ability array to "Heroic NPC (15/14/13/12/10/8)"

Step 2: Go to the Background tab and select the race you wish to test. Give it a quick look to make sure that the italicized text at the top is correct, and that the description for the race is there and correctly formatted.

Step 3: Set up the race to match the statblock. For PC races this usually means setting the attributes, adding class levels and making choices for those classes (such as memorizing spells), as well as adding equipment shown in the statblock and equipping it. If the tactics section of the statblock mentions that a certain spell effect is assumed to be on the hero, add that to the adjustments tab. Do the same for any constant spell like abilities which may be present (if said abilities are likely to affect the statblock). Many monster races have no class levels and eschew equipment, so you may be able to skip this step entirely.

Step 4: Go to "File -> Output Hero Statblock" and then compare the generated statblock to the one shown in the book. Go line by line, item by item for this initial check. Make note of any discrepancies between the two statblocks, such as a racial special being shown on the wrong line (or not at all), differences in naming (for racial specials, SLAs, etc.), attack bonuses not matching, skill totals not matching, and so on.

Step 5: Investigate and fix the issues you found in step 4.
*Skills are a frequent issue between HL and official statblocks. Here are some tips at resolving them:
::Look for patterns in the skill ranks spent. Most authors don't sprinkle around skill ranks willy-nilly, either maximizing some skills and putting others at a lower level (usually half), or dividing ranks more or less evenly among all skills (all half, all max, so on). In any of the following steps, if you can bring the ranks closer to a pattern then you're probably going in the right direction.
::For monster races, you have a wide latitude in assigning class skills, so if the bonus is low by three and it isn't already a class skill, making it so can resolve things. Similarly, if the monster seems overspent on skill ranks by a multiple of 3, then look for skills which you can make class and drop by 3 ranks to get closer to parity.
::For PC races, Hero lab is often more inclusive of skill bonuses and penalties than paizo's statblocks are. For example, paizo statblocks usually assume a character has tools to use any craft skills, even if none are listed in the gear section. The skill total also usually doesn't count the bonus for mwk tools either, even when those ARE listed in the gear section. Hero Lab applies the bonuses to disable device from a rogue's trapfinding ability, while the official statblock does not, and so on. With time and a little practice you'll get a sense for what HL adds that paizo doesn't and learn to filter that out when looking for patterns.
::Paizo applies Armor check penalties inconsistently from statblock to statblock. The general assumption seems to be that all characters are lightly encumbered, so if you can store any non-combat gear elsewhere (like on a mount or dropped to the ground) in order to reach light encumbrance, do so. If you can't get to light encumbrance without dropping things like weapons and armor, then make a note of that to report. If you're still having trouble getting the skill ranks to work out, try unequipping any armor and going to light encumbrance. If you can make the skill totals work out that way, then it is likely that paizo forgot to add the ACP when building the statblocks, so re-equip the armor and make a note for Paizo stating the discrepancy.
*Generalized, re-used racial specials often need to be set in a special way so that they create their name and apply their effects in a consistent manner. If you've bootstrapped one and it doesn't seem to be working like expected, try copying the special and looking at the eval scripts on it. Or make a copy of a monster which has the same ability and see how it does the bootstrapping.
*Small attack bonus mismatches seem to be most commonly from development tweaks when paizo is creating a monster or NPC and decide to switch up the attributes but forgetting to adjust the follow on stats. In this case you can assume HL is in the right and make a note for Paizo.
*Natural attacks are also a place where we have some leeway, like with class skills. If you've bootstrapped a natural attack which is normally secondary, but the official statblock shows an attack bonus 5 higher and the full strength bonus to damage, then it is likely that for this monster it is a primary attack and you can bootstrap it with Helper.NatPrimary. It is rarer for a normally primary attack to be secondary for a monster, but you can accomplish that with Helper.NatOverSec. You should only apply that if the monster is not wielding manufactured weapons in combination with their natural attack, as Hero Lab automatically forces natural attacks to secondary when that happens.

Step 6: Repeat step 4 and confirm all issues have either been fixed or properly noted for paizo.

Step 7: Take the time to examine the character as shown in hero lab. For example, check the specials tab and make sure the racial specials of this creature have appropriate summaries. If the race has any activated abilities, test them out on the in-play tab as well. If you discover anything wrong during this step, fix it before moving on to the final step.

Step 8: Now that everything is done, create the stock version of this race. Go to the NPC tab and if this is a Monster race, hit the Default button to populate the ecology entries for the character. Make sure they are in sentence case (if they aren't then adjust them on the race and hit the button again). PC races usually have tactics entries (such as Before Combat, During Combat, or Base Statistics) which you add on the NPC tab, and further description text (the stuff after the statblock) which you should copy onto the Personal tab. Finally, use "Develop -> Prepare Portfolio for Distribution" and save or re-save the portfolio (if you hadn't already).

= Creating Magic Items =

== General Name Issues ==
Magic items are named in sentence case, with the first letter capitalized and all others (save proper nouns) not. Artifacts tend to be an exception, and you should look at the description text of an artifact to see how it is capitalized there.

;Examples
:Cloak of protection +1
:Boots of striding and springing
:Bastard's sting
:Baba Yaga's besom
:Thundering blade of the house of Sugimatu
:Deskari's Tooth

== Specific Magic Armor/Weapons ==
Most specific magic arms have item powers or materials, which should be added through the editor by clicking on the Materials and Weapon or Armor Powers buttons. You can also click on the "Gizmo" button on the upper right, and bootstrap that material or power to the listed entity. In many cases, the bootstrapped picks will take care of most of the coding needed.

== Testing Created Magic Items ==
Once you have hit the test now button or reloaded the system, follow these steps to make sure the item is correct. For simplicity, testing should usually be carried out on a blank character, so that any changes will be immediately obvious.

*Step 1 Go to the appropriate tab and table to add the item and visually inspect it in the selection window. Compare the heading information (like item caster level, aura, price, and so on) to the source and make note of discrepancies to correct.
*Step 2 Scan the description for errors like incorrect structure (linebreaks where there should be none, paragraphs smashed together), typos (often there is a space between f and l, caused by copy paste from pdfs), missing italics of spell/magic item names, missing alternate ability info (as granted by SpInfo and DescInfo tags) and so on.
*Step 3 Verify the item is correctly sourced.
*Step 4 Add the item to the hero and confirm that any eval scripts on the item behave as expected. If it is something which requires being equipped, make sure that its effects are not yet seen. Toggle the equip state on and off and make sure it works in both cases. If the item has effects which are "always on" and so it isn't equipped, you can do the same by adding and deleting the item. If the item must select something else, verify the list of selections behaves as expected as well.
*Step 5 Check alternate tabs. If the item has charges or bootstraps item spells, go to the In-Play or Spells tab to verify that they are set up correctly. Be especially careful of spells, which may have limitations that should be spelled out in the livename.
*Step 6 If the item should be shown on the specials tab, go there and take a look at it's summary. If the summary is too long and gets cut off, try to condense it further so all pertinent info is shown (see [[#Constructing a Summary|Constructing a Summary]]).

= Entering Stock Heroes =

== Populate the NPC tab ==
* Make sure the sourcebook name and SKU is set properly for the character. This is the book that this specific NPC is printed in. For example, if the NPC was printed in "Goblins of Golarion" but uses a race from the Bestiary, enter the sourcebook as "Goblins of Golarion", not the Bestiary.
* Add any appropriate tactics, ecology, etc NPC information from the NPC's entry.

= Testing Adventure Path Encounter Libraries =

== Step 1 Check Structure & File Names ==

Examine the layout of the folder. Are the portfolios divided into folders which follow (more or less) the organization of the book, like others in Hero Lab's encounter library?

For example, most AP issues are divided into parts, so the files may have one folder per part, with perhaps sub-folders for different encounter areas. While examining structure, look for typos in the names of portfolios, and verify that they match the standard format:

pXX - Map key (if present) - Encounter Name (CR Y)

XX is the page number, and single digit pages should be preceded by a 0 to bring things to a minimum of 2 digits (so that page 11 sorts after page 09). Y is the challenge rating of this encounter. Some aspects may be omitted (for example, there may be no map key for the encounter), but each portfolio should include at least the page number and Encounter name.

Here's an example from Rise of the Runelords:

Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p16 - Goblin Pyros (CR2).por
Chapter 1 - Burnt Offerings\Part 1 - Festival and Fire\p17 - Die, Dog, Die!.por
Chapter 1 - Burnt Offerings\Part 2 - Local Heroes\p19 - The Desecrated Vault (CR ½).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p33 - B1 - Guard Cave (CR 2).por
Chapter 1 - Burnt Offerings\Part 3 - Glass and Wrath\p34 - B4 - Washing Pool (CR 2).por

Note how there are separate folders for parts 1, 2, and 3, which can have multiple portfolios in them, each inside a single "chapter 1" folder. The chapter folder and part 1-3 folders all include the name of the section.

== Step 2 Check Portfolios ==

Proceed through each portfolio in the PDF / book, noting each encounter and opening the corresponding Portfolio in HL. Make sure that the correct number and types of heroes are present.

Verify that each NPC is set to "enemy of the party" (if applicable) and specified as an NPC on the configure hero form.

The text in the "Creatures" entry should be on the Personal tab for all heroes in the portfolio, and any "Treasure", "Story Awards", or "Development" entries should be on the NPC tab (using the Additional Info option). If the encounter shows a statblock, compare the statblock to what's output by Hero Lab (under the File menu) to what is in the book. If you find any differences between the book and what Hero Lab generates, note them down for correction (either by yourself or whatever author you are reviewing this for).

It is important to note that THERE WILL BE THINGS WHERE HL HAS IT RIGHT AND THE BOOK IS WRONG. In such cases, do NOT force HL to use the incorrect information, but do note it down to pass along to Paizo. For common discrepancies between HL and statblocks, see the section on testing created races (esp the section on skill discrepancies) above. If this monster is used in several different encounters elsewhere in the encounter library, make sure that you make any corrections everywhere else it was used.

Verify that any hero who has art in the book has the same Art on the personal tab, because this is what is shown for the creature when selecting it in the encounter library and on the Tactical console. In the event of NPCs with more than one piece of art (for example, a head shot and a full body), favor the full body shot by placing it first on the personal tab.

Be sure to read the book's entry for this encounter carefully. It is possible there might be variations you need to account for (such as sleeping guards not having their armor equipped), or even necessitating an extra version of the encounter (for example, if the adventure mentions another NPC may have retreated here to join up with the current encounter).

== Step 3 Handle Appendices ==
Most APs include a section on random encounters, and they have special formatting rules. Where the encounter describes a variable number of monsters encountered, the portfolio should only include a single representative monster, with a "#1" appended to the name, and the portfolio name should not display the "average CR". The number serves as a reminder that there are probably more than one in the encounter, and prompts the user to use the incrementer to select the true number in the encounter.

If, on the other hand, the encounter is with a specific group of monsters and described in detail, you should append the CR to the portfolio name and add the encounter description to the Personal tab for the monsters.

Many issues also have Bestiaries in the appendix. Not all monsters defined there may have been used during the earlier parts of the adventure, so make sure there are .stock files created for all such races. Test them as with any race (see above), comparing the statblocks between HL and the book. Of special note is that sourcebook information needs to be specially added for races defined first in a AP appendix, specifying which issue of the AP they premiered in.

== Step 4 Handle Player Content ==
Scroll through the AP looking for player content defined in this issue, such as new items and feats or deific obediences. Make sure that they are functioning correctly (as appropriate for testing whatever they are, see the guidance above), and then integrate them once they are finished.

== Step 5 Prepare Portfolios in Folder ==
Check the all options except "Turn Off Shrink Images". Look through the generated log for any errors which may have occurred and double check those portfolios to fix whatever necessary.

== Step 6 Get Package Sources for Portfolios in Folder (only possible for HL staff) ==
Use the generated file to create a table to help you search and add the AP's GM source to all the things which are referenced in this issue. First scroll down to the bottom section, and replace the "-" which divides the unique ID from the file name with a TAB character. Then go to Google Docs and create a spreadsheet. Copy and paste that bottom section into the spreadsheet, such that the Unique IDs are in the first column and the files are in the second column (this should automatically happen because of the tab). Select both columns, and rearrange things alphabetically by the file name column.

Open all files in a text editor and search for each unique ID and add the GM source to that. As you add the source, delete the file name and move down the line until everything is correctly sourced.

== Step 7 Package Testing ==
Mostly not needed anymore thanks to Colen. Suck that, tedium!

Pathfinder RPG Best Practices

2015-09-24T18:07:54Z

Colen:

Pathfinder RPG Best Practices

2015-09-24T18:07:33Z

Colen:

LoadOnce Element (Data)

2014-12-08T06:44:47Z

Colen:

{{context|Kit Reference|Data File Reference}}

==The "loadonce" Element==

The loadonce element has the following attributes:

:{| class="infotable"
|class="leftnormal"|key
|Key – Specifies a unique text key for the file. Only one file will ever be loaded for any given key.
|-
|}

If a "loadonce" element is found at the top of a file, the file is only parsed if another file with the same key has NOT been loaded. If a file with that key has already been loaded, the contents of the file are totally ignored.

If two or more files have the same loadonce element, exactly one of them will be loaded, with no guarantee of which one it will be. Don't assume anything about which file of a pair will be loaded - for example, on one computer, file A might be loaded and file B skipped, while on another computer file B might be loaded and file A skipped.

'''Please note''': When choosing your key, make sure to choose something unique that won't be picked by anyone else! If you and someone else both use the same key, only one of your files will be loaded, which would cause problems that would be very hard to debug.

==Example==

If two files had the following loadonce elements, only a single one of them would be loaded:

<pre>
File A: <loadonce key="John Smith's Source Definition File"/>

File B: <loadonce key="John Smith's Source Definition File"/>
</pre>

If four files had the following loadonce elements, file A would be loaded and only one of file B, C or D would also be loaded:

<pre>
File A: <loadonce key="John Smith's Source Definition File"/>

File B: <loadonce key="John Smith's Other Definition File"/>

File C: <loadonce key="John Smith's Other Definition File"/>

File D: <loadonce key="John Smith's Other Definition File"/>
</pre>

LoadOnce Element (Data)

2014-12-08T06:44:19Z

Colen:

{{context|Kit Reference|Data File Reference}}

==The "loadonce" Element==

The loadonce element has the following attributes:

:{| class="infotable"
|class="leftnormal"|key
|Key – Specifies a unique text key for the file. Only one file will ever be loaded for any given key.
|-
|}

If a "loadonce" element is found at the top of a file, the file is only parsed if another file with the same key has NOT been loaded. If a file with that key has already been loaded, the contents of the file are totally ignored.

If two or more files have the same loadonce element, exactly one of them will be loaded, with no guarantee of which one it will be. Don't assume anything about which file of a pair will be loaded - for example, on one computer, file A might be loaded and file B skipped, while on another computer file B might be loaded and file A skipped.

**Please note**: When choosing your key, make sure to choose something unique that won't be picked by anyone else! If you and someone else both use the same key, only one of your files will be loaded, which would cause problems that would be very hard to debug.

==Example==

If two files had the following loadonce elements, only a single one of them would be loaded:

<pre>
File A: <loadonce key="John Smith's Source Definition File"/>

File B: <loadonce key="John Smith's Source Definition File"/>
</pre>

If four files had the following loadonce elements, file A would be loaded and only one of file B, C or D would also be loaded:

<pre>
File A: <loadonce key="John Smith's Source Definition File"/>

File B: <loadonce key="John Smith's Other Definition File"/>

File C: <loadonce key="John Smith's Other Definition File"/>

File D: <loadonce key="John Smith's Other Definition File"/>
</pre>

LoadOnce Element (Data)

2014-12-08T06:30:39Z

Colen: Created page with "{{context|Kit Reference|Data File Reference}} ==The "loadonce" Element== The loadonce element has the following attributes: :{| class="infotable" |class="leftnormal"|key |K..."

{{context|Kit Reference|Data File Reference}}

==The "loadonce" Element==

The loadonce element has the following attributes:

:{| class="infotable"
|class="leftnormal"|key
|Key – Specifies a unique text key for the file. Only one file will ever be loaded for any given key.
|-
|}

If a "loadonce" element is found at the top of a file, the file is only parsed if another file with the same key has NOT been loaded. If a file with that key has already been loaded, the contents of the file are totally ignored.

If two or more files have the same loadonce element, exactly one of them will be loaded, with no guarantee of which one it will be. Don't assume anything about which file of a pair will be loaded - for example, on one computer, file A might be loaded and file B skipped, while on another computer file B might be loaded and file A skipped.

==Example==

If two files had the following loadonce elements, only a single one of them would be loaded:

<pre>
File A: <loadonce key="Source Definition File"/>

File B: <loadonce key="Source Definition File"/>
</pre>

If four files had the following loadonce elements, file A would be loaded and only one of file B, C or D would also be loaded:

<pre>
File A: <loadonce key="Source Definition File"/>

File B: <loadonce key="Other Definition File"/>

File C: <loadonce key="Other Definition File"/>

File D: <loadonce key="Other Definition File"/>
</pre>

FileInfo Element (Data)

2014-12-08T06:22:28Z

Colen: Created page with "{{context|Kit Reference|Data File Reference}} ==The "fileinfo" Element== This element allows you to specify information about the author, history, and "to-do" list for the f..."

{{context|Kit Reference|Data File Reference}}

==The "fileinfo" Element==

This element allows you to specify information about the author, history, and "to-do" list for the file. This can be useful for leaving yourself notes, providing information about what's in the file for other users, or identifying yourself as the creator of a file so that other people can contact you.

The contents of the "fileinfo" element can be viewed in the Hero Lab editor via the "View" menu.

The "fileinfo" element has no attributes, but possesses several child elements that can be used to store information. The list of these child elements is below and must appear in the order shown.

:{| class="infotable"
|class="leftnormal"|info_author
|An optional "info_author" element can be used to hold information about the file's author, by storing text in its PCDATA.
|-
|info_history
|An optional "info_history" element can be used to hold information about historical details and changes to the file, by storing text in its PCDATA.
|-
|info_todo
|An optional "info_todo" element can be used to hold information about work still to be done on the file, by storing text in its PCDATA.
|-
|}

Data File Reference

2014-12-08T06:16:25Z

Colen: /* Structural Composition */

{{context|Kit Reference}}

==Overview==

The data file is where you'll be defining all of the top-level elements that the user will directly control. This includes visual elements like panels, layouts, templates, and portals. It also includes game system elements like things.

All data files have the ".dat" file extension and are loaded after all of the structural files have defined the framework for the game system.

This section outlines the structure and mechanics for writing a definition file.

{{important}}This section utilizes [[Kit Reference#conventions|critical notational conventions]] that should be reviewed.

{{important}}Just because you '''can''' put numerous different elements in the same file does not mean you '''should''' do so. Keeping your data files small and focused will also keep them much more manageable, so break up all the information across files where appropriate. See the Skeleton data files for examples of this.

==Structural Composition==

The overall file structure is that of a standard XML file. The file must start with an XML version element in the form: "<?xml version="1.0"?>". Following this, the top-level XML element must be a "document" and it must have a "signature" attribute containing the explicit value "Hero Lab Data".

The following table defines the attributes for a "document" element.

:{| class="infotable"
|class="leftnormal"|signature
|Text – Must be the value "Hero Lab Data".
|-
|}

Within the document element, every data file possesses the following child elements, appearing in the sequence given and with the names specified.

:{| class="infotable"
|class="leftnormal"|{{flalt|LoadOnce Element (Data)|loadonce}}
|A single "loadonce" element may appear as defined by the given link. This element allows you to conditionally exclude files from being loaded if a similar file has already been loaded.
|-
|{{flalt|FileInfo Element (Data)|fileinfo}}
|A single "fileinfo" element may appear as defined by the given link. This element specifies information about the data file and its author.
|-
|{{flalt|Procedure Element (Data)|procedure}}
|Zero or more "procedure" elements may appear as defined by the given link. This element specifies a collection of procedures that may be called by scripts throughout the data files.
|-
|{{flalt|Thing Element (Data)|thing}}
|Zero or more "thing" elements may appear as defined by the given link. This element specifies various thing objects for use within the game system.
|-
|{{flalt|Portal Element (Data)|portal}}
|Zero or more "portal" elements may appear as defined by the given link. This element specifies an assortment of portals for use within layouts.
|-
|{{flalt|Template Element (Data)|template}}
|Zero or more "template" elements may appear as defined by the given link. This element specifies an assortment of templates for use within layouts.
|-
|{{flalt|Layout Element (Data)|layout}}
|Zero or more "layout" elements may appear as defined by the given link. This element specifies an assortment of layouts for use within panels, forms, and sheets.
|-
|{{flalt|Panel Element (Data)|panel}}
|Zero or more "panel" elements may appear as defined by the given link. This element specifies a variety of panels that will be presented to the user as part of the game system.
|-
|{{flalt|Form Element (Data)|form}}
|Zero or more "form" elements may appear as defined by the given link. This element specifies a variety of forms that will be presented to the user as part of the game system.
|-
|{{flalt|Sheet Element (Data)|sheet}}
|Zero or more "sheet" elements may appear as defined by the given link. This element specifies a variety of sheets that will be used for printouts within dossiers.
|-
|{{flalt|Dossier Element (Data)|dossier}}
|Zero or more "dossier" elements may appear as defined by the given link. This element specifies a collection of dossiers that the user can select for character output.
|-
|{{flalt|Hidden Element (Data)|hidden}}
|Zero or more "hidden" elements may appear as defined by the given link. This element identifies things that HL should remove from use within the game system.
|-
|{{flalt|Edit Thing Element (Data)|editthing}}
|Zero or more "editthing" elements may appear as defined by the given link. This element specifies a variety of elements that enable use of the integrated Editor for creation of things.
|-
|{{flalt|FAQ Element (Data)|faq}}
|Zero or more "faq" elements may appear as defined by the given link. This element specifies various FAQ entries that will be included within the FAQ page for the game system.
|-
|}

==DTD==

To edit data files in your XML editor, you can use the [[Data File DTD|Data File DTD here]].

Structural File Reference

2014-12-08T06:15:08Z

Colen: /* Structural Composition */

{{context|Kit Reference}}

==Overview==

Structural files are where you'll be defining all of the pieces that provide the underlying framework for the game system. They are loaded immediately after the definition file.

The Kit supports four different structural file types that share the identical contents. They possess the file extensions ".1st", "core", ".str", and ".aug". These files are always loaded in that same order.

This section outlines the structure and mechanics for writing a structural file.

{{important}}This section utilizes [[Kit Reference#conventions|critical notational conventions]] that should be reviewed.

{{important}}Just because you '''can''' put numerous different elements in the same file does not mean you '''should''' do so. Keeping your data files small and focused will also keep them much more manageable, so break up all the information across files where appropriate. See the Skeleton data files for examples of this.

==Structural Composition==

The overall file structure is that of a standard XML file. The file must start with an XML version element in the form: "<?xml version="1.0"?>". Following this, the top-level XML element must be a "document" and it must have a "signature" attribute containing the explicit value "Hero Lab Structure".

The following table defines the attributes for a "document" element.

:{| class="infotable"
|class="leftnormal"|signature
|Text – Must be the value "Hero Lab Structure".
|-
|}

Within the document element, every structural file possesses the following child elements, appearing in the sequence given and with the names specified.

:{| class="infotable"
|class="leftnormal"|{{flalt|LoadOnce Element (Data)|loadonce}}
|A single "loadonce" element may appear as defined by the given link. This element allows you to conditionally exclude files from being loaded if a similar file has already been loaded.
|-
|{{flalt|EnMasse Element (Data)|enmasse}}
|Zero or more "enmasse" elements may appear as defined by the given link. This element specifies categories of things to automatically add to every actor.
|-
|{{flalt|Bootstrap Element (Data)|bootstrap}}
|Zero or more "bootstrap" elements may appear as defined by the given link. This element specifies specific things to automatically add to every actor.
|-
|{{flalt|AutoAdd Element (Data)|autoadd}}
|Zero or more "autoadd" elements may appear as defined by the given link. This element identifies choices that are pre-selected for every actor.
|-
|{{flalt|UsagePool Element (Data)|usagepool}}
|Zero or more "usagepool" elements may appear as defined by the given link. This element specifies usage pools for use by the game system.
|-
|{{flalt|Reference Element (Data)|reference}}
|Zero or more "reference" elements may appear as defined by the given link. This element details references used throughout the data files.
|-
|{{flalt|Group Element (Data)|group}}
|Zero or more "group" elements may appear as defined by the given link. This element defines a collection of tag groups and their tags.
|-
|{{flalt|Source Element (Data)|source}}
|Zero or more "source" elements may appear as defined by the given link. This element specifies sources that can be configured by the user for each actor.
|-
|{{flalt|Resource Element (Data)|resource}}
|Zero or more "resource" elements may appear as defined by the given link. This element defines resources like fonts and bitmaps used by styles for visual display.
|-
|{{flalt|Style Element (Data)|style}}
|Zero or more "style" elements may appear as defined by the given link. This element specifies an assortment of visual styles that can be used by portals.
|-
|{{flalt|Component Element (Data)|component}}
|Zero or more "component" elements may appear as defined by the given link. This element specifies a variety of components that can be used by component sets.
|-
|{{flalt|Component Set Element (Data)|compset}}
|Zero or more "compset" elements may appear as defined by the given link. This element defines various component sets that can be used to define things.
|-
|{{flalt|Entity Element (Data)|entity}}
|Zero or more "entity" elements may appear as defined by the given link. This element defines entities that can be used within the game system.
|-
|{{flalt|Sort Set Element (Data)|sortset}}
|Zero or more "sortset" elements may appear as defined by the given link. This element defines various sort sets that can be used by the game system.
|-
|}