Aliasing API

So you want to write aliases for your commonly used commands - cool! This cheatsheet details some of the nitty-gritty syntactical shenanigans that you can use to make your aliases very powerful.

When placed inline in an alias, any syntax in the syntax table will have the listed effect. For a list of built-in cvars, see the Cvar Table.

For a list of user-created aliases, plus help aliasing, join the Avrae Discord!

Draconic

The language used in Avrae aliases is a custom modified version of Python, called Draconic. In most cases, Draconic uses the same syntax and base types as Python - any exceptions will be documented here!

As Draconic is meant to both be an operational and templating language, there are multiple ways to use Draconic inside your alias.

Syntax

This section details the special syntax used in the Draconic language. Note that these syntaxes are only evaluated in an alias, the test command, or the tembed command.

Rolls

Syntax: {diceexpr}

Description: Rolls the expression inside the curly braces and is replaced by the result. If an error occurs, is replaced by 0. Variables are allowed inside the expression.

Examples

>>> !test Rolling 1d20: {1d20}
Rolling 1d20: 7
>>> !test Strength check: {1d20 + strengthMod}
Strength check: 21

Values

Syntax: <var>

Description: Replaced by the value of the variable, implicitly cast to str. The variable can be a user variable, character variable, or a local variable set in a Draconic script.

Examples

>>> !test My strength modifier is: <strengthMod>
My strength modifier is: 2

Draconic Expressions

Syntax: {{code}}

Description: Runs the Draconic code inside the braces and is replaced by the value the code evaluates to. If the code evaluates to None, is removed from the output.

See below for a list of builtin Draconic functions.

Examples

>>> !test 1 more than my strength score is {{strength + 1}}!
1 more than my strength score is 15!
>>> !test My roll was {{"greater than" if roll("1d20") > 10 else "less than"}} 10!
My roll was less than 10!

Draconic Blocks

Syntax

<drac2>
code
</drac2>

Description: Runs the multi-line Draconic code between the delimiters. If a value is returned (via the return keyword), is replaced by the returned value.

Examples

>>> !test <drac2>
... out = []
... for i in range(5):
...   out.append(i * 2)
...   if i == 2:
...     break
... return out
... </drac2>
[0, 2, 4]
>>> !test <drac2>
... out = []
... for stat in ['strength', 'dexterity', 'constitution']:
...   out.append(get(stat))
... </drac2>
... My STR, DEX, and CON scores are {{out}}!
My STR, DEX, and CON scores are [12, 18, 14]!

Argument Parsing

Often times when writing aliases, you will need to access user input. These special strings will be replaced with user arguments (if applicable)!

Syntax: %1%, %2%, etc.

Description: Replaced with the Nth argument passed to the alias. If the argument contains spaces, the replacement will contain quotes around the argument.

Syntax: %*%

Description: Replaced with the unmodified string following the alias.

Syntax: &1&, &2&, etc.

Description: Replaced with the Nth argument passed to the alias. If the argument contains spaces, the replacement will not contain quotes around the argument. Additionally, any quotes in the argument will be backslash-escaped.

Syntax: &*&

Description: Replaced with the string following the alias. Any quotes will be backslash-escaped.

Syntax: &ARGS&

Description: Replaced with a list representation of all arguments - usually you’ll want to put this in Draconic code.

Examples

>>> !alias asdf echo %2% %1%
>>> !asdf first "second arg"
"second arg" first
>>> !alias asdf echo %*% first
>>> !asdf second "third word"
second "third word" first
>>> !alias asdf echo &1& was the first arg
>>> !asdf "hello world"
hello world was the first arg
>>> !alias asdf echo &*& words
>>> !asdf second "third word"
second \"third word\" words
>>> !alias asdf echo &ARGS&
>>> !asdf first "second arg"
['first', 'second arg']

Cvar Table

This table lists the available cvars when a character is active.

Name

Description

Type

armor

Armor Class.

int

charisma

Charisma score.

int

charismaMod

Charisma modifier.

int

charismaSave

Charisma saving throw modifier.

int

constitution

Constitution score.

int

constitutionMod

Constitution modifier.

int

constitutionSave

Constitution saving throw modifier.

int

description

Full character description.

str

dexterity

Dexterity score.

int

dexterityMod

Dexterity modifier.

