Latest revision as of 13:18, 27 February 2022

Page Updated:   2022-02-27

Main Page: API:Script Index

Public releases as above. Dogfood builds at hyphz/Roll20PF2 .

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

[edit] Syntax

!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] damage! <amount> [tags..]
!pf[s] [@targets] heal! <amount> [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>

[edit] 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!

[edit] Script Use

[edit] Targeting

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. (A PC is defined as a token controlled by anyone who is not a GM.)

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!

[edit] Modifiers and Tags

Every command that is listed as "taggable" below also accepts any number of tags to specify properties of the roll/value that might contribute to calculating modifiers, listed as hashtags after the command; eg #fear #arcane

Each command also automatically adds some tags based on the nature of the check made. Skill checks automatically have the name of the skill, its governing attribute, and #skill as tags. Saving throws automatically have the same of the save, its governing attribute, and #save. So, for example, a roll reflex command will automatically be treated as having the tags #dexterity #reflex #save without you needing to enter these.

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; so, for example, the modifier added above with #fortitude #fear would not be listed since it does not affect all Fortitude rolls, only fear related ones)

[edit] 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.

damage! <amount> will deal damage to the selected tokens. Tokens controlled by PCs will have the damage applied to the character's HP on their character sheet. Tokens not controlled by PCs will instead have damage applied to token bar 1, which - if it is not already set up - will be set to the current and max HP from the related character sheet. (This is because multiples of the same monster usually have the same character sheet, so this ensures that damage done to one of them is not done to all). This accepts tags to modify the amount of damage done, and adds the automatic tag #damage, so you can use the modifier system to represent resistances or vulnerabilities. Note that the modifier is applied to the amount of damage, so resistances should be negative modifiers.

heal! <amount> will heal the selected tokens following the same rules as damage! and not exceeding their max HP. It would be very unusual for a character to have a modifier that affects healing amounts, but just in case, this accepts tags in the same way as damage! but adds the automatic tag #healing.

[edit] 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.

aid+
balance
borrowanarcanespell
climb
coerce
commandananimal
concealanobject*
craft
createadiversion
createforgery*
decipherwriting+*
demoralize
disarm
disabledevice
earnincome+
feint
forceopen
gatherinformation
grapple
hide*
highjump
identifyalchemy*
identifymagic*+
impersonate*
learnaspell+
lie*
longjump
maneuverinflight
palmanobject
perform
pickalock
recallknowledge*+
repair
request
seek*
sensedirection*
sensemotive*
shove
sneak*
squeeze
steal
subsist+
swim
track
treatdisease
treatpoison
treatwounds
trip
tumblethrough

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.

awesomeblow
battleassessment*
battleprayer
delaytrap
evangelize
goblinsong
recognizespell*+
sabotage
sacreddefense
scaretodeath
trainanimal
trickmagicitem
whirlingthrow

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)

[edit] 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.

[edit] Debugging Commands

These commands are intended for people who are modifying or working on the script itself. They do not produce "pretty" output and are not intended to be used during play.

• debug targets lists the names of all tokens targeted by the command's @ specification(s).
• debug rawget <attr-name> reads the named attribute from the Roll20 character sheet for each target and prints out its name and type. Note this uses the Roll20 internal names of the character sheet attributes, not those in the "supported values" section above (they do not always match).
• debug echo <message> prints the message back, to check that the script is responding at a basic level.

[edit] Changelog

v310520 (2020-05-24)

• Added "damage!" and "heal!" commands
• Fixed a bug in use of the selected token
• Records and matches token names as well as character names if they're different
• Generic autotags added for roll types

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