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. It is recommended to use AliasCharacter.levels.get() to access arbitrary levels instead.

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

enumerate(x)

Returns a iterable of tuples containing a count and the values from the iterable.

Parameters

x (iterable) – The value to convert.

Returns

enumerate of count and objects.

Return type

iterable[tuple[int, any]]

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]']
character()

Returns the active character if one is. Otherwise, raises a FunctionRequiresCharacter error.

Return type

AliasCharacter

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.

ctx

The context the alias was invoked in. See AliasContext for more details.

Note that this is an automatically bound name and not a function.

Type

AliasContext

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.

Retrieves names in the order of local > cvar > uvar. Does not interact with svars.

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

get_svar(name)

Retrieves and returns the value of a svar (server variable).

Parameters

name (str) – The name of the svar.

Returns

The value of the svar, or None if it does not exist.

Return type

str or None

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

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

Warning

The following functions are deprecated and should be avoided:

chanid()

Returns the ID of the active Discord channel.

Deprecated since version 2.5.0: Use ctx.channel.id instead.

Return type

str

servid()

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

Deprecated since version 2.5.0: Use ctx.guild.id instead.

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.

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.

Warning

As of v2.2.0, all character context functions have been deprecated and should be replaced. See each function’s documentation for its replacement.

Custom Counters

Warning

cc_exists(name)

Deprecated since version 2.5.0: Use character().cc_exists() instead.

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)

Deprecated since version 2.5.0: Use character().cc_str() instead.

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)

Deprecated since version 2.5.0: Use character().create_cc() instead.

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)

Deprecated since version 2.5.0: Use character().create_cc_nx() instead.

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)

Deprecated since version 2.5.0: Use character().delete_cc() instead.

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)

Deprecated since version 2.5.0: Use character().get_cc() instead.

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)

Deprecated since version 2.5.0: Use character().get_cc_max() instead.

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)

Deprecated since version 2.5.0: Use character().get_cc_min() instead.

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)

Deprecated since version 2.5.0: Use character().mod_cc() instead.

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

set_cc(name, value, strict=False)

Deprecated since version 2.5.0: Use character().set_cc() instead.

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

Warning

get_slots(level)

Deprecated since version 2.5.0: Use character().spellbook.get_slots() instead.

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)

Deprecated since version 2.5.0: Use character().spellbook.get_slots_max() instead.

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)

Deprecated since version 2.5.0: Use character().spellbook.set_slots() instead.

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)

Deprecated since version 2.5.0: Use character().spellbook.slots_str() instead.

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)

Deprecated since version 2.5.0: Use character().spellbook.use_slot() instead.

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

Hit Points

Warning

get_hp()

Deprecated since version 2.5.0: Use character().hp instead.

Returns

The character’s current hit points.

Return type

int

get_temphp()

Deprecated since version 2.5.0: Use character().temp_hp instead.

Returns

The character’s current temporary hit points.

Return type

int

hp_str()

Deprecated since version 2.5.0: Use character().hp_str() instead.

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

mod_hp(value, overflow=True)

Deprecated since version 2.5.0: Use character().modify_hp() instead.

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)

Deprecated since version 2.5.0: Use character().set_hp() instead.

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

Parameters

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

set_temphp(value)

Deprecated since version 2.5.0: Use character().set_temp_hp() instead.

Sets the character’s remaining temp HP.

Parameters

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

Cvars

Warning

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)

Deprecated since version 2.5.0: Use character().delete_cvar() instead.

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)

Deprecated since version 2.5.0: Use character().set_cvar() instead.

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)

Deprecated since version 2.5.0: Use character().set_cvar_nx() instead.

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

Warning

get_raw()

Deprecated since version 2.5.0: Deprecated without replacement. Use character() to get a representation of the character instead.

Returns a raw representation of character data.

Variable Scopes

In addition to Python’s normal variable scoping rules, Avrae introduces 4 new scopes in the form of character variables, user variables, server variables, and global variables. The intended purpose and binding rules of each are detailed below.

Variable Type

Read

Write

Binding

Scope

Who

Cvar

