Style Guide
This is a style guide for entering actor, item, and journal data. When this page talks about items, it's using the Foundry definition - so equipment, spells, feats, effects, individual monster abilities are all items. We have a tool for data entry (https://github.com/TikaelSol/PF2e-Foundry-Data-Entry) that will automatically set up most of the inline formatting for you, and it is encouraged that you always use the latest version of the tool available. When major updates are done to the tool we send a message on discord to the data entry team. If you are routinely doing system data entry and do not have this role please ask to have it added to you so you have access to the data entry dev channels. This role does require system contributions however, as our dev channels are not meant to be public.
The first time that a spell, feat, condition, item (or basically anything that's in a compendium) is mentioned in an item, it should be linked by dragging and dropping. If necessary, you can edit the label of the cross-reference to make it more grammatically correct.
If the same item is referenced again, it shouldn't be linked. The exception is for conditions with numerical values, where you should cross-link every unique numerical value.
The exception is for the most basic actions like Strike, Stride, Step and so on. Every cross-link makes the text slightly less readable. We have to assume a certain baseline level of knowledge about the most common actions. Specific actions (e.g., Trip or Grapple) should be linked, as most people probably won't remember offhand what the critical success damage from a trip is and these actions provide quick access to the action macro.
When doing new data entry linking needs to be the last step done. This is because the link needs to be made to the item in compendium, not in your world.
Roll links are very useful for any rolled value (e.g. 'breath weapon recharges in 1d4 rounds') or value that's handy to output to chat (e.g. 'the monster heals 10 hit points after using this ability'). Inline rolls are done with a pair of brackets [[/r 1d20+17 #Counteract]] This would make a button showing 1d20+17 and have a roll flavor of "Counteract". Inline rolls like this are useful for non-damage rolls.
As of PF2e v5.3 we have implemented @Damage. This is a more versatile way of handling inline rolls. The syntax for a simple damage roll looks like @Damage[1d6[fire]]{ouch!} with @Damage and like this [[/r 1d6[fire]]]{ouch!} in the old style. The string in curly braces at the end gives the link a custom label: without one a simple label will be automatically generated. For other damage types, substitute in the desired type, or simply omit it if the damage has no particular type. The bracketed damage type has a very high "operator" precedence in the roll-formula syntax, making parentheses necessary when used with more complicated expressions: @Damage[(1d6 + 3)[fire]]. For damage formulas with multiple damage types, separate, comma-separate pools of dice added to a single roll: @Damage[5d6[acid],5d6[cold],5d6[fire]]. The benefit of using @Damage is that it is processed before rendering down to HTML, which means that you can target it with rule elements to override the damage dice or apply modifiers. An @Damage roll on an NPC will automatically gain a +2 modifier if you make the NPC elite, and a +4 modifier if that ability has a set frequency.
We can also add special damage categories to a roll: @Damage[(2d6 + 4 + (2d6[precision]))[slashing]]. This would deal 2d6+4 slashing plus 2d6 precision slashing damage. Note the inner parentheses for precision damage, which are also necessary for splash. Persistent damage can also be added: @Damage[1d6[persistent,fire]]. Note the lack of inner parentheses for persistent damage, as well as its inclusion directly alongside the damage type.
If the number isn't a damage value, use something like [[/br 1d4 #Recharge Breath Weapon]]{1d4 rounds} or equivalent. In this example of a monster cooldown, we use blind rolls (/br) to hide the roll message from players.
You can make an inline roll links for different checks, including setting a DC to output the degree of success, traits and other roll options can be pushed to the roll to make the links activate automation stored in rule elements and elsewhere.
@Check[type:fortitude|dc:20|basic:true]
The link will inherit the traits from the item and actor it is on. For example, placing the above link on a breath weapon for a large dragon and giving the action the poison trait will automatically pass the origin:trait:dragon, action:breath-weapon, origin:size:large, and poison roll options. It would also have damaging-effect added automatically by being marked as a basic save. For simplicity sake this syntax calls all the roll options traits as part of the input, anything can be passed in them and they will enable automation of specific bonuses. For saves against damage that are not basic save, remember to add damaging-effect to make Bulwark or other automation work properly.
Skill rolls can also be made using the following syntax: @Check[type:athletics|dc:20|traits:action:long-jump] as well as Perception rolls: @Check[type:perception|dc:20|traits:auditory] or @Check[type:perception|dc:24|traits:action:search,secret] to have a blind rolled search check. Flat rolls can also be done with this syntax: @Check[type:flat|dc:4]
The full list of applicable fields is as follows. For the purposes of data entry into the system, the attributes should be in the order presented below:
type - Supported type values are: flat, perception, fortitude, reflex, will, a skill slug in short or long form e.g. med or medicine, a lore slug such as engineering-lore, or a statistic slug such as kineticist for the kineticist class statistic. Everything from the system except lores will have a default localized inline link label that can be overwritten by adding {Some Label} to the check. This is the only mandatory parameter, however type: can be excluded. @Check[athletics] will work because the first parameter is always assumed to be type:. The system itself has standardized to be explicit with the parameter name however.
defense - The defense statistic to roll against. This is the only way to refer to target actor data. @Check[type:deception|defense:perception] for example would roll a deception check against the targeted creature's perception DC.
dc - A numeric value that sets the DC. You can also use @self.level for a level based DC of the roller from the DC by level chart, not that this is not the owning actor's level based DC, but the actor making the roll. There is no current way to include target data in these rolls. You can resolve data from the item the check is embedded in or the actor the item is on using resolve(...) as an input. resolve(@actor.attributes.classDC.value) or resolve(max(1,5,@actor.level)). resolve() will try to resolve any value on the actor (@actor...value). For example, a link resolving the class DC would be @Check[type:reflex|dc:resolve(@actor.attributes.classDC.value)], or a link to resolve the higher of class or spell DC would be @Check[type:will|dc:resolve(@actor.attributes.classOrSpellDC.value)]. This actor data can be found in the Foundry console, and is subject to change as system data structure changes. Changes to the structure are normally migrated, so little maintenance should be needed for these inline links in this regard.
basic:true - Only works with save checks. The inline roll label will be Basic {checkName} e.g. Basic Reflex.
showDC - Defaults to owner visible only. Can be changed to gm to only show the GM or all to show DCs to all players, or none to show the DC to no one.
adjustment - Increases or decreases the dc field based on the value passed when used alongside dc:@self.level to replicate "Very Hard" or other adjusted DCs by level. For example @Check[type:performance|dc:@self.level|adjustment:2|traits:action:perform] would be a link to roll a perform check at a hard DC for the roller's level, useful for things like Lingering Composition or One for All.
immutable:true - The DC is static and will not be changed by modifiers like frightened, elite, or weak.
name - The name of the check in the rolled chat card. This will default to {itemName} DC if no name parameter is given.
traits - Any additional traits that the roll should have. If no traits parameter is given the roll traits will default to the item traits. The final traits will be a deduplicated list of item traits, actor traits, action name, and parameter traits. Any check with the secret trait will be rolled as a blind roll by the system.
overrideTraits:true - The roll traits will omit the item traits.
Links can be made to create pre set templates. These use the PF2e names for the templates, not the Foundry names. You only need to specify the shape and distance, by default it uses the user's assigned color.
@Template[type:emanation|distance:x]
@Template[type:burst|distance:x]
@Template[type:cone|distance:x]
@Template[type:line|distance:x]
The labels for these links will automatically be generated as X-foot Type, but a label can be specified. For cases where a label is needed, for example in an aura where the word emanation is dropped we can manually specify. @Template[type:emanation|distance:90]{90 Feet}.
There are also optional fields.
- The
traitsfield is optional, and should be omitted if left blank. By default the command will provide the traits from item data. Traits are picked up by certain modules and should not be included in any system data entry. - The
widthfield is optional, and should be omitted left blank. It can be used to create a line template with a width larger than 5 feet (default if omitted). A Wand of Crackling Lightning for example would use an inline that looks like@Template[type:line|distance:120|width:10]{120- by 10-Foot Line}
width should be used to make square or rectangular templates: @Template[type:line|distance:20|width:20]{20-Foot Square}. While it is possible to use the Foundry rect template type as an inline doing so is not advisable as the same results are more easily obtained by using line with a width. rect can only be used with the old <span ...> tag method.
If you need to make a very specific template the shape can be passed and the template data can be passed as a JSON object directly in the HTML form of these using any of Foundry's or a module's template data such as specifying the fill color, line color, angle, etc. These should not be used in the system but are provided here only for user reference.
<span data-pf2-effect-area="cone" data-pf2-template-data='{"fillColor": "#15B39D", "distance": 15, "angle": 90}'>15 foot cone</span>
Secret GM text is no longer used in the system style. It is presented here for reference but future data entry should not use it.
You can make text visible to GMs only by using <p data-visibility="gm">GM-Only Text Here</p> or wrap multiple <p> in one <div data-visibility"gm"> <p>Text 1</p> <p>Text 2</p> </div> This feature is included with the DC button above (the showDC="gm" portion).
A saving throw roll with a GM only DC looks like this to a player:
Paizo's text is sometimes very compressed, as they have to worry about fitting things onto physical pages of printed text. We don't have that problem, and so extra line breaks and formatting can (and should!) be added to aid readability. For example, look at our version of Animal Form versus the PDF:
If an ability has critical success/success etc. outcomes, these should be separated from the main ability text by a horizontal line:
If an item has multiple activations we change our normal practice of putting an <hr> between the top text of the activation and the effect itself to instead put an <hr> between each activation. This helps to more quickly see the separation between different effects without looking too crowded.
For example, the Marvelous Calliope
Use the in-build font style for action symbols (make sure the text isn't set to bold, as otherwise they're hard to read). If you're updating an older item, the action symbols will be in a different font style that doesn't fit as well within the lines - and so they should be replaced with the new version.
We generally follow Paizo's lead here:
A condition should be linked the first time it's referenced. If there's a number associated, make sure to link it each time, like Fear:
Here's the correct format for linking conditions, which should happen automatically if you drag and drop within Foundry: @UUID[Compendium.pf2e.conditionitems.Item.<ID>]{<Conditiontextandnumber>} e.g. @UUID[Compendium.pf2e.conditionitems.Item.e1XGnhKNSQIm5IXg]{Stupefied 1}. Once the changes are extracted the ID will change to the item name for easier review outside of Foundry.
Paizo sometimes saves space by saying an ability is identical to that of another monster. We don't have to worry as much about space, and so always copy and paste the full text in and replace references to the creature type as well as any necessary updates to DCs or damage values.
For example if a generic NPC had an ability with the text The ruffian brandishes his sword while striking with it. He attempts to demoralize then makes a scimitar strike against the same target. If a female NPC named Lucy had this ability and simply had the text As ruffian you should edit the text to Lucy brandishes her sword while striking with it. She attempts to demoralize then makes a scimitar strike against the same target. This changes the references to the specific NPC and alters the gendered language to match the stated gender of the NPC.
There's a compendium with this name which contains commonly-used monster abilities. If you're editing the monster with an ability from here, add a fresh copy onto the monster.
For effects like telepathy, scent and so on, add the extra info about the range or degree of precision into the ability title (e.g. "Telepathy 100 feet" or "Scent (Imprecise) 60 feet)"). If there's a lot of information here, it may be better off in the first line of the ability (e.g. "Telepathy 100 feet" as the title, with "Other myconids and those affected by purple poison only" in the main ability body. Note the capitalization of Imprecise, but the lack of capitalization on feet. This is the standard for ability titles where the units do not follow title case.
Lore that's available in the Bestiaries and Adventure Toolbox sections of APs can and should be added to monsters where possible. This can be done on the Notes tab of the default NPC sheet.
Text specific to a monster should go above text specific to a family of monsters, and should be separated by a horizontal line, as shown above. Below creature family descriptions we can put relevant sidebars. Some sidebar information is relevant to entire families of creatures such as the above example, some is relevant only to that specific creature. If a creature lacks family information, or family information is in a different book don't add any.
Some sidebars contain mechanical information about the creature in question. Because GMs do not expect mechanical information in the notes section move this to a new passive ability on the creature in question. For example the Quickiron Plasm (Pathfinder Rage of Elements page 154) has the following sidebar:
This is then on the actor's abilities for quick reference for the GM. These new passives can be set as interaction for their action category.
Some sidebars contain mechanical information that requires the creation of variant creatures. For example this sidebar in Soulbound Doll (Pathfinder Bestiary page 304):
If an attack has a secondary effect (e.g. Grab), it should be linked into the attack. Make sure to add a copy of the ability to the monster, and then it'll turn up in the chat log when the GM uses that attack!
Make sure to always add the ability itself to the NPC, even if it can be added as an attack effect without being on the actor.
Many monster abilities can be automated by adding rules elements to the relevant ability. See the rules element page on the wiki for details on how to do this.
Many NPCs have bonuses to skills in specific situations, e.g. a +4 to Stealth in forests. To access the menu to set these bonuses, click here:
Once the dialogue is open, go to the 'Details' tab. The label is what will appear on the stat block, and the roll modifiers is what macros and other parts of the system will interact with:
Typical options for roll modifiers are terrain:X, action:X, target:X for a condition on the target. For example a bonus to athletics to trip would use action:trip or a bonus to lie to humanoids would use both action:lie and target:trait:humanoid.
You also need to add a rules element to the rules tab to fully automate this. See the rules element page on how to write this; you want a flat modifier type of element.
{
"key": "FlatModifier",
"predicate": [
"terrain:forest"
],
"selector": "stealth",
"value": 2,
"label": "PF2E.SkillVariant.Forest"
}Note the localization of the label. Labels should not be left unlocalized, you can see or add to the localization text for these strings in static/lang/re-en.json.
If you are in doubt about the roll options to use look for similar creatures or abilities. In general terrain roll options will be in the form terrain:<terrain-name-singular> so a bonus to survival in deserts would predicate on the roll option terrain:desert (singular). Bonuses in different lighting conditions are done with lighting:dim-light for example, under the lighting option domain instead of terrain.
Sometimes Paizo neglects to add a DC to a creature's ability, calling instead for a save. In those cases we use a moderate DC from the creature building guidelines (https://2e.aonprd.com/Rules.aspx?ID=995). Once you have looked up the right DC and put it into an inline check add the following to the bottom of the ability text
<hr /><p><em>Note: A DC was not provided for this ability by Paizo. The DC present here is a moderate DC for the creature level according to the GM Core creature building Tables.</em></p>With the release of GM Core this text will likely change to refer to GM Core instead.
Sometimes only a DC is listed. In this case, put the DC - 8 into the attack value, so we don't have an empty box (the tables in the GMG always set the attack value at 8 lower than the DC).
If a spell is at will or constant, add that into the spell's title. You should also add the 'at will spells' or 'constant spells' ability from the glossary.
If a spell has a restricted target or other note, update it (both the description and details page) to match that info, as well as putting it in the title.
If the alterations are really long-winded they'll make the spell look weird. Instead, add 'Modified' to the spell name and list the modifications at the start of the spell's description
Spells that deal damage will have a button when cast that lets you roll the correct damage, and so the core damage (e.g. 6d6 fire for Fireball) doesn't need to be made into a roll link.
There should be a horizontal line between the main part of the spell and the heightened text.
For spells with different effects on critical success through to critical failure, put each entry onto its own line - it makes it much easier to read.
You can put a horizontal line between the spell introduction and the saving throw breakdown.'
Each item and actor has a source value. These should be filled according to the book the creature or item is from. It's only necessary for the base sheet, not embedded items like NPC-strikes. For NPCs, this field can now be set on the Notes tab. For hazards this can be set at the bottom of the sheet when editing it. For most items this can be edited on the details tab. For effects, this field must still be changed by manual json editing or through a macro or console.
The source should match the name used by Paizo on the product page with the exception that we remove the words Adventure Path and parentheticals from AP volumes. So Pathfinder Adventure Path #166: Despair on Danger Island (Fists of the Ruby Phoenix 1 of 3) on the Paizo store (https://paizo.com/products/btq027qd/) becomes Pathfinder #166: Despair on Danger Island.