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 (AKA automation node), each of which may have additional effects that it runs under certain conditions. This recursive structure is called the automation tree.
Glossary
- automation engine
The Automation Engine is the code responsible for reading the automation tree and executing it against the current game state. It handles rolling the dice, checking against your targets’ armor classes, modifying hit points, and other game mechanics.
- automation tree
- automation
The automation tree (sometimes just called “automation”) is the program that the Automation Engine runs. It’s made up of multiple nodes that all link together to make an attack, action, spell, or more.
- effect
- node
A single step of automation - usually, this is a D&D game mechanic like rolling to hit, making a saving throw, or dealing damage, but this can also be used in more programmatic ways to help set up other nodes.
Runtime Variables
All Automation runs provide the following variables:
caster
(AliasStatBlock
) The character, combatant, or monster who is running the automation.targets
(list ofAliasStatBlock
,str
, or None) A list of combatants targeted by this automation (i.e. the-t
argument).spell_attack_bonus
(int
or None) - The attack bonus for the spell, or the caster’s default attack bonus.spell_dc
(int
or None) - The DC for the spell, or the caster’s default DC.choice
(str
) - The input provided by the-choice
argument, always lowercase. If the arg was not used, it will be an empty string.
Additionally, runs triggered by an initiative effect (such as automation provided in a ButtonInteraction) provide the following variables:
ieffect
(SimpleEffect
) The initiative effect responsible for providing the automation.
Target
{
type: "target";
target: "all" | "each" | int | "self" | "parent" | "children";
effects: Effect[];
sortBy?: "hp_asc" | "hp_desc";
}
A Target effect should only show up as a top-level effect. It designates what creatures to affect.
- class Target
- target
"all"
or"each"
(actions only): Affects each of the given (by the-t
argument) targets.int
(actions only): Affects the Nth target (1-indexed)."self"
: Affects the caster, or the actor the triggering effect is on if run from an IEffect button."parent"
(IEffect buttons only): If the triggering effect has a parent effect, affects the actor the parent effect is on."children"
(IEffect buttons only): If the triggering effect has any children effects, affects each actor a child effect is on.
- effects
A list of effects that each targeted creature will be subject to.
- sortBy
optional - Whether to sort the target list. If not given, targets are processed in the order the
-t
arguments are seen. This does not affectself
targets.hp_asc
: Sorts the targets in order of remaining hit points ascending (lowest HP first, None last).hp_desc
: Sorts the targets in order of remaining hit points descending (highest HP first, None last).
Variables
target
(AliasStatBlock
) The current target.targetIteration
(int
) If running multiple iterations (i.e.-rr
), the current iteration (1-indexed).targetIterations
(int
) The total number of iterations. Minimum 1, maximum 25.targetIndex
(int
) The index of the target in the list of targets processed by this effect (0-indexed - first target =0
, second =1
, etc.). Self targets, nth-targets, and parent targets will always be0
.targetNumber
(int
) Same astargetIndex
, but 1-indexed (equivalent totargetIndex + 1
).
Attack
{
type: "attack";
hit: Effect[];
miss: Effect[];
attackBonus?: IntExpression;
adv?: IntExpression;
}
An Attack effect makes an attack roll against a targeted creature. It must be inside a Target effect.
- Attack:
- 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).
- adv
optional - An IntExpression that details whether the attack has inherent advantage or not.
0
for flat,1
for Advantage,2
for Elven Accuracy,-1
for Disadvantage (Default is flat).
Variables
lastAttackDidHit
(bool
) Whether the attack hit.lastAttackDidCrit
(bool
) If the attack hit, whether it crit.lastAttackRollTotal
(int
) The result of the last to-hit roll (0 if no roll was made).lastAttackNaturalRoll
(int
) The natural roll of the last to-hit roll (e.g. 10 in 1d20 (10) + 5 = 15; 0 if no roll was made).lastAttackHadAdvantage
(int
) The advantage type of the last to-hit roll.0
for flat,1
for; Advantage,2
for Elven Accuracy,-1
for Disadvantage
Save
{
type: "save";
stat: "str" | "dex" | "con" | "int" | "wis" | "cha";
fail: Effect[];
success: Effect[];
dc?: IntExpression;
adv?: -1 | 0 | 1;
}
A Save effect forces a targeted creature to make a saving throw. It must be inside a Target effect.
- class Save
- 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).
- adv
optional, default 0 - Whether the saving throw should have advantage by default (
-1
= disadvantage,1
= advantage,0
= no advantage).
Variables
lastSaveDidPass
(bool
) Whether the target passed the save.lastSaveDC
(int
) The DC of the last save roll.lastSaveRollTotal
(int
) The result of the last save roll (0 if no roll was made).lastSaveNaturalRoll
(int
) The natural roll of the last save roll (e.g.10
in1d20 (10) + 5 = 15
; 0 if no roll was made).lastSaveAbility
(str
) The title-case full name of the ability the save was made with (e.g."Strength"
,"Wisdom"
, etc).
Damage
{
type: "damage";
damage: AnnotatedString;
overheal?: boolean;
higher?: {int: string};
cantripScale?: boolean;
}
Deals damage to or heals a targeted creature. It must be inside a Target effect.
Note
This node can also be used to heal a target; simply use negative damage to supply healing.
- class Damage
- damage
How much damage to deal.
- 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.
Variables
lastDamage
(int
) The amount of damage dealt.
TempHP
{
type: "temphp";
amount: AnnotatedString;
higher?: {int: string};
cantripScale?: boolean;
}
Sets the target’s THP. It must be inside a Target effect.
- class TempHP
- amount
How much temp HP the target should have.
- 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.
Variables
lastTempHp
(int
) The amount of temp HP granted.
IEffect
{
type: "ieffect2";
name: AnnotatedString;
duration?: int | IntExpression;
effects?: PassiveEffects;
attacks?: AttackInteraction[];
buttons?: ButtonInteraction[];
end?: boolean;
conc?: boolean;
desc?: AnnotatedString;
stacking?: boolean;
save_as?: string;
parent?: string;
}
Adds an InitTracker Effect to a targeted creature, if the automation target is in combat. It must be inside a Target effect.
Note
If the targeted creature is not in combat, this will display the effects of the initiative effect but not save it on the creature.
- class IEffect
- name
The name of the effect to add. Annotations will show as Variable in the attack string.
- duration
optional, default infinite - The duration of the effect, in rounds of combat. If this is negative, creates an effect with infinite duration.
- effects
optional, default no effects - The effects to add. See PassiveEffects.
- attacks
optional, default no attacks - The attacks granted by this effect. See AttackInteraction.
- buttons
optional, default no buttons - The buttons granted by this effect. See ButtonInteraction.
- end
optional, default false - Whether the effect timer should tick on the end of the turn, rather than start.
- conc
optional, default false - Whether the effect requires concentration.
- desc
optional - The description of the effect (displays on combatant’s turn).
- stacking
optional, default false - If true and another effect with the same name is found on the target, instead of overwriting, add a child effect with name
{name} x{count}
and no description, duration, concentration, attacks, or buttons.
- save_as
optional, default None - If supplied, saves an
IEffectMetaVar
to the automation runtime, which can be used in another IEffect’sparent
key to set its parent to this effect. Must be a valid identifier.
- parent
optional, default None - If supplied, sets the created effect’s parent to the given effect. This must be the name of an existing
IEffectMetaVar
.If
parent
is supplied but the parent effect does not exist, will not set a parent.If
conc
is true, the given parent effect will take priority over the concentration effect.If
stacking
is true and a valid stack parent exists, the stack parent will take priority over the given parent.
Variables
(supplied save_as)
(IEffectMetaVar
orNone
) A reference to the effect that was added to the target. Use this in another IEffect’sparent
key to set that IEffect’s parent to the given one.
PassiveEffects
{
attack_advantage: IntExpression;
to_hit_bonus: AnnotatedString;
damage_bonus: AnnotatedString;
magical_damage: IntExpression;
silvered_damage: IntExpression;
resistances: AnnotatedString[];
immunities: AnnotatedString[];
vulnerabilities: AnnotatedString[];
ignored_resistances: AnnotatedString[];
ac_value: IntExpression;
ac_bonus: IntExpression;
max_hp_value: IntExpression;
max_hp_bonus: IntExpression;
save_bonus: AnnotatedString;
save_adv: AnnotatedString[];
save_dis: AnnotatedString[];
check_bonus: AnnotatedString;
check_adv: AnnotatedString[];
check_dis: AnnotatedString[];
}
Used to specify the passive effects granted by an initiative effect.
- class PassiveEffects
- attack_advantage
optional, default no advantage - Whether this effect gives the combatant advantage on all attacks. -1 for dis, 1 for adv, 2 for elven accuracy.
- to_hit_bonus
optional - A bonus that this effect grants to all of the combatant’s to-hit rolls.
- damage_bonus
optional - A bonus that this effect grants to all of the combatant’s damage rolls.
- magical_damage
optional, default false - Whether this effect makes all of the combatant’s attacks do magical damage. 0 for false, anything else for true.
- silvered_damage
optional, default false - Whether this effect makes all of the combatant’s attacks do silvered damage. 0 for false, anything else for true.
- resistances
optional - A list of damage types and optionally modifiers (e.g. “fire”, “nonmagical slashing”) that the combatant should be resistant to while this effect is active.
- immunities
optional - A list of damage types and optionally modifiers (e.g. “fire”, “nonmagical slashing”) that the combatant should be immune to while this effect is active.
- vulnerabilities
optional - A list of damage types and optionally modifiers (e.g. “fire”, “nonmagical slashing”) that the combatant should be vulnerable to while this effect is active.
- ignored_resistances
optional - A list of damage types and optionally modifiers (e.g. “fire”, “nonmagical slashing”) that the combatant should not be resistant, immune, or vulnerable to while this effect is active.
- ac_value
optional - A value to set the combatant’s armor class to while this effect is active.
Note
If both
ac_value
andac_bonus
are specified, the resulting value will be equal toac_value + ac_bonus
.If multiple effects specify
ac_value
, the highest value will be used.
- ac_bonus
optional - A bonus added to the combatant’s armor class while this effect is active.
- max_hp_value
optional - A value to set the combatant’s maximum hit points to while this effect is active.
Note
If both
max_hp_value
andmax_hp_bonus
are specified, the resulting value will be equal tomax_hp_value + max_hp_bonus
.If multiple effects specify
max_hp_value
, the highest value will be used.
- max_hp_bonus
optional - A bonus added to the combatant’s maximum hit points while this effect is active.
- save_bonus
optional - A bonus that this effect grants to all of the combatant’s saving throws.
- save_adv
optional - A list of stat names (e.g.
strength
) that the combatant should have advantage on for their respective saving throws while this effect is active. Useall
as a stat name to specify all stats.
- save_dis
optional - A list of stat names (e.g.
strength
) that the combatant should have disadvantage on for their respective saving throws while this effect is active. Useall
as a stat name to specify all stats.
- check_bonus
optional - A bonus that this effect grants to all of the combatant’s skill checks.
- check_adv
optional - A list of skill names (e.g.
sleightOfHand
,strength
) that the combatant should have advantage on for ability checks for while this effect is active. If a base ability is given, the advantage will apply to all skills based on that ability (e.g.strength
gives advantage onathletics
checks). Useall
as a stat name to specify all skills.
- check_dis
optional - A list of skill names (e.g.
sleightOfHand
,strength
) that the combatant should have disadvantage on for ability checks for while this effect is active. If a base ability is given, the disadvantage will apply to all skills based on that ability (e.g.strength
gives disadvantage onathletics
checks). Useall
as a stat name to specify all skills.
AttackInteraction
{
attack: Attack;
defaultDC?: IntExpression;
defaultAttackBonus?: IntExpression;
defaultCastingMod?: IntExpression;
}
Used to specify an attack granted by an initiative effect: some automation that appears in the combatant’s
!action list
and can be run with a command.
- class AttackInteraction
- attack
The Attack model is any valid individual entity as exported by the attack editor on the Avrae Dashboard. See Custom Attack Structure.
- defaultDC
optional - The default saving throw DC to use when running the automation. If not provided, defaults to the targeted combatant’s default spellcasting DC (or any DC specified in the automation). Use this if the effect’s DC depends on the original caster’s DC, rather than the target’s DC.
- defaultAttackBonus
optional - The default attack bonus to use when running the automation. If not provided, defaults to the targeted combatant’s default attack bonus (or any attack bonus specified in the automation). Use this if the effect’s attack bonus depends on the original caster’s attack bonus, rather than the target’s attack bonus.
- defaultCastingMod
optional - The default spellcasting modifier to use when running the automation. If not provided, defaults to the targeted combatant’s default spellcasting modifier. Use this if the effect’s spellcasting modifier depends on the original caster’s spellcasting modifier, rather than the target’s spellcasting modifier.
Remove IEffect
New in version 4.0.0.
{
type: "remove_ieffect";
removeParent?: "always" | "if_no_children";
}
Removes the initiative effect that triggered this automation. Only works when run in execution triggered by an initiative effect, such as a ButtonInteraction (see ButtonInteraction).
- class RemoveIEffect
- removeParent
optional, default null - If the removed effect has a parent, whether to remove the parent.
null
(default) - Do not remove the parent effect."always"
- If the removed effect has a parent, remove it too."if_no_children"
- If the removed effect has a parent and its only remaining child was the removed effect, remove it too.
Variables
No variables are exposed.
Roll
{
type: "roll";
dice: AnnotatedString;
name: string;
higher?: {int: string};
cantripScale?: boolean;
hidden?: boolean;
displayName?: string;
}
Rolls some dice and saves the result in a variable. Displays the roll and its name in a Meta field, unless
hidden
is true
.
- class Roll
- dice
An AnnotatedString detailing what dice to roll.
- name
The variable name 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.
optional - If
true
, won’t display the roll in the Meta field, or apply any bonuses from the-d
argument.
- displayName
The name to display in the Meta field. If left blank, it will use the saved name.
Variables
(supplied name)
(RollEffectMetaVar
) The result of the roll.You can use this in an AnnotatedString to retrieve the simplified result of the roll. Using this variable in an AnnotatedString will always return a string that itself can be rolled.
You can use this in an IntExpression to retrieve the roll total.
You can compare this variable against a number to determine if the total of the roll equals that number.
lastRoll
(int
) The integer total of the roll.
Text
{
type: "text";
text: AnnotatedString | AbilityReference;
title: string
}
Outputs a short amount of text in the resulting embed.
- class Text
- text
Either:
An AnnotatedString (the text to display).
An AbilityReference (see AbilityReference). Displays the ability’s description in whole.
- title
optional - Allows you to set the name of the field. Defaults to “Effect”
Set Variable
New in version 2.7.0.
{
type: "variable";
name: string;
value: IntExpression;
higher?: {int: IntExpression};
onError?: IntExpression;
}
Saves the result of an IntExpression
to a variable without displaying anything.
Condition (Branch)
New in version 2.7.0.
{
type: "condition";
condition: IntExpression;
onTrue: Effect[];
onFalse: Effect[];
errorBehaviour?: "true" | "false" | "both" | "neither" | "raise";
}
Run certain effects if a certain condition is met, or other effects otherwise. AKA “branch” or “if-else”.
- class Condition
- condition
The condition to check.
- onTrue
The effects to run if
condition
isTrue
or any non-zero value.
- onFalse
The effects to run if
condition
isFalse
or0
.
- errorBehaviour
How to behave if the condition raises an error:
"true"
: Run theonTrue
effects."false"
: Run theonFalse
effects. (default)"both"
: Run both theonTrue
andonFalse
effects, in that order."neither"
: Skip this effect."raise"
: Raise the error and halt execution.
Use Counter
New in version 2.10.0.
{
type: "counter";
counter: string | SpellSlotReference | AbilityReference;
amount: IntExpression;
allowOverflow?: boolean;
errorBehaviour?: "warn" | "raise" | "ignore";
}
Uses a number of charges of the given counter, and displays the remaining amount and delta.
Note
Regardless of the current target, this effect will always use the caster’s counter/spell slots!
- class UseCounter
- counter
The name of the counter to use (case-sensitive, full match only), or a reference to a spell slot (see SpellSlotReference).
- amount
The number of charges to use. If negative, will add charges instead of using them.
- allowOverflow
optional, default False - If False, attempting to overflow/underflow a counter (i.e. use more charges than available or add charges exceeding max) will error instead of clipping to bounds.
- errorBehaviour
optional, default “warn” - How to behave if modifying the counter raises an error:
"warn"
: Automation will continue to run, and any errors will appear in the output. (default)"raise"
: Raise the error and halt execution."ignore"
: All errors are silently consumed.
Some, but not all, possible error conditions are:
The target does not have counters (e.g. they are a monster)
The counter does not exist
allowOverflow
is false and the new value is out of bounds
Variables
lastCounterName
(str
) The name of the last used counter. If it was a spell slot, the level of the slot (safe to cast to int, i.e.int(lastCounterName)
). (None
on error).lastCounterRemaining
(int
) The remaining charges of the last used counter (0 on error).lastCounterUsedAmount
(int
) The amount of the counter successfully used.lastCounterRequestedAmount
(int
) The amount of the counter requested to be used (i.e. the amount specified by automation or requested by-amt
, regardless of the presence of the-i
arg).
SpellSlotReference
{
slot: number | IntExpression;
}
AbilityReference
{
id: number;
typeId: number;
}
In most cases, an AbilityReference
should not be constructed manually; use the Automation editor to select an
ability instead. A list of valid abilities can be retrieved from the API at /gamedata/limiteduse
.
Note
The Automation Engine will make a best effort at discovering the appropriate counter to use for the given ability - in most cases this won’t affect the chosen counter, but in some cases, it may lead to some unexpected behaviour. Some examples of counter discovery include:
Choosing
Channel Divinity (Paladin)
may discover a counter granted by the Cleric’s Channel Divinity featureChoosing
Breath Weapon (Gold)
may discover a counter for a breath weapon of a different colorChoosing
Sorcery Points (Sorcerer)
may discover a counter granted by the Metamagic Adept feat
Cast Spell
New in version 2.11.0.
{
type: "spell";
id: int;
level?: int;
dc?: IntExpression;
attackBonus?: IntExpression;
castingMod?: IntExpression;
parent?: string;
}
Executes the given spell’s automation as if it were immediately cast. Does not use a spell slot to cast the spell. Can only be used at the root of automation. Cannot be used inside a spell’s automation.
This is usually used in features that cast spells using alternate resources (i.e. Use Counter, Cast Spell).
- class CastSpell
- id
The DDB entity id of the spell to cast. Use the Automation Editor to select a spell or the
/gamedata/spells
API endpoint to retrieve a list of valid spell IDs.
- level
optional - The (slot) level to cast the spell at.
- dc
optional - The saving throw DC to use when casting the spell. If not provided, defaults to the caster’s default spellcasting DC (or any DC specified in the spell automation).
- attackBonus
optional - The spell attack bonus to use when casting the spell. If not provided, defaults to the caster’s default spell attack bonus (or any attack bonus specified in the spell automation).
- castingMod
optional - The spellcasting modifier to use when casting the spell. If not provided, defaults to the caster’s default spellcasting modifier.
- parent
optional, default None - If supplied, sets the spells created effect’s parent to the given effect. This must be the name of an existing
IEffectMetaVar
. Useful for handling concentration.
Variables
No variables are exposed.
Ability Check
New in version 4.0.0.
{
type: "check";
ability: string | string[];
contestAbility?: string | string[];
dc?: IntExpression;
success?: Effect[];
fail?: Effect[];
contestTie?: "fail" | "success" | "neither";
adv?: -1 | 0 | 1;
}
An Ability Check effect forces a targeted creature to make an ability check, optionally as a contest against the caster. It must be inside a Target effect.
- class Check
- ability
The ability to make a check for. Must be one of or a list of the following:
"acrobatics" "animalHandling" "arcana" "athletics" "deception" "history" "initiative" "insight" "intimidation" "investigation" "medicine" "nature" "perception" "performance" "persuasion" "religion" "sleightOfHand" "stealth" "survival" "strength" "dexterity" "constitution" "intelligence" "wisdom" "charisma"
If multiple skills are specified, uses the highest modifier of all the specified skills.
- contestAbility
optional - Which ability of the caster’s to make a contest against. Must be one of or a list of the valid skills listed above. If multiple skills are specified, uses the highest modifier of all the specified skills.
Mutually exclusive with
dc
.
- dc
optional - An IntExpression that specifies the check’s DC. If neither
dc
norcontestAbility
is given, the check will not run either thefail
orsuccess
nodes.Mutually exclusive with
contestAbility
.
- success
optional - A list of effects to execute on a successful check or if the target wins the contest. Requires the contestAbility or dc attribute to be set.
- fail
optional - A list of effects to execute on a failed check or if the target loses the contest. Requires the contestAbility or dc attribute to be set.
- contestTie
optional, default success - Which list of effects to run if the ability contest results in a tie.
- adv
optional, default 0 - Whether the check should have advantage by default (
-1
= disadvantage,1
= advantage,0
= no advantage).
Variables
lastCheckRollTotal
(int
) The result of the last check roll (0 if no roll was made).lastCheckNaturalRoll
(int
) The natural roll of the last check roll (e.g.10
in1d20 (10) + 5 = 15
; 0 if no roll was made).lastCheckAbility
(str
) The title-case full name of the rolled skill (e.g."Animal Handling"
,"Arcana"
).lastCheckDidPass
(bool
orNone
) If a DC was given, whether the target succeeded the check. If a contest was specified, whether the target won the contest.None
if no or contest given.lastCheckDC
(int
orNone
) If a DC was given, the DC of the last save roll.None
if no DC given.
Contest Variables
lastContestRollTotal
(int
orNone
) The result of the caster’s contest roll;None
if no contest was made.lastContestNaturalRoll
(int
orNone
) The natural roll of the caster’s contest roll (e.g.10
in1d20 (10) + 5 = 15
;None
if no contest was made).lastContestAbility
(str
orNone
) The title-case full name of the skill the caster rolled (e.g."Animal Handling"
,"Arcana"
).None
if no contest was made.lastContestDidTie
(bool
) Whether a ability contest resulted in a tie.
AnnotatedString
An AnnotatedString is a string that can access saved variables.
To access a variable, surround the name in brackets (e.g. {damage}
).
Available variables include:
implicit variables from Effects (see relevant effect for a list of variables it provides)
any defined in a
Roll
orSet Variable
effectall variables from the Cvar Table
This will replace the bracketed portion with the value of the meta variable.
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
Attack
A normal attack:
[
{
"type": "target",
"target": "each",
"effects": [
{
"type": "attack",
"attackBonus": "dexterityMod + proficiencyBonus",
"hit": [
{
"type": "damage",
"damage": "1d10[piercing]"
}
],
"miss": []
}
]
}
]
Save
A spell that requires a Dexterity save for half damage:
[
{
"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": "target",
"target": "all",
"effects": [
{
"type": "save",
"stat": "dex",
"fail": [
{
"type": "damage",
"damage": "{damage}"
}
],
"success": [
{
"type": "damage",
"damage": "({damage})/2"
}
]
}
]
},
{
"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."
}
]
Attack & Save
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."
}
]
Draining Attack
An attack that heals the caster for half the amount of damage dealt:
[
{
"type": "variable",
"name": "lastDamage",
"value": "0"
},
{
"type": "target",
"target": "each",
"effects": [
{
"type": "attack",
"attackBonus": "charismaMod + proficiencyBonus",
"hit": [
{
"type": "damage",
"damage": "3d6[necrotic]"
}
],
"miss": []
}
]
},
{
"type": "target",
"target": "self",
"effects": [
{
"type": "damage",
"damage": "-{lastDamage}/2 [heal]"
}
]
},
{
"type": "text",
"text": "On a hit, the target takes 3d6 necrotic damage, and you regain hit points equal to half the amount of necrotic damage dealt."
}
]
Target Health-Based
A spell that does different amounts of damage based on whether or not the target is damaged:
[
{
"type": "target",
"target": "each",
"effects": [
{
"type": "save",
"stat": "wis",
"fail": [
{
"type": "condition",
"condition": "target.hp < target.max_hp",
"onTrue": [
{
"type": "damage",
"damage": "1d8 [necrotic]"
}
],
"onFalse": [
{
"type": "damage",
"damage": "1d4 [necrotic]"
}
],
"errorBehaviour": "both"
}
],
"success": []
}
]
},
{
"type": "text",
"text": "The target must succeed on a Wisdom saving throw or take 1d4 necrotic damage. If the target is missing any of its hit points, it instead takes 1d8 necrotic damage."
}
]
Area Vampiric Drain
An effect that heals the caster for the total damage dealt to all targets:
[
{
"type": "variable",
"name": "totalDamage",
"value": "0"
},
{
"type": "target",
"target": "each",
"effects": [
{
"type": "damage",
"damage": "1d6 [necrotic]"
},
{
"type": "variable",
"name": "totalDamage",
"value": "totalDamage + lastDamage"
}
]
},
{
"type": "target",
"target": "self",
"effects": [
{
"type": "damage",
"damage": "-{totalDamage} [heal]"
}
]
},
{
"type": "text",
"text": "Each creature within 10 feet of you takes 1d6 necrotic damage. You regain hit points equal to the sum of the necrotic damage dealt."
}
]
Damage Over Time Effect
An effect that lights the target on fire, adding two buttons on their turn to take the fire damage and douse themselves.
[
{
"type": "target",
"target": "each",
"effects": [
{
"type": "ieffect2",
"name": "Burning",
"buttons": [
{
"label": "Burning",
"verb": "is on fire",
"style": "4",
"automation": [
{
"type": "target",
"target": "self",
"effects": [
{
"type": "damage",
"damage": "1d6 [fire]"
}
]
},
{
"type": "text",
"text": "At the start of each of the target's turns, the target takes 1d6 fire damage."
}
]
},
{
"label": "Douse",
"verb": "puts themself out",
"automation": [
{
"type": "remove_ieffect"
},
{
"type": "text",
"text": "The target can use an action to put themselves out."
}
]
}
]
}
]
}
]
Custom Attack Structure
{
_v: 2;
name: string;
automation: Effect[];
verb?: string;
proper?: boolean;
criton?: number;
phrase?: string;
thumb?: string;
extra_crit_damage?: string;
activation_type?: number;
}
In order to use Automation, it needs to be contained within a custom attack or spell. We recommend building these on the Avrae Dashboard, but if you wish to write a custom attack by hand, the structure is documented here.
Hand-written custom attacks may be written in JSON or YAML and imported using the !a import
command.
- class AttackModel
- _v
This must always be set to
2
.
- name
The name of the attack.
- automation
The automation of the attack: a list of effects (documented above).
- verb
optional, default “attacks with” - The verb to use in attack title displays.
- proper
optional, default false - Whether or not the attack’s name is a proper noun. Affects title displays.
- criton
optional - The natural roll (or higher) this attack should crit on. For example,
criton: 18
would cause this attack to crit on a natural roll of 18, 19, or 20.
- phrase
optional - A short snippet of flavor text to display when this attack is used.
- thumb
optional - A URL to an image to display in a thumbnail when this attack is used.
- extra_crit_damage
optional - How much extra damage to deal when this attack crits, in addition to normal crit rules such as doubling damage dice. For example, if this attack normally deals 1d6 damage with
extra_crit_damage: "1d8"
, it will deal 2d6 + 1d8 damage on a crit.
- activation_type
optional - What action type to display this attack as in an action list (such as
!a list
).ACTION = 1 NO_ACTION = 2 BONUS_ACTION = 3 REACTION = 4 MINUTE = 6 HOUR = 7 SPECIAL = 8 LEGENDARY = 9 MYTHIC = 10 LAIR = 11
Specifying Class Feature DC Bonuses
New in version 4.1.0.
You can grant bonuses to your class Saving Throw DCs by creating a cvar: XDCBonus
(WarlockDCBonus
, BloodHunterDCBonus
, MonkDCBonus
, etc).
This is to account for items such as the Dragonhide Belt, which adds a flat +1/2/3 bonus to the save DC for your class.
Note
XDCBonus
is not generated by the the sheet itself, but is instead set by the user. It will grant the given bonus to the save DC of actions for that class.
You can set it with !cvar XDCBonus #
, such as !cvar MonkDCBonus 2
, or with Draconic using set_cvar()
.
This cvar should be an integer, or it could cause the automation to not run.
To account for this in your automations, use the Set Variable node, with a value of XDCBonus
and an onError of 0.
{
"type": "variable",
"name": "BloodHunterDCBonus",
"value": "BloodHunterDCBonus",
"onError": "0"
}
Then, when you set your save DC’s in that automation, add +XDCBonus
to the DC total.
{
"type": "save",
"stat": "str",
"dc": "8+proficiencyBonus+intelligenceMod+BloodHunterDCBonus",
"fail": [],
"success": []
}