Yes

Yes

Implicit

Character

User

Uvar

Yes

Yes

Implicit

User

User

Svar

Yes

No

Explicit

Server

Anyone on server

Gvar

Yes

No

Explicit

Everywhere

Anyone

Character Variables

aka cvars

Character variables are variables bound to a character. These are usually used to set character-specific defaults or options for aliases and snippets (e.g. a character’s familiar type/name). When running an alias or snippet, cvars are implicitly bound as local variables in the runtime.

Cvars can be written or deleted in Draconic using AliasCharacter.set_cvar() and AliasCharacter.delete_cvar(), respectively.

All characters contain some built-in character variables (see Cvar Table). These cannot be overwritten.

User Variables

aka uvars

User variables are bound per Discord user, and will go with you regardless of what server or character you are on. These variables are usually used for user-specific options (e.g. a user’s timezone, favorite color, etc.). When running an alias or snippet, uvars are implicitly bound as local variables in the runtime. If a cvar and uvar have the same name, the cvar takes priority.

Uvars can be written or deleted in Draconic using set_uvar() or delete_uvar(), respectively.

Server Variables

aka svars

Server variables are named variables bound per Discord server, and can only be accessed in the Discord server they are bound in. These variables are usually used for server-specific options for server aliases (e.g. stat rolling methods, server calendar, etc.). Unlike cvars and uvars, svars must be explicitly retrieved in an alias by calling get_svar(). Svars can be listed and read by anyone on the server, so be careful what data you store!

Svars can only be written or deleted using !svar <name> <value> and !svar delete <name>, respectively. These commands can only be issued by a member who has Administrator Discord permissions or a Discord role named “Server Aliaser” or “Dragonspeaker”.

Global Variables

aka gvars

Global variables are uniquely named variables that are accessible by anyone, anywhere in Avrae. These variables are usually used for storing large amounts of read-only data (e.g. an alias’ help message, a JSON file containing cards, etc.). These variables are automatically assigned a unique name on creation (in the form of a 36 character UUID), and must be explicitly retrieved in an alias by calling get_gvar(). Gvars can be read by anyone, so be careful what data you store!

Gvars can only be created using !gvar create <value>, and by default can only be edited by its creator. See !help gvar for more information.

See Also

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

Initiative Models

SimpleCombat

class SimpleCombat
combatants

A list of all SimpleCombatant in combat.

current

The SimpleCombatant or SimpleGroup representing the combatant whose turn it is.

me

The SimpleCombatant representing the active character in combat, or None if the character is not in the combat.

round_num

An int representing the round number of the combat.

turn_num

An int representing the initiative score of the current turn.

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

get_group(name)

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

Parameters

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

Returns

The group.

Return type

SimpleGroup

SimpleCombatant

class SimpleCombatant(AliasStatBlock)

Represents a combatant in combat.

effects

A list of SimpleEffect active on the combatant.

Type

list of SimpleEffect

init

What the combatant rolled for initiative.

Type

int

initmod

An int representing the combatant’s initiative modifier.

Type

int

level

Deprecated since version 2.5.0: Use SimpleCombatant.levels.total_level or SimpleCombatant.spellbook.caster_level instead.

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

Type

int

resists

Deprecated since version 2.5.0: Use SimpleCombatant.resistances instead.

The combatant’s resistances, immunities, and vulnerabilities.

Type

AliasResistances

type

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

Type

str

property ac

The armor class of the creature.

Return type

int or None

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.

property attacks

The attacks of the creature.

Return type

AliasAttackList

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

property hp

The current HP of the creature.

Return type

int or None

hp_str()

Returns a string describing the creature’s current, max, and temp HP.

Return type

str

property levels

The levels of the creature.

Return type

AliasLevels

property max_hp

The maximum HP of the creature.

Return type

int or None

property maxhp

Deprecated since version 2.5.0: Use SimpleCombatant.max_hp instead.

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

Return type

Optional[int]

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

Deprecated since version 2.5.0: Use SimpleCombatant.modify_hp() instead.

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.

modify_hp(amount, ignore_temp=False, overflow=True)

