Skip to content

Quickstart guide for rule elements

Jump to bottom
Gunnar Busch edited this page Mar 24, 2021 · 133 revisions

[[TOC]]

Introduction

A short guide to using rule elements:

Note: This document refers to items, items are feats/ class features, spell effects, weapons basically anything that can be added to a character Note: This interface is currently being developed and subject to change Note: Take care when adding rule elements, make sure to do any troubleshooting/experimenting on a spare/blank token/actor Note: People love to talk rule elements on the discord! Ask for help or questions Note: This is document is not exhaustive

What are they?

A series of instructions applied to an item that modifies the character sheet in some way. It another way to create change without coding!

When would I use them?

For setting up modifiers, conditions that apply to a character for example a barbarians Rage, bless/ inspire courage, etc.

How do they work

  1. Enable the rules elements in-game settings -> configure settings -> system settings -> Advanced Rule Element using
  2. Check that they have been activated:
    • Open any item and check that the "rules" tab is revealed
  3. Try some out, head to the compendia, and find spell effects, pick one and drag it to your character.
    • inspire courage is a good place to start.
  4. Open up the spell effect you chose and look at Rules Tab notice text in the boxes, that is a rule element

A correctly created rule element will do the work of several lines of macro. Once you get the hang of them it allows for easy automation.

My First Rule Element

The first Rule Element for this guide is the Item Bonus of the Armbands of Athleticism

{
    "key":"PF2E.RuleElement.FlatModifier",
    "label":"Armbands of Athleticism",
    "selector":"athletics",
    "type":"item",
    "value":2
}

They might be tricky to get the hang of. These once set up, will save you lines and lines of code.

Let's break these down:

  1. Key: This is the name given to the rule element within the code.
    • If this is not correct your rule with do nothing!
  2. Label: Name your rule. For flat modifiers text will show up when you look at the modifiers of a given roll
    • To see this in action apply the rule effect then look at the ac modifiers, you should see "Inspire courage"
  3. Selector: Specifies, or selects, what to apply your modifier to.
    • There is a list at the bottom of the document.
    • An incorrect selector will make your rule do nothing
    • Add the _id/ of an item to the selector to target a specific item or item type
  4. Type: This is the modifier type,
    • With this set appropriately the modifier will be taken into account for bonus stacking rules
  5. Value: the value can be minus if you are applying a penalty

A slightly more advanced case appears in inspire courage, only one of these contains the new element, so this guide will keep the other two "minified"

{"key":"PF2E.RuleElement.FlatModifier","label":"Inspire Courage","selector":"attack","type":"status","value":1}

{"key":"PF2E.RuleElement.FlatModifier","label":"Inspire Courage","selector":"damage","type":"status","value":1}

{
    "key":"PF2E.RuleElement.FlatModifier",
    "label":"Inspire Courage (vs fear)",
    "predicate":{
        "all":[
            "fear"
        ]
    },
    "selector":"will",
    "type":"status",
    "value":1
}
  1. Predicate: If you want your bonus to apply only at certain times, like only vs. fear, you can use a predicate, which comes in three modes:
    • "all": if everything in the list is present for a roll the modifier is applied
    • "any": if at least one in the list is present the modifier is applied
    • "not": if at least one item in the list is present the modifier is not applied
    • an incorrect predicate will make your rule act unexpectedly, these are case sensitive.
    • predicates currently enjoy automation from the spell save button and weapon attacks/damage by querying all their traits. They can also be set in Macros.

Basic Rule Elements

This and the following section will present basic variations of all Rule Elements, most of these can be enhanced with the advanced Rule Element controls later in this guide.

Flat Modifier

In the introduction Flat Modifiers got a lot of spotlights already, but they are good to introduce one more of the major automation features, brackets:

PF2E.RuleElement.FlatModifier

{
    "key": "PF2E.RuleElement.FlatModifier",
    "selector": "damage",
    "label": "Rage",
    "predicate": {
        "not": [
            "agile", 
            "rage"
        ]
    },
    "value": {
        "brackets": [
            { 
                "end": 6, 
                "value": 2 
            },
            { 
                "start": 7,
                "end": 14,
                "value": 6
            },
            { 
                "start": 15, 
                "value": 12 
            }
        ]
    }
}

