Nodes and automations, step by step

Start with a simple sentence

Write down what should happen: “if my Strength is 3 or more, I get a +2 bonus; otherwise, I get 0”. That sentence has one question and two possible results.

In the editor, Start marks where the rule begins. If asks the question. Each Bonus provides one result. Lines tell the rule which result to use. A box with no path from Start does not take part in the rule.

Names you will see

Step or node: a box that does one thing. Flow: the whole diagram of a rule. Connection: the line leading from a step to the next.

Condition: a question that may be met or not, such as “do I have at least 2 Mana?”. Trigger: the action that starts a rule, such as using a card. In the editor, what starts a rule may also be called an event.

Variable: a name that reads a sheet value, such as @forca. Expression: a formula using values, such as @forca + 2. Target: the field that will receive a change, such as current Health.

Canvas: the area displaying the diagram. This guide calls the rectangular steps boxes; resource cards are the items, spells and abilities on the sheet.

Does the rule stay active or happen when you use something?

For a bonus that follows Strength, use a rule that begins at Start. It calculates what applies in the current situation. The editor also uses this kind of rule to show fields and maintain effects from equipped items.

To spend mana when you use a spell, use a rule that begins at Trigger. A trigger means “what starts this rule”: using a button, using or equipping a card, or making a roll.

For example, a shield gives defense while equipped; a spell spends mana each time you use it. Open the automation in the part of the sheet that matches your idea. The editor offers the steps suitable for it.

Follow the lines to understand the order

Read from Start or Trigger and follow the lines. Moving a box only arranges the diagram: the lines define the order. On If, Yes follows when the condition is met; No follows when it is not.

To spend mana and then roll, connect Trigger → Change value → Roll dice. When one action depends on another, place them in that sequence. Two lines from the same output create separate paths.

For more than two alternatives, look up Switch in the reference. It compares several conditions and offers Default when none matches.

I want to calculate a bonus or show a field

Open the settings of the attribute, skill or block that should receive the rule. Look for the bonus, modifier or visibility automation editor. If these options do not appear, check that you are editing the sheet and that the field type supports automation.

A bonus is an extra number; a modifier is the calculated number used by that attribute; visibility decides whether something appears. In a bonus editor, the rule ends at Bonus. In a visibility editor, it ends at Show or hide.

Advanced block rules may offer other results, such as Modify field, Text and Theme. Start with the option that matches what you want to change.

I want something to happen on a click or roll

For an ability the player uses, open that button's action. For something that happens when clicking the sheet's drawing area, called the canvas, open that click action. Rolls and their advanced results may also offer automations.

Some screens already connect Trigger to Roll dice. Others allow only certain actions, such as Change value and Play sound. If a step does not appear in search, check that you opened the automation in the right part of the sheet.

I want a rule for a resource card

Edit the card and choose when the rule should apply. On use runs when the card is used. On roll responds to the rolls you choose. On equip runs an action when you equip the card.

While equipped maintains an effect for as long as the card is equipped. While present maintains it for as long as the card is on the sheet. For a shield that should lose its bonus when unequipped, choose While equipped.

A context menu option is an action in the menu of the card or supported element. Its Trigger defines the text, where it appears and when it is visible. For roll rules, also check which skills or blocks should start the rule.

Strength 3 or higher grants +2

Goal: receive +2 when Strength is at least 3 and 0 when it is lower. Open the bonus automation in an attribute or skill's settings. Use the ready-made diagram at the start of this guide as a reference.

In this guide, @forca means “the Strength value”. On your sheet, pick the variable the editor suggests for that attribute: the name may differ. The comparison >= 3 means “3 or more”.