Modifies the creature’s remaining HP by a given amount.

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

  • ignore_temp (bool) – If amount is negative, whether to damage temp HP first or ignore temp.

  • overflow (bool) – If amount is positive, whether to allow overhealing or cap at the creature’s max HP.

property name

The name of the creature.

Return type

str

property note

The note on the combatant. None if not set.

Return type

str or None

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.

reset_hp()

Heals a creature to max and removes any temp HP.

property resistances

The resistances, immunities, and vulnerabilities of the creature.

Return type

AliasResistances

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

property saves

The saves of the creature.

Return type

AliasSaves

set_ac(ac: int)

Sets the combatant’s armor class.

Parameters

ac (int) – The new AC.

set_hp(new_hp)

Sets the creature’s remaining HP.

Parameters

new_hp (int) – The amount of remaining HP (a nonnegative integer).

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_temp_hp(new_temp)

Sets a creature’s temp HP.

Parameters

new_temp (int) – The new temp HP (a non-negative integer).

set_thp(thp: int)

Deprecated since version 2.5.0: Use SimpleCombatant.set_temp_hp() instead.

Sets the combatant’s temp HP.

Parameters

thp (int) – The new temp HP.

property skills

The skills of the creature.

Return type

AliasSkills

property spellbook

The creature’s spellcasting information.

Return type

AliasSpellbook

property stats

The stats of the creature.

Return type

AliasBaseStats

property temp_hp

The current temp HP of the creature.

Return type

int

property temphp

Deprecated since version 2.5.0: Use SimpleCombatant.temp_hp instead.

How many temporary hit points the combatant has.

Return type

int

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.

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.

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.

Context Models

AliasContext

class AliasContext

Used to expose some information about the context, like the guild name, channel name, author name, and current prefix to alias authors.

You can access this in an alias by using the ctx local.

property author

The user that ran the alias.

Return type

AliasAuthor

property channel

The channel the alias was run in.

Return type

AliasChannel

property guild

The discord guild (server) the alias was run in, or None if the alias was run in DMs.

Return type

AliasGuild or None

property prefix

The prefix used to run the alias.

Return type

str

AliasGuild

class AliasGuild

Represents the Discord guild (server) an alias was invoked in.

property id

The ID of the guild.

Return type

int

property name

The name of the guild.

Return type

str

AliasChannel

class AliasChannel

Represents the Discord channel an alias was invoked in.

property id

The ID of the channel.

Return type

int

property name