Brackets, by default, use the Level of the player or monster the Rule is attached to. This Modifier adds the Barbarian Rage Damage the way a Fury Instinct Barbarian does.

For some cases, like a swashbuckler's precise strikes, "damageCategory" can be used to change the damage to precision damage, "damageType" can be used to change the damage to "fire" for certain barbarians.

It is possible to query different values, as is explained in the advanced controls sections.

Toggle Property

A Toggle Property adds a checkbox to the Character's action sheet. The path in the property follows the schema "flags.pf2e.rollOptions.." where corresponds to the selector of another Rule Element that gets activated or deactivated with the toggle and is a unique name for the toggle that is used in the predicate of the other Rule Element.

PF2E.RuleElement.ToggleProperty

{
    "key": "PF2E.RuleElement.ToggleProperty",
    "property": "flags.pf2e.rollOptions.damage-roll.power-attack"
}

A toggle Property may also have a label to change the text beside the checkbox from the item's name to a more fitting one. For Power Attack, the label is the name of the feat and doesn't need to be changed.

Damage Dice

A Damage Dice Rule element adds additional Dice to damage or critical damage rolls. The example adds 3d6 piercing damage to a critical strike with an improvised weapon.

PF2E.RuleElement.DamageDice

{
    "critical": true,
    "key": "PF2E.RuleElement.DamageDice",
    "selector": "damage",
    "diceNumber": 3,
    "dieSize": "d6",
    "damageType": "piercing",
    "predicate": {
        "all": [
            "improvised"
        ]
    },
    "label": "Shattering Strike"
}

dieSize and damageType can be omitted to add additional damage dice of the type and size that the weapon already has to the damage.

The diceNumber or dieSize properties can be set in a value brackets object, examples for such use are in the advanced section. Targeting a very specific weapon with this rule is also explained in the advanced section.

Base Speed

To add a base speed value, maybe with a Fly Spell Effect or with a feat granting a climbing speed a Base Speed Rule can be used.

The speed rule elements were built for the familiars, with the intention of refactoring the PCs to use the same data structure for speed. That refactoring has not (yet?) happened.

PF2E.RuleElement.BaseSpeed

{
    "key": "PF2E.RuleElement.BaseSpeed",
    "selector": "fly",
    "value": 30
}

The selector for the Base Speed Element differs from the list of selectors at the end of this file by omitting the "-speed" part.

Fixed Proficiency

This Rule Element can be used well for Animal Form and similar spells, as the name suggests it sets the proficiency to the given value. It appears in the game as a modifier to the skill that makes up for the difference.

PF2E.RuleElement.FixedProficiency

{
    "key":"PF2E.RuleElement.FixedProficiency",
    "selector":"athletics",
    "value":9
}

The Fixed Proficiency Rule supports a label and a name if the label is not unique.

Strike

This rule element is a bit trickier in that there are a lot of necessary fields. The easiest way to create your own custom strike would be to start from a finished strike like the monk's Tiger Claw strike here.

PF2E.RuleElement.Strike

{
    "key": "PF2E.RuleElement.Strike",
    "category": "unarmed",
    "damage": {
        "base": {
            "damageType": "slashing",
            "dice": 1,
            "die": "d8"
        }
    },
    "group": "brawling",
    "label": "Tiger Claw",
    "range": "melee",
    "traits": [
        "agile",
        "finesse",
        "unarmed",
        "nonlethal"
    ]
}

If necessary an "ability": "int"-entry could be used for a strike that scales its to-hit with intelligence, as the "Spiritual Weapon" Spell could. This works with the other 3 character ability shorthands too. The advanced section will cover how to use a custom weapon proficiency with a strike. To add a Flat part to the damage like an ability modifier, add an additional Flat Modifier Element.

Note

