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!
Note
It is highly recommended to be familiar with the Python language before diving into Draconic, as the two use the same syntax and types.
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, returnFalse
.
-
ceil
(x)¶ Rounds a number up to the nearest integer. See
math.ceil()
.
-
enumerate
(x)¶ Returns a iterable of tuples containing a count and the values from the iterable.
-
float
(x)¶ Converts x to a floating point number.
-
floor
(x)¶ Rounds a number down to the nearest integer. See
math.floor()
.
-
int
(x)¶ Converts x to an integer.
-
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
-
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, aValueError
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, aValueError
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 to0
. If step is zero,ValueError
is raised.For a positive step, the contents of a range
r
are determined by the formular[i] = start + step*i
wherei >= 0
andr[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 arei >= 0
andr[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.
-
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.
-
sqrt
(x)¶ See
math.sqrt()
.- Returns
The square root of x.
- Return type
-
str
(x)¶ Converts x to a string.
- Parameters
x (Any) – The value to convert.
- Returns
The string.
- Return type
-
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
Draconic Functions¶
-
argparse
(args)¶ Parses arguments.
- Parameters
args (str or Iterable) – A list of arguments to parse.
- Returns
The parsed arguments.
- Return type
>>> 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
-
combat
()¶ Returns the combat active in the channel if one is. Otherwise, returns
None
.- Return type
Note
If called outside of a character context,
combat().me
will beNone
.
-
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
-
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, pm_user=False)¶ Stops evaluation of an alias and shows the user an error.
-
exists
(name)¶ Returns whether or not a name is set in the current evaluation context.
- Return type
-
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).
-
get_svar
(name)¶ Retrieves and returns the value of a svar (server variable).
-
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)
.
-
roll
(dice)¶ Rolls dice and returns the total.
-
set_uvar
(name, value)¶ Sets a user variable.
-
set_uvar_nx
(name, value)¶ Sets a user variable if there is not already an existing name.
-
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
-
vroll
(rollStr, multiply=1, add=0)¶ Rolls dice and returns a detailed roll result.
- Parameters
- Returns
The result of the roll.
- Return type
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
-
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
-
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.
-
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
- 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'
, orNone
.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.
-
get_cc_max
(name)¶ Deprecated since version 2.5.0: Use
character().get_cc_max()
instead.Gets the maximum value of a custom counter.
-
get_cc_min
(name)¶ Deprecated since version 2.5.0: Use
character().get_cc_min()
instead.Gets the minimum value of a custom counter.
-
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.
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.
-
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.
-
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.
-
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.
-
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
-
get_temphp
()¶ Deprecated since version 2.5.0: Use
character().temp_hp
instead.- Returns
The character’s current temporary hit points.
- Return type
-
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.
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.
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:
Ternary Operators (
x if a else y
)Slicing (
"Hello world!"[2:4]
)Operators (
2 + 2
,"foo" in "foobar"
, etc)Assignments (
a = 15
)
Initiative Models¶
SimpleCombat¶
-
class
SimpleCombat
¶ -
combatants
¶ A list of all
SimpleCombatant
in combat.
-
current
¶ The
SimpleCombatant
orSimpleGroup
representing the combatant whose turn it is.
-
groups
¶ A list of all
SimpleGroup
in combat.
-
me
¶ The
SimpleCombatant
representing the active character in combat, orNone
if the character is not in the combat.
-
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
-
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
-
SimpleCombatant¶
-
class
SimpleCombatant
(AliasStatBlock)¶ Represents a combatant in combat.
-
effects
¶ A list of
SimpleEffect
active on the combatant.- Type
list of
SimpleEffect
-
level
¶ Deprecated since version 2.5.0: Use
SimpleCombatant.levels.total_level
orSimpleCombatant.spellbook.caster_level
instead.The combatant’s spellcaster level.
0
if the combatant is not a player or spellcaster.- Type
-
resists
¶ Deprecated since version 2.5.0: Use
SimpleCombatant.resistances
instead.The combatant’s resistances, immunities, and vulnerabilities.
- Type
-
add_effect
(name: str, args: str, duration: int = -1, concentration: bool = False, parent=None, end: bool = False, desc: str = None)¶ 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.
desc (str) – A description of the effect.
-
property
attacks
¶ The attacks of the creature.
- Return type
-
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
-
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
-
property
group
¶ The name of the group the combatant is in, or
None
if the combatant is not in a group.
-
property
levels
¶ The levels of the creature.
- Return type
-
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.
-
modify_hp
(amount, ignore_temp=False, overflow=True)¶ Modifies the creature’s remaining HP by a given amount.
-
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
-
save
(ability: str, adv: bool = None)¶ Rolls a combatant’s saving throw.
- Parameters
- Returns
A SimpleRollResult describing the rolled save.
- Return type
-
property
saves
¶ The saves of the creature.
- Return type
-
set_group
(group)¶ Sets the combatant’s group
- Parameters
group (str) – The name of the group. None to remove from group.
- Returns
The combatant’s new group, or None if the combatant was removed from a group.
- Return type
SimpleGroup
or None
-
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_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
-
property
spellbook
¶ The creature’s spellcasting information.
- Return type
-
property
stats
¶ The stats of the creature.
- Return type
-
property
temphp
¶ Deprecated since version 2.5.0: Use
SimpleCombatant.temp_hp
instead.How many temporary hit points the combatant has.
- Return type
-
SimpleGroup¶
-
class
SimpleGroup
¶ -
combatants
¶ A list of all
SimpleCombatant
in this group.- Type
list of
SimpleCombatant
-
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
-
SimpleEffect¶
-
class
SimpleEffect
¶ -
-
ticks_on_end
¶ Whether the effect duration ticks at the end of the combatant’s turn or at the start.
- Type
-
property
children
¶ Gets the child effects of this effect.
- Return type
list of
SimpleEffect
-
property
parent
¶ Gets the parent effect of this effect, or
None
if this effect has no parent.- Return type
SimpleEffect
or None
-
set_parent
(parent)¶ Sets the parent effect of this effect.
- Parameters
parent (
SimpleEffect
) – The parent.
-
SimpleRollResult¶
-
class
SimpleRollResult
¶ -
-
result
¶ The RollResult object returned by the roll.
- Type
-
raw
¶ The Expression object returned by the roll. Equivalent to
SimpleRollResult.result.expr
.- Type
-
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__
()¶ 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, custom: dict = None)¶ 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.
custom – Dictionary of custom values to parse for. There should be a key for each value you want to overwrite.
custom={'adv': 'custom_adv'}
would allow you to parse for advantage if thecustom_adv
argument is found.
- 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
- Returns
The relevant argument list.
- Return type
-
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.
-
update
(new)¶ Updates the arguments in this argument list from a dict.
-
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
alias
¶ The name the alias was invoked with. Note: When used in a base command, this will return the deepest sub-command, but when used in an alias it will return the base command.
>>> !test {{ctx.alias}} 'test'
- Return type
The user that ran the alias.
- Return type
-
property
channel
¶ The channel the alias was run in.
- Return type
-
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
AliasGuild¶
AliasChannel¶
-
class
AliasChannel
¶ Represents the Discord channel an alias was invoked in.
-
property
category
¶ The category of the channel the alias was run in
- Return type
AliasCategory
or None
-
property
AliasCategory¶
AliasCharacter¶
-
class
AliasCharacter
(AliasStatBlock)¶ -
-
property
attacks
¶ The attacks of the creature.
- Return type
-
cc
(name)¶ Gets the AliasCustomCounter with the name name
- Parameters
name (str) – The name of the custom counter to get.
- Returns
The custom counter.
- Return type
- Raises
ConsumableException
if the counter does not exist.
-
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
- 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
-
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'
, orNone
.dispType (str) – Either
None
or'bubble'
.reset_to (str) – The value the counter should reset to. Supports Cvar Table parsing.
reset_by (str) – How much the counter should change by on a reset. Supports dice but not cvars.
title (str) – The title of the counter.
desc (str) – The description of the counter.
- Return type
- Returns
The newly created counter.
-
create_cc_nx
(name: str, minVal: str = None, maxVal: str = None, reset: str = None, dispType: str = None, reset_to: str = None, reset_by: str = None, title: str = None, desc: 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, reset_to, reset_by, title, desc)
-
property
death_saves
¶ Returns the characters death saves.
- Return type
-
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.
-
get_cc_max
(name)¶ Gets the maximum value of a custom counter.
-
get_cc_min
(name)¶ Gets the minimum value of a custom counter.
-
property
levels
¶ The levels of the creature.
- Return type
-
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.
-
reset_hp
()¶ Heals a creature to max and removes any temp HP.
-
property
resistances
¶ The resistances, immunities, and vulnerabilities of the creature.
- Return type
-
property
saves
¶ The saves of the creature.
- Return type
-
set_cc
(name, value: int, strict=False)¶ Sets the value of a custom counter.
- Parameters
- Raises
ConsumableException
if the counter does not exist.- Returns
The cc’s new value.
- Return type
-
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
-
property
skills
¶ The skills of the creature.
- Return type
-
property
spellbook
¶ The creature’s spellcasting information.
- Return type
-
property
stats
¶ The stats of the creature.
- Return type
-
property
AliasCustomCounter¶
-
class
AliasCustomCounter
¶ -
-
reset
()¶ Resets the cc to its reset value. Errors if the cc has no reset value or no reset.
The reset value is calculated in 3 steps: - if the cc has a
reset_to
value, it is reset to that - else if the cc has areset_by
value, it is modified by that much - else the reset value is its max- Return CustomCounterResetResult
(new_value: int, old_value: int, target_value: int, delta: str)
-
property
reset_by
¶ Returns the amount the cc changes by on a reset, if it was created with an explicit
resetby
.
-
property
reset_on
¶ Returns the condition on which the cc resets. (‘long’, ‘short’, ‘none’, None)
-
property
reset_to
¶ Returns the value the cc resets to, if it was created with an explicit
resetto
.
-
set
(new_value, strict=False)¶ Sets the cc’s value to a new value.
-
AliasDeathSaves¶
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
andAliasCharacter
.-
property
attacks
¶ The attacks of the creature.
- Return type
-
property
levels
¶ The levels of the creature.
- Return type
-
modify_hp
(amount, ignore_temp=False, overflow=True)¶ Modifies the creature’s remaining HP by a given amount.
-
reset_hp
()¶ Heals a creature to max and removes any temp HP.
-
property
resistances
¶ The resistances, immunities, and vulnerabilities of the creature.
- Return type
-
property
saves
¶ The saves of the creature.
- Return type
-
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
-
property
spellbook
¶ The creature’s spellcasting information.
- Return type
-
property
stats
¶ The stats of the creature.
- Return type
-
property
AliasBaseStats¶
AliasLevels¶
AliasAttackList¶
-
class
AliasAttackList
¶ A container of a statblock’s attacks.
-
for attack in AliasAttackList:
Iterates over attacks in this attack list.
- Type
Iterable[
AliasAttack
]
-
AliasAttackList[i]
Gets the i-th indexed attack.
- Type
-
AliasSkill¶
-
class
AliasSkill
¶ A skill modifier.
-
property
adv
¶ The guaranteed advantage or disadvantage on this skill modifier. True = adv, False = dis, None = normal.
-
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
-
property
prof
¶ The proficiency multiplier in this skill. 0 = no proficiency, 0.5 = JoAT, 1 = proficiency, 2 = expertise.
-
property
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
-
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
]]
-
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
-
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
-
property
resist
¶ A list of damage types that the stat block is resistant to.
- Return type
-
property
vuln
¶ A list of damage types that the stat block is vulnerable to.
- Return type
-
property
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.
-
applies_to
(tokens)¶ Note that tokens should be a set of lowercase strings.
-
AliasSpellbook¶
-
class
AliasSpellbook
¶ A statblock’s spellcasting information.
-
spell in AliasSpellbook
Returns whether the spell named spell (str) is known.
- Type
-
can_cast
(spell, level)¶ Returns whether or not the given spell can currently be cast at the given level.
-
cast
(spell, level)¶ Uses all resources to cast a given spell at a given level.
-
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.
-
reset_slots
()¶ Resets the number of remaining spell slots of all levels to the max.
-
set_slots
(level, value)¶ Sets the remaining number of spell slots of a given level.
-
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
spells
¶ The list of spells in this spellbook.
- Return type
-