1. Find Start in the diagram. It is the first step of the rule. If a Bonus is already connected to it, you will place the condition before that result.
2. Click + or Add step, search for If and add it. Connect Start's output to If's input by dragging between the small connectors on the boxes.
3. Click If. In its settings, choose Strength in the condition builder, compare with “greater than or equal” and enter 3. If using Expression mode, choose the suggested variable and complete the comparison; this example uses @forca >= 3.
4. Add a Bonus. Click it, choose Fixed and enter 2 in Value. Connect If's Yes output to this Bonus's input.
5. Add another Bonus with a Fixed value of 0. Connect If's No output to it. Check that Start reaches If first and that each path ends at its own Bonus. Remove an old connection that skips the condition.
6. Enable Test. Check a case with Strength 3 or higher and one below 3. The first should show +2; the second, 0. Use the test data controls available on that screen or a test copy of your sheet to check both cases.
7. Click Save. If it becomes Review issues, open the review and fix the indicated field or connection. Confirm the sheet settings screen too if it has another save button, then check the bonus on the field.

Start → If (@forca >= 3)
  Yes → Bonus (2)
  No → Bonus (0)

Two Bonus steps do not add themselves together

Bonus sets the result of that calculation. If the same path passes through Bonus 2 then Bonus 3, the result is 3. To get 5, use one Bonus with 5 or the expression 2 + 3.

To add values from other fields, use the variable names suggested by the editor. The example below adds two parts and provides the total through one Bonus. You can leave this formula until after the first exercise.

Bonus in expression mode:
@bonus_item + @bonus_treino

Where to click to add and edit steps

Click + or Add step, search for what you need and choose the step. The + on a connection inserts a step in the middle of it. Click the new box to open Configure step and fill in its fields.

A connection is the line between two boxes. Drag from an output to the next step's input to connect them. Next continues the rule. Yes and No are If's answers. Answer and Cancel are Ask's outputs. Chosen and Cancel are Choose's outputs.

Use Step name to give a recognizable name, such as Spend mana. Drag boxes to arrange the diagram. The settings panel may appear on the side or in a larger window. Notes leave reminders and do not perform actions.

When to choose Fixed, Expression and Target

Fixed uses exactly what you enter. For a bonus that is always +2, choose Fixed and enter 2. Expression calculates a value: @nivel / 2 means “half the level”. Start with Fixed when the number does not need to change.

A target is the field that will receive a change. In Change value, use Pick on sheet and select the desired field. For Health or Mana, check whether you chose its current value or its maximum. Typing only Health does not identify the field to change.

For conditions, prefer the visual builder when available: choose the field, comparison and value. If you need a formula, the editor suggests variables as you type. Variables and expressions explains this part.

Useful shortcuts

With focus on the canvas: Tab opens Add step; Ctrl+Z undoes; Ctrl+Shift+Z or Ctrl+Y redoes; Ctrl+C and Ctrl+V copy and paste the selection; Ctrl+D duplicates; Delete or Backspace deletes; Escape closes search or clears selection. On macOS, use Command instead of Ctrl.

While editing a field, keys belong to that field. In step search, use arrows to choose and Enter to add. To move normally between controls, keep focus on the panel controls; Tab on the canvas is the creation shortcut.

What does @forca mean?

A variable is a name representing a value on the sheet. @forca reads Strength; @forca + 2 takes that value and adds 2. If Strength is 3, the result is 5. The @ symbol tells the editor that you are using a variable.

Choose the names suggested by the editor. The names in this guide are examples and may differ on your template. A name containing spaces can be written as @{Força Bruta}. Modifiers and maximums may have their own names, such as @forca_mod and @vida_max.

A variable name that does not exist is read as 0. If a result looks wrong, check its name and the value shown in the test. Use a period for decimals, such as 1.5. Use * to multiply, such as @forca * 2. Put text inside quotes.

@nivel + 2
floor((@forca - 10) / 2)
clamp(@vida + 5, 0, @vida_max)
@{Força Bruta} * 2

How to write a question with a Yes or No answer

A condition is a question. @vida > 0 asks whether Health is above zero. @forca >= 3 asks whether Strength is 3 or more. > means greater; >= means greater or equal; < and <= make the opposite comparisons.