The Note Rule Element adds additional text to the chat output of a roll. The Example (taken from the Alchemist's Evasion Feat) adds a reminder to all reflex saves about the feat.

PF2E.RuleElement.Note

{
    "key":"PF2E.RuleElement.Note",
    "selector":"reflex",
    "text":"<p class='compact-text'><strong>{item|name}</strong> When you roll a success on a Reflex save, you get a critical success instead.</p>"
}

for damage Rolls, it is possible to set a message only on a critical roll or only on a normal hit.

{
  "key": "PF2E.RuleElement.Note",
  "selector": "damage",
  "text": "<p class='compact-text'><strong>Axiomatic Rune</strong> When you critically succeed at an attack roll with this weapon against a chaotic creature, instead of rolling, count each weapon damage die as average damage rounded up (3 for d4, 4 for d6, 5 for d8, 6 for d10, 7 for d12).</p>",
  "outcome": ["criticalSuccess"]
}

Dexterity Modifier Cap

Some spells and items, while not armor, do impose a cap on the dexterity modifier. For those, a Dexterity Modifier Cap can be set per Rule Element.

PF2E.RuleElement.DexterityModifierCap

{
    "key": "PF2E.RuleElement.DexterityModifierCap",
    "value": 5
}

Sense

A Rule ELement for Feats, Spells, and Items that grant additional senses or increase the acuity of existing ones. The Examples are the bloodhound mask and the Sensate Gnomes scent.

PF2E.RuleElement.Sense

{
    "key": "PF2E.RuleElement.Sense",
    "label": "PF2E.SensesDarkvision",
    "selector": "darkvision"
}
{
    "acuity":"imprecise",
    "key":"PF2E.RuleElement.Sense",
    "label":"PF2E.SensesScent",
    "range":30,
    "selector":"scent"
}

For these Rules, the Label is queried from the language database.

Weapon Potency and Striking

The weapon potency and striking rule elements do basically the same as the flat modifier and damage dice rule elements, but with the additional feature of properly changing the damage rolls for things like backstabber (+2 to damage with a +3 potency rune) and deadly (more dice if striking rune).

PF2E.RuleElement.WeaponPotency

{
    "key": "PF2E.RuleElement.WeaponPotency",
    "selector": "{item|data.target}-attack",
    "value": 1
}

PF2E.RuleElement.Striking

{
    "key": "PF2E.RuleElement.Striking",
    "selector": "{item|data.target}-damage",
    "value": 1
}

Another Example would be the Handwraps of mighty blows at +1 striking:

{
    "key": "PF2E.RuleElement.WeaponPotency",
    "predicate":{
        "all":[
            "unarmed"
        ]
    },
    "selector": "attack",
    "value": 1
}

PF2E.RuleElement.Striking

{
    "key": "PF2E.RuleElement.Striking",
    "predicate":{
        "all":[
            "unarmed"
        ]
    },
    "selector": "damage",
    "value": 1
}

Multiple Attack Penalty

The Multiple Attack Penalty rule element can change the MAP Progression of specific strikes, or the character as a whole. The two sample Rule Elements implement a flurry ranger, put them on an Effect item and they'll make you hit very often

PF2E.RuleElement.MultipleAttackPenalty

{
    "key":"PF2E.RuleElement.MultipleAttackPenalty",
    "predicate": {
        "all": [
            "agile",
            "hunted-prey"
        ]
    },
    "roll-options": [
        "all"
    ],
    "selector":"attack",
    "value":-2
}
{
    "key":"PF2E.RuleElement.MultipleAttackPenalty",
    "predicate": {
        "all": [
            "hunted-prey"
        ],
        "not": [
            "agile"
        ]
    },
    "roll-options": [
        "all"
    ],
    "selector":"attack",
    "value":-3
}

Effect Rule Elements

While these Rule Elements can be used anywhere, just like the rest, they are usually used for temporary Effects and for technical reasons work better when used on an Effect item than with a Toggle Property.

Temp HP

Just as the name implies this Rule element adds Temporary HP to a character the moment it is added. Many Temp HP Effects derive their value from player stats, the Rage Element is a prime example of how this can be done with the system. The first example is from the Aeon Stone (Pink Rhomboid).

PF2E.RuleElement.TempHP

{
    "key": "PF2E.RuleElement.TempHP",
    "value": 15
}
{
    "key": "PF2E.RuleElement.TempHP",
    "value": "@details.level.value + @abilities.con.mod"
}

Set Property

This works as a toggle property or with a toggle property to toggle it off/on. It does, however, not add the checkbox to the Actions tab.

PF2E.RuleElement.SetProperty

{
    "key": "PF2E.RuleElement.SetProperty",
    "property": "flags.pf2e.rollOptions.all.rage",
    "on": {
        "added": true,
        "removed": false
    },
    "retain": true
}

Rage has a lot of different mechanics depending on the instinct and some feats, some of these need to be on an Effect item, like the temp HP and token size or even image changes. to avoid clutter it's easier to use predicated rules on feats and features and set them active with a rage effect using the setProperty rule element. Some breakdown:

  1. property: this works the same way as in the toggle property "flags.pf2e.rollOptions..name"
  2. on -> added: technically optional but mostly useless without it
  3. on -> removed: optional, will disable the "retain" field if present
  4. retain: optional, will restore the old value when an item with this rule element is deleted from the character.

Token Effect Icon

This will apply an effect icon to the token it is applied to.

PF2E.RuleElement.TokenEffectIcon

{
    "key":"PF2E.RuleElement.TokenEffectIcon"
}

By Default the Effect Icon is the Icon of the Item/feat/Effect that carries the Rule element, to change that an additional field can be used.

{
    "key":"PF2E.RuleElement.TokenEffectIcon",
    "value":"systems/pf2e/icons/spells/all-is-one-one-is-all.jpg"
}

Token Image

This rule element will change the token of an actor to the boar token that is included in the system. It is useful for Wild Shape or can be customized to set expressions on PCs per effect item.

PF2E.RuleElement.TokenImage

{
    "key":"PF2E.RuleElement.TokenImage",
    "value":"systems/pf2e/icons/bestiary-1/boar.webp"
}

Token Size

This rule element can be used on a 2nd level enlarge spell effect to resize the token. Deleting the latest TokenSize effect from the token will reset the size to the original token size again.

PF2E.RuleElement.TokenSize

{
    "key":"PF2E.RuleElement.TokenSize",
    "value":2
}

or:

{
    "key":"PF2E.RuleElement.TokenSize",
    "value":"large"
}

Effect Target

The effect target rule element will add a dropdown to the effect sheet, so you can make a selection - for example for a weapon. You can then use that for creating a dynamic selector to target an effect to a single weapon.

PF2E.RuleElement.EffectTarget

{
    "key": "PF2E.RuleElement.EffectTarget",
    "scope": "weapon"
}

Advanced Rule Element Controls

Bracket using Item Attribute

This Rule Element uses brackets that do not depend on the players level but on the carrier items level instead (In this case the Spell Effect for Heroism)

{
    "key":"PF2E.RuleElement.FlatModifier",
    "label":"Heroism",
    "selector":"saving-throw",
    "type":"status",
    "value":{
        "brackets":[
            {
                "end":5,
                "start":3,
                "value":1
            },
            {
                "end":8,
                "start":6,
                "value":2
            },
            {
                "start":9,
                "value":3
            }
        ],
        "field":"item|data.level.value"
    }
}

Character stats in value formula

in a value, the @ notation can be used to query anything under the actor.data path.

{
    "key": "PF2E.RuleElement.TempHP",
    "value": "@details.level.value + @abilities.con.mod"
}

Bracketed Properties

"value":{"brackets":[]} can be used to edit properties that are not the value property by declaring the properties in an object under "value". This example acts as a diceNumber Property on the lowest level of the Rule ELement.

{
    "key": "PF2E.RuleElement.DamageDice",
    "predicate": {
        "all": [
            "melee",
            "power-attack"
        ]
    },
    "selector": "damage",
    "value": {
        "brackets": [
            {
                "end": 9,
                "value": {
                    "diceNumber": 1
                }
            },
            {
                "end": 17,
                "start": 10,
                "value": {
                    "diceNumber": 2
                }
            },
            {
                "start": 18,
                "value": {
                    "diceNumber": 3
                }
            }
        ]
    }
}

Damage Dice override

It is possible to override damage dice properties by using an override field. In this case the Rule element will model the effect of a critical fatal d12 strike against a creature that is immune to critical damage, by increasing the number of dice by one undeclared (weapon) die and the range of the die to d12, regardless of the base damage die size.

{
    "key": "PF2E.RuleElement.DamageDice",
    "selector": "{item|_id}-damage",
    "critical": true,
    "diceNumber": 1,
    "override": {
        "dieSize": "d12"
    }
}

Advanced Selectors

To edit rolls derived from an item (only strikes and damage right now) you can prepend the selector with either a "slugified" version of the name (only small letters and "-") or the ID of the item. If you place the rule on the item you can use "{item|_id}" as part of the selector, this will be translated to the items ID without the hassle to look it up and is portable between items.

{
    "key": "PF2E.RuleElement.DamageDice",
    "selector": "{item|_id}-damage",
    "diceNumber": 1,
    "dieSize": "d4",
    "damageType": "fire",
    "predicate": {
        "all": [
            "on-fire"
        ]
    },
    "label": "Ignited"
}

Another way to prepend the selector is to use the "slugified" name of the weapon group like this:

{
    "key": "PF2E.RuleElement.FlatModifier",
    "selector": "brawling-weapon-group-damage",
    "value": 1,
    "label": "Ignited"
}

Predicate by proficiency

Some Rule Elements should only work if the character uses a specific proficiency, this can be done with brackets over "actor.data.skills.at.rank" or with predicates. An Example is the Rangers Masterful Hunter Feature, here a RUle Element for the Flurry Hunter.

{
    "key":"PF2E.RuleElement.MultipleAttackPenalty",
    "predicate": {
        "all": [
            "hunted-prey"
        ],
        "not": [
            "agile"
        ],
        "any": [
            "proficiency:master",
            "proficiency:legendary"
        ]
    },
    "roll-options": [
        "all"
    ],
    "selector":"attack",
    "value":-2
}

custom weapon category

As promised earlier in this guide here is a set of rule elements to create a proper Spiritual weapon attack. To get a custom martial proficiency create the proficiency first and then run this macro while substituting the name in it to your proficiencies name. If you have the console (f12) open at the same time you'll see an ID (some random letters/number) in a line when you run the macro, those will be the category for your custom proficient strike. If there is an error instead check that the name is exactly the same as on the sheet, including capitalization of the letters.

console.log(actor.items.find(i => i.name === 'spell')._id)
{
    "key":"PF2E.RuleElement.Strike",
    "category":"XU2ucQfB5Ojpdn2m",
    "damage":{
        "base":{
            "damageType":"force",
            "dice":1,
            "die":"d8"
        }
    },
    "group":"club",
    "label":"Spiritual Weapon",
    "range":"melee",
    "ability":"int"
}

this one needs to be on the effect to add the spellcasting modifier, set to int in this example.

{
    "key":"PF2E.RuleElement.FlatModifier",
    "label":"Intelligence",
    "selector":"spiritual-weapon-damage",
    "type":"status",
    "value":"@abilities.int.mod - @abilities.str.mod"
}

and the last one to accommodate heightening:

{
    "key":"PF2E.RuleElement.DamageDice",
    "label":"Heightening",
    "selector": "spiritual-weapon-damage",
    "value": {
        "brackets": [
            {
                "end": 5,
                "start": 4,
                "value": {
                    "diceNumber": 1
                }
            },
            {
                "end": 7,
                "start": 6,
                "value": {
                    "diceNumber": 2
                }
            },
            {
                "end": 9,
                "start": 8,
                "value": {
                    "diceNumber": 3
                }
            },
            {
                "start": 10,
                "value": {
                    "diceNumber": 4
                }
            }
        ],
        "field":"item|data.level.value"
    }
}

Rule Elements and Macros

Macros can fill many purposes in conjunction with Rule Elements. three of these uses are included in this guide:

  1. Adding an Effect Item (that usually will have rule elements on it) directly from the compendium or the Item Directory (this Macro can be used to add any other items as well once you get the hang of it)

To find the ITEM_UUID of the Effect, jsut drag it into an items description, you'll get something like this: @Compendium[pf2e.equipment-srd.Kf4eJEXnFPuAsseP]{Chain Mail}

To add this Item then to your Inventory (or delete it if you have it) set the ITEM_UUID to 'Compendium.pf2e.equipment-srd.Kf4eJEXnFPuAsseP'

const ITEM_UUID = 'Compendium.pf2e.spell-effects.Jemq5UknGdMO7b73'; // Spell Effect: Shield

(async () => {
  const item = await fromUuid(ITEM_UUID);
  for (const token of canvas.tokens.controlled) {
    let existing = token.actor.items.filter(i => i.type === item.type).find(e => e.name === item.name);
    if (existing) {
      await token.actor.deleteOwnedItem(existing._id);
    } else {
      item = duplicate(item);
      await token.actor.createOwnedItem(item);
    }
  }
})();
  1. toggling a toggle (not really a high value for a macro, but some people like the keyboard)
actor.toggleRollOption('all', 'target:flatFooted');

To not toggle but fix the state of the toggle this line can be used:

actor.setRollOption('all', 'target:flatFooted', true);
  1. Activate a Predicate using a Rule element. As written this macro and Effect will only work if the Effect is on a weapon called "Greataxe", because the Macro is rather restricted.
{
  "key":"PF2E.RuleElement.FlatModifier",
  "label":"Sweep",
  "selector":"{item|_id}-attack",
  "type":"circumstance",
  "value":1,
  "predicate":{"all":["Sweep"]}
}
let options = actor.getRollOptions(['attack']);
options.push('Sweep');
const strikeItem = () => ((actor.data.data.actions ?? [])
  .filter((action) => action.type === "strike")
  .find((strike) => strike.name === "Greataxe")
);
strikeItem().variants[1]?.roll(event, options);
  1. adding a condition and an effect with a single macro, using the giant rage as an example.
const ITEM_UUID = 'Compendium.pf2e.feature-effects.z3uyCMBddrPK5umr'; // const ITEM_UUID = 'Compendium.pf2e.feature-effects.z3uyCMBddrPK5umr'; // Effect: Rage
let conditionType = game.pf2e.ConditionManager.getCondition('Clumsy'); // condition clumsy

(async () => {
// Clumsy first, the Spell effect follows clumsy
  let conditionName = conditionType.name;
  let conditionValue = (token.actor.data.items.find((x) => x.name === conditionType.name)) ? 0 : 1; // set the value of a valued condition here
  if (conditionValue) await game.pf2e.ConditionManager.addConditionToToken(conditionType, token); 
  await game.pf2e.ConditionManager.updateConditionValue(token.actor.data.items.find((x) => x.name === conditionType.name)._id, token, conditionValue); // only for conditions with a value

// make the effect follow the condition
  let item = await fromUuid(ITEM_UUID);
  for (const token of canvas.tokens.controlled) {
    let existing = token.actor.items.filter(i => i.type === item.type).find(e => e.name === item.name);
    if (conditionValue) {
      if (!existing) {
        item = duplicate(item);
        await token.actor.createOwnedItem(item);
      }
    } else {
      if (existing) {
        await token.actor.deleteOwnedItem(existing._id);
      }
    }
  }

})();
  1. A full example of how to create a fully automation integrated action macro.

The system is currently in the process of getting full action support. A supported action can be called in a macro like this:

game.pf2e.actions.feint({ event });

Actions that have not yet gotten support or that you want to modify slightly for your game can be automated like this:

const a = token.actor ?? game.user.character;
const traits = ['concentrate', 'secret'];
const options = a.getRollOptions([
  'all',
  'skill-check',
  'arcana',
  'action:recall-knowledge'
]);
options.push(...traits);
options.push('action:recall-knowledge');

PF2Check.roll(
  new PF2CheckModifier('Recall Knowledge: Arcana', a.data.data.skills.arc),
  {
    actor: a,
    type: 'skill-check',
    options,
    notes: a.data.data.skills.arc.notes,
    traits,
  },
  event
);

List of valid selectors

List of valid selectors

all

str-based
dex-based
con-based
int-based
wis-based
cha-based
attack
spell-attack
attack-roll
str-attack
dex-attack
con-attack
int-attack
wis-attack
cha-attack

damage

saving-throw
fortitude
reflex
will

initiative
perception
class (still subject to change)

ac

hp
hp-per-level

speed
land-speed
burrow-speed
climb-speed
fly-speed
swim-speed

skill-check
acrobatics
arcana
athletics
crafting
deception
diplomacy
intimidation
medicine
nature
occultism
performance
religion
society
stealth
survival
thievery

Clone this wiki locally