Aliasing

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.

Syntax Table

Syntax Description Example
{CVAR/roll} Evaluates the cvar/rolls the input. Input: echo Rolling 1d20: {1d20}
Output: Rolling 1d20: 7
<CVAR> Prints the value of the cvar. Input: echo My strength modifier is: <strengthMod>
Output: My strength modifier is: 2
%1%, %2%, etc. Replaced with the value of the nth argument passed to the alias. Input: echo %2% %1%
Output (when called as !(name) first second): second first
{{code}} Runs the statement as raw Python-like code. See the functions table for a list of allowed functions. Input: echo {{set("strength_plus_one", strength+1)}}1 more than my strength score is {{strength_plus_one}}!
Output (given a STR of 14): 1 more than my strength score is 15!

Input: echo My roll was {{"greater than" if roll("1d20") > 10 else "less than"}} 10!
Output (assuming the roll was 8): My roll was less than 10!

Cvar Table

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
proficiencyBonus Proficiency bonus. 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 (Dicecloud sheets only) How many levels a character has in class X. int
currentHp (scripting only) The character's current remaining HP. int

Functions Table

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

Name Description Arguments Returns Syntax
randint(x) Returns a random integer in the range [0..x). x - int - The upper limit (non-inclusive). int - The random number. randint(10)
roll(dice) Rolls a given string. dice - str - The dice to roll. int - The result of the roll, or 0 if an error was encountered. roll("1d20")
vroll(dice) Verbosely rolls a given string, returning a formatted output. dice - str - The dice to roll. Result - The result of the roll.
Use Result.dice (str) to access the rolled dice, Result.total (int) for the final total, and str(Result) (str) for the combined output.
vroll("1d20")
int(x) Converts x to an int. x - str, int, float - The value to convert. int - The integer. int("10")
str(x) Converts x to a string. x - str, int, float - The value to convert. str - The string. str(5)
len(x) Returns the length of a string or list. x - str, list - The element to find the length of. int - The length. len("words")
floor(x) Rounds a number down to the nearest integer. x - float, int - The number to round. int - The resulting integer. floor(6/5)
ceil(x) Rounds a number up to the nearest integer. x - float, int - The number to round. int - The resulting integer. ceil(6/5)
round(x, digits) Rounds x to digits digits. Rounds towards the nearest even number. x - float, int - The number to round.
digits - int, optional - How many digits to round to.
int or float - The resulting number. round(6.5)
round(3.1415, 2)
max(x, y[, z...]) Returns the largest of all the arguments. x, y - float, int - The numbers to compare. int or float - The largest argument. max(3, 14, 2)
min(x, y[, z...]) Returns the smallest of all the arguments. x, y - float, int - The numbers to compare. int or float - The smallest argument. min(3, -2)
set(name, value) Sets a temporary variable (for the execution of the command only). name - str - The name of the variable.
value - Any - The value of the variable.
None set("foo", "bar")
get_cc(name) Gets the value of a custom counter. name - str - The name of the custom counter to get the value of. int - The value of the counter. get_cc("Ki")
get_cc_max(name) Gets the maximum value of a custom counter. name - str - The name of the custom counter to get the max value of. int - The max value of the counter. Returns 2^32-1 if there is no max. get_cc_max("Ki")
get_cc_min(name) Gets the minimum value of a custom counter. name - str - The name of the custom counter to get the min value of. int - The min value of the counter. Returns -(2^32) if there is no min. get_cc_min("Ki")
set_cc(name, value[, strict]) Sets a custom counter to a new value. name - str - The name of the custom counter to modify.
value - int - The new value of the counter.
strict - True/False (optional, default False) - if True, error if out of bounds.
None set_cc("Ki", 5)
mod_cc(name, value[, strict]) Modifies a custom counter by a certain value. name - str - The name of the custom counter to modify.
value - int - The number to modify by of the counter.
strict - True/False (optional, default False) - if True, error if out of bounds.
None mod_cc("Ki", -2)
create_cc_nx(name[, minVal, maxVal, reset, dispType]) Creates a custom counter only if one with the same name doesn't exist. name - str - The name of the cc to create.
minVal - str (Optional) - The minimum value of the cc. Default: unlimited.
maxVal - str (Optional) - The maximum value of the cc. Default: unlimited.
reset - str (Optional) - The reset type of the cc ("short", "long", "none", None). Default: None.
dispType - str (Optional) - The display type of the cc ("default", "bubble"). Default: default.
None create_cc_nx("SP", 0, "SorcererLevel", "long", "bubble")
cc_exists(name) Returns whether a certain cc exists. name - str - The name of the custom counter to check.
bool - Whether the cc exists. cc_exists("Ki")
get_slots(level) Gets the number of remaining spell slots of a certain level. level - int - The level to get spell slots of. int - The number of remaining slots. get_slots(3)
get_slots_max(level) Gets the maximum number of spell slots of a certain level. level - int - The level to get the max spell slots of. int - The max number of slots. get_slots_max(3)
set_slots(level, value) Sets the number of spell slots of a certain level. level - int - The level of spell slot.
value - int - The number of remaining slots.
None set_slots(3, 1)
use_slot(level) Uses one spell slot of a certain level. level - int - The level of spell slot. None use_slot(3)
get_hp() Gets the character's remaining HP. No arguments. int - The character's remaining HP. get_hp()
set_hp(val) Sets the character's HP. val - int - The remaining HP. None set_hp(7)
mod_hp(val) Modified the character's HP. val - int - The amount to change HP by. None mod_hp(-2)
get_temphp() Gets the character's temp HP. No arguments. int - The character's temp HP. get_temphp()
set_temphp(val) Sets the character's temp HP. val - int - The new temp HP. None set_temphp(7)
set_cvar(name, value) Sets a cvar to a new value. name - str - The name of the cvar to modify.
value - str - The new value of the cvar.
None set_cvar("potato", "fifteen")
set_cvar_nx(name, value) Sets a cvar to a new value, only if it doesn't already exist. name - str - The name of the cvar to create.
value - str - The new value of the cvar.
None set_cvar_nx("potato", "fifteen")
delete_cvar(name) Deletes a cvar. Does nothing if the cvar does not exist. name - str - The name of the cvar to delete.
None delete_cvar("potato")
get_gvar(name) Gets the value of a global variable. name - str - The name of the gvar to get. Should be a UUID4.
str - The value of the gvar. get_gvar("87228cfb-43b6-4cd4-ac2e-14b59db149c0")
exists(name) Returns whether a cvar or uvar exists. name - str - The name of the cvar or uvar to check.
bool - Whether the var exists. exists("potato")
get_raw() Returns the raw character object (see the debug tab of a character in the dashboard). dict - The raw character dictionary. get_raw()
combat() Returns a SimpleCombat object representing the current combat of the channel, if the character is in it. SimpleCombat - The combat. combat()
load_json(jsonstr) Loads an object from a JSON string. jsonstr - str - The JSON string to load.
object - The encoded object. load_json('{"one": 1}')
dump_json(obj) Serializes an object to a JSON string. obj - dict, list, str, int - The object to serialize.
str - The serialized string. dump_json({"one": 1})