== asks whether two values are equal, and != whether they differ. and requires both conditions to be met. or requires at least one. not reverses the answer. Use parentheses to clarify which parts should be compared together.

If chooses a whole path. Within a formula, if(condition, value if yes, value if no) or condition ? yes : no chooses only a value. Text comparisons are exact: Fight and fight differ. Look up these forms when your rule needs them.

@forca >= 3 and @vida > 0
$event.attribute == "agilidade"
if(@nivel >= 5, 2, 1)
@vida <= 0 ? "Down" : "Standing"

$event, $sheet and earlier step outputs

These forms are for more advanced rules. $event reads information about the action that started the rule. $sheet reads sheet information. $("Step name") reads a result provided by an earlier step.

In a roll rule, $event may offer formula, total, dice, skillName and attribute. Fields vary by event. Before rolling, total and dice do not exist yet.

$sheet contains lists of attributes, skills, values such as Health and Mana, fields, cards and variables, plus memory. A list is a collection of items; [0] accesses the first. null means “no value”, such as a missing field or a path that did not run.

To use $("Step name"), copy Step name exactly and keep that name unique in the diagram. The step must have run earlier on the same path. Ask returns the answer directly; do not add .answer. Choose returns data about the selected item, which may include name, total and targets.

When a value may be missing, coalesce(value, default) uses the default only when the value is null. It does not replace 0, false or empty text. Look up these examples when you need to pass one step's result to the next.

$("Roll dice").total
$("Ask")
$("Choose").targets.misc
$sheet.skills[0].name
coalesce($sheet.memory.usos, 0)

How to put a value inside text or a dice formula

In a number or condition field, write the formula directly. In a text or dice field in Expression mode, put only the calculated part between {{ and }}. For example, Total: {{ @forca + 2 }} shows Total: 5 when Strength is 3.

To roll 1d20, use Roll dice. An expression alone does not make a roll. Dice formulas can use sheet variables; the dice guide explains options such as keeping the highest die and exploding dice.

Text in expression mode:
Total: {{ $("Roll dice").total }}

Dice in expression mode:
1d20 + {{ @forca_mod }}

Condition in expression mode:
@vida > 0

Ready-made formulas for common situations

A function is a ready-made operation in a formula. max(@dano - 2, 0) subtracts 2 from damage but never goes below 0. clamp(@vida + 5, 0, @vida_max) adds 5 to Health and keeps the result between 0 and its maximum.

min picks the lowest value; max, the highest. floor rounds down; ceil rounds up; round rounds to the nearest, with ties away from zero; trunc/fix removes the decimal part toward zero.

For lists, sum adds, avg averages and len counts items. first and last pick the first and last. contains checks whether something is present. join combines items into text. For text, upper, lower and trim change capitalization and spaces at the ends. number tries to read a value as a number.

Additional reference for when needed: abs, sign, sqrt, cbrt, pow, exp, log, log10, log2, mod, sin, cos, tan, asin, acos, atan and atan2, plus pi, e and tau. The in-editor expression guide helps you look up functions.

max(@dano - 2, 0)
ceil(@nivel / 4)
round(2.5)
contains(["forca", "agilidade"], $event.attribute)
join($event.dice, " + ")

Filter list → Sum or count

Filter list reads attributes, skills, resources, fields, variables, vitals or your own list. Inside its filter, $item is the current item and $index is its position, starting at 0. These values exist only in fields evaluated per item.

Name the filter Equipped, choose Resources and filter with $item.equipped == true. In Sum or count, use $("Equipped") as the list. Count returns the number of cards; Sum with field quantity adds their quantities.

Flows do not allow circular connections or repetition steps. Use filters and aggregations to process lists; do not connect the final step back to the first.

Filter on Resources:
$item.equipped == true

List for Sum or count:
$("Equipped")

