Character Vault
Any Concept / Any System
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:Pathfinder 2 Utilities"

From Roll20 Wiki

Jump to: navigation, search
Line 30: Line 30:
{{API command|pf[s] [@targets] debug targets}}<br>
{{API command|pf[s] [@targets] debug targets}}<br>
{{API command|pf[s] [@targets] debug rawget <roll20-property-name>}}<br>
{{API command|pf[s] [@targets] debug rawget <roll20-property-name>}}<br>
{{API command|pf[s] [@targets] debug echo <string>}}<br>
{{API command|pf[s] debug echo <string>}}<br>
{{syntaxbox end}}
{{syntaxbox end}}

Revision as of 23:33, 23 May 2020

API ScriptAuthor: Mark G.
Version: 240520
Last Modified: 2020-05-24
Code: Pathfinder2Utilities
Dependencies: None
Conflicts: None

Public releases as above. Dogfood builds at .

A collection of utilities for GMing and playing Pathfinder 2nd Edition, in particular support for PF2's abilities.



!pf[s] [@targets] get <valuename> [tags..]
!pf[s] [@targets] best <valuename> [tags..]
!pf[s] [@targets] roll <valuename> [tags..]
!pf[s] [@targets] assure <skillname>
!pf[s] [@targets] rollinit[!] [valuename] [tags..]
!pf[s] [@targets] ability <ability> [skill] [tags..]
!pf[s] [@targets] mod add <name> <type> <value> <tags..>
!pf[s] mod list
!pf[s] mod clear
!pf[s] mod del <name>
!pf[s] [@targets] mod explain <tags..>

The following strings also trigger debugging commands which are not likely to be useful when actually running a game:

!pf[s] [@targets] debug targets
!pf[s] [@targets] debug rawget <roll20-property-name>
!pf[s] debug echo <string>

Installation and Configuration

Select the script from the library and run.

If you wish to use a dogfood (less tested) build, copy the script's code from the URL above and paste it into a "new script" in your PF2 campaign, then save the script.

Do not attempt to use a library build and dogfood build at the same time!

Script Use


All commands start with "!pf". Starting with "!pfs" will send the result only to the running player and the GM.

Targets can be specified as a list beginning with an @ sign. Each is specified as part of a character name, in lower case with no spaces. So, for example, "Ed Goblin" could be specified as edgo.

You can target all PCs with @pcs, all NPCs with @npcs, and all tokens with @all.

You can target several tokens by separating their names with commas: eg @edgo,billgo .

If you do not specify a target, all selected token(s) are targeted.

If you do not specify a target and do not have any tokens selected, and you are not the GM, all tokens you control are targeted.

There is no "protection" on targeting; anyone can target any token. It is assumed you are playing cooperatively!

Modifiers and Tags

Every command that rolls a dice (listed as "taggable") below also accepts any number of tags to specify properties of the roll that might alter modifiers, listed as hashtags after the command; eg #fear #arcane

Commands that roll skills automatically add the name of the skill and its governing attribute as tags: eg, rolling athletics will automatically add #athletics #strength without you needing to type them.

mod add will add a modifier to tracking. It must be followed by a name for the modifier, its type (c, s, i, or u for circumstance, status, item or untyped, respectively) and a set of tags. Only rolls with all the listed tags are affected.

For example, !pf @edgo mod add Bravery s 2 #fortitude #fear will add a modifier called "Bravery", affecting Ed Goblin, which is a +2 status bonus affecting rolls tagged with both "fortitude" and "fear".

Using mod add with the name of a modifier that already exists will update the existing modifier. Note that this checks only for a matching name, not matching targets. After the above command, !pf @billgo mod add Bravery s 2 #fortitude #fear will update the "Bravery" modifier to refer to Bill Goblin instead of Ed Goblin. If you want Ed to keep the modifier, you can either add a new named modifier for Bill (!pf @billgo mod add BraveryBill..., or modify the modifier to include them both !pf @billgo,edgo mod add Bravery...)

!pf mod list will list all current modifiers. !pf mod clear will erase all modifiers. !pf mod del <name> will delete the named modifier. These don't need any targets.

mod explain will display a table calculating how the final modifier for the given targets and tags is calculated - when rolling, normally only the final modifier is shown. So, for example, !pf @edgo mod explain #fortitude will show the net effect of all modifiers affecting all Fortitude rolls made by Ed Goblin (but not specific types of Fortitude rolls)

Functional Commands

get <value> will read the named value from the character sheet and print it out, applying any active modifiers to it. This can be any stat, save, skill, or certain calculated values such as ac or level. Value names can be abbreviated to any unique prefix. Extra tags can be specified to customize modifiers. This is primarily intended for GMs to quickly read values from character sheets without opening them, but can be used by any player.