The name of the channel, not including the preceding hash (#).

Return type

str

property topic

The channel topic.

Return type

str

AliasAuthor

class AliasAuthor

Represents the Discord user who invoked an alias.

property discriminator

The user’s discriminator (number after the hash).

Return type

str

property display_name

The user’s display name - nickname if applicable, otherwise same as their name.

Return type

str

property id

The user’s ID.

Return type

int

property name

The user’s username (not including the discriminator).

Return type

str

AliasCharacter

class AliasCharacter(AliasStatBlock)
property ac

The armor class of the creature.

Return type

int or None

property attacks

The attacks of the creature.

Return type

AliasAttackList

property background

Gets the character’s background.

Return type

str or None

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.

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")
'◉◉◉〇〇'
property consumables

Returns a list of custom counters on the character.

Return type

list[AliasCustomCounter]

create_cc(name: str, *args, **kwargs)

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'.

Return type

AliasCustomCounter

Returns

The newly created counter.

create_cc_nx(name: str, minVal: str = None, maxVal: str = None, reset: str = None, dispType: str = 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)
property csettings

Gets a copy of the character’s settings dict.

Return type

dict

property cvars

Returns a dict of cvars bound on this character.

Return type

dict

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.

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.

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 INT_MAX (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 INT_MIN (-2^31).

Return type

int

Raises

ConsumableException if the counter does not exist.

property hp

The current HP of the creature.

Return type

int or None

hp_str()

Returns a string describing the creature’s current, max, and temp HP.

Return type

str

property levels

The levels of the creature.

Return type

AliasLevels

property max_hp

The maximum HP of the creature.

Return type

int or None

mod_cc(name, val: int, strict=False)

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

modify_hp(amount, ignore_temp=False, overflow=True)

Modifies the creature’s remaining HP by a given amount.

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

  • ignore_temp (bool) – If amount is negative, whether to damage temp HP first or ignore temp.

  • overflow (bool) – If amount is positive, whether to allow overhealing or cap at the creature’s max HP.

property name

The name of the creature.

Return type

str

property owner

Returns the id of this character’s owner.

Return type

int

property race

Gets the character’s race.

Return type

str or None

reset_hp()

Heals a creature to max and removes any temp HP.

property resistances

The resistances, immunities, and vulnerabilities of the creature.

Return type

AliasResistances

property saves

The saves of the creature.

Return type

AliasSaves

set_cc(name, value: int, 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.

Returns

The cc’s new value.

Return type

int

set_cvar(name, val: str)

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, val: str)

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.

set_hp(new_hp)

Sets the creature’s remaining HP.

Parameters

new_hp (int) – The amount of remaining HP (a nonnegative integer).

set_temp_hp(new_temp)

Sets a creature’s temp HP.

Parameters

new_temp (int) – The new temp HP (a non-negative integer).

property sheet_type

Returns the sheet type of this character (beyond, dicecloud, google).

Return type

str

property skills

The skills of the creature.

Return type

AliasSkills

property spellbook

The creature’s spellcasting information.

Return type

AliasSpellbook

property stats

The stats of the creature.

Return type

AliasBaseStats

property temp_hp

The current temp HP of the creature.

Return type

int

property upstream

Returns the upstream key for this character.

Return type

str

AliasCustomCounter

class AliasCustomCounter
property display_type

Returns the cc’s display type. (None, ‘bubble’)

Return type

str

property max

Returns the maximum value of the cc, or 2^31-1 if the cc has no max.

Return type

int

property min

Returns the minimum value of the cc, or -2^31 if the cc has no min.

Return type

int

property name

Returns the cc’s name.

Return type

str

reset()

Resets the cc to its max. Errors if the cc has no max or no reset.

Returns

The cc’s new value.

Return type

int

property reset_on

Returns the condition on which the cc resets. (‘long’, ‘short’, ‘none’, None)

Return type

str or None

set(new_value, strict=False)

Sets the cc’s value to a new value.

Parameters
  • new_value (int) – The new value to set.

  • strict (bool) – Whether to error when going out of bounds (true) or to clip silently (false).

Returns

The cc’s new value.

Return type

int

property value

Returns the current value of the cc.

Return type

int

AliasDeathSaves

class AliasDeathSaves
fail(num=1)

Adds one or more failed death saves.

Parameters

num (int) – The number of failed death saves to add.

property fails

Returns the number of failed death saves.

Return type

int

is_dead()

Returns whether or not the character is dead.

Return type

bool

is_stable()

Returns whether or not the character is stable.

Return type

bool

reset()

Resets all death saves.

succeed(num=1)

Adds one or more successful death saves.

Parameters

num (int) – The number of successful death saves to add.

property successes

Returns the number of successful death saves.

Return type

int

StatBlock Models

AliasStatBlock

class AliasStatBlock

A base class representing any creature (player or otherwise) that has stats.

Generally, these are never directly used - notable subclasses are SimpleCombatant and AliasCharacter.

property ac

The armor class of the creature.

Return type

int or None

property attacks

The attacks of the creature.

Return type

AliasAttackList

property hp

The current HP of the creature.

Return type

int or None

hp_str()

Returns a string describing the creature’s current, max, and temp HP.

Return type

str

property levels

The levels of the creature.

Return type

AliasLevels

property max_hp

The maximum HP of the creature.

Return type

int or None

modify_hp(amount, ignore_temp=False, overflow=True)

Modifies the creature’s remaining HP by a given amount.

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

  • ignore_temp (bool) – If amount is negative, whether to damage temp HP first or ignore temp.

  • overflow (bool) – If amount is positive, whether to allow overhealing or cap at the creature’s max HP.

property name

The name of the creature.

Return type

str

reset_hp()

Heals a creature to max and removes any temp HP.

property resistances

The resistances, immunities, and vulnerabilities of the creature.

Return type

AliasResistances

property saves

The saves of the creature.

Return type

AliasSaves

set_hp(new_hp)

Sets the creature’s remaining HP.

Parameters

new_hp (int) – The amount of remaining HP (a nonnegative integer).

set_temp_hp(new_temp)

Sets a creature’s temp HP.

Parameters

new_temp (int) – The new temp HP (a non-negative integer).

property skills

The skills of the creature.

Return type

AliasSkills

property spellbook

The creature’s spellcasting information.

Return type

AliasSpellbook

property stats

The stats of the creature.

Return type

AliasBaseStats

property temp_hp

The current temp HP of the creature.

Return type

int

AliasBaseStats

class AliasBaseStats

Represents a statblock’s 6 base ability scores and proficiency bonus.

property charisma

Charisma score.

Return type

int

property constitution

Constitution score.

Return type

int

property dexterity

Dexterity score.

Return type

int

get_mod(stat: str)

Gets the modifier for a base stat (str, dex, con, etc). Does not take skill check bonuses into account.

For the skill check modifier, use StatBlock.skills.strength etc.

Parameters

stat (str) – The stat to get the modifier for.

Return type

int

property intelligence

Intelligence score.

Return type

int

property prof_bonus

The proficiency bonus.

Return type

int

property strength

Strength score.

Return type

int

property wisdom

Wisdom score.

Return type

int

AliasLevels

class AliasLevels

Represents a statblock’s class levels.

for (cls, level) in AliasLevels:

Iterates over pairs of class names and the number of levels in that class.

Type

Iterable[tuple[str, int]]

get(cls_name, default=0)

Gets the levels in a given class, or default if there are none.

Parameters
  • cls_name (str) – The name of the class to get the levels of.

  • default (int) – What to return if the statblock does not have levels in the given class.

Return type

int

property total_level

The total level.

Return type

int

AliasAttackList

class AliasAttackList

A container of a statblock’s attacks.

str(AliasAttackList)

Returns a string representation of all attacks in this attack list.

Type

str

len(AliasAttackList)

Returns the number of attacks in this attack list.

Type

int

for attack in AliasAttackList:

Iterates over attacks in this attack list.

Type

Iterable[AliasAttack]

AliasAttackList[i]

Gets the i-th indexed attack.

Type

AliasAttack

AliasAttack

class AliasAttack

An attack.

str(AliasAttack)

Returns a string representation of this attack.

Type

str

property name

The name of the attack.

Return type

str

property proper

Whether or not this attack is a proper noun.

Return type

bool

property raw

A dict representing the raw value of this attack.

Return type

dict

property verb

The custom verb used for this attack, if applicable.

Return type

str or None

AliasSkill

class AliasSkill

A skill modifier.

property adv

The guaranteed advantage or disadvantage on this skill modifier. True = adv, False = dis, None = normal.

Return type

bool or None

property bonus

The miscellaneous bonus to the skill modifier.

Return type

int

d20(base_adv=None, reroll=None, min_val=None, mod_override=None)

Gets a dice string representing the roll for this skill.

Parameters
  • base_adv (bool) – Whether this roll should be made at adv (True), dis (False), or normally (None).

  • reroll (int) – If the roll lands on this number, reroll it once (Halfling Luck).

  • min_val (int) – The minimum value of the dice roll (Reliable Talent, Glibness).

  • mod_override (int) – Overrides the skill modifier.

Return type

str

property prof

The proficiency multiplier in this skill. 0 = no proficiency, 0.5 = JoAT, 1 = proficiency, 2 = expertise.

Return type

float or int

property value

The final modifier. Generally, value = (base stat mod) + (profBonus) * prof + bonus.

Return type

int

AliasSkills

class AliasSkills

An object holding the skill modifiers for all skills.

for (skill_name, skill) in AliasSkills:

Iterates over pairs of skill names and corresponding skills.

Type

Iterable[tuple[str, AliasSkill]]

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

The skill modifier for the given skill.

Type

AliasSkill

AliasSaves

class AliasSaves

An objecting holding the modifiers of all saves.

for (save_name, skill) in AliasSaves:

Iterates over pairs of save names and corresponding save.

Type

Iterable[tuple[str, AliasSkill]]

get(base_stat)

Gets the save skill for a given stat (str, dex, etc).

Parameters

base_stat (str) – The stat to get the save for.

Return type

AliasSkill

AliasResistances

class AliasResistances

A statblock’s resistances, immunities, vulnerabilities, and explicit neural damage types.

property immune

A list of damage types that the stat block is immune to.

Return type

list[Resistance]

property neutral

A list of damage types that the stat block ignores in damage calculations. (i.e. will not handle resistances/ vulnerabilities/immunities)

Return type

list[Resistance]

property resist

A list of damage types that the stat block is resistant to.

Return type

list[Resistance]

property vuln

A list of damage types that the stat block is vulnerable to.

Return type

list[Resistance]

Resistance

class Resistance

Represents a conditional resistance to a damage type.

Only applied to a type token set T if \(dtype \in T \land \lnot (unless \cap T) \land only \subset T\).

Note: transforms all damage types given to lowercase.

dtype

The damage type.

Type

str

unless

A set of tokens that if present, this resistance will not apply.

Type

set[str]

only

A set of tokens that unless present, this resistance will not apply.

Type

set[str]

applies_to(tokens)

Note that tokens should be a set of lowercase strings.

Parameters

tokens (set[str]) – A set of strings to test against.

Return type

bool

applies_to_str(dtype)

Returns whether or not this resistance is applicable to a damage type.

Parameters

dtype (str) – The damage type to test.

Return type

bool

AliasSpellbook

class AliasSpellbook

A statblock’s spellcasting information.

spell in AliasSpellbook

Returns whether the spell named spell (str) is known.

Type

bool

can_cast(spell, level)

Returns whether or not the given spell can currently be cast at the given level.

Parameters
  • spell (str) – The name of the spell.

  • level (int) – The level the spell is being cast at.

Return type

bool

cast(spell, level)

Uses all resources to cast a given spell at a given level.

Parameters
  • spell (str) – The name of the spell.

  • level (int) – The level the spell is being cast at.

property caster_level

The caster’s caster level.

Return type

int

property dc

The spellcasting DC.

Return type

int

get_max_slots(level)

Gets the maximum number of level level spell slots available.

Parameters

level (int) – The spell level [1..9].

Returns int

The maximum number of spell slots.

get_slots(level)

Gets the remaining number of slots of a given level. Always returns 1 if level is 0.

Parameters

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

Returns int

The number of slots remaining.

remaining_casts_of(spell, level)

Gets a string representing the remaining casts of a given spell at a given level.

Parameters
  • spell (str) – The name of the spell (case-sensitive).

  • level (int) – The level the spell is being cast at.

Return type

str

reset_slots()

Resets the number of remaining spell slots of all levels to the max.

property sab

The spell attack bonus.

Return type

int

set_slots(level, value)

Sets the remaining number of spell slots of a given level.

Parameters
  • level (int) – The spell level to set [1..9].

  • value (int) – The remaining number of slots.

slots_str(level)
Parameters

level (int) – The level of spell slot to return.

Returns str

A string representing the caster’s remaining spell slots.

property spell_mod

The spellcasting modifier.

Return type

int

property spells

The list of spells in this spellbook.

Return type

list[AliasSpellbookSpell]

use_slot(level)

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

Parameters

level (int) – The level of spell slot to use.

AliasSpellbookSpell

class AliasSpellbookSpell
property dc

The spell’s overridden DC. None if this spell uses the default caster DC.

Return type

int or None

property mod

The spell’s overridden spellcasting modifier. None if this spell uses the default caster spellcasting modifier.

Return type

int or None

property name

The name of the spell.

Return type

str

property sab

The spell’s overridden spell attack bonus. None if this spell uses the default caster spell attack bonus.

Return type

int or None