Automation Reference

This page details the structure of Avrae’s Automation system, the backbone behind custom spells and attacks.

Basic Structure

An automation run is made up of a list of effects. See below for what each effect does.

{
    type: string;
    meta?: Effect[];
}

All effects in an effect’s meta will be executed before the rest of the effect, if there is a meta.

Target

{
    type: "target";
    target: "all"|"each"|int|"self";
    effects: Effect[];
}

A Target effect should only show up as a top-level effect. It designates what creatures to affect.

target
  • "all": Affects all targets (usually save spells)

  • "each": Affects each target (usually attack spells)

  • int: Affects the Nth target (1-indexed)

  • "self": Affects the caster

effects

A list of effects that each targeted creature will be subject to.

Attack

{
    type: "attack";
    hit: Effect[];
    miss: Effect[];
    attackBonus?: IntExpression;
}

An Attack effect makes an attack roll against a targeted creature. It must be inside a Target effect.

hit

A list of effects to execute on a hit.

miss

A list of effects to execute on a miss.

attackBonus

optional - An IntExpression that details what attack bonus to use (defaults to caster’s spell attack mod).

Save

{
    type: "save";
    stat: "str"|"dex"|"con"|"int"|"wis"|"cha";
    fail: Effect[];
    success: Effect[];
    dc?: IntExpression;
}

A Save effect forces a targeted creature to make a saving throw. It must be inside a Target effect.

stat

The type of saving throw.

fail

A list of effects to execute on a failed save.

success

A list of effects to execute on a successful save.

dc

optional - An IntExpression that details what DC to use (defaults to caster’s spell DC).

Damage

{
    type: "damage";
    damage: AnnotatedString;
    overheal?: boolean;
    higher?: {int: string};
    cantripScale?: boolean;
}

Deals damage to a targeted creature. It must be inside a Target effect.

damage

How much damage to deal. Can use variables defined in a Meta tag.

overheal

New in version 1.4.1: optional - Whether this damage should allow a target to exceed its hit point maximum.

higher

optional - How much to add to the damage when a spell is cast at a certain level.

cantripScale

optional - Whether this roll should scale like a cantrip.

TempHP

{
    type: "temphp";
    amount: AnnotatedString;
    higher?: {int: string};
    cantripScale?: boolean;
}

Sets the target’s THP. It must be inside a Target effect.

amount

How much temp HP the target should have. Can use variables defined in a Meta tag.

higher

optional - How much to add to the THP when a spell is cast at a certain level.

cantripScale

optional - Whether this roll should scale like a cantrip.

IEffect

{
    type: "ieffect";
    name: string;
    duration: int | IntExpression;
    effects: AnnotatedString;
    end?: boolean;
}

Adds an InitTracker Effect to a targeted creature, if the automation target is in combat. It must be inside a Target effect.

name

The name of the effect to add.

duration

The duration of the effect, in rounds of combat. Can use variables defined in a Meta tag.

effects

The effects to add (see add_effect()). Can use variables defined in a Meta tag.

end

optional - Whether the effect timer should tick on the end of the turn, rather than start.

Roll

{
    type: "roll";
    dice: AnnotatedString;
    name: string;
    higher?: {int: string};
    cantripScale?: boolean;
    hidden?: boolean;
}

Rolls some dice and saves the result. Should be in a Meta tag.

dice

An AnnotatedString detailing what dice to roll.

name

What to save the result as.

higher

optional - How much to add to the roll when a spell is cast at a certain level.

cantripScale

optional - Whether this roll should scale like a cantrip.

hidden

optional - If true, won’t display the roll in the Meta field, or apply any bonuses from -d.

Text

{
    type: "text";
    text: AnnotatedString;
}

Outputs a short amount of text in the resulting embed.

text

An AnnotatedString detailing the text to display.

AnnotatedString

An AnnotatedString is a string that can access saved variables from a meta effect. To access a variable, surround the name in brackets (e.g. {damage}). Available variables are any defined in Meta effects and the Cvar Table.

This will replace the bracketed portion with the value of the meta variable (usually a roll).

To perform math inside an AnnotatedString, surround the formula with two curly braces (e.g. {{floor(dexterityMod+spell)}}).

IntExpression

An IntExpression is similar to an AnnotatedString in its ability to use variables and functions. However, it has the following differences:

  • Curly braces around the expression are not required

  • An IntExpression can only contain one expression

  • The result of an IntExpression must be an integer.

These are valid IntExpressions:

  • 8 + proficiencyBonus + dexterityMod

  • 12

  • floor(level / 2)

These are not valid IntExpressions:

  • 1d8

  • DC {8 + proficiencyBonus + dexterityMod}

Examples

A normal attack:

[
  {
    "type": "target",
    "target": "each",
    "effects": [
      {
        "type": "attack",
        "attackBonus": "{dexterityMod + proficiencyBonus}",
        "hit": [
          {
            "type": "damage",
            "damage": "1d10[piercing]"
          }
        ],
        "miss": []
      }
    ]
  }
]

A spell that requires a Dexterity save for half damage:

[
  {
    "type": "target",
    "target": "all",
    "effects": [
      {
        "type": "save",
        "stat": "dex",
        "fail": [
          {
            "type": "damage",
            "damage": "{damage}"
          }
        ],
        "success": [
          {
            "type": "damage",
            "damage": "({damage})/2"
          }
        ]
      }
    ],
    "meta": [
      {
        "type": "roll",
        "dice": "8d6[fire]",
        "name": "damage",
        "higher": {
          "4": "1d6[fire]",
          "5": "2d6[fire]",
          "6": "3d6[fire]",
          "7": "4d6[fire]",
          "8": "5d6[fire]",
          "9": "6d6[fire]"
        }
      }
    ]
  },
  {
    "type": "text",
    "text": "Each creature in a 20-foot radius must make a Dexterity saving throw. A target takes 8d6 fire damage on a failed save, or half as much damage on a successful one."
  }
]

An attack from a poisoned blade:

[
  {
    "type": "target",
    "target": "each",
    "effects": [
      {
        "type": "attack",
        "attackBonus": "{strengthMod + proficiencyBonus}",
        "hit": [
          {
            "type": "damage",
            "damage": "1d10[piercing]"
          },
          {
            "type": "save",
            "stat": "con",
            "dc": "12",
            "fail": [
              {
                "type": "damage",
                "damage": "1d6[poison]"
              }
            ],
            "success": []
          }
        ],
        "miss": []
      }
    ]
  },
  {
    "type": "text",
    "text": "On a hit, a target must make a DC 12 Constitution saving throw or take 1d6 poison damage."
  }
]