int

dexteritySave

Dexterity saving throw modifier.

int

hp

Maximum hit points.

int

image

Character image URL.

str

intelligence

Intelligence score.

int

intelligenceMod

Intelligence modifier.

int

intelligenceSave

Intelligence saving throw modifier.

int

level

Character level.

int

name

The character’s name.

str

proficiencyBonus

Proficiency bonus.

int

spell

The character’s spellcasting ability mod.

int

strength

Strength score.

int

strengthMod

Strength modifier.

int

strengthSave

Strength saving throw modifier.

int

wisdom

Wisdom score.

int

wisdomMod

Wisdom modifier.

int

wisdomSave

Wisdom saving throw modifier.

int

XLevel

How many levels a character has in class X.

int

Note

XLevel is not guaranteed to exist for any given X, and may not exist for GSheet 1.3/1.4 characters.

Function Reference

Warning

It may be possible to corrupt your character data by incorrectly calling functions. Script at your own risk.

All Contexts

These functions are available in any scripting context, regardless if you have a character active or not.

Python Builtins

all(iterable)

Return True if all elements of the iterable are true, or if the iterable is empty.

any(iterable)

Return True if any element of the iterable is true. If the iterable is empty, return False.

ceil(x)

Rounds a number up to the nearest integer. See math.ceil().

Parameters

x (float or int) – The number to round.

Returns

The smallest integer >= x.

Return type

int

float(x)

Converts x to a floating point number.

Parameters

x (str, int, or float) – The value to convert.

Returns

The float.

Return type

float

floor(x)

Rounds a number down to the nearest integer. See math.floor().

Parameters

x (float or int) – The number to round.

Returns

The largest integer <= x.

Return type

int

int(x)

Converts x to an integer.

Parameters

x (str, int, or float) – The value to convert.

Returns

The integer.

Return type

int

len(s)

Return the length (the number of items) of an object. The argument may be a sequence (such as a string, bytes, tuple, list, or range) or a collection (such as a dictionary, set, or frozen set).

Returns

The length of the argument.

Return type

int

max(iterable, *[, key, default])
max(arg1, arg2, *args[, key])

Return the largest item in an iterable or the largest of two or more arguments.

If one positional argument is provided, it should be an iterable. The largest item in the iterable is returned. If two or more positional arguments are provided, the largest of the positional arguments is returned.

There are two optional keyword-only arguments. The key argument specifies a one-argument ordering function like that used for list.sort(). The default argument specifies an object to return if the provided iterable is empty. If the iterable is empty and default is not provided, a ValueError is raised.

If multiple items are maximal, the function returns the first one encountered.

min(iterable, *[, key, default])
min(arg1, arg2, *args[, key])

Return the smallest item in an iterable or the smallest of two or more arguments.

If one positional argument is provided, it should be an iterable. The smallest item in the iterable is returned. If two or more positional arguments are provided, the smallest of the positional arguments is returned.

There are two optional keyword-only arguments. The key argument specifies a one-argument ordering function like that used for list.sort(). The default argument specifies an object to return if the provided iterable is empty. If the iterable is empty and default is not provided, a ValueError is raised.

If multiple items are minimal, the function returns the first one encountered.

range(stop)
range(start, stop[, step])

Returns a list of numbers in the specified range.

If the step argument is omitted, it defaults to 1. If the start argument is omitted, it defaults to 0. If step is zero, ValueError is raised.

For a positive step, the contents of a range r are determined by the formula r[i] = start + step*i where i >= 0 and r[i] < stop.

For a negative step, the contents of the range are still determined by the formula r[i] = start + step*i, but the constraints are i >= 0 and r[i] > stop.

A range object will be empty if r[0] does not meet the value constraint. Ranges do support negative indices, but these are interpreted as indexing from the end of the sequence determined by the positive indices.

Parameters
  • start (int) – The start of the range (inclusive).

  • stop (int) – The end of the range (exclusive).

  • step (int) – The step value.

Returns

The range of numbers.

Return type

list

round(number[, ndigits])

Return number rounded to ndigits precision after the decimal point. If ndigits is omitted or is None, it returns the nearest integer to its input.

Parameters
  • number (float or int) – The number to round.

  • ndigits (int) – The number of digits after the decimal point to keep.

Returns

The rounded number.