best <value> should be used with multiple targets. It works like get but displays only the highest value and the name of the target that has it. As with get, this is primarily intended for GMs who need to quickly know "the group's best Perception score", for example. It also respects modifiers and the specified tags, so if the best result is not what you expect, check a modifier isn't changing things!

assure <value> gets the Assurance value for the given skill on the selected target(s). It does not attempt to check that they have the Assurance feat. It does not accept tags or apply modifiers because the Assurance feat explicitly does not do so.

roll <value> (taggable) rolls the target value for all targets, applying modifiers for the given tags, and displays the results in a table. The results also include the highest level at which the roll beats the standard DC, and the highest opponent modifier such that the opponent's DC would be beaten.

rollinit <skill> (taggable) rolls initiative using the given skill, applying the initiative modifier from the character sheet. If no skill is specified the default is Perception. If a ! is included after the command (ie, rollinit!), the results are sent to the turn tracker. So you can quickly roll initiative for all pcs with !pf @pcs rollinit!.

ability <ability> [skill] (taggable) uses the given ability, rolling the appropriate skill or attribute and displaying an abbreviated form of the ability's success/failure chart in chat. Ability names are lower case without spaces as with character names, and can be abbreviated to any unique suffix. If the ability is Secret, the roll is sent only to the GM. If the ability is one which allows the player to choose the used skill, the skill must be specified after the ability.

Supported Abilities

The following basic abilities from the core book are supported. This shows the string that can be entered to refer to them; any unique prefix can also be used. For example, borrowanarcanespell can be abbreviated to just borrow, or even bo. Unfortunately, leaving out articles cannot be used as an abbreviation (eg, creatediversion for createadiversion will not work). Inconsistencies in article use match the main rulebook.

The symbol * indicates an ability is secret. + indicates that a skill must be specified.


The two uses of Medicine are represented as separate abilities: stabilize and stopbleeding.

identifycreature is technically a special case of Recall Knowledge but is supported as a separate ability as a reminder.

The following class special abilities or skill feats are also supported. Note that the script makes no attempt to check that targets actually have these abilities.


Also, the following custom actions from Adventure Paths are included. They are prefixed by abbreviations indicating the adventure path in order to minimise accidental matching.

aabefriendalocal (Age of Ashes Player's Guide)
aaadministeraltaerein (Age of Ashes 2)
aaorganizelabor (Age of Ashes 2)
aatopplecrates (Age of Ashes 3)
aadeducetraditions (Age of Ashes 4)
aainfluenceregent (Age of Ashes 4)
aacheckthewalls (Age of Ashes 4)
aaguildinvestigation (Age of Ashes 4)
aaseekthehiddenforge (Age of Ashes 4)
aabuildconnections (Age of Ashes 5)
aahostevent (Age of Ashes 5)
aainfluenceguild (Age of Ashes 5)
aaissuechallenge (Age of Ashes 5)
aadistractguards (Age of Ashes 6)
aainvestigatechamber (Age of Ashes 6)
aaconvincemengkare (Age of Ashes 6)
ecpromotethecircus (Extinction Curse 1)
ecperformatrick (Extinction Curse 1)

Supported values

These are legal values for <valuename> in the above command listing.

  • Statistics: strength dexterity constitution intelligence wisdom charisma. Since only a unique prefix is required, the standard abbreviations str dex con int wis cha also work.
  • Skills: acrobatics arcana athletics crafting deception diplomacy intimidation medicine nature occultism performance religion society stealth survival. Lore skills are not currently supported.
  • Saves: fortitude reflex will.
  • Perception (not technically a skill, but acts like one): perception.
  • Armor class: ac.
  • Level: level.
  • Current HP: hp.
  • Initiative modifier: initiative. Note that this is only the additional modifier added to skill rolls to calculate initiative; the base modifier for initiative rolls is the skill in question, which is variable. Use !pf rollinit to roll values with the initiative modifier added.
  • Melee to-hit with first melee weapon: melee. May be zero if no melee weapon is equipped.
  • Ranged to-hit with first ranged weapon: ranged. May be zero if no ranged weapon is equipped.


v240520 (2020-05-24)

  • Added "melee" and "ranged" property specifiers
  • Changed internal model from class to revealing module
  • No longer crashes listing modifiers if a token affected by a modifier was deleted
  • Results for tokens with the same name in multiple selections are no longer merged

v160520 (2020-05-16)

  • "AC" as a property specifier is treated as armor class, not a shortening of acrobatics
  • Assure command added
  • Get and Best are now taggable and respect modifiers
  • Some more abilities added from Age of Ashes

v100520 (2020-05-10)

  • Release