See also:
Ternary Operators (x if a else y)
Slicing ("Hello world!"[2:4])
Operators (2 + 2, "foo" in "foobar", etc)
List Comprehensions

Models

This is the documentation of the miscellaneous models returned through scripting.

SimpleCombat

Name Description Arguments Returns Syntax
combatants A list of all combatants in combat. list of SimpleCombatant - All combatants in combat. combat.combatants
current The SimpleCombatant or SimpleGroup representing the current turn. SimpleCombatant or SimpleGroup - The combatant or group. combat.current
me The SimpleCombatant representing the current character in combat. SimpleCombatant - The combatant. combat.me
round_num The round number of the combat. int - The round number. combat.round_num
turn_num The turn number (current initiative) of the combat. int - The turn number. combat.turn_num
get_combatant(name) Gets a SimpleCombatant, fuzzy searching (partial match) for a match. name - The name of the combatant to get. SimpleCombatant - The combatant. combat.get_combatant("Padellis")
get_group(name) Gets a SimpleGroup, searching (full match) for a match. name - The name of the group to get. SimpleGroup - The group. combat.get_group("Zombies")

SimpleCombatant

Name Description Arguments Returns Syntax
ac The combatant's ac. Returns None if not visible. int or None - The combatant's AC. c.ac
hp The combatant's current hit points. Returns None if not visible. int or None - The combatant's HP. c.hp
init The combatant's rolled initiative. int - The combatant's initiative. c.init
initmod The combatant's initiative mod. Returns None if not visible. int or None - The combatant's init mod. c.initmod
maxhp The combatant's max HP. Returns None if not visible. int or None - The combatant's max HP. c.maxhp
name The combatant's name. str - The combatant's name. c.name
note The note on the combatant. Returns an empty string if there is none. str - The combatant's notes. c.note
ratio The combatant's health ratio (0%=0.0, 100%=1.0). Shows even if combatant is hidden. float - The combatant's ratio of health:max health. c.ratio
temphp The combatant's temporary hit points. Returns None if not visible. int or None - The combatant's temp HP. c.temphp
set_hp(hp) Sets a combatant's remaining hit points to a new value. hp - int - The HP to set. None c.set_hp(50)
mod_hp(hp) Modifies a combatant's remaining hit points by a value. hp - int - The amount of HP to add. None c.mod_hp(-7)
hp_str() Gets a string describing a combatant's HP. str - The string. Will show HP value if combatant is not hidden, or generalization. c.hp_str()
save(ability[, adv]) Rolls a combatant's saving throw. ability - str - The type of save ("str", "dexterity", etc). adv - bool or None (default None) - Whether to roll the save with advantage. Rolls with advantage if True, disadvantage if False, or normally if None. Result - The rolled save. See vroll(). c.save("str")
wouldhit(to_hit) Checks whether a roll would hit a combatant. to_hit - int - The roll to check against AC. bool - Whether the attack would hit or not. None if the combatant's AC is not defined. c.wouldhit(18)

SimpleGroup

Name Description Arguments Returns Syntax
get_combatant(name) Gets a SimpleCombatant, fuzzy searching (partial match) for a match. name - The name of the combatant to get. SimpleCombatant - The combatant. group.get_combatant("Padellis")