Return type

float

sqrt(x)

See math.sqrt().

Returns

The square root of x.

Return type

float

str(x)

Converts x to a string.

Parameters

x (Any) – The value to convert.

Returns

The string.

Return type

str

sum(iterable[, start])

Sums start and the items of an iterable from left to right and returns the total. start defaults to 0. The iterable’s items are normally numbers, and the start value is not allowed to be a string.

time()

Return the time in seconds since the UNIX epoch (Jan 1, 1970, midnight UTC) as a floating point number. See time.time().

Returns

The epoch time.

Return type

float

Draconic Functions

argparse(args)

Parses arguments.

Parameters

args (str or Iterable) – A list of arguments to parse.

Returns

The parsed arguments.

Return type

ParsedArguments

>>> args = argparse("adv -rr 2 -b 1d4[bless]")
>>> args.adv()
1
>>> args.last('rr')
'2'
>>> args.get('b')
['1d4[bless]']
chanid()

Returns the ID of the active Discord channel.

Return type

str

combat()

Returns the combat active in the channel if one is. Otherwise, returns None.

Return type

SimpleCombat

Note

If called outside of a character context, combat().me will be None.

delete_uvar(name)

Deletes a user variable. Does nothing if the variable does not exist.

Parameters

name (str) – The name of the variable to delete.

dump_json(self, obj)

Serializes an object to a JSON string. See json.dumps().

err(reason)

Stops evaluation of an alias and shows the user an error.

Parameters

reason (str) – The error to show.

Raises

AliasException

exists(name)

Returns whether or not a name is set in the current evaluation context.

Return type

bool

get(name, default=None)

Gets the value of a name, or returns default if the name is not set.

Parameters
  • name (str) – The name to retrieve.

  • default – What to return if the name is not set.

get_gvar(address)

Retrieves and returns the value of a gvar (global variable).

Parameters

address (str) – The gvar address.

Returns

The value of the gvar.

Return type

str

load_json(self, jsonstr)

Loads an object from a JSON string. See json.loads().

randint(x)

Returns a random integer in the range [0..x).

Parameters

x (int) – The upper limit (non-inclusive).

Returns

A random integer.

Return type

int

roll(dice)

Rolls dice and returns the total.

Parameters

dice (str) – The dice to roll.

Returns

The roll’s total, or 0 if an error was encountered.

Return type

int

servid()

Returns the ID of the active Discord guild, or None if in DMs.

Return type

str

set(name, value)

Sets the value of a name in the current scripting context.

Deprecated since version 0.1.0: Use name = value instead.

Parameters
  • name – The name to set.

  • value – The value to set it to.

set_uvar(name, value)

Sets a user variable.

Parameters
  • name (str) – The name of the variable to set.

  • value (str) – The value to set it to.

set_uvar_nx(name, value)

Sets a user variable if there is not already an existing name.

Parameters
  • name (str) – The name of the variable to set.

  • value (str) – The value to set it to.

typeof(inst)

Returns the name of the type of an object.

Parameters

inst – The object to find the type of.

Returns

The type of the object.

Return type

str

uvar_exists(name)

Returns whether a uvar exists.

Return type

bool

vroll(rollStr, multiply=1, add=0)

Rolls dice and returns a detailed roll result.

Parameters
  • dice (str) – The dice to roll.

  • multiply (int) – How many times to multiply each set of dice by.

  • add (int) – How many dice to add to each set of dice.

Returns

The result of the roll.

Return type

SimpleRollResult

Character Context

These functions are only available when a character is active in a scripting context. Otherwise, attempts to call these functions will raise a FunctionRequiresCharacter exception.

Custom Counters

cc_exists(name)

Returns whether a custom counter exists.

Parameters

name (str) – The name of the custom counter to check.

Returns

Whether the counter exists.

Return type

bool

cc_str(name)

Returns a string representing a custom counter.

Parameters

name (str) – The name of the custom counter to get.

Returns

A string representing the current value, maximum, and minimum of the counter.

Return type

str

Raises

ConsumableException if the counter does not exist.

Example:

>>> cc_str("Ki")
'11/17'
>>> cc_str("Bardic Inspiration")
'◉◉◉〇〇'
create_cc(name, minVal=None, maxVal=None, reset=None, dispType=None)

