¶ Introduction
Rule Elements are the new tool we are using for the PTR system to handle most of the basic automation for any type of item (feats, edges, abilities, moves etc.)
Rule Elements generally are quite stable and should catch errors without breaking or corrupting your actors.
This document will often refer to items, actors and rules.
In Foundry terms, an item is something that goes on an actor, while an actor is a type of being, in our case Trainers (type: character) and Pokemon (type: pokemon)
¶ What is a Rule Element?
A Rule Element or Rule is a series of instructions written in JavaScript Object Notation (JSON), which can then be applied to an item. When that item is then added to an actor it will modify the actor's data in some way, shape or form. It's an easy way of creating automation without requiring to code it!
This is the prefered way to add automation where possible, as it does not require any hard-coding in the system and can be re-used for other items. Despite the fact that JSON sounds hard and may look a little intimidating at first glance, it's a lot easier and more flexible than writing macros, and where possible we are adding UIs for rules to help make it even easier for you to fill them in!
¶ My First Rule Element
For this guide we'll start of with a sample rule, this one is made based off of the Feature Acquired Knowledge
Acquired Knowledge
Prerequisites: Novice Pokemon Education
Static
Effect: Add your Pokemon Education Rank * 2 to any capture check you make
{
"key": "FlatModifier",
"label": "Acquired Knowledge",
"selectors": "capture-check",
"slug": "acquired-knowledge",
"value": "@actor.system.skills.pokemonEd.value.total * 2"
}
Lets break this down:
- Key: This is the name given to the rule element within the code
- If this one is incorrect, your rule will be ignored!
- Label: Name your rule! Some rules will use this for displaying in the UI. f.e., when posting to the chat
- Selectors: This specifies what to apply your modifier to.
- A list of selectors can be found at the bottom of this document
- Having no selectors will make your rule do nothing
- Add the
_idof an item to the selector to target a specific item - A selector can be singular as in this example, or can be an array and specify multiple.
- Slug: Modifiers only allow one modification from the same source, this is identified using the
slug, if you have the same item twice providing the same effect, by default it will only trigger once. To work around this limitation, you can give them both unique slugs. This is however something you rarely will have to worry about, as the field is optional and will automatically use the Label to generate a slug if one isn't provided. - Value: The value you wish to provide
- You can directly apply a number like
5 - But you can also apply a math formula if you wrap it in a string like
"5 + 5" - In a string you can also resolve other attributes, such as in the example where we grab the actor's pokemonEd skill rank.
- A non-exhaustive list of properties can be found at the bottom of this page, as well as an explanation on how to find more.
- You can directly apply a number like
There is one more important property know about, this is the predicate property, and I will explain it using a simplified version of the Torrent (Last Chance Water) ability, ignoring the secondary part of the effect.
Torrent
Effect: The user gains a +5 bonus to Damage Rolls when using Water-Type moves. This bonus increases to +10 when the user is under 1/3rd of their Maximum Hit Points
{
"key": "FlatModifier",
"label": "Torrent",
"selectors": "damage-roll",
"slug": "Torrent",
"value": "5",
"predicate": ["move:type:water"]
}
- Predicate: If you want your bonus to only apply at certain times, like in this case only if the move is a Water Type, you can define so in this field.
- Predicates are an array, which means they need to have
[]around them. You can seperate multiple items with,. Every item in the array must be satisfied to enable the rule element.- F.e., if you wanted it to only trigger on special water moves you could make the predicate
"predicate": ["move:type:water", "move:category:special"]
- F.e., if you wanted it to only trigger on special water moves you could make the predicate
- Usually the thing you predicate on is called a "Roll Option". There are way too many out there to list them all, but some of the most useful ones will be listed down below.
- Think of each roll option as a statement about the state of the game, or the actor/item. While predicates are tests of those statements to determine if the effect should be active
- You can use any of the basic logical tests as part of a predicate:
and,or,nor,nand,not,lt(less than),lte(less than or equal to),gt(greater than),gte(greater than or equal to).
- Predicates are an array, which means they need to have
¶ Basic Rule Elements
Basic rules are the most simple variants of Rule Elements and can often be enhanced with advanced rule elements found in a later section of this guide
¶ Effectiveness
The Effectiveness Rule Element allows you to manipulate the effectiveness of a type on the target Actor.
{
"key": "Effectiveness",
"type": "Normal",
"value": 2
}
Please keep in mind that the value of Effectiveness is an addition to what is currently the case, and is calculated in steps of times 2 or divide by 2.
For example, if you are 1.5x weak to Water, and you add a Water Effectiveness rule with value 2, your total will become 2x weak to Water, while if you had added it with a value of 0.5, it would make Water neutral against you.
¶ Flat Modifier
FlatModifier was featured in the introduction already, and this is one of the rules which has a UI associated with it. We can use this to highlight some other features available to many rule elements: brackets
{
"key":"FlatModifier",
"label":"Torrent",
"selectors":"damage-roll",
"predicate":[
"move:type:water"
],
"value":{
"brackets":[
{
"end":33,
"value":10
},
{
"start":34,
"value":5
}
],
"field":"actor|system.health.percent"
}
}
Brackets are a way of changing the value based on some actor/item's current data.
Brackets are built up from multiple smaller objects that tell the value to change at certain points, the above example adds +10 to damage if your HP percent is 33 or lower, and otherwise adds +5, automating the Last Chance ability fully.
The value in question is defined in field.
Now what if we want to only add +10 if your health is below 33% and otherwise nothing? Well then we could instead use a different predicate:
{
"key":"FlatModifier",
"label":"Torrent",
"selectors":"damage-roll",
"predicate":[
"move:type:water",
"lte": ["{actor|system.health.percent}", 33]
],
"value":10
}
You can combine and nest predicates as much as you want to make truly complex predicates.
¶ Temp HP
The TempHP Rule Element as the name suggests, allows you to grant Temporary Hit Points to an actor the moment the effect is applied.
You can easily derive the Temp HP value from a character, for example by giving them a tick of their HP as Temp HP.
{
"key": "TempHP",
"value": "@actor.system.health.tick",
"removeOnDelete": true
}
If you would like the Temp HP to persist even after deleting this effect, simply set the removeOnDelete property to false, by default this one is true and does not need to be included.
¶ Temp Species
The Temporary Species Rule Element allows you to temporary alter the species of a Pokemon Actor, this can be useful for things like Mega Evolution.
You can either provide the UUID (recommended) of the species it should temporarily be transformed into, or manually build up a species object (not recommended).
This does not change things like their current Abilities, Moves, etc. Only the base stats, capabilities and the like are changed.
A sample from the Mega Sceptile effect:
{
"key":"TemporarySpecies",
"predicate":[
"species:sceptile"
],
"uuid":"Compendium.ptu.species.Item.q8NvxY7vmTv8s18x"
}
¶ Token Light
The TokenLight rule element can be used to add a light source to a token using an effect. The json data for such an effect should contain all the needed Foundry data to create a light source. You can find all the properties in Foundry API's LightData Definition. the dim and bright properties can have bracketed values.
{
"key": "TokenLight",
"value": {
"animation": {
"intensity": 4,
"speed": 1,
"type": "torch"
},
"bright": 1.5,
"color": "#f18927",
"dim": 2,
"shadows": 0.2
}
}
¶ Token Name
TokenName is a simple rule element that overrides a token's name. This is useful if you have a disguise effect or for things like Mega Evolution.
{
"key": "TokenName",
"value": "???"
}
¶ Token Image
This rule element will allow you to change the image of a token, this can be useful for temporary form-changes like Mega Evolution, like this example here for Mega Sceptile which uses two of these rules:
{
"key":"TokenImage",
"predicate":[
"species:sceptile",
"self:pokemon:shiny"
],
"value":"/systems/ptu/static/images/sprites/254s_MEGA.webp"
}
{
"key":"TokenImage",
"predicate":{
"and":[
"species:sceptile",
{
"not":"self:pokemon:shiny"
}
]
},
"value":"/systems/ptu/static/images/sprites/254_MEGA.webp"
}
Additionally you can also specify the scale, tint and alpha properties to modify your token image further!
¶ Type Overwrite
The Type Overwrite rule element can be used to manipulate the types of an actor, both for Trainers or Pokemon.
As you can see in the example above, Type Overwrite will overwrite the type of a Pokemon, but it stacks with other Type Overwrite rule elements, so if you first overwrite something to be a Water/Fire type, any further Type Overwrite rules would add to the total, unless the overwrite property is set to true.
There currently is no way to decide the order of when this would apply, but as of now no real use-case for this has been found.
Besides this, you may also want to add a type to a pokemon, in that case you can use something like the following:
{
"key":"TypeOverwrite",
"value":[
"{actor｜species.system.types}",
"Steel"
]
}
Taking the original types of the Pokemon's species and adding Steel on-top of it.
¶ Complex Rule Elements
¶ Active Effect Like
You may remember Active Effects from older versions of PTR. Active Effects allow us to manipulate a certain piece of data on character sheets like adding modifiers to your stats.
Active Effects should generally be your 'last resort' rule type, they are the most basic and 'raw' of the rule types, which can often cause unintended side effects. However you will see them used often in items of type effect
Effect items are an item type we will often embed in the text of another feature, for example Effect: Agile which a link to can be found in the feature Agile Training
[
{
"key":"ActiveEffectLike",
"path":"system.modifiers.capabilities.all",
"mode":"add",
"value":1
}
]
The above rule simply adds the associated values to the Actor, and this can stack as many times as you want. So you could have one Effect: Agile from your daily training, and another for when you Order your pokemon, to double the effect.
¶ Roll Option
RollOption is an extension to the AE-Like rule element, it is effectively a shortcut for setting roll options.
The domain field is optional and will default to all, meanwhile the option field is mandatory as you need to describe the option you wish to set! These options will then be put under the appropriate actor's flags.ptu.rollOptions.[domain].[option]
The option is the thing you will want to predicate on in other rule elements
{
"key": "RollOption",
"domain": "all",
"option": "inspired-training",
}
This would set the rolloption inspired-training which another Rule can use in their predicate
{
"key":"ActiveEffectLike",
"label": "Critcal Moment",
"path":"system.modifiers.initiative.mod",
"mode":"add",
"value":8,
"predicate": ["inspired-training"]
}
You can use any domain or option, however keep in mind that not every domain is used in every check. For example, a damage roll checks the damage-roll domain but does not check the capture-check domain. All rolls will check the all domain, however we want to avoid overstuffing one domain as much as possible. As a general rule use all if unsure or if many different domains need to make use of this rule. Otherwise use a specific one.
Roll Option has a useful UI as well as shown here with Fountain:
A list of useful Roll Options can be found at the bottom of this guide.
¶ Grant Item
The GrantItem rule allows for an item to be granted to an actor by another item. This occurs whenever the item is first added to said actor, the rule won't do anything if retroactively added to an item already existing on a character.
The example here is the Work Up edge, which grants the Work Up move
{
"key":"GrantItem",
"uuid":"Compendium.ptu.moves.Item.E8b4fi2ZakBHepmr"
}
You can find an item's compendium UUID by opening the item in the compendium, going to its rules tab and it'll display right there, clicking the button on the right will automatically copy it to your clipboard:
Just like with other rules you can add predicates so the grant will only trigger for certain characters.
As an example, lets say that this rule only works if you have the class Martial Artist:
{
"key":"GrantItem",
"uuid":"Compendium.ptu.moves.Item.E8b4fi2ZakBHepmr",
"predicate": ["class:martial-artist"]
}
However, due to how GrantItem works, if a character later is updated and does meet the predicate, the rule won't be triggered again thus the item won't be granted.
In this case you can add "reevaluateOnUpdate": true to cause the Rule Element to check if the character does meet the prerequisite after any update.
Sometimes it may also be useful to turn on "replaceSelf": true after the item is granted, the original item will be deleted. This can be useful if you want something to replace something else, for example in the system we have the move "Bubblebeam" but there are two items for it "Bubblebeam" and "Bubble Beam", we could give one of these two a GrantItem rule with "replaceSelf": true to automatically turn it into the other one!
Finally, you can also use GrantItem with ChoiseSet to allow your user to choose an item from a list, an example of this is the Hobbyist's Dilettante
{
"key":"ChoiceSet",
"flag":"dilettanteRank1Feat",
"adjustName":false,
"allowedDrops":{
"label":"Custom General Feat",
"predicate":[
"item:type:feat",
"feat:type:general"
]
},
"choices":[{
"value":"Compendium.ptu.feats.Item.1otscPPJIq4HWkwD"
},{
"value":"Compendium.ptu.feats.Item.Wvs66BTJ7t6965f2"
},{
"value":"Compendium.ptu.feats.Item.PMI58lLIZJqHwuwW"
},{
"value":"Compendium.ptu.feats.Item.JiO7eCRryFoYiBSe"
},{
"value":"Compendium.ptu.feats.Item.beL0mQ0ddaiE24tt"
},{
"value":"Compendium.ptu.feats.Item.NVnFquC0fdo74toT"
},{
"value":"Compendium.ptu.feats.Item.M028wUlRhCcuOqZ3"
},{
"value":"Compendium.ptu.feats.Item.1DFCJm5rhnTh8pJz"
},{
"value":"Compendium.ptu.feats.Item.UF07jMVuiSeRawZR"
},{
"value":"Compendium.ptu.feats.Item.r1OvX4IECRfZUkwJ"
},{
"value":"Compendium.ptu.feats.Item.2WbLqVLtcQhLOUyi"
},{
"value":"Compendium.ptu.feats.Item.mIqSUpYJRx7QoIWd"
},{
"value":"Compendium.ptu.feats.Item.c2uDrArNVis0yMlT"
},{
"value":"Compendium.ptu.feats.Item.MkkO6bYRLHH2TaZW"
}]
}
{
"key":"GrantItem",
"uuid":"{item|flags.ptu.rulesSelections.dilettanteRank1Feat}",
"onDeleteActions":{
"grantee":"restrict",
"granter":"cascade"
},
},
If you are granting an item that has a ChoiceSet you can also pre-select the choice if you so desired.
{
"key": "GrantItem",
"preselectChoices": {
"basic-skills": "acrobatics"
},
"uuid": "Compendium.ptu.edges.Item.HSJnMW0wcFNtbhp7"
}
The onDeleteActions object controls the deletion behavior whenever either the granter or grantee gets deleted. grantee is the item that was granted by the effect granter is meanwhile the effect granting the item.
In most cases grantee will be the property to modify. In this case restrict locks the feature in place for as long as we have the Dilettante Rank 1 feat. The other two valid options are cascade which will delete both granter and grantee if either are removed, and finally detach which means they can be deleted independently.
¶ Choice Set
The ChoiceSet rule is highly flexible and can be used to prompt users to make a choice from a list of options. This choice is then stored as a flag on the actor, which can then be referenced by other rule elements using the data path flags.ptu.rulesSelections.[flag]
{
"key":"ChoiceSet",
"adjustName":true,
"choices":[
{
"label":"acrobatics",
"value":"system.skills.acrobatics.value.mod"
},
{
"label":"athletics",
"value":"system.skills.athletics.value.mod"
},
{
"label":"charm",
"value":"system.skills.charm.value.mod"
},
{
"label":"combat",
"value":"system.skills.combat.value.mod"
},
{
"label":"command",
"value":"system.skills.command.value.mod"
},
{
"label":"generalEd",
"value":"system.skills.generalEd.value.mod"
},
{
"label":"medicineEd",
"value":"system.skills.medicineEd.value.mod"
},
{
"label":"occultEd",
"value":"system.skills.occultEd.value.mod"
},
{
"label":"pokemonEd",
"value":"system.skills.pokemonEd.value.mod"
},
{
"label":"techEd",
"value":"system.skills.techEd.value.mod"
},
{
"label":"focus",
"value":"system.skills.focus.value.mod",
},
{
"label":"guile",
"value":"system.skills.guile.value.mod",
},
{
"label":"intimidate",
"value":"system.skills.intimidate.value.mod",
},
{
"label":"intuition",
"value":"system.skills.intuition.value.mod",
},
{
"label":"perception",
"value":"system.skills.perception.value.mod",
},
{
"label":"stealth",
"value":"system.skills.stealth.value.mod",
},
{
"label":"survival",
"value":"system.skills.survival.value.mod",
}
]
}
Which can then be used to increase the path defined in value like so:
{
"key":"ActiveEffectLike",
"mode":"add",
"path":"{item|flags.ptu.rulesSelections.basicSkills}",
"value":1,
"priority":10
}
If you'd like, besides a label you can also provide an "img" property so that the option will display an image.
You can also provide a UUID in the value, in which case the label is no longer necessary, as it is automatically pulled from the linked item.
Now to explain a few more properties including optional ones not shown above:
The adjustName property when set to true will change the name of the item that applied this effect to include the choice label. For example, Basic Skills (charm).
The flag property can be used to customize the flag, by default it will be set to the label as dromedaryCase.
The prompt property can be used to customize the prompt, the default prompt is "Make a selection."
By default choices only persist on the item in question, but if you'd like for them to also be set as a rollOption on the actor you can do so using the rollOption property like "rollOption": "basic-skill:selection" which if we picked charm would create a rollOption on the all domain of the actor with value: "basic-skills:selection:charm"
¶ Ephemeral Effects
An EphemeralEffect Rule Element allows you to place temporary effects that only apply during some calculations. For example, you may want to automate the Scrappy Ability which allows the user to ignore the Normal & Fighting type immunity of opposing ghost types.
{
"key": "EphemeralEffect",
"affects": "target",
"predicate": ["target:types:ghost"],
"selectors": ["damage-received"],
"uuid": "Item.8ghrCQlqPNclDxK9"
}
The above image doesn't show a predicate, but in the example json I have provided one for completeness.
¶ Lists
¶ Selectors
Properties in brackets [like-this] are references to a dynamic value. For example [move-id] refers to the id of a move item.
all (all checks & damage rolls)
attack
attack-roll
[move-id]-attack
[move-slug]-attack (attack name in hyphen-case)
[move-type]-attack (attack type, such as water)
[move-category]-attack (move category, such as physical)
[move-frequency]-attack (move frequency, such as at-will)
melee-attack
ranged-attack
self-attack
damage-roll
[move-id]-damage
[move-slug]-damage
[move-type]-damage
[move-category]-damage
[move-frequency]-damage
melee-damage
ranged-damage
self-damage
damage-received
save-check
save-dc
skill-check
skill-[skill] (such as skill-charm)
skill-check-dice
skill-[skill]-dice (such as skill-charm-dice)
pokeball-throw
capture-check
capture-dc
initiative
¶ Roll Options
Listed below are some of the roll options you may wish to use, of course you can always create your own as needed.
struggle:[type] - F.e. 'water' to grant struggle of a certain type, telekinetic type is 'normal'
condition:disabled:[move-slug] - Keeps track of disabled moves
[item-type]:[item-slug] - keeps track of whether you have a certain item, f.e. feat:quick-capture, class:martial-artist, condition:sleep
self:[option] - Checks whether the user of a move has a certain option
target:[option] - Check whether target of a move has a certain option
damage:component:critical - When damage is a crit
item:overwrite:defense:[stat] - Overwrite what defensive stat is used to resolve this attack
origin:distance:[number]
target:distance:[number] Distance between origin & target
move:target:underground - Used to tell a move to ignore negative altitude if the target is underground (this is a special state, and not just by burrowing)
move:target:underwater - Used to tell a move to ignore negative altitude if the target is underwater (this is a special state, and not just by swimming)
move:target:sky - Used to tell a move to ignore positive altitude if the target is in the sky (this is a special state, and not just by flying/levitating)
target:location:underground - Used to signify a target is underground through usage of moves such as Dig
target:location:underwater - Used to signify a target is underwater through usage of moves such as Dive
target:location:sky - Used to signify a target is in the sky through usage of moves such as Fly
self:immune:flanked - Used to signify the actor is immune to being flanked
target:flanked - Applied only during a calculation when a user is flanked
self:ignores:defensive - Ignore defensive abilities