Operation: Sum
Field: quantity

Store value: this run or sheet memory

Store value with local scope provides a value for later steps. Numbers can be used as @name; text, lists and records are read through $("Step name"). This does not automatically change a sheet field.

In an event action, Sheet memory scope retains a value between runs. Read it with $sheet.memory.key. null deletes the key. In a continuous calculation this scope behaves as local: calculations do not write memory.

For a usage counter, store coalesce($sheet.memory.usos, 0) + 1 under usos. Use memory for rule state; use Change value to write a visible vital, table or skill field.

Name: usos
Scope: Sheet memory
Value in expression mode:
coalesce($sheet.memory.usos, 0) + 1

When the list is empty

Count and Sum return 0 for an empty list. Min, Max, Average, First and Last return null in Sum or count. Use coalesce($("Sum or count"), 0) when you need a number.

When aggregating record properties, provide the field name, such as quantity or total. Adding whole records is not the same as adding their totals. A missing property may become null; check the filter and the fields that item type offers.

What should happen: With Mana 3, the rule requests spending 2, then rolls. With Mana 1, it only shows the message. The test describes actions without subtracting points from a real character.

Also check: Keep the connection from spending to rolling: it defines the order. In real use, spending is not automatically reversed if the next roll fails. Check the formula before use.

What should happen: Health 8, maximum 10 and answer 5 produce Health 10. The editor uses answer 0 in the simulation and shows Health 8. This is expected: the player answers the question in real use.

Also check: Set writes the calculated total. Add would add that total again; keep Set for this formula. Cancel should not change Health.

What should happen: An Agility roll receives +1d4 before calculation. Another attribute's roll receives no extra part. This example's simulation uses Agility.

Also check: agilidade is the sample identifier; your sheet's displayed name may use a different one. This rule decides the extra die before a roll total exists.

What should happen: The example's two equipped cards give +2. Each card counts once, even if its quantity field lists multiple units.

Also check: To count units, use Sum and enter the quantity field. To count cards, keep Count.

What should happen: The chosen skill's extra bonus increases by 1 when the action runs. The simulation chooses Acrobatics automatically; it does not change your character's skill.

Also check: The test for the Skills source may use a sample item without an attached field. This example therefore uses Own options with a sample target. Check actual choices on a test sheet.

What should happen: Each real use increases the counter by 1. This guide's simulation shows the next write as 3 because sample memory starts at 2. The counter does not automatically appear as a visible field.

Also check: Pick a name unique to this rule: other automations on the same sheet can read the same memory. Storing 0 resets the counter; storing null deletes the value.

The test shows what the rule would do

Enable Test and open What the test would do to inspect the path and predicted effects. If a rule should spend 2 Mana, look for that change in the test result. Rolls use a reproducible sequence; Roll again changes that sequence.

The test does not save spending, cards or memory to the sheet. Save on your sheet saves the rule for later use. Save in this guide changes only the example on the page. View on sheet helps check selected fields and results that support previews.

In tests, Ask uses sample answers: 0 for numbers, true for confirmations and the first option in lists. Choose may also use a sample item. That is why the healing example starts with Health 8 and answer 0, staying at 8; a real answer of 5 would produce 10. Check other answers and Cancel on a test sheet.

A short list before saving

In the bonus example, Strength 3 should give +2 and Strength 2 should give 0. Make similar checks for your rule. Real actions can change sheet values; try them on a test copy first.

1. Test a case where the condition is met and one where it is not. Also check the boundary: for example, exactly 2 Mana for an ability costing 2.
2. If a rule changes a field, check which one is selected: current Health, maximum Health or skill bonus, for example. If it uses a list, check the case with no items.
3. If Ask or Choose takes part, check the answer and cancellation on a test sheet. The editor's automatic answer does not cover every real choice.
4. If Save becomes Review issues, open the review and fix what it reports. A disconnected step is not reached from the start: connect it or remove it if unnecessary.
5. Save the automation and confirm its containing screen if it also asks for confirmation. Then check the result on the test sheet. Spending already performed is not automatically reversed if a later step fails.