Creates a custom counter. If a counter with the same name already exists, it will replace it.

Parameters
  • name (str) – The name of the counter to create.

  • minVal (str) – The minimum value of the counter. Supports Cvar Table parsing.

  • maxVal (str) – The maximum value of the counter. Supports Cvar Table parsing.

  • reset (str) – One of 'short', 'long', 'hp', 'none', or None.

  • dispType (str) – Either None or 'bubble'.

create_cc_nx(name, minVal=None, maxVal=None, reset=None, dispType=None)

Creates a custom counter if one with the given name does not already exist. Equivalent to:

>>> if not cc_exists(name):
>>>     create_cc(name, minVal, maxVal, reset, dispType)
delete_cc(name)

Deletes a custom counter.

Parameters

name (str) – The name of the custom counter to delete.

Raises

ConsumableException if the counter does not exist.

get_cc(name)

Gets the value of a custom counter.

Parameters

name (str) – The name of the custom counter to get.

Returns

The current value of the counter.

Return type

int

Raises

ConsumableException if the counter does not exist.

get_cc_max(name)

Gets the maximum value of a custom counter.

Parameters

name (str) – The name of the custom counter maximum to get.

Returns

The maximum value of the counter. If a counter has no maximum, it will return an obscenely large number (2^31-1).

Return type

int

Raises

ConsumableException if the counter does not exist.

get_cc_min(name)

Gets the minimum value of a custom counter.

Parameters

name (str) – The name of the custom counter minimum to get.

Returns

The minimum value of the counter. If a counter has no minimum, it will return an obscenely small number (-2^31).

Return type

int

Raises

ConsumableException if the counter does not exist.

mod_cc(name, value, strict=False)

Modifies the value of a custom counter. Equivalent to set_cc(name, get_cc(name) + value, strict).

set_cc(name, value, strict=False)

Sets the value of a custom counter.

Parameters
  • name (str) – The name of the custom counter to set.

  • value (int) – The value to set the counter to.

  • strict (bool) – If True, will raise a CounterOutOfBounds if the new value is out of bounds, otherwise silently clips to bounds.

Raises

ConsumableException if the counter does not exist.

Spell Slots

get_slots(level)

Gets the number of remaining spell slots of a given level that a character has.

Parameters

level (int) – The level to get the remaining slots of.

Returns

The number of remaining slots of that level.

Return type

int

get_slots_max(level)

Gets the maximum number of spell slots of a given level that a character has.

Parameters

level (int) – The level to get the maximum slots of.

Returns

The maximum number of slots of that level.

Return type

int

set_slots(level, value)

Sets how many spell slots of a given level a character has.

Parameters
  • level (int) – The level of spell slots to set.

  • value (int) – The value to set the remaining slots to.

Raises

CounterOutOfBounds if the number of slots is invalid.

slots_str(level)

Returns a string representing how many spell slots a character has of a given level.

Parameters

level (int) – The level to get the slots of.

Returns

A string representing the current remaining and maximum number of slots of that level.

Return type

str

use_slot(level)

Uses one spell slot of a given level. Equivalent to set_slots(level, get_slots(level) - 1).

Hit Points

get_hp()
Returns

The character’s current hit points.

Return type

int

get_temphp()
Returns

The character’s current temporary hit points.

Return type

int

hp_str()

Returns a string representing a character’s current HP, max HP, and temp HP.

mod_hp(value, overflow=True)

Modifies the character’s remaining hit points by value. If value is negative, will deal damage to temp HP first.

Parameters
  • value (int) – How much to modify remaining HP by.

  • overflow (bool) – If False, clips the new HP value to [0..hp].

set_hp(value)

Sets the character’s remaining hit points. Ignores temp HP.

Parameters

value (int) – The new value for hit points.

set_temphp(value)

Sets the character’s remaining temp HP.

Parameters

value (int) – The new value for temporary hit points.

Cvars

Note

All custom character variables are locally bound to a Draconic scope. To access their values, use them like a normal name.

delete_cvar(name)

Deletes a custom character variable. Does nothing if the cvar does not exist.

Parameters

name (str) – The name of the variable to delete.

set_cvar(name, value)

Sets a custom character variable, which will be available in all scripting contexts using this character.

Parameters
  • name (str) – The name of the variable to set. Must be a valid identifier and not be in the Cvar Table.

  • value (str) – The value to set it to.

set_cvar_nx(name, value)

Sets a custom character variable if it is not already set.

Parameters
  • name (str) – The name of the variable to set. Must be a valid identifier and not be in the Cvar Table.

  • value (str) – The value to set it to.

Other

get_raw()

Returns a raw representation of character data.

See Also

Draconic’s syntax is very similar to Python. Other Python features supported in Draconic include:

SimpleRollResult

class SimpleRollResult
dice

The rolled dice (e.g. 1d20 (5)).

Type

str

total

The total of the roll.

Type

int

full

The string representing the roll.

Type

str

result

The RollResult object returned by the roll.

Type

d20.RollResult

raw

The Expression object returned by the roll. Equivalent to SimpleRollResult.result.expr.

Type

d20.Expression

consolidated()

Gets the most simplified version of the roll string. Consolidates totals and damage types together.

Note that this modifies the result expression in place!

>>> result = vroll("3d6[fire]+1d4[cold]")
>>> str(result)
'3d6 (3, 3, 2) [fire] + 1d4 (2) [cold] = `10`'
>>> result.consolidated()
'8 [fire] + 2 [cold]'
Return type

str

__str__()

Equivalent to result.full.

SimpleCombat

SimpleCombatant

class SimpleCombatant
ac

The combatant’s armor class. None if not set.

Type

Optional[int]

attacks

A list of the combatant’s attacks.

Type

list of dict

effects

A list of SimpleEffect active on the combatant.

Type

list of SimpleEffect

hp

The combatant’s current hit points. None if not set.

Type

Optional[int]

init

What the combatant rolled for initiative.

Type

int

initmod

An int representing the combatant’s initiative modifier.

Type

int

level

The combatant’s spellcaster level. 0 if the combatant is not a player or spellcaster.

Type

int

maxhp

The combatant’s maximum hit points. None if not set.

Type

Optional[int]

name

The combatant’s name.

Type

str

note

The note on the combatant. Can be None.

Type

Optional[str]

ratio

Deprecated since version 1.1.5: Use combatant.hp / combatant.maxhp instead.

The percentage of health the combatant has remaining (0.0 = 0%, 1.0 = 100%).

Type

float

resists

The combatant’s resistances, immunities, and vulnerabilities.

Type

Resistances

temphp

How many temporary hit points the combatant has.

Type

int

type

The type of the object ("combatant"), to determine whether this is a group or not.

Type

str

add_effect(name: str, args: str, duration: int = -1, concentration: bool = False, parent=None, end: bool = False)

Adds an effect to the combatant.

Parameters
  • name (str) – The name of the effect to add.

  • args (str) – The effect arguments to add (same syntax as init effect).

  • duration (int) – The duration of the effect, in rounds.

  • concentration (bool) – Whether the effect requires concentration.

  • parent (SimpleEffect) – The parent of the effect.

  • end (bool) – Whether the effect ticks on the end of turn.

damage(dice_str, crit=False, d=None, c=None, critdice=0, overheal=False)

Does damage to a combatant, and returns the rolled result and total, accounting for resistances.

Parameters
  • dice_str (str) – The damage to do (e.g. "1d6[acid]").

  • crit (bool) – Whether or not the damage should be rolled as a crit.

  • d (str) – Any additional damage to add (equivalent of -d).

  • c (str) – Any additional damage to add to crits (equivalent of -c).

  • critdice (int) – How many extra weapon dice to roll on a crit (in addition to normal dice).

  • overheal (bool) – Whether or not to allow this damage to exceed a target’s HP max.

Returns

Dictionary representing the results of the Damage Automation.

Return type

dict

get_effect(name: str)

Gets a SimpleEffect, fuzzy searching (partial match) for a match.

Parameters

name (str) – The name of the effect to get.

Returns

The effect.

Return type

SimpleEffect

hp_str()

Gets a string describing a combatant’s HP.

mod_hp(mod: int, overheal: bool = False)

Modifies a combatant’s remaining hit points by a value.

Parameters
  • mod (int) – The amount of HP to add.

  • overheal (bool) – Whether to allow exceeding max HP.

remove_effect(name: str)

Removes an effect from the combatant, fuzzy searching on name. If not found, does nothing.

Parameters

name (str) – The name of the effect to remove.

save(ability: str, adv: bool = None)

Rolls a combatant’s saving throw.

Parameters
  • ability (str) – The type of save (“str”, “dexterity”, etc).

  • adv (bool) – Whether to roll the save with advantage. Rolls with advantage if True, disadvantage if False, or normally if None.

Returns

A SimpleRollResult describing the rolled save.

Return type

SimpleRollResult

set_ac(ac: int)

Sets the combatant’s armor class.

Parameters

ac (int) – The new AC.

set_hp(newhp: int)

Sets a combatant’s remaining hit points to a new value.

Parameters

newhp (int) – The new HP.

set_init(init: int)

Sets the combatant’s initiative roll.

Parameters

init (int) – The new initiative.

set_maxhp(maxhp: int)

Sets the combatant’s max HP.

Parameters

maxhp (int) – The new max HP.

set_name(name: str)

Sets the combatant’s name.

Parameters

name (str) – The new name.

set_note(note: str)

Sets the combatant’s note.

Parameters

note (str) – The new note.

set_thp(thp: int)

Sets the combatant’s temp HP.

Parameters

thp (int) – The new temp HP.

wouldhit(to_hit: int)

Deprecated since version 1.1.5: Use to_hit >= combatant.ac instead.

Checks if a roll would hit this combatant.

Parameters

to_hit (int) – The rolled total.

Returns

Whether the total would hit.

Return type

bool

SimpleGroup

class SimpleGroup
combatants

A list of all SimpleCombatant in this group.

type

The type of the object ("group"), to determine whether this is a group or not.

Type

str

get_combatant(name)

Gets a SimpleCombatant, fuzzy searching (partial match) on name.

Parameters

name (str) – The name of the combatant to get.

Returns

The combatant.

Return type

SimpleCombatant

SimpleEffect

class SimpleEffect
conc

Whether the effect requires concentration.

Type

bool

duration

The initial duration of the effect, in rounds (-1 = infinite).

Type

int

effect

The applied effect of the object.

Type

dict

name

The name of the effect.

Type

str

remaining

The remaining duration of the effect, in rounds.

Type

int

set_parent(parent)

Sets the parent effect of this effect.

Parameters

parent (SimpleEffect) – The parent.

ParsedArguments

class ParsedArguments
add_context(context, args)

Adds contextual parsed arguments (arguments that only apply in a given context)

Parameters
  • context – The context to add arguments to.

  • args (ParsedArguments) – The arguments to add.

adv(ea=False, boolwise=False, ephem=False)

Determines whether to roll with advantage, disadvantage, Elven Accuracy, or no special effect.

Parameters
  • ea – Whether to parse for elven accuracy.

  • boolwise – Whether to return an integer or tribool representation.

  • ephem – Whether to return an ephemeral argument if such exists.

Returns

-1 for dis, 0 for normal, 1 for adv, 2 for ea

get(arg, default=None, type_=<class 'str'>, ephem=False)

Gets a list of all values of an argument.

Parameters
  • arg (str) – The name of the arg to get.

  • default – The default value to return if the arg is not found. Not cast to type.

  • type – The type that each value in the list should be returned as.

  • ephem (bool) – Whether to add applicable ephemeral arguments to the returned list.

Returns

The relevant argument list.

Return type

list

ignore(arg)

Removes any instances of an argument from the result in all contexts (ephemeral included).

Parameters

arg – The argument to ignore.

join(arg, connector: str, default=None, ephem=False)

Returns a str formed from all of one arg, joined by a connector.

Parameters
  • arg – The arg to join.

  • connector – What to join the arg by.

  • default – What to return if the arg does not exist.

  • ephem – Whether to return an ephemeral argument if such exists.

Returns

The joined str, or default.

last(arg, default=None, type_: type = <class 'str'>, ephem=False)

Gets the last value of an arg.

Parameters
  • arg (str) – The name of the arg to get.

  • default – The default value to return if the arg is not found. Not cast to type.

  • type – The type that the arg should be returned as.

  • ephem – Whether to return an ephemeral argument if such exists.

Raises

InvalidArgument if the arg cannot be cast to the type

Returns

The relevant argument.

set_context(context)

Sets the current argument parsing context.

Parameters

context – Any hashable context.