Opening an older flow

The editor may convert an older flow and leave review notes. Read those notes and test its behavior before saving. The previous version remains in use until you save the conversion.

Join and Stop may appear in older flows but are not in the current creation list. A path without a next connection already ends. A Join set to wait for all continues only after all incoming connections arrive; this may prevent mutually exclusive paths from continuing.

“Nothing happens”

Check that the step connects to the entry and that the path selected by If or Switch reaches it. A disabled step does not perform its calculation or action; it continues through Next or its first available fixed output.

For event actions, check Trigger's event and source. When using a card, the chosen action must match the automation. On roll, the selected source must match the roll you are making.

1. Enable Test and find the last highlighted step. Follow the lines from Start or Trigger to see where the path ends.
2. Click the expected step and check that it is enabled and connected to the correct path. For actions, check which use or roll starts the rule in Trigger.

“It always returns 0 or chooses No”

Check the variable token: a missing name evaluates to 0. For text comparisons, use quotes and the exact key; an event's attribute is a key and may differ from its displayed sheet name.

Check the field mode. For numbers and conditions, use a direct expression; for text and dice, put calculations between {{ and }} in expression mode. Equality uses ==, not =.

1. Click If or Bonus and check the value used by the test. If it uses a variable, pick the editor's suggested name again.
2. Check Fixed or Expression mode. For equality in an expression, use ==. Test a value that should follow Yes and one that should follow No.

“I cannot find the node”

The list follows the context. Roll dice does not belong in a bonus calculation. Add to roll and Replace roll belong to card automations responding to roll events. Open the automation that fits your rule.

This guide covers character sheets. Scene automations have their own VTT events and actions; Change door and Token light are not character sheet steps.

1. Return to the part of the sheet where you opened the automation and check whether it matches your goal.
2. To spend points or make a new roll, open an action. To change a roll already happening, open the card's On roll. To calculate a bonus, open the bonus calculation.

“Change value did not change the field”

Pick the target on the sheet and check its part: a vital's current or maximum value, a skill's miscellaneous bonus or a selector option. Text without the actual target key can be ignored with a warning.

If the target comes from Choose, connect Chosen and use the appropriate property, such as $("Choose").targets.misc. Cancel returns null; do not change a target on that path without checking the choice.

1. Click Change value and select the field again with Pick on sheet. Check whether it is the current value or maximum.
2. Open What the test would do and look for the change and warnings. If the field depends on a player's selection, also check an actual selection on a test sheet.

“Add to roll did not apply the bonus”

The extra formula must be reachable before the roll. At that point $event.total and $event.dice do not exist, so do not use the result to decide a bonus added to that same roll.

Before Add to roll or Replace roll, use logic and data. Steps such as Ask, Choose, Change value or a new Roll dice stop the early scan of that path. To request a value before rolling, create an action that asks and then performs its own roll.

1. Check that the card responds to the right roll and that the path reaches Add to roll before asking questions or changing fields.
2. Test the simple path Trigger → If → Add to roll first. Then add only the steps you need and check again.

“The effect happens twice” or “I cannot save”

Check whether two paths reach the same action. A step can execute on each arrival. In Switch, All cases runs every true case; First case stops at the first. Use an explicit sequence and only the necessary connections.

Step names must be unique. References use those names, and connections cannot form cycles. Also check unclosed expressions, required parameters and steps incompatible with the context.

For bonuses that should disappear on unequipping, use a continuous while-equipped effect. Change value writes once and does not revert when the condition stops applying.

1. If an effect happens twice, follow each line and check whether two paths reach the same action. Remove a duplicate connection.
2. If you cannot save, click Review issues. Fix the indicated item: repeated name, empty field, invalid expression or a connection back to an earlier step.