Contents 1 Introduction to ScriptCards 1.1 What is ScriptCards 1.2 ScriptCards 2.0 - Now with Triggers 1.2.1 Is ScriptCards Related to PowerCards? 1.3 What is a ScriptCard Script 1.4 Structure of a ScriptCard Script 1.4.1 A Note on Whitespace 1.4.2 Quick Reference: Statement Types 2 ScriptCard Statement Type Details 2.1 Comment (--/) 2.2 Console Log (--\) 2.3 Set Parameter (--#) 2.3.1 Parameter Definitions and Details 2.4 Direct Output (--+) 2.5 GM Output (--*) 2.6 Roll Variable Assignment (--=) 2.6.1 Adding Flavor Text to Rolls 2.6.2 Customizing Dice Rolls 2.6.3 Using Dice Rolls in Equations 2.6.4 Roll Modifiers 2.6.5 Mathematical Functions in Roll Expressions 2.6.6 Rolling on Rollable Tables 2.6.7 Special Notes about Dice Rolls 2.7 String Variable Assignment (--&) 2.8 Call Mod (--@) 2.9 Branching 2.9.1 Branch Label (--:) 2.9.2 Return (--<) 2.9.3 Branch (--^) 2.9.4 Call Procedure (-->) 2.9.5 Conditional Statement (--?) 2.9.5.1 Syntax 2.9.5.2 Comparators 2.9.5.3 Branch Types 2.9.5.4 Multi-part Conditionals 2.9.6 Code Blocks 2.9.7 Case Statement (--c) 2.10 Save and Load: Persistent Data Storage (--s) and (--l) 2.10.1 Original Method of Saving and Loading 2.10.1.1 Examples of Syntax 2.10.1.2 Practical Application Examples 2.10.2 Enhanced methods of Saving and Loading data 2.10.2.1 Examples of Syntax 2.11 Visual Effects (--v) 2.11.1 Location Specifiers 2.11.2 Effect Specifiers 2.11.3 Pings 2.12 Audio Effects (--a) 2.13 Echo to Chat (--e) 2.14 Repeating Section Access (--R) 2.15 Built-In Functions (--~) 2.15.1 Non-Categorized Functions 2.15.2 Categorized Functions 2.16 Information Request (--i) 2.17 Object Modification (--!) 2.17.1 General syntax for Modifying Objects: 2.17.2 objectType 2.17.3 objectID 2.17.3.1 Object Modification Examples 2.18 Wait (--w) 3 Inline Formatting 3.1 Button formatting 3.2 Table formatting 4 Variables 4.1 Roll Variables 4.2 String Variables 4.2.1 Predefined String Variables 5 Arrays 5.1 Intro to Arrays 5.2 Adding Elements to an Existing Array 5.3 Changing Array Element Values 5.4 Referencing Array Elements 5.5 Array Metadata 5.6 Traversing Arrays 5.7 Special Array Functions 5.8 Manipulating Array Elements 5.9 Predefined Arrays 6 Hashtables (--h) 6.1 Intro to Hashtables 6.2 Hashtables vs Arrays 6.3 Defining Hashtables, Keys and Values 6.4 Referencing Hashtable Keys and Values 6.5 Removing Keys from Hashtables 6.6 Built-in Functions for Hashtables 6.7 Practical Application Examples 7 Looping Structures (--%) 7.1 For...Next Loops 7.2 While Loops 7.3 Until Loops 7.4 For Each Loops 8 Referencing 8.1 Referencing Overview 8.2 Roll Variables 8.3 String Variables 8.3.1 Expanded String Referencing 8.4 Object Attribute Referencing 8.5 Nested References 8.6 Character/Token Attributes 8.7 Subroutine Parameters 8.8 Campaign Attribute 8.9 Page Attributes 8.10 Repeating Section Values 8.11 ScriptCards Settings 8.12 Deferred Resolution for Meta Scripts 8.13 Arrays 8.13.1 Array Elements 8.13.2 Defining Arrays 9 Interacting with the GM and Players 9.1 Method 1: The Information Request (--i) Command 9.2 Method 2: Buttons 9.2.1 Simple ScriptCards chat button 9.2.2 Ability Macro Sheetbuttons 9.2.3 Reentrant Buttons 9.3 Button Colors 9.4 Reentrant Scripts 9.4.1 Examples of Syntax 9.4.2 Practical Application Example 10 Libraries 10.1 Example Libraries 10.1.1 dnd5elib 11 Triggers 12 Override Templates 13 [For script writers] Registering your token change events to ScriptCards 14 What to Know if you are Coming from PowerCards 15 Example Scripts 15.1 Divine Smite 15.1.1 How It Works 15.1.2 Alternative Script 15.2 Magic Missile 15.2.1 How It Works 15.3 Longsword Attack 15.3.1 How it Works 15.4 Party Health Status 15.4.1 How it Works 15.5 Expanded Magic Missile Script 15.6 Hidden Roll 15.7 Elsewhere

Introduction to ScriptCards

What is ScriptCards

The ScriptCards Mod (Mod Script) implements a feature-rich script interpreter for writing programs inside macros and abilities within Roll20. ScriptCards is not tied to any specific game system or character sheet. The language supports many traditional programming features and a number of features specifically geared towards Roll20, including:

Main Features Implemented:
Settings – More than 70 modifiable settings to control the appearance and behavior of executing scripts (fonts, colors, image backgrounds, and many, many more)
Variables – String variables and Roll variables. Roll variables can be set using a built-in roll parser that can reference other variables and values when creating Rolls, as well as a number of other math related modifiers.
Arrays – Arrays can be defined directly in your scripts or sourced from game information (e.g. status markers on tokens, etc.)
For…Next Loops – Including the ability to break out of the current loop execution or exit the loop entirely. Loops support start, end, and step values.
Branching – Both direct (goto-style) branching and function calling (gosub branching) are supported. Gosub nesting is supported, and parameters can be passed to a gosub branch.
Conditionals – If/Then/Else style conditionals (including code block support) and Switch/Case style conditionals.
Built-in Functions – A library of built-in functions for array manipulation, math, string manipulation, and system interaction with Roll20 (turnorder, date/time)
Calling other Mod Scripts – A syntax for building Mod calls to run asynchronously as part of a ScriptCard execution.
Object Property access and Manipulation – Access and update the properties of Roll20 objects such as tokens, characters, graphics, etc. Built-in property modification is immediately available to the remained of the executing script.
Nested, Run-Time Referencing – Because ScriptCards lines are processed by an interpreter when the line executes, any portion of the line can be replaced by a variable reference, and any type of reference can be nested. Evaluation works from the inside out, so the final reference can be made up of subreferences.
Code Libraries – Roll20 Handouts can be used to store common code functions that you wish to make available to your other scripts.
Infinite Loop Protection – ScriptCards maintains an internal execution count to prevent crashing the Roll20 sandbox if your script enters an infinite loop.

New in ScriptCards 2.0
Triggers – ScriptCards can be configured to respond to various events that take place in the Roll20 VTT environment, such as tokens taking damage, turn order updates, and more.

Current OneClick Version: 2.3.9 (v 2.3.9 has been deployed to One-Click)

Current Development Version: 2.4.2

Critically Important: ScriptCards does not parse inline rolls. ScriptCards includes its own built-in dice roll parser to allow for the use of variables inside dice rolls. The final numeric value of an inline roll can be used in a ScriptCard, but only as a text substitution value, so inline rolls can't reference the value of ScriptCards variables.

ScriptCards 2.0 - Now with Triggers

The newest version of ScriptCards (currently in development on the GitHub repo and tagged as experimental) supports a feature called "ScriptCards Triggers", which allows you to respond to in-game events by running macros (ScriptCards scripts or otherwise) when tokens, pages, attributes, etc. change in your game. This wiki documentation is in the process of being updated to include information for post 1.7.7 updates, including information for 2.0. While these features are available now from the experimental section of the repo, they will not be available in OneClick installs until the newest version has been pushed to Roll20.

Is ScriptCards Related to PowerCards?

I (Kurt J.) have been maintaining and updating PowerCards for a couple of years now, and ScriptCards isn't an effort to supplant PowerCards, but rather represents my effort to address some of the most common issues that PowerCards users run into because of the intrinsic nature of the way PowerCards was conceived and developed over time. ScriptCards is more of a follow-up to PowerCards. Perhaps the most frequent question asked in the PowerCards thread on the forum is something along the lines of “how do I use the result of THIS roll in the roll I make two lines later?” Unfortunately, due to the architecture of PowerCards, this isn’t possible.

Besides this issue, there are various elements of a PowerCards macro that can’t support certain features. For example, you can’t set most card-wide settings (name, leftsub, rightsub) dependent upon the results of a dice roll, and while I’ve implemented a simple “skip forward” mechanism in PowerCards to allow for some flow control, true branching (forward and backwards) is not possible due to the way cards are processed. While it might be possible to rewrite some of the core of PowerCards to allow for implementation of (some) of these features, the result would be a very different script that would not be backwards compatible with the host of users currently using PowerCards in their games.

Instead, I have taken the approach of writing a completely new script from the ground up. There is very little (if any) of the original PowerCards code included in ScriptCards because I am fundamentally changing the way the macro is processed. Note that this isn’t a slight against the original author of PowerCards (Sky). The script has been widely used for years now, and is a testament to the flexibility of the original code that I was able to add so many features over the past two years.

By implementing ScriptCards as a new, separate script, those using PowerCards as it currently exists can continue to do so without interruption, while those interested in the functionality of ScriptCards can make use of its updated feature set. The two script (PowerCards and ScriptCards) can happily coexist in the same game, and do not interfere with each other in any way.

Check the What to Know if you are Coming from PowerCards-section for a comparison table between the two scripts.

What is a ScriptCard Script

A ScriptCard script is text written into the q Text Chat (either typed directly, pasted, or run via a macro/character ability) that will be interepreted and executed by the ScriptCards language processor. In most cases, the result of the script will produce output displayed as an HTML formatted "card" in the chat window. A ScriptCard script is composed of an API command: !scriptcard {{ }} enclosing any number of lines that determine what actions the script will take and the output that will be added to the card. At it simplest, the following macro:

!scriptcard  {{ }}

Will produce just a title card that displays “ScriptCards” as the name:

Of course, this is just the bare essential macro and isn’t very useful. In order to produce output that is helpful for playing a Roll20 game, we need to include lines between the {{ and }} that direct the API script as to what it should do.

Structure of a ScriptCard Script

The body of a ScriptCard Script contains one or more statement lines, which, as a general rule, are interpreted as they are executed and run sequentially from top to bottom. There are exceptions to this general functionality, including the ability to branch to other parts of the code, call subroutines, and terminate execution. There are also special constructs utilized by Reentrant Scripts, that allow execution to begin at locations other than the top of the script. These exceptions will be covered later in this documentation.

A ScriptCard line begins with two dashes, followed by a statement identifier character that lets the interpreter know what type of line it is. There are many different types of statements, and the bulk of this Wiki entry is dedicated to covering the use and function of each one.

After the line type identifier, an optional bit of text referred to as the line's Tag is supplied. This name is essentially free-form and CAN be omitted in the case of some line types. Also note that if you are used to using PowerCards, Tags in ScriptCards do not need to be unique.

Following the Tag is a vertical bar, and then the Content portion of the line. Again, each type of line might interpret this content differently, and in the case of some statement types it is optional.

Example:

--#title|Longsword Attack

In this example:

• # is the statement identifier character, indicating that this line will be a "settings" statement.
• title is the statement Tag. For the "#" statement type, the Tag indicates what setting we will be updating.
• | separates the Tag from the Content
• Longsword Attack is the Content portion of the statement. In this case, it indicates what will be placed in the "title" setting.

A Note on Whitespace

---

ScriptCards lines are delimited by the -- sequence. This means that whitespace before/after a line is ignored by the interpreter. The following two scripts are identical as far as the interpreter is concerned:

!script {{
  --#title|Stealth Check
  --=Roll|1d20 + @{selected|stealth}
  --+|@{selected|token_name} attempts to move undetected...
  --+Stealth|@{selected|token_name} rolled a [$Roll]
}}

!script{{--#title|Stealth Check--=Roll|1d20 + @{selected|stealth}--+|@{selected|token_name} attempts to move undetected...--+Stealth|@{selected|token_name} rolled a [$Roll]}}

Quick Reference: Statement Types

The table below lists each of the statement identifier types available in the ScriptCards language. Each entry also lists what the Tag is used for (if at all) and the format the Content is expected to be in along with usage notes.

Identifier	Statement Type	Tag	Content	Notes
--/	Comment	unused	unused	The --/ sequence is used to add comments to a script. No processing will take place on a --/ line, so the tag and comment can be freely used to add notes to your code.
--\	Console Log	unused	Log Text	) to the API console log.
--#	Set Parameter	Parameter name	Desired parameter value	Parameters generally control the behavior of large segments of the output card. Things like the Title of the card, the colors of the header and rows, etc. There are also parameters that control how various features of the card behave (like "usehollowdice").
--+	Direct Output	Free Text - Is output in bold at start of the line.	Output in normal text after Tag	Direct Output statements are what creates row sections on the output card. A script without any direct output sections will end up looking similar to the sample at the start of this wiki (the !script {{ }} script) because all other statement types do not create output lines.
--=	Assign Roll Variable	Variable Name	Roll Equation (or text) to assign	Roll/Numeric variables are assigned with this command. The content will be processed as a dice roll, and various properties will be set along with the numeric results.
--&	Assign String (or Array Element) Variable	Variable name	Content to store in the string variable.	Roll Variables and String Variables are completely separate entities, and can technically share names, but this would likely lead to confusion and should be avoided. Elements in an array can be assigned with this statement by specifying the array name followed by the index number you wish to assign in parenthesis (ex: Fruits(4)) as the variable name
--@	API Call	API ! Command	API call parameters (replace -- with _)	Other Roll20 API scripts can be called using this command. The Tag is the trigger command for the API script (e.g., !token-mod, or !setattr, etc.)
--:	Branch Label	Label Name	Unused (Comments if desired)	Branch labels are the destination for branch and procedure call statement types. The content portion of the statement is unused, though it is recommended to list parameter information here if you are writing a procedure that accepts passed parameters
--^	Branch To (GOTO)	Label name to branch to	Unused (Comments if desired)	An unconditional branch to a label (--:). Execution of the script will jump to the line after the named label. A GOTO branch does not support parameter passing or a return point.
-->	Call Procedure (GOSUB)	Label name to call	Procedure parameter list semicolon (;) separated	An unconditional procedure call. Execution will jump to the line after the named label, and a return statement (--<) will return execution to the line after the procedure call. Procedure calls can be nested and called recursively.
--<	Return from Sub	Unused	Unused (Comments if desired)	The return statement returns execution to the most recent procedure call line. Note that the vertical bar is required for the statement to be complete.
--?	Conditional Statement	Condition to be evaluated	True action|False action	The condition will be evaluated and, by default, execution will jump to one of the two indicated branch labels as a GOTO branch (or simply continue to the next line if only a True branch is specified and the result is False). You can make the branch a procedure call by prefixing the label with a > symbol. In this case, you can include a semicolon separated list of parameters. Several other true/false actions are supported. See the --? statement description for details.
--s	Store to Persistent Storage	"settings", "rollvariables", or "stringvariables"	Name of the data set to store (see save/load section below)	This statement type (and the --l statement) still function, but it is recommended to use the storage mechanism in the --~ command instead.
--l	Load from Persistent Storage	"settings", "rollvariables", or "stringvariables"	Name of the data set to store (see save/load section below)	This statement type (and the --s statement) still function, but it is recommended to use the storage mechanism in the --~ command instead.
--v	Create Visual Effect	"token", "betweentokens", or "point"	Tokens and parameters for generating the effect	Visual effects are played on the page the token is on. "point" effects require Version 1.2.8+
--a	Play Audio Track	Unused	Jukebox track name (case sensitive)	Plays an audio track by name from the Roll20 jukebox. Requires v1.5.2+
--e	Echo to Chat	Name to send chat command as	Chat message to send	Variable substitution takes place on the tag and content.
--R	Retrieve Repeating Section Row information	"find", "first", "next", "byindex", "bysectionid", "dump"	Parameters for retrieving row information. See Referencing below	Working with repeating section information on character sheets is possible without tracking row indexes ($0, $1, etc.) by using the --R statements.
--~	Assign a variable to the result of a built-in function	Variable Name	Parameters for function call	ScriptCards includes a number of built-in functions for things like measuring distance, manipulating strings, etc. The type of variable that gets set (Roll or String) is dependent upon the function that is being called.
--c	Case Statement	Test Value	Vertical bar separated list of cases, with the match:branchlabel format.	Branch labels can be procedure calls by prefixing them with ">", and can contain parameters.
--i	Information Request	User Prompt;Button Caption	InfoType;VariableName;ParameterText	See full documentation below.
--d	Data Statement	! for data definition or StringVar for data read	For definition lines, a semicolon separated list of data elements. Unused to read lines.	Similar to BASIC read/data statements. --d! defines string data elements anywhere in your code. --dvarName reads the next data element into varName.
--%	For...Next Loop	Loop Counter for "For", empty for "Next"	For "For", Start;End;Step, empty for Next	See For...Next Loop documentation below. Allows you to create loops that will run a specified number of times with a loop counter.
--*	GM Output	Free Text - Is output in bold at start of the line.	Output in normal text after Tag	GM Output statements are whispered to the GM as a separate card after the output of the main card is completed. Their use is identical to the Direct Output statement (--+). If there are no GM Output statements in a card, no GM card will be whispered.
--!	Object Modification	<objectType>:<objectId>	setting:value|setting:value...	Set properties of tokens/characters or character attributes (v1.5.0+ required)
--X	Exit Script	none	none	End script processing and exit the script.

ScriptCard Statement Type Details

The sections below detail the individual statement types supported by ScriptCards

Comment (--/)

A --/ statement is ignored by the ScriptCards parser. You can use this type of statement to add comments and informational text to your script.

  --/|[Comment Text]

Example:

!script {{
  --/|Script Name : Fireball
  --/|Purpose     : Allow the player to cast a fireball and blow stuff up!
  .
  .
  .
}}

Console Log (--\)

A --\ statement will ignore the tag portion of the statement and output the content portion of the statement to the API console log, including variable substitution.

  --\|[Log Text]

Example:

!script {{
  --\|The value of Roll is [$Roll]
}}

Set Parameter (--#)

A --# statement sets parameters used by ScriptCards when the card output is built. These include things like the title of the card, the background colors used for various portions of the card, the content of the left and right subtitle blocks, the tokens displayed in the emote (if any), the emote text, etc. A full list of these setting values is included below.

  --#<ParameterName>|[Parameter Value]

For settings statements, the Tag determines the setting that will be updated, while the Content determines the value that will be stored in that setting.

For global settings, if the same setting is set multiple times in a script, the MOST RECENTLY EXECUTED setting will be what is used when the card output is built. Most settings are "Per-Line", meaning they will only impact output lines generated after the setting is made, and can thus be changed with every line if desired.

Examples:

  --#title|Magic Missile
  --#leftsub|Level 1 Spell
  --#rightsub|Force Damage

The three examples above set the “title”, “leftsub”, and “rightsub” values for the card to the content value for the line.

Content portions can include roll variables (see --= lines below) and can be used multiple times in a macro. The last execution of a setting line will be the one used when the card output is generated. Settings Lines do not produce output lines on the card.

The following link is an image that shows the various sections of a ScriptCard:
https://cdn.discordapp.com/attachments/1034740409580130358/1066948467437617172/SC_Card_Illustrated.png

Parameter Definitions and Details

The following settings are available and are grouped by the section they apply to.
ℹ️   Please Note: Parameter names are not case sensitive.

[Expand/Collapse
Parameters]

Parameter Definitions

Overall/ Admin Settings
Name	Effect/Use	Default Value	Type
hideCard	If set to any non-default value, the entire card output will be suppressed	0	Global
whisper	Comma separated list of who to whisper the output to. Use "gm" for GMs and "self" for the sender	none	Global
showFromForNonWhispers	If set to a non-zero value, will include the sender on cards that aren't whispered	0	Global
reentrant	Used to name a script for re-entrant button use	0	Global
parameterDelimiter	Specify the character sequence used to separate parameters in various calls (defaults is semi-colon (;)) (1.6.7+)	none	Per-Line
executionLimit	Maximum number of script lines the interpreter will try to execute. This prevents "infinite loop" sandbox crashes	40000	Global
deferralCharacter	Changes the meta script deferral sequence to the specified value	^	Per-Line
debug	If set to a non-zero value, will output lots (and LOTS) of information to the API console log about the running script. Useful for troubleshooting.	0	Per-Line
timezone	IANA Specifier for the local time zone, used in system/date functions	America/New_York	Per-Line
overrideTemplate	Allows a user to specify one of the templates provided by Keith Curtis' Supernotes mod, which will cause ScriptCards to ignore most of the visual output settings from this section in favor of the Supernotes template.	none	Global
concatenationCharacter	Changes the character used to identify a concatenation (append) operation from a standard assignment operation.     Example: --#concatenationCharacter|_  --&test|A quick brown fox  --&test|_ jumped over the lazy dog.  --+Output:|[&test]  would display:    Output: A quick brown fox jumped over the lazy dog.	+	Per-Line
Selection Settings
Name	Effect/Use	Default Value	Type
activePage	If set to a page ID, will be used for [*P:] attribute references. The "playerpage" string can be used to retrieve the current player ribbon page.	empty	Per-Line
sourceToken	Token ID of the Source character. Will be displayed in the left portion of the emote area if specified, and will be used for referencing attributes.	None	Per-Line
targetToken	Token ID of the Target character. Will be displayed in the right portion of the emote area if specified, and will be used for referencing attributes.	None	Per-Line
Title Settings
Name	Effect/Use	Default Value	Type
hideTitleCard	If set to any non-default value, the top portion of the card (title and subtitle area) will not be included on the output	0	Global
titleCardBackground	A hex color code representing the background color of the title area.	#1c6ea4	Global
titlecardBackgroundImage	Specify an image (content for a CSS background-image tag) for the title card area     Example: --#titlecardbackground|url('https://s3.amazonaws.com/files.d20.io/images/248538196/c9xft1A2jWNqOkBsxQwyLQ/max.jpg?1633278017'); background-size: 100% 100%; background-repeat: no-repeat;	none	Global
titleFontLineHeight	Line spacing on the title area	1.2em	Global
titleFontFace	Name of the font used on the title area	Contrail One	Global
titleFontSize	Size of the title font	1.2em	Global
titleFontColor	Color of the text on the card title	#FFFFFF	Global
titleCardBottomBorder	Border CSS specifier for the bottom of the title card area	2px solid #444444;	Global
titleCardGradient	If set to non-zero value, will place a vertical gradient on the title card area. Using the SC-Utility script is highly encouraged as it makes setting gradients very easy (along with tons of other benefits).     Example 1: --#titlecardbackgroundimage| linear-gradient( to right, Lavender, MediumPurple, Indigo );     Example 2: --#titlecardbackgroundimage| radial-gradient( ellipse farthest-side at left top, LightGreen, MediumSeaGreen, DarkOliveGreen ).	0	Global
title	Text displayed in the title area of the card	ScriptCards	Global
Subtitle Settings
Name	Effect/Use	Default Value	Type
subtitleFontFace	Name of the font used on the subtitle sections	Tahoma	Global
subtitleFontSize	Size of the subtitle font	13px	Global
subtitleFontColor	Color of the text in the subtitle areas	#FFFFFF	Global
subtitleSeparator	The character(s) that will be placed between leftsub and rightsub	♦	Global
leftSub	Subtitle text. Will be centered if rightsub isn’t specified, otherwise will be offset to the left with a separator between leftsub and rightsub.	None (Empty)	Global
rightSub	Subtitle text. Will be centered if leftsub isn’t specified, otherwise will be offset to the right with a separator between leftsub and rightsub.	None (Empty)	Global
Emote Settings
Name	Effect/Use	Default Value	Type
emoteState	If set to anything other than "visible", the emote portion of the card will not be displayed	visible	Global
emoteBackground	Background color of the emote area	#f5f5ba	Global
emoteFontWeight	Font weight for the font in the emote area	bold	Global
emoteFont	Name of the font used in emote area (above the title of the output card)	font-family: Georgia, serif; font-weight: bold;	Global
emoteFontSize	Size of the font used in the emote area	14px	Global
emoteFontColor	Color of the font in the emote area	None (Empty)	Global
emoteSourceTokenSize	Specify the size of the Source Token image (left side image) in pixels. NOTE: Do not include the "px" on the end like other size settings as the script automatically adds "px" after the number.     Image of example usage: https://cdn.discordapp.com/attachments/855799249366155284/1109262372239056927/sc_tokensizes.png	50	Global
emoteTargetTokenSize	Specify the size of the Target Token image (right side image) in pixels. NOTE: Do not include the "px" on the end like other size settings as the script automatically adds "px" after the number.     Image of example usage: https://cdn.discordapp.com/attachments/855799249366155284/1109262372239056927/sc_tokensizes.png	50	Global
emoteSourceTokenOverride	Specify the URL of the image that will override the avatar that represents the Source Token (left side image) in the emote section, if emoteState is set to display the emote section.	0	Global
emoteTargetTokenOverride	Specify the URL of the image that will override the avatar that represents the Target Token (right side image) in the emote section, if emoteState is set to display the emote section.	0	Global
emoteText	Text to display in the emote portion of the card	None (Empty)	Global
Main Description Settings
Name	Effect/Use	Default Value	Type
evenRowBackground	Hex code for the background color for even rows	#eeeeee	Per-Line
oddRowBackground	Hex code for the background color for odd rows	#d0e4f5	Per-Line
bodyBackgroundImage	Specify an image (content for a CSS background-image tag) for the body area	none	Global
evenRowBackgroundImage	Specify an image (content for a CSS background-image tag) for the even card rows     Example: --#evenRowBackgroundImage|url('https://s3.amazonaws.com/files.d20.io/images/248538196/c9xft1A2jWNqOkBsxQwyLQ/max.jpg?1633278017'); background-size: 100% 100%; background-repeat: no-repeat;	none	Per-Line
oddRowBackgroundImage	Specify an image (content for a CSS background-image tag) for the odd card rows     Example: --#oddRowBackgroundImage|url('https://s3.amazonaws.com/files.d20.io/images/248538196/c9xft1A2jWNqOkBsxQwyLQ/max.jpg?1633278017'); background-size: 100% 100%; background-repeat: no-repeat;	none	Per-Line
LineHeight	Vertical size of each line on the output card	normal	Per-Line
bodyFontFace	Name of the font used in the card rows	Helvetica	Global
bodyFontSize	Size of the text in the card rows	14px	Global
evenRowFontColor	Hex code for the text color for even rows	#000000	Per-Line
oddRowFontColor	Hex code for the text color for odd rows	#000000	Per-Line
tableBGcolor	Background color of the whole card. Normally not visible	#EEEEEE	Global
tableBorder	Color of the border that surrounds the whole card	2px solid #000000;	Global
tableBorderRadius	CSS specifier for how rounded the borders of the output card are. Use "0px;" for square borders	6px;	Global
tableShadow	CSS specifier for the drop shadow under the output card	5px 3px 3px 0px #aaa;	Global
Dice Roll Settings
Name	Effect/Use	Default Value	Type
rollHilightLineHeight	Determines the height of the hilight box placed around roll results (1.4.2+)	1.0em	Per-Line
diceFontSize	Size of the dice created with the [d4] [d6], etc. formatting markers	3.0em	Per-Line
diceFontColor	Color of the dice created with the [d4] [d6], etc. formatting markers	#1C6EA4	Per-Line
rollHilightcolorboth	Background box hilight color if both a 1 and a max on the die are rolled (1.4.4+)	#8FA4D4	Per-Line
rollHilightColorCrit	Background box hilight color if the maximum number on the die was rolled (1.4.4+)	#88CC88	Per-Line
rollHilightColorFumble	Background box hilight color if a 1 was rolled (1.4.4+)	#FFAAAA	Per-Line
rollHilightColorNormal	Background box hilight color if neither a 1 or a max on the die are rolled (1.4.4+)	#FFFEA2	Per-Line
noMinMaxHighlight	If set to anything other than "0", rolls will not display crit/fumble/mixed highlight colors.	0	Per-Line
noRollHighlight	If set to anything other than "0", rolls will not be formatted (plain numbers) but will still get a tooltip with details	0	Per-Line
allowPlainTextInRolls	If set to a non-zero value, plain character text in rolls will be copied to the roll text	0	Per-Line
disableInlineFormatting	If set to a non-zero value, inline formatting (bold, italics, color, text alignment, etc.) will not be performed on --+ lines	0	Per-Line
disableRollProcessing	If set to a non-zero value, --= lines will not process dice rolls strings	0	Per-Line
roundUp	If set to a non-default value, integer division will round up instead of down	0	Per-Line
useHollowDice	If set to a non-zero value, the hollow/outline versions of the dice fonts will be used	0	Per-Line
explodingonesandaces	If set to 1, rerolls on exploding dice will be figured into the Ones and Aces properties of the roll	0	Per-Line
Button Settings
Name	Effect/Use	Default Value	Type
buttonBackground	Background color for buttons created with [button][/button]	#1C6EA4	Per-Line
buttonBackgroundImage	A CSS specifier for a background image to use for buttons (i.e. url(...);)     Example: --#buttonBackgroundImage|url('https://s3.amazonaws.com/files.d20.io/images/248538196/c9xft1A2jWNqOkBsxQwyLQ/max.jpg?1633278017'); background-size: 100% 100%; background-repeat: no-repeat;	empty	Per-Line
buttonFontSize	Text size for captions on buttons created with [button][/button]	x-small	Per-Line
buttonFontFace	Font Family specifier for captions on buttons created with [button][/button]	Tahoma	Per-Line
buttonTextColor	Text color of labels on buttons created with [button][/button]	#FFFFFF	Per-Line
buttonPadding	Set the size of the padding area around buttons	5px	Per-Line
buttonBorderColor	Border (outline) color for buttons created with [button][/button]	#999999	Per-Line

As of ScriptCards 1.6.0, ten user settings (usersetting0 thru usersetting9) are now available. These settings are not used by ScriptCards but are available for script author use. These settings are stored with setting set (--Ssettings and --Lsettings).

Settings Lines (--#) do not produce output lines on the card </div>

Direct Output (--+)

A direct output line(--+) that displays a line of content on the ScriptCard. It can be a simple line of text with a Tag/Content pair, or it can include Roll Variable references and inline formatting. The Tag can be blank (the | is still required). If a tag is specified, it is output in bold at the beginning of the line followed by the content.

  --+[Bolded Text Output]|[Text Output]

Examples of Direct Output lines:

  --+Hello|World
  --+Attack|The monster rolls [$Attack] to hit!
  --+Damage|@{target|token_name} is hit for [$Damage] [#3333AA][b]frost[/b][/#] damage.

Direct Output lines support inline formatting, roll variable replacement, character attribute references, and procedure variables.

GM Output (--*)

A GM Output line--* is identical to a direct output line(--+), except that it will be sent on a separate card that is only visible to GMs.

  --*[Bolded Text Output]|[Text Output]

Example:

  --+PlayerLine|This line is shown on the public card
  --*GMLine|This line will only be shown to GMs, on a separate card.

Roll Variable Assignment (--=)

See the Variables section for more information on Roll Variables

In ScriptCards, when you want to roll dice you need to store the result of the roll into a Roll Variable. This is done by specifying the name of the Roll Variable as the Tag, and the roll text as the Content of the line.

  --=<Roll Variable Name>|[Roll Component] [Roll Component] ...

All components of a roll equation should be separated with spaces.

Examples:

  --=MissileDamage|1d4 + 1
  --=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]

In these examples, the MissileDamage Roll Variable will be set to the result of rolling 1d4 and adding 1. The Attack Roll Variable will roll 1d20, add the selected character’s strength modifier and proficiency bonus (assuming D&D 5E) and store that value into the variable.

Adding Flavor Text to Rolls

Text enclosed in square brackets [ ]'s is considered "flavor text" and will be added to the result text but does not impact the roll result. You can also think of this as a method for labeling parts of more complex rolls. The roll will appear normally in the chat message but when someone hovers over the result with their mouse, the pop up will provide the flavor text entered. Be aware that if the labeled result is used in a subsequent roll the label will be lost, so the flavor text/ labeling should only be added to a roll variable right before it's displayed.

Example 1:

!script{{
  --=ForceRoll| 1d8 [Force Damage]
  --=PainRoll| 1d4 [Pain]
  --=BleedRoll| 1d6 [Bleeding]
  --+| [$ForceRoll] [$PainRoll] [$BleedRoll]
}}

The result of running Example 1 would be something like this:

6 3 4

(Hover your mouse over each result to see the flavor text labels.)

Example 2:

!script{{
  --=AthleticsBonus| @{selected|athletics_bonus} [Athletics]
  --=AcrobaticsBonus| @{selected|acrobatics_bonus} [Acrobatics]
  --=SkillBonus| [$AthleticsBonus] + [$AcrobaticsBonus]
  --+| Athletics Bonus: [$AthleticsBonus]  Acrobatics Bonus: [$AcrobaticsBonus]  Skill Bonus: [$SkillBonus]
}}

The result of running Example 2 would be something like this:

Athletics Bonus: 2 Acrobatics Bonus: 1 Skill Bonus: 3

Hovering your mouse over each result, you can see that the Athletics and Acrobatics flavor text is available, but that it didn't carry through to the Skill Bonus where they were added together. If you want the Skill Bonus to display the flavor text, you'd want to do something like example 3.

Example 3:

!script{{
  --=AthleticsBonus| @{selected|athletics_bonus} [Athletics]
  --=AcrobaticsBonus| @{selected|acrobatics_bonus} [Acrobatics]
  --=SkillBonus| [$AthleticsBonus] [Athletics] + [$AcrobaticsBonus] [Acrobatics]
  --+| Athletics Bonus: [$AthleticsBonus]  Acrobatics Bonus: [$AcrobaticsBonus]  Skill Bonus: [$SkillBonus]
}}

The result of running Example 3 would be something like this:

Athletics Bonus: 2 Acrobatics Bonus: 1 Skill Bonus: 3

Hovering over each result, you can see that now the Skill Bonus has flavor text identifying the components that make up the total.

Customizing Dice Rolls

The following dice formats are supported:

Format Pattern	Example	Description
XdY	3d8	Simple format. Roll a Y-sided die X times
XdYkhZ	2d20kh1	Roll Y-sided die X times and keep the highest Z number of dice
XdYklZ	4d6kl3	Roll Y-sided die X times and keep the lowest Z number of dice
XdY>Z	5d6>3	Roll Y-sided die X times and count a 1 for each roll greater than Z
XdY<Z	5d6<3	Roll Y-sided die X times and count a 1 for each roll less than Z
XdYr<Q and XdYr>Q	10d6r<2	Roll a Y-sided die X times, rerolling results less than or equal (or greater than or equal to) to Q
XdYro<Q and XdYro>Q	10d6ro<2	Roll a Y-sided die X times, rerolling results less than or equal (or greater than or equal to) to Q one time, keeping the reroll result
XdY! and XdY!>Q and XdY!<Q	8d6!	Roll a Y-sided die X times, rerolling max results and adding them to the total for the die (or rerolling results >= or <= Q and adding (Exploding dice)
XdYkhZr<Q and XdYkhZr>Q	4d6kh3r<1	Roll a Y-sided die X times, rerolling results less than or equal to (or greater than or equal to) Q, and keep the highest Z results
XdY!h and XdY!l	4d6!h	Roll 1dY X times. If the max number on the dice is rolled, roll it again and add to that die's total. Return only the highest (h) or lowest (l) die roll (Deadlands skill checks).
XdF	4dF	Fudge dice support. Roll a Fudge die X times, with possible values of +, -, or blank. Roll hover text and .Text will display the values appropriately.
XdYW, XdYWS, XdYWH, XdYWSH	4d6W	Wild dice support (as seen in games like d6 system). X-1 dice of Y sides will be rolled normally. 1 die of Y sides will be rolled as an exploding die. If the "S" modifier is specified, the Wild die will eliminate itself from the total if the first roll on it is a 1. If the H modifier is included, a 1 on the initial Wild die will remove the highest die amongst the non-wild dice. None, one, or both can be specified.
XuY	3u8	Roll a Y-sided die X times, but only generate unique values. If X is greater than Y, only Y dice will be rolled.
XmY	3m8	Roll a Y-sided die X times, but always use this highest number on the die. Ex: 3m8 will always roll 24.

(Note: As of writing this (v 1.7.7 and likely previous versions too), Y cannot equal 0. The result of rolling Xd0 is the error "NaN" where the result should be.)

Using Dice Rolls in Equations

The following operators are supported in a roll equation:

Operator	Operation
+	Addition
-	Subtraction
*	Multiplication
/	Division
\	Integer Division (Rounds down)
%	Modulo (Remainder of Divison)

Roll Modifiers

Roll Variables can be accessed at any time after they have been created by using the [$VariableName] format, with the optional modifiers in the following table. Please note that Roll modifiers are case sensitive. Also, Roll Modifiers will remove any flavor text that was included with the original roll assignment.

Modifier	Meaning
No modifier	In a Direct Output Line (--+) will be replaced with a formatted roll display, including a mouseover with roll text details. In any other type of line, will display the same results as .Total
.Total	The end result of the roll equation as an unformatted number
.Base	The cumulative result of any dice rolled in the Roll Text (Numeric modifiers are not included)
.Ones	The number of dice in the roll that came up as 1s
.Aces	The number of dice in the roll that came up as the maximum number on the die
.Odds	The number of dice in the roll that came up with an odd number
.Evens	The number of dice in the roll that came up with an even number
.RollText	The raw text of the roll that was use to generate the results
.Text	A text representation of the results of the roll, including the numbers rolled for each die
.tableEntryText	The text portion of the result of a table roll
.tableEntryImgURL	The image source portion of the result of a table roll
.tableEntryValue	Numeric value of tableEntryText (via parseInt). If a non-numeric value, will be 0
.Raw	The total numeric result without any formatting, even if placed somewhere formatting would normally be done.
.RollCount	The total number of actual dice rolled to make up the roll calculation. If multiple dice are rolled in a single roll set, the results of each die will be counted. ***v1.7.0***
.RolledDice(x)	A 1-based "array" of the dice rolled during a roll assignment. If multiple dice are rolled (ie, 1d20 + 1d4) the results of all of the die rolls will be concatenated into the array. ***v1.7.0***
.KeptCount	The number of dice rolled that have not been eliminated by a KH or KL clause. If the roll does not contain a KH or KL clause, this will be the same as RollCount. ***v1.7.0***
.KeptDice(x)	A 1-based "array" of the rolled dice that were kept after processing a KH or KL clause. It the roll does not contain a KH or KL clause, all of the rolled dice will be included. ***v1.7.0***
.DroppedCount	The number of dice dropped from the roll due to a KH or KL clause. If the roll does not contains a KH or KL clause, DroppedCount will be 0. ***v1.7.0***
.DroppedDice(x)	A 1-based "array" of the rolled dice that were dropped from the total after processing a KH or KL clause. If the roll does not contain a KH or KL clause, no dice will be added. ***v1.7.0***

Examples:

  --+Total Damage|[$MissileDamage.Total] (roll was 1d4+1)
  --+Base Damage|[$MissileDamage.Base]  (without the +1)
  --=Attack|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF] + [$BlessBonus] [Bless]

In this case, 1d4 will be rolled and stored in “BlessBonus”, which can then be used in the Attack line.

Mathematical Functions in Roll Expressions

The ScriptCards roll parser works from left to right, always maintaining a current value and applying whatever comes next to the total. The functions here below can be added to a roll expression:

Expression	Meaning
{ABS}	Absolute Value
{CEIL}	Ceiling value (round up to the next whole number)
{FLOOR}	Floor value (round down to the next whole number)
{ROUND}	Round value (round up if the decimal portion is greater than 0.5, otherwise round down)
{ROUND:X}	Round value to X decimal places (round up if the decimal portion is greater than 0.5, otherwise round down)
{NEGATE}	Multiply the value by negative one.
{SQRT}	Take the square root of the running value.
{SQUARE}	Square the running value.
{CUBEROOT}	Take the cube root of the running value.
{CUBE}	Cube the running value.
{SIN}	Return the SIN of running value.
{COS}	Return the COS of running value.
{TAN}	Return the TAN of running value.
{ASIN}	Return the ASIN of running value.
{ACOS}	Return the ACOS of running value.
{ATAN}	Return the ATAN of running value.
{MAX:X}	Caps the running value at X. (v1.4.12)
{MIN:X}	If the running value is less than X, set the value to X.
{CLAMP:X:Y}	Adjust the running value to remain between X (lower bound) and Y (upper bound)
{PAD:X}	Whenever the .Raw or .Total (same as no suffix) gets displayed, leading zeros will be added to the number to make it at least X digits long (ex. {PAD:3} would result in 5 being displayed as 005). Note that this can have a negative impact on conditional statements if they are being used as string comparisons instead of numeric comparisons.

Here are the syntax rules when using the above listed functions:

Example 1.

!script {{
  --=output|2.9 {FLOOR}
  --+output|[$output]
}}

The output from this example is "2".

Example 2.

!script {{
  --=output|2.9 {FLOOR} {NEGATE} - 3
  --+output|[$output]
}}

The output from this example is "-5".

Basically, a function will use as its input whatever the current "running total" is. Please note that there must always be a space between the function expression and its input. For example, "2.9 {FLOOR}" will work, but "2.9{FLOOR}" will not work.

Rolling on Rollable Tables

You can also roll on a rollable table using the expression [T#tablename], where tablename is the case-sensitive name of the table in your game. Proper weighting for each entry in the table is taken into account when rolling on rollable tables. The .tableEntryText and .tableEntryImgURL properties of the Roll Variable will be set to the matching values on the resultant table entry.

Example:
Note: To see this script in action, you'll first need to create a new rollable table named "FruitTable" in your list of Roll Tables, and then add a couple entries of fruit with images for each. For the entry names, use the fruit name or a brief description of the fruit. Add an image to each entry that represents the fruit. With the rollable table setup complete you can use the following script to randomly select and display a fruit, along with its image, from the table.

!script{{
--=Fruit|[T#FruitTable]
--&fruitText|[$Fruit.tableEntryText]
--&fruitImg|[$Fruit.tableEntryImgURL]
--+|[img width=32][&fruitImg][/img] [&fruitText]
}}

Special Notes about Dice Rolls

(READ THIS!): In order to support the ability to include Roll Variable values in rolls, ScriptCards does not use the built-in Roll20 dice rolling engine, and does not support “inline rolls” (rolls included with [[ ]] in the card). Because I have included my own roll parser, there may be some odd roll methods that are not currently implemented. If you run into dice roll options that don’t work, please let me know and I’ll try to support them.

Special Notes Update: As of version 1.2.3, inline rolls will be parsed by ScriptCards, using only the FINAL RESULT of the roll. The components (dice, modifiers, etc.) will not be visible to ScriptCards.

Roll Variable Lines do not produce output lines on the card, so you must use an output line .

String Variable Assignment (--&)

See the Variables-section for more information on String Variables

String variables function in most ways like roll variables, except that they do not attempt to process any dice rolls, and do not have the list of properties that a roll variable has. They are designed to simply contain text. To assign a string variable, use the --& statement:

  --&<String Variable Name>|[+][Content]

Examples:

  --&MyText|Hello
  --&First|Alpha
  --&Last|Omega
  --&Final|[&First] [&Second]
  --&Phrase|The quick brown fox
  --&Phrase|+ jumped over the lazy dog

The first example simply assigns the word "Hello" to the MyText string variable. The second and third examples similarly assign "Alpha" and "Omega" to the First and Last string variables. The fourth example uses string variable referencing to set the value of Final to what is in First, a space, and what is in Last, resulting in "Alpha Omega" being in Final.

The last two examples demonstrate using the "+" modifier to add text to an existing string variable. Phrase is initially set to "The quick brown fox", and then " jumps over the lazy dog" is added to it because the first character of the content is a "+" symbol, indicating that the content should be added to the variable instead of replacing it.

As indicated in the fourth example above, string variables are referenced using the syntax [&variablename]

Call Mod (--@)

ScriptCards can use a Call API instruction to execute other Mod commands. The Tag contains the Mod command to use (alter, or roll20AM, for example - do not include the !) The content portion of the statement contains the parameters that are passed to the API script. Because the -- sequence can't be used here, an underscore (_) at the beginning of the line or preceded by a space is replaced with -- before the Mod command is executed.

Examples:

  --@eh|list
  --@alter|_target|@{target|token_id} _bar|3 _amount|-[$Damage]

In the first example above, the command !eh list will be executed, calling EncounterHelper. In the second, AlterBars^(Forum) is called to modify a token's Bar 3 value.

Note: When ScriptCards (or any Mod script) runs other Mod script commands, there is not an associated player attached to the executed command. This means that the script being called won't know if the person running the ScriptCard is, for example, a GM. The most common instance of this is when calling !token-mod and trying to use --ids instead of acting on selected tokens. Since this is an ability normally limited to GMs, you need to enable "Players can IDs" (in !token-mod config).

See API:Script Index for more options.

Branching

ScriptCards supports several methods that allow code execution to branch to different parts of the script, rather than only being able to proceed directly through each line of code in the script. Branching relies on the use of Branch Labels --: and then one of several types of statements that evaluate which code branch to execute.

Branch Label (--:)

A branch label defines a line in your code that can be reached by one of the branching instructions (--^, -->, --? or --c). The Tag serves as the label name, and must be unique on the card.

The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment.

Examples:

  --:MyLoop|
  --:CriticalHit|Will jump here if we roll a critical hit!

A Branch Label line does not produce an output line on the card.

Return (--<)

A return instruction marks the end of a Gosub procedure. As long as the branch statement is not a direct branch --^, execution will return to the statement after the one that called the subroutine. The Tag and Content portions are both optional, but the vertical bar separator must be included.

  --<|

Examples:

  --<|
  --<|End of MySub

In both cases, the value of the tag and the content portions of the statement are ignored, but the vertical bar separator must still be present.

Branch (--^)

A Branch line (aka direct branch) jumps execution to the label indicated by the Tag. The vertical bar (|) separator must be present, but the content portion of the line is unused and can be treated as a comment. This type of branch does not directly allow a return statement --< to bring the code execution back to where the branch occurred. If you want the code to be able to return to the original branch point, one of the remaining branch types below should be used instead.

Examples:

  --^MyLoop|Jumps to MyLoop
  --^SkipCrit|We didn't crit, so skip the Crit code

A Branch line does not produce an output line on the card.

Call Procedure (-->)

Similar to a branch, a Call Procedure (sometimes known as a "gosub") line branches execution to the label indicated by the Tag. However, the return pointer of the call will be pushed onto a stack so that a Return instruction (--<) will return execution to the next line in the card. A list of parameters for the subroutine can be passed as the content portion of the tag, and are separated by semicolons (;).

  --><Procedure Label>|[Parameters (Separated by semicolons (;)]

Examples:

  -->FixFormat|#3333FF;#999999

In this example, a label called FixFormat will be branched to as a subroutine, passing the parameters #3333FF and #999999. In the subroutine, these parameters are referenced by number as [%1%] and [%2%].

Conditional Statement (--?)

See the Variables section for more information on Variables

See the Referencing section for information on referencing variable content

Syntax

---

General syntax of conditional statements:

 --?  [Equation used to determine True/False]  |  [Execution path if True] | [Optional Execution path if False]
|  ---  ---  ---  TAG SECTION   ---  ---  ---  |  -----   ----   ----   CONTENT SECTION   ----   ----   ----  |

A conditional statement contains some equation in the Tag that will be evaluated to True/False. If any part of the comparison can/does contain a space, it needs to be surrounded by double quotes. Examples of different equations:

Example 1)  --?[$AttackRoll.Base] -eq 20|
Example 2)  --?"[&Fruit]" -inc "Green grapes"|
Example 3)  --?@{selected|dexterity_mod} -lt 8|
Example 4)  --?@"{targeted|name}" -inc "dwarf"|

Notice the double quotes used in Example 2 and Example 4.  
In Example #2 we have direct evidence that at least one entry in the list will have at least one space, so we enclose the variable and the value we're comparing it against in double quotes.
In Example #4 the targeted creature's name *could* contains spaces.  Since it would be painful to check ahead what creature names might be involved in this script one day, quotes surround the variable and the value we're comparing it against to rule out potential future issues with spaces.

Comparators

---

The following comparison operators are available for use in the equation portion of the syntax to achieve a True/False evaluation:

[Expand/Collapse Comparators]

Comparators

Comparator	Meaning	Works on Numbers	Works on Text	Case Sensitive for Text
-eq	Equal To (Case Sensitive)	Yes	Yes	Yes
-eqi	Equal To (Not Case Sensitive)	Yes	Yes	No
-ne	Not Equal To (Case Sensitive)	Yes	Yes	Yes
-nei	Not Equal To (Not Case Sensitive)	Yes	Yes	No
-ge	Greater Than or Equal To (numeric strings only)	Yes	No	N/A
-lt	Less Than (numeric strings only)	Yes	No	N/A
-le	Less Than or Equal To (numeric strings only)	Yes	No	N/A
-inc	Includes (Not Case Sensitive).	Yes	Yes	No
-ninc	Does Not Include (Not Case Sensitive).	Yes	Yes	No

Branch Types

---

After the equation, there are several types of branching behavior that you can choose from in order to utilize the results of the equation's comparison. Generally speaking, one of two execution paths will be taken, based on the equation returning True or False. These execution paths are detailed in the content section of the statement. The "If True" path is required and is specified first (directly after the vertical bar). The Optional "If False" path is specified after "If True" path, and is also separated by a vertical bar. The details of the different branch types are in the table below, along with examples of syntax.

Example:

  --?[$AttackRoll.Total] -ge [$TargetAC] | Hit     | Miss
     | ---- ----  (Equation)  ----  ---- |If True) |If False)  

The following Branch types can be utilized after the equation to achieve the results you desire. Remember that the False path is optional, which affords an incredible amount of flexibility in how you evaluate conditions and subsequently act on results.

[Expand/Collapse Branch Types]

Branch Types

Branch Format	Meaning
:Label	If just a label is specified, execution will branch to that label when the comparison is matched. NOTE: You cannot use a standard Return (--<|) statement to return to the Conditional (--?) statement if you use the default branch label syntax. Use a >Label synax (below) instead. Example: --?[$AttackRoll.Total] -ge [$TargetAC] |Hit |Miss
>Label	If a label name is preceded by a ">" character, a gosub branch will be performed. In this case, parameters can be passed to the subroutine by separating them from the label and each other with semicolons (;). Parameters that can contain a semicolon (like token/character IDs) should be surrounded by double quotes. Example: --?[$AthleticsRoll.Base] -gt 8 |>AthleticsSuccess;@{selected|athletics} |>AthleticsFailed;@{selected|strength}
=VariableName	The roll variable "VariableName" will be assigned the value following a semicolon (for example, the code "=Roll;1d20" will roll 1d20 and assign the result to a variable named "Roll", if the condition is true). Example: --?@{selected|strength} -le 7 |=StrengthCheck;1d20+@{selected|strength_mod} |=DexCheck;1d20+@{selected|dexterity_mod}+2
&VariableName	The string variable "VariableName" will be assigned the value following a semicolon (for example, the code "&Result;Hit" will assign the value "Hit" to a variable named "Result", if the condition is true). Example: --?@{selected|wisdom} -lt 10 |&fInterpret;You immediately recognize that you won't be able to interpret the sigils without years of study. |&Interpret;It takes some time but you're able to interpret the sigils.
% or %!	The current for...next loop will perform the "next" action (%) or will break out (%!). Will not directly initiate a sub-level loop though. Example: --?[$StrengthCheck.Total] -gt 5 |% |%!
[	Code block Example: (see Code Block section below)
As of ScriptCards v2.1.7+
<	Return from the currently executing subroutine and continue processing the script from the line after the branch that sent the script to this line. Example: --?"[&Fruit]" -eq "Tomato" |<
+Tag;Content	Create a Direct Output line (ie, --+) with the Tag portion in bold and the Content portion in normal text. Example: --?@{selected|strength} -le 4 |+Strength results:;Your strength is not great enough to overcome the boulder |+Strength results:;With some effort you finally wrestle the boulder out of the way.
*Tag;Content	Create a GM-Only Output line (ie, --*) with the Tag portion in bold and the Content portion in normal text. Example:--?@{target|dexterity} -lt 5 |*GM Note:;Player dexterity is much lower than the intended success value of 7.
Fun Fact!	Prior to version 1.2.1, all conditional statements resulted in either a branch to a label statement, or a gosub branch. As of version 1.2.1 additional options for what happens when a condition is matched were added, and 1.2.5 adds further additional functionality.

Additional Examples:

Example 1)  --?[$AttackRoll.Base] -eq 20 |CriticalHit
Example 2)  --?[$AttackRoll.Base] -eq 1 |>Fumble;@{selected|dexterity_mod}
Example 3)  --?"@{target|npc_type}" -inc "undead" |&MonsterType;Undead |&MonsterType;Not Undead
Example 4)  --?[$Attack.Total] -ge [$ArmorClass] |>Hit |>Miss

Example 1: If the Base value of AttackRoll is a 20 (natural 20 on the die) execution will branch to the CriticalHit label, otherwise the execution will proceed directly to the next line of the script.
Example 2: If the Base value of the AttackRoll is 1 a gosub branch will be executed to the "Fumble" label, and passed the value of the selected character's dexterity_mod as parameter [%1%].
Example 3: If the npc_type attribute of the targeted character is "undead", the MonsterType string variable will be set to "Undead", otherwise it will be set to "Not Undead".
Example 4: Calls the "Hit" procedure on a hit and the "Miss" procedure on a miss and return execution to the next line after the procedure calls were finished.

Text that does (or could) contain a space should be enclosed in double quotes.

Multi-part Conditionals

---

Multi-part conditionals are supported with -and and -or as separators. For example:

--?[$Attack.Total] -ge @{target|npc_ac} -and [$Attack.Base] -ne 20|HitButNotCrit

Multi-part conditionals are evaluated from left to right, and each evaluation is either ANDed or ORed with the current cumulative state. This means that (assuming "true" and "false" are actually conditional expressions that evaluate to either true or false):

true AND false OR true

Will be evaluated as true. The first two (true and false) will be false, but then false OR true will be true.

Conversely:

true or false and false

Will be false, because the first true and false will evaluate to true, and then true and false will be false.

Code Blocks

A new feature (1.2.7), code block allow you to treat a group of statements as a single unit based on a condition. This is similar to begin...end or curly braces in some languages, though a bit more limited. As part of the true or false execution branch of a conditional, you can use the "[" character to begin a code block.

If that execution path is taken, the code in the block will be executed. Otherwise, the code in the block will be skipped. Blocks are completed with the --]| statement, and can optionally include an "else" block by using --]|[ as the block terminator. Here is an example:

!script {{
  --=Roll|1d2
  --+Roll|[$Roll]
  --?[$Roll.Total] -eq 2|[
    --&Value|Yep!
    --+|We are inside the TRUE portion of the block
  --]|[
    --&Value|Nope
    --+|We are inside the FALSE portion of the block
  --]|
  --+After|the blocks!
  --+Value|[&Value]
}}

In this case, we begin by rolling 1d2 and then use a conditional to see if the result is 2. if it is, we execute everything inside the code block that begins on the conditional line, up until the end of the block marked with --]|[ because we have an "else" block. The else block is terminated with --]|.

At this time, blocks cannot be nested, and can only be created as part of a conditional (--[ is not a valid statement type)

A conditional statement does not produce a line of output on the card.

Case Statement (--c)

For more information related to Case statements check out the sections on Variables and Referencing

The case statement (--c) allows you to specify a value to test as the tag and a list of possible matches. These matches are case-insensitive. Matching groups are separated with vertical bars and matches and their branch labels are separated by a colon (:). It is also allowable to use Roll Variable or String Variable assignment syntax instead of a branch label, just as with the --? statement. If none of the values are matches, the script will simply proceed onto the next line. Both direct and procedure branches are supported, and procedure branches can include parameters as normal.

Example 1:

!script {{
    --#title|Case Statement Testing
    --=Roll|1d4
    --C[$Roll.Total]|1:>One;[$Roll]|2:>Two;[$Roll]|3:>Three;[$Roll]|4:>Four;[$Roll]
    --X|

    --:One|  --+Value|was One ([%1%])  --<|
    --:Two|  --+Value|was Two ([%1%])  --<|
    --:Three|  --+Value|was Three ([%1%])  --<|
    --:Four|  --+Value|was Four ([%1%])  --<|
}}

This script uses the value of [$Roll.Total] and compares it against 1, 2, 3, and 4, using a gosub branch to the matching value. The first match test is 1:>One;[$Roll], where 1 is the value being matched, followed by a procedure branch to One which gets the Roll roll variable as a parameter. As a further example, the case statement below uses the value of a roll query to assign a Roll Variable based on the query result:

Example 2:

--c?{Difficulty|10|20|30|40}|10:=BonusHealing;0|20:=BonusHealing;10|30:=BonusHealing;30|40:=BonusHealing;50

The $BonusHealing variable will then contain either 0, 10, 30, or 50 depending upon the user's choice.

Using this syntax, the first example in this section (Example 1) could be rewritten as:

!script {{
    --#title|Case Statement Testing
    --=Roll|1d4
    --C[$Roll.Total]|1:&Result;One|2:&Result;Two|3:&Result;Three|4:&Result;Four
    --+Value|was [&Result] ([$Roll.Raw])
}}

Instead of branching to various section labels, this revised example assigns the string variable &Result to "One", "Two", "Three", or "Four", depending on the output of the roll, and displays it along with the $Roll itself.

Save and Load: Persistent Data Storage (--s) and (--l)

 

Original Method of Saving and Loading

[Expand/Collapse Save & Load Info]

Details on Save & Load Commands

Command to Save (--s)	Command to Load (--l)	Notes
--Ssettings Lines starting with --#	--Lsettings Lines starting with --#	Saving Settings (--Ssettings) (--Lsettings), will save the --# lines that are used throughout a Scriptcards script. A great use for saving Settings is to create "templates" for the appearance and layout of various Cards saving the trouble of having to remember or keep notes nearby that document your favorite combinations of layouts, sizes, colors, fonts, etc. Make sure to keep a separate backup, just in case something happens to the Roll20 servers or website that causes the stored settings to become lost or corrupted. This particular storage command works by identifying any Settings (aka parameters) that are overridden from the default base values and captures the setting name and the updated value, saving that information under whatever name you assign in the tag section part of the command. For Example: Let's say you changed the title and subtitle by putting --#title|NewTitle and --#rsub|New Right-side Subtitle. To store this to use as a "template" you would add --sSettings|newTitle1 (newTitle1 is just for the example, you can name it anything that makes sense for you). Then in any different script, to recall the "template" you would put --lSettings|newTitle1 near the beginning of your script. When loading Settings, all stored settings will be applied to the current card settings. You can override settings by changing them after the load, meaning that if you then put another title parameter line that says --#title|Different_Title_Than_Template after loading settings with a --L line, you will override the "template" you loaded initially with the "Different_Title_Than_Template" title that comes after the load statement. ✅   Tip:  For best results, you should put the Save command on a line after all the settings are updated to what you want. You should put the Load command early in the script, ideally within the first few lines. For more information on Parameters (aka Settings), please check this article in the wiki: Parameters (--#)
--SrollVariables Lines starting with --=	--LrollVariables Lines starting with --=	When Roll Variables are saved, all roll variables that exist in the currently executing script will be saved under the name listed in the tag section of the command. When loading roll variables, the saved variables will be appended to any variables already on the current card. Loaded variables will overwrite any existing variables that have the same name as variables already defined in the scriptcard that the variables are loaded to). This means it is safe to create roll variables before the load statement. For more information on Roll Variables, please check this article in the wiki: Roll Variables (--#)
--SstringVariables Lines starting with --&	--LstringVariables Lines starting with --&	When String Variables are saved, all string variables that exist in the currently executing script will be saved under the name listed in the tag section of the command. When loading string variables, the saved variables will be appended to any variables already on the current card. Loaded variables will overwrite any existing variables that have the same name as variables already defined in the scriptcard that the variables are loaded to). This means it is safe to create roll variables before the load statement. For more information on String Variables, please check this article in the wiki: String Variables (--&)

Examples of Syntax

---

--Ssettings|GreenStyle
--Srollvariables|FirstCardVars
--Sstringvariables|FirstCardStringVars

--Lsettings|GreenStyle
--Lrollvariables|FirstCardVars
--Lstringvariables|FirstCardStringVars

!sc-liststoredsettings

Practical Application Examples

---

!scriptcard {{
  --#titlecardbackground|#22CC22
  --#oddrowbackground|#cceecc
  --#evenrowbackground|#99ee99
  --Ssettings|@{selected|token_name}
}}

--Lsettings|@{selected|token_name}

Enhanced methods of Saving and Loading data

As of Scriptcards version 2.6.0 saving and loading data to persistent storage has received an update that provides expanded functionality. In order to tap into the expanded functionality you must:

Saving data still begins with --s and Loading data still begins with --l; but with the expanded functionality, various data types can be specified with their respective symbols. All data will be saved to the mule character ScriptCards_Storage, so you can manage or review the stored data by reviewing the storage character sheet. Items stored in this way are stored in attributes on the Storage character. You can transmog this character into other games as needed and all of your stored data will be preserved.

Syntax: --s(symbol)[optional prefix]|[Optional list of items to save, separated by semicolons (;)]

[Expand/Collapse Save & Load Info]

Details of expanded Save & Load Commands

Command to Save (--s)	Command to Load (--l)	Attribute Prefix	Notes
--s$	--l$	SCR_	This is for saving and loading Roll Variables.
--s&	--l&	SCS_	This is for saving and loading String Variables.
--s@	--l@	SCA_	This is for saving and loading Arrays.
--s:	--l:	SCH_	This is for saving and loading Hash Tables Note: Hash Tables are newly introduced in update 2.6.0
--s#	--l#	SCT_	This is for saving and loading ScriptCards Settings

Examples of Syntax

---

!script{{
--=MyFirstRoll|1d20
--=MySecondRoll|1d10
--=MyThirdRoll|1d5
--=Number1|1d3
--=Number2|1d3
--=Number3|1d3
--s$|MyFirstRoll;MySecondRoll;Number3
}}

This example shows how to save selected roll variables from within a script. Three variables are saved: MyFirstRoll, MySecondRoll; Number3.
❗  Important:  The normal variable referencing is not used (i.e. [$MyFirstString]) as this would be replaced with the actual value of MyFirstString. We need to refer to the variable name itself.

The optional prefix can be used to store multiple variables with the same name - perhaps for different characters, scripts, etc.

--s&fred|charactername

Would store the variable on the character sheet in an attribute named "SCS_fred-charactername", while leaving the prefix off would store the variable as "SCS_-charactername". The various variable types have their own "SC" prefix, so different variable types with the same name won't collide. Ex. "SCS_-attack" is a string variable called attack, while "SCR_-attack" is a roll variable.

The types are:

SCR_ - Roll Variable

SCS_ - String Variable

SCA_ - Array

SCH_ - Hash Table

SCT_ - ScriptCards Setting

Visual Effects (--v)

The --v statement allows you to create visual effects on the VTT. The tag portion of the statement (before the |) specifies the location of the effect. The standard statement format for --v is:

  --v<Location Specifier>|< X Y | Token_ID | Token_ID Token_ID> <Effect Specifier> [moveall]

Location Specifiers

There are three potential location specifiers, each of which requires a different number/type of parameters, which are passed in the content portion of the command:

Location Specifier	Effect Location	Effect Types	Notes
point	X and Y Coordinate on the map specified by first two parameters of content	bomb, bubbling, burn, burst, explosion, glow, nova, ping* and custom**	Upper left corner of the map is 0 0
token	The center point of a specified token (by Token ID)	bomb, bubbling, burn, burst, explosion, glow, nova, ping* and custom**	None
betweentokens	Used for line-stlye effects. Two Token IDs are required	beam, breath, missile, splatter and custom**	First token will be the effect source, and second token determined the direction

(* see notes on the ping specifier below) (** Custom effects can be created in the Roll20 VTT and their names can be used as specifiers for effects)

Effect Specifiers

Roll20 provides 11 pre-defined effect types and 11 pre-defined effect colors. An effect specifier is comprised of a type, followed by a dash (-), followed by the color:

  burst-fire
  explosion-magic
  breath-acid

Available effect types: beam*, bomb, breath*, bubbling, burn, burst, explosion, glow, missile*, nova, splatter*

 (* These effects are line/direction based and only function with the betweentokens location specifier)

Available effect colors: acid, blood, charm, death, fire, frost, holy, magic, slime, smoke, water

Note: Effect types and colors are case sensitive (all lower case).

Examples:

  --vpoint|250 250 explosion-magic
  --vtoken|@{selected|token_id} nova-water
  --vbetweentokens|@{selected|token_id} @{target|token_id} beam-acid

Pings

As of version 2.0.0, it is now possible to use "ping" as a special type of effect specifier. When used, the VTT will ping the given location (either an X/Y coordinate or the center point of a given Token_ID). This is the same effect that users can create by holding down their mouse button at a location on the map. It is also possible to specify the "moveall" modifier at the end of the command to re-center all player's views on the pinged location.

Examples:

  --vtoken|@{selected|token_id} ping
  --vpoint|150 150 ping moveall

Audio Effects (--a)

The --a statement plays an audio track from your Roll20 jukebox by name. The content value of the statement specifies the case-sensitive name of the track to play. If the jukebox track does not exist, no sound will be played, and a warning will be output to the API console log indicating the missing track.

  --a|< Jukebox Track Name>

Example:

  --a|SwordHitSound
  --a|Woodland_Exploration_Ambient

No external APIs are required.

Echo to Chat (--e)

The echo statement is simply a call to the API's sendChat command, using the tag as the speakingAs parameter and the content as the text to send.

  --e[Speaking As]|[ Text to Speak ]

Example:

  --eThe Ghost|/em hovers around @{selected|character_name}... BOO!

Would output "The Ghost hovers around (charactername)... BOO!" as an emote to chat. This will happen whether or not you have a character named "The Ghost" in your journal or not (roll20 sees this message as coming from the API, not from a player or a character).

Whispering

You can use the echo statement to send a whisper, but there's a trick to it. If you execute this code here:

--eThe Ghost|/w ExamplePlayerName Boo.

Then the player named "ExamplePlayerName" would see on his screen a whisper from "The Ghost" that says "Boo."... but you would not see anything on your screen! And you wont see anything on your screen no matter what you try to replace "The Ghost" with... not even if you try to use "GM" or your own player name. Because, again, roll20 sees the message as coming from the API, not from a player or a character.

So, in conclusion, it's best to use something like this when you're sending a whisper:

!script {{
  --#hidecard|1
  --&sender|The Ghost
  --&receiver|ExamplePlayerName
  --&message|Boo.
  --e[&sender]|/w [&receiver] [&message]
  --eScriptCards|/w gm **Whispered from [&sender] to [&receiver]:** [&message] 
}}

This will ensure that the message appears in your chat feed as well.

Repeating Section Access (--R)

See the Referencing-section for information on referencing repeating section content

Roll20 provides a mechanism for character sheet authors to allow for entries for data types that can be repeated on the same sheet via Repeating Section rows (ex, weapons, actions, inventory, etc.) Repeating sections can potentially be one of the most complicated and confusing Roll20 systems to work with, and ScriptCards tries to streamline this process via the --R statement type.

  --r<subcommand>|<parameters>

In the examples below, the following terms will be used:

• Sub Command - This specifies exactly what you want the --R command to do
• Character_Id - Refers to the internal ID associated with a character. One method for retrieving the ID is @{selected|character_id}
• Section Prefix - Repeating sections each have a prefix name associated with the section. For example, in the D&D 5E by Roll20 sheet, repeating_attack is the section prefix for the portion of the player character sheet that contains any defined attack options. For NPCs, repeating_npcaction is the section prefix for NPC Actions. Note that these will be character sheet specific.
• Repeating Row - A repeating section can contain 0 or more rows. Each row contains all of the information for a given entry in the section.
• Row Index - Rows in a repeating section are numbered starting at 0, and often referenced in the chat window as @{selected|repeating_attack_$0_atkname} or something similar. The 0 in this case represents the index of the first row in the section.
• Field - A repeating section row consists of any number of fields, specifying entries like name, damage, range, and the like.
• SearchText - Represents a string that you will be looking for in a field.

Working with Repeating Section data
ScriptCards handles repeating sections by loading a single row from a single repeating section into memory at a time and then allowing you to reference the fields associated with that row. You can move through the rows in a section sequentially, by index, or by searching for a particular item.

There are several subcommands available when using the --R statement:

Sub Command	Parameters	Description
first	Character_Id;Section Prefix	Loads the first row from the repeating section defined by Section Prefix into memory
next	none	Loads the next row from the current section into memory (used after --Rfirst)
find	Character_Id;SearchText;Section Prefix;Field	Searches the "Section Prefix" repeating section looking for "SearchText" in the field named "Field" and loads the matching row into memory
byindex	Character_id;Section Prefix;Index	Loads the entry matching "Index" from the Section Prefix repeating row into memory
bysectionid	Character_id;Section Prefix;Section ID	Loads the entry matching "Section ID" from the Section Prefix repeating row into memory. Section IDs are standard Roll20 strings, and may be referenced from other repeating sections. For example, the 5E sheet's repeating_attacks have an itemid attribute that refers to the repeating_inventory list.
dump	none	Outputs all of the available fields for the loaded repeating section row to the Mod Scripts console for debugging or research

Examples:

---

Example 1:

  --Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname

Will look at the character's repeating_attack section for an entry with an atkname value equal to "Greatsword".

---

Example 2:

--Rfind|@{selected|character_id};Bite;repeating_npcaction;name

Will look for a "Bite" action on the character's repeating_npcaction list.

---

Example 3:

  --Rfirst|@{selected|character_id};repeating_attack

Would load the character's first repeating_attack row into memory.

---

Example 4:

--Rnext|

No parameters are required for --Rnext, which loads the next entry in the list that was obtained with "first" into memory.

---

Example 5:

  --Rbyindex|@{selected|character_id};repeating_attack;4

Loads the character's 5th repeating_attack entry into memory. (NOTE: index numbers start at 0 to match Roll20's $X numbering system.)

---

Section prefixes and how to use them
To see the complete list of the section prefixes for the "D&D 5E by Roll20" character sheet, as well as a nice explanation for how to use them, please refer to the D&D 5E by Roll20 wiki page that includes a section of info on repeating sections.

For other character sheets, you will need to view the documentation on those sheets, or examine the character sheet code live through Browser Developer Tools, or go look at the sheet sourcecode if it's available on the character sheet repository.

Additional information

• However a row is obtained, it will be parsed to replace any attribute references (ie, @{level}) with the corresponding character attribute.
• If at any point a valid entry isn't found (find doesn't find something, first doesn't see any rows, or next goes off the end of the list) any attempts to reference the row data will return "NoRepeatingAttributeLoaded".
• You can reference repeating attribute data using the syntax [*R:attributename] syntax (similar to referencing standard character attributes).
  
  

Examples:

Example 1: This example will display the details of the "Greatsword" PC attack:

!script {{
 --Rfind|@{selected|character_id};Greatsword;repeating_attack;atkname
 --+Attack Name|[*R:atkname]
 --+Base Damage|[*R:dmgbase]
}}

Example 2: This example will list all of the actions an NPC can take (just actions, not legendary, etc.)

!script {{
 --#title|NPC Actions
 --#sourcetoken|@{selected|token_id}
 --Rfirst|[*S:character_id];repeating_npcaction
 --?"[*R:name]" -eq "NoRepeatingAttributeLoaded"|END

 --:NPC_Action_Display|
 --+[*R:name]|[*R:description]
 --Rnext|
 --?"[*R:name]" -ne "NoRepeatingAttributeLoaded"|NPC_Action_Display

 --:END|
}}

In the script above, we get the "first" repeating_npcaction and check to make sure it exists (ie, [*R:name] doesn't return "NoRepeatingActionLoaded". As long as we have a valid repeating row, we display the name and description of the action.We then execute "next" and repeat until we run into "NoRepeatingAttributeLoaded", indicating that we have run out of repeating_npcaction rows.

See Repeating Section Values for more information.

Special debugging command: dump

--Rdump|

The "dump" command will list all of the attributes ScriptCards knows about for the currently loaded repeating row to the API Console Log.

Built-In Functions (--~)

ScriptCards has the ability to run a function built into the API script and return the results to a variable by using --~ calls. Some functions return roll variables, while others return strings. Functions are grouped into several different categories. There are a handful of functions without a category, in which case the category is omitted from the call.

General Syntax:

  --~[Variable Name]|[Category];<Function>;[parameter];[parameter]...

Non-Categorized Functions

The following functions do not have categories associated with them, and are called without listing a category.

Syntax:

 --~[Variable Name]|<Function>;[parameter];[parameter]...

Table of Non-Categorized Functions:
[Expand/Collapse
Non-Categorized Functions]

Non-Categorized Functions

Function Name	Parameters	Return Type	Description
distance	token_A_ID;token_B_ID	rollVariable	Calculate the Chebyshev distance in grid units between two tokens. This is the measurement scheme D&D 4E/5E use for diagonal distance measurement
euclideandistance	token_A_ID;token_B_ID	rollVariable	Calculate the Euclidean distance between two tokens. This is essentially the Pythagorean theorem in action. Returns the result in grid units.
euclideanpixel	token_A_ID;token_B_ID	rollVariable	Calculate the Euclidean distance between two tokens and returns the result in pixels instead of grid units.
euclideanlong	token_A_ID;token_B_ID	rollVariable	Calculate the Euclidean distance between two tokens and returns the result in grid units, but the grid unit conversion is performed AFTER the pixel distance isCalculated instead of before. More accurate over long distances.
manhattandistance	token_A_ID;token_B_ID	rollVariable	Also called "taxicabdistance" (which is an acceptable function name), this measures to how-many-over, how-many-up/down distance, disallowing diagonal movement.
getselected	none	stringVariable	Using the variable name in the tag, a series of string variables will be created: VariableNameCount will contain the number of selected tokens. VariableName1 will contain the token ID of he first selected token, VariableName2 the second, etc.

Examples:
This example uses a non-categorized function, returning the HowFarAway roll variable as the result:

--~HowFarAway|distance;@{selected|token_id};@{target|token_id}

Categorized Functions

Most ScriptCards functions are grouped into several major categories. The table below lists the function categories and their sub functions within each category.

Syntax:

  --~[Variable Name]|<Category>;<Function>;[parameter];[parameter]...

Table of Categorized Functions:
[Expand/Collapse
Categorized Functions]

Categorized Functions

Category Name	Function Name	Parameters	Return Type	Description / Example
Categorized Array Functions
array	define	arrayname;value1;value2;...	none	Creates an array called "arrayname" and adds value1, value2, etc. to the array
array	sort	arrayname(;descending-optional)	none	Sorts the specified array in place in ascending order (alphabetically).
array	numericsort	arrayname(;descending-optional)	none	Sorts the specified array in place in ascending order (numerically).
array	add	arrayname;value1;value2;...	none	Adds value1, value2, ... to the existing array "arrayname"
array	remove	arrayname;value1;value2;...	none	Removes value1, value2, ... from the existing array "arrayname". Resets the array index to 0.
array	replace	arrayname;currentvalue;newvalue	none	Replaces all occurrences of "currentvalue" in "arrayname" with "newvalue"
array	setatindex	arrayname;index;newvalue	none	Replaces the array item at index "index" with "newvalue"
array	getindex	arrayname	stringVariable	Retrieves the current index in "arrayname" and stores it in the supplied string variable
array	setindex	arrayname;newindex	none	Sets the current index in array "arrayname" to "newindex"
array	getcurrent	arrayname	stringVariable	Gets the item at the current array index in "arrayname" and returns it as a string variable. Will return "ArrayError" if there is no current item.
array	getnext	arrayname	stringVariable	Increments the current index in "arrayname" and returns the new current value. Will return "ArrayError" if the end of the array is reached.
array	getprevious	arrayname	stringVariable	Decrements the current index in "arrayname" and returns the new current value. Will return "ArrayError" if the the current index was already zero.
array	getfirst	arrayname	stringVariable	Set the current index of "arrayname" to zero and retrieve the current item. Will return "ArrayError" if there is no current item.
array	getlast	arrayname	stringVariable	Set the current index of "arrayname" to the last item in the array and retrieve the current item. Will return "ArrayError" if there is no current item.
array	removeat	arrayname;indexposition	none	Removes the item at index "indexposition" from "arrayname". Resets the current array index to 0.
array	indexof	arrayname;searchvalue	stringVariable	Searches the array "arrayname" for an item with the value of "searchvalue" and, if found, returns the index of the first matching value or "ArrayError" if not found
array	getlength	arrayname	stringVariable	Returns the number of items in array "arrayname"
array	pagetokens	arrayname;tokenid OR pageid;(optional filter)	stringVariable	Creates an array (arrayname) of all of the token ids (technically Graphics objects) on the same page as the specified token id or on the page matching the page id. Returns the number of tokens found to the stringVariable. Available optional filters are : all, char, graphic, pc, npc. The filters will return only those tokens that match that criteria (char means tokens have a "represents", graphic doesn't. pc indicates a represents token has a controlledby, npc doesn't.)
array	selectedtokens	arrayname	stringVariable	Creates an array (arrayname) of all of the token ids (technically Graphics objects) selected when the script was executed. Returns the number of tokens found to the stringVariable.
array	stringify	arrayname(;separator-optional)	stringVariable	Returns all of the items in "arrayname" as a string separated by default semicolon (;) or the current #parameterdelimeter. New in 2.1.0, an additional parameter can be added that specifies the delimiter to be used.
array	fromstring	arrayname;delimiter;string	unused	Creates an array from "string", splitting "string" on "delimiter" to separate the items
array	statusmarkers	arrayname;tokenid	none	Creates an array (arrayname) of the active statusmarkers (sometimes called Token Markers) for the specified tokenid
array	objects:objectype	arrayname;filter	none	Creates an array (arrayname) of the IDs of game objects of the specified type that match the indicated filter. Note that "filter" is really just that the designated field starts with the specified value. The designated field is "name" for all objects with names. For other objects, the filter field is _displayname for players, title for jukeboxtracks, stroke (color) for paths, text for text and not supported for campaign, card, and hand objects. Filters are not case sensitive.
array	fromrepeatingsection	arrayname;charid;repsection name;field name	unused	Creates an array from the entries in the repeating section defined by repsection name, returning the values of field name as the elements in the array
array	fromtable	arrayname;tablename;"name", "image", or "both"	unused	Creates an array from the entries in a rollable table. "name" and "image" determine if the entry name or image URL is returned in the array. If "both" is specified, both components will be returned for each array element separated by a vertical bar.
array	fullrepeatingsection	arrayname;charid;repsection name;field1:field2:field...;sepsequence	unused	Creates an array from the entries in the repeating section defined by repsection name, returning the values of each field specified in the field list parameter (separated by colons). The values in the array entries will be separated by the sepsequence.
Categorized Hashtable Functions
hash	clear	HashTableName	none	This command will clear all entries from a hashtable. Note: This feature is introduced in ScriptCards version 2.6.2 on Jan-20-2024 and could change depending on further testing of the suite of functions and commands associated to the hashtable command (--h) introduced in version 2.6.0. Example: --~|hash;clear;MyHashTable
hash	set	HashTableName;Key1==Value1;Key2==Value2;Key3==Value3;...	none	Creates the hashtable HashTableName with the Keys and Values provided. There is not a limit to the number of Key/Value pairs that can be used with this function. Example: --~|hash;set;Fruits;Mango-Cost==2sp;Mango-Size==Medium;Mango-Shape==Oblong;Mango-Avail-Spring==False;Mango-Avail-Summer==True;Mango-Avail-earlyAutumn==True;Mango-Avail-lateAutumn==False;Mango-Avail-Winter==False
Categorized Math Functions
math	angle	math;angle;tokenid;tokenid	rollVariable	Calculates the angle between two tokens and returns the value in degrees
math	ceil	math;ceil;value	rollVariable	Rounds value up to the next integer, dropping any decimal portion of the number
math	clamp	math;clamp;value;lowerBound;upperBound	rollVariable	Returns value, but restricted to the range of lowerBound and upperBound.
math	floor	math;floor;value	rollVariable	Rounds value down, dropping any decimal portion of the number
math	max	math;max;valueA;valueB	rollVariable	Returns the larger of valueA vs valueB
math	min	math;min;valueA;valueB	rollVariable	Returns the smaller of valueA vs valueB
math	round	math;round;value	rollVariable	Rounds value to the nearest integer
Categorized String Functions
string	length	string;length;stringValue	rollVariable	Returns the length of stringValue in characters
string	before	string;before;searchText;stringValue	stringVariable	Searches stringValue for searchText and returns the portion of stringValue prior to that text
string	after	string;after;searchText;stringValue	stringVariable	Searches stringValue for searchText and returns the portion of stringValue after that text
string	left	string;left;count;stringValue	stringVariable	Returns the leftmost count characters of stringValue
string	right	string;right;count;stringValue	stringVariable	Returns the rightmost count characters of stringValue
string	replace	string;replace;searchText;replaceText;stringValue	stringVariable	Replaces searchText in stringValue with replaceText and returns the resulting string
string	replaceall	string;replaceall;searchText;replaceText;stringValue	stringVariable	Replaces all intances of searchText in stringValue with replaceText and returns the resulting string Requires 1.2.9+
string	trim	string;trim;stringValue	stringVariable	Removes leading and trailing spaces from stringValue and returns the result.
string	substring	string;substring;start;count;stringValue	stringVariable	Returns count characters starting at start from stringValue
string	split	string;split;delimiter;stringValue	special	Splits stringValue into pieces, breaking it at delimiter. Returns a rollVariable with "Count" appended to the assigned variable name and a series of string variables with numbers appended (starting at 1) for each of the returned pieces.
string	tolowercase	string;tolowercase;stringValue	stringVariable	Converts the passed string to lower case and assigns to the passed variable name.
string	touppercase	string	stringVariable	Converts the passed string to upper case and assigns to the passed variable name.
string	totitlecase	string	stringVariable	Converts the passed string to title case (capitlaizes the first letter of each word) and assigns to the passed variable name.
string	onlynumbers	string	stringVariable	Returns only the number values from a string, preserving a leading - sign if it is the first non-whitespace character in the string.
string	nonumbers	string	stringVariable	Returns a string with all numeric characters (0 thru 9) removed.
Categorized State Item Functions
stateitem	write	stateitem;write;variableType	None	Writes the variable specified in the tag to persistent storage. Specify either rollvariable or stringvariable for variableType. One of each type can be stored in persistent storage at a time.
stateitem	read	stateitem;read;variableType	Depends on variableType	Reads the stored variable of the specified type (either rollvariable or stringvariable) and stores the result in a variable named for the line tag.
Categorized Turn Order Functions
turnorder	clear	none	none	Clears all entries from the t Turn Tracker/Initiative
turnorder	addtoken	tokenid;trackervalue	none	Adds the token represented by "tokenid" to the initiative tracker with an initiative value of "trackervalue"
turnorder	replacetoken	tokenid;trackervalue	none	Replaces the token represented by "tokenid" in the initiative tracker with an initiative value of "trackervalue". Will add the token if it doesn't exist in the tracker.
turnorder	removetoken	tokenid	none	Removes the token represented by "tokenid" from the initiative tracker if it exists
turnorder	addcustom	textlabel;trackervalue;(optional)formula	none	Add a custom text entry to the t Turn Tracker/Initiative named "textlabel" with an initiative value of "trackervalue"
turnorder	removecustom	custom name	none	Removes the custom turn order token matching the given name from the turn tracker
turnorder	sort	none or "a" or "u"	none	Sorts the turn order in descending numerical order unless the additional "a" or "u" parameter is set ("a"scending or "u"p). Version 2.1.1
Categorized System Functions
system	date	getdatetime	stringVariable	Returns the date time in the active timezone (see settings)
system	date	getdate	stringVariable	Returns the date in the active timezone (see settings)
system	date	gettime	stringVariable	Returns the time in the active timezone (see settings)
system	dumpvariables	"rolls", "string", or "array"	none	Dumps all of the defined variables of the indicated type to the console log
system	findability	system;findability;charactername;abilityname	stringVariable	Returns the object ID of the ability on the indicated character or "AbilityNotFound"

Examples:
This example uses a function in the turnorder category. There is no return value for the turnorder/addtoken function:

--~|turnorder;addtoken;@{selected|token_id};5

Information Request (--i)

An Information Request statement allows your script to pause and “ask” the user for additional input. The statement type is --i, and uses the Tag portion of the statement to define a prompt to the user and the caption of a button that will be displayed for the user to press to provide additional information. The content portion of the line is made up of a series of information request in the format type;VariableName;PromptText, with each request separate by double vertical bars.

  --i<Text Prompt>|< Type;VariableName;Prompt >...

ScriptCards will use the display text and the button caption to whisper the script sender a message with a button to click that can ask for information via roll queries or ask for targets to be selected. Multiples of each type and combinations are allowed. The result of each information request will be stored in a string variable matching the VariableName parameter for that request.

After the user has clicked the button and responded to the requests, ScriptCards will resume processing the script from where it left off.

Here is an example “i” line:

--IScriptCards needs additional information to continue;Click to select a target and provide information|t;MyNewTarget;Missile1Target||q;MyNameIs;What is your name?

The sample above will whisper the user "ScriptCards needs additional information to continue" and provide a button labeled "Click to select a target and provide information". When the user clicks the button, they will be requested to select a target labeled Missile1Target and a prompt will appear asking that they enter their name into a text field.

Supported information request types are “t” for target token, and “q” for query.

For “t” types, specify the variable name to store the token ID in as the second parameter and the prompt text that will appear in the “Choose Target” window (i.e. Choose Target: Missile1Target above).

For “q” types, specify the variable name to store the response in as the second parameter, and the text of the roll query without the ?{} identifiers. You can specify values for dropdowns, etc. For example:

q;UserName;What is your name?|Fred|Bob|Sally|Nancy

Would have a dropdown menu with four choices.

Object Modification (--!)

ScriptCards supports direct manipulation of object properties within your script. While updating object properties is possible by utilizing the --@ command to call external Mod (API) scripts, the biggest advantage of doing this directly through ScriptCards is that the modifications to the objects take place immediately, so reading values back works as you would expect.
As of version 2.1.7, Object modification statements now support the ability to modify any type of object by specifying the object type and object id in the tag portion of the statement. Note that very little checking is done on this (if the property you are setting is imgsrc, the image source will be reformatted per Roll20 requirements).

General syntax for Modifying Objects:

  --!<objectType>:<objectId>|[setting:value]|[setting:value]|[setting:value]...

objectType

You can fill in the objectType with anything in the following table. For any objectTypes with a shortcut, you can reference the shortcut instead of the complete objectType name.

Object Type	Shortcut		Object Type	Shortcut		Object Type	Shortcut
ability	b		attribute	a		campaign	N/A
card	N/A		character	c		custfx	N/A
deck	N/A		graphic	N/A		hand	N/A
handout	N/A		jukeboxtrack	N/A		macro	N/A
page	N/A		path	N/A		player	N/A
rollabletable	#		tableitem	e		text	N/A
token	t

 NOTE: As of version 2.1.0, any Roll20 object type is now supported as well. As of this writing, the Roll20 object types are: campaign, player, page, path, text, graphic, character, attribute, ability, handout, macro, rollabletable, tableitem, deck, card, hand, jukeboxtrack, custfx.

objectID

objectId can be a token id or a character id (or "S"/"T" for the Source/Target token/char defined with --#sourcetoken and --#targettoken)

 NOTE: As of version 2.1.0, this can refer to any type of object, but will only function if the object is of the type specified by the objectType parameter.

setting and value pairs can be chained in a single statement separated by | to impact more than one property/attribute with a single line

When using the "t", "c", and "a" object types, values can be prefixed with += or -= to add/subtract from the current value (no bounds checking is done). Using [*X] notation, the updated values can be read immediately. Using += or -= on non-numeric data will simply result in a string append. NOTE: using the extended object types in 2.1.0 does not support += and -=. If you need this functionality, you will need to implement it manually in order to keep these commands as open and powerful as possible.

For "a" types, setting names can be prefixed with a ! to create the attribute if it doesn't exist (by default, it will not be created), and postfixed with ^ to set the max value instead of the current value.

Note that there are VERY few attributes associated with a character object, and there are likely few cases where you would want to set anything on the character object, but it is still possible.

When setting values listed in the Roll20 Object API as boolean types, use the words true or false to indicate the desired value.

Ex: --!graphic:@{selected|token_id}|bar1_value:256

Will set the bar1_value property of the selected graphic object to 256. As with variable referencing, you are likely better off using the specific object type commands (ie, --!t: and --!a:, etc.) when they are available. Note that setting Bio, Notes, and GMNotes will actually make the setting, but it isn't immediate and will not necessarily be available if read back within the same script. It will also throw a console message about needing to pass a callback.

Object Modification Examples

Example 1 (Update Token): Set the value of bar1_value for the selected token to 5:

  --!t:@{selected|token_id}|bar1_value:5

Example 2 (Update Token): Add 1 to the bar3_value for the selected token:

  --!t:@{selected|token_id}|bar3_value:+=1

Example 3 (Update Token): Set bar2_value to 5 and bar2_max to 10 for the selected token:

  --!t:@{selected|token_id}|bar2_value:5|bar2_max:10

Example 4 (Update Attribute): For the character the selected token represents, set dndstyling attribute on, set size to enormous, and set attitude to epic. The attitude-attribute will be created if it doesn't exist on the character already. The same is not true for dndstyling and size:

  --!a:@{selected|token_id}|dndstyling:on|size:enormous|!attitude:epic

Example 5 (Update Attribute): Adds 50 to the npc_xp attribute for the character represented by the selected token, displaying the value before and after the update:

  !script {{
    --+XP|[*@{selected|token_id}:npc_xp]
    --!a:@{selected|token_id}|npc_xp:+=50
    --+XP|[*@{selected|token_id}:npc_xp]
  }}

Note that asynchronous read/update fields (bio, notes, gmnotes) can be set by object modification statements, but the values of these fields cannot be read back into ScriptCards.


Abilites
are created with the following syntax: --!ob:ReturnVarName:CharacterID:AbilityName:IsTokenAction|Text of the Ability

Note that you will need to define string variables for special characters you would like to hide from the Roll20 chat server. The following example adds an ability to the selected character called "SayHello" that uses the "Lightning-Bolt" ability on a character called "Spell_Mule":

!script {{
  --&obrac|{
  --&cbrac|}
  --&perc|%
  --!ob:AbilID:@{selected|character_id}:SayHello:y|[&perc][&obrac]Spell_Mule|Lightning-Bolt[&cbrac]
  --+AbilID|[&AbilID]
}}

To break down the --! line from the example above: --!ob:AbilID:@{selected|character_id}:SayHello:y|[&perc][&obrac]Spell_Mule|Lightning-Bolt[&cbrac]
--! ... is the start of an object modification command
o ... means create a new object
b ... means aBility ("A" would be reserved for attributes)
AbilID ... is the string variable that the object id of the new ability will be returned to
@{selected|character_id} ... is filled in with the Character ID of the currently selected character
SayHello ... is The name of the ability that will be created
y ... says that this ability should show up as a token action button when the token is selected
[&perc][&obrac]Spell_Mule|Lightning-Bolt[&cbrac] ... is the text of the ability, with variables used on place of %, {and } to avoid having them processed by the chat server.

You could also include references to global macros by creating the variable --&hash and placing that before the global macro name in the ability text, Ex: --!ob:AbilID:@{selected|character_id}:ActionMenu:y|[&hash]ActionMenu


Rollable Tables
are created using two different syntax lines:

To create the overall table (rollabletable): --!o#:ReturnVarName|TableName

ReturnVarName will be populated with the table_ID of the created table.

To create individual entries in the table (tableitem): --!oe:ReturnVarName|Table_ID|TableItemName;TableItemWeighting

ReturnVarName will be populated with the tableitem_ID of the newly created table items. If you create multiple table items, the return var will be overwritten with each line, so be sure to display the tableitem ID between each tableitem creation or the tableitem IDs will not all be displayed.

For example, the following would create a sample rollable table with five entries. The first two entries in the table will have the default weighting of 1. The last three entries have the weighting specified. This script will not provide the tableitem IDs that are created.

!script {{
   --!o#:tableid|MySCTable
   --+Result|[&tableid]
   --!oe:entryid|[&tableid];Entry 1
   --!oe:entryid|[&tableid];Entry 2
   --!oe:entryid|[&tableid];Entry 3;2
   --!oe:entryid|[&tableid];Entry 4;6
   --!oe:entryid|[&tableid];Entry 5;10
}}

If you want to be given the tableitem IDs during the creation, you would use this method instead:

!script {{
   --!o#:tableid|MySCTable
   --+New Table ID|[&tableid]
   --!oe:entryid|[&tableid];Entry 1
   --+New Entry ID|[&entryid]
   --!oe:entryid|[&tableid];Entry 2
   --+New Entry ID|[&entryid]
   --!oe:entryid|[&tableid];Entry 3;2
   --+New Entry ID|[&entryid]
   --!oe:entryid|[&tableid];Entry 4;6
   --+New Entry ID|[&entryid]
   --!oe:entryid|[&tableid];Entry 5;10
   --+New Entry ID|[&entryid]
}}

TableItem images cannot be added directly through the creation syntax, so you would use the object modification syntax to modify the image (from blank to populated) which could follow this example:

!script {{
   --!o#:tableid|MySCTable
   --+New Table ID|[&tableid]
   --!oe:entryid|[&tableid];Entry 1
   --!tableitem:[&entryid]|avatar:https://s3.amazonaws.com/files.d20.io/images/301251426/y7xmdikPD6SLuY4u4E8odw/max.png?1661354880
   --+New Entry ID|[&entryid]
}}

Note: Images can only be used if they are uploaded to your library. The URL of an acceptable image must always begin with https://s3.amazonaws.com/files.d20.io/


Repeating Rows
are created using the syntax: --!or:character_id:sectionName|value:current:max|value:current:max...

For example, to create a language proficiency on the currently selected character (5E):

--!or:@{selected|character_id}:proficiencies|prof_type:LANGUAGE|name:Abyssal

The max portion is optional and can be left out if it doesn't make sense (as in the line above). A bit more complicated example is below. This creates a repeating_npcaction on the currently selected character (note that ScriptCards doesn't have a way to check to see if the section exists, it will just create the appropriate attributes on the character - again, this is a 5E example, but repeating sections on any sheet can be created as long as you know what attributes you need to specify and the name of the section):

!script {{
  --!or:@{selected|character_id}:npcaction|
        name:Mega Bite|
        attack_flag:on|
        attack_type:melee|
        attack_target:one target|
        attack_range:5 ft.|
        attack_tohit:8|
        attack_damage:1d4 + 3|
        attack_damagetype:piercing|
        attack_tohitrange:+5, Reach 5ft., one target|
        attack_onhit:5 (1d4 + 3) piercing damage|
        attack_crit:1d4
}}

Note that this is all one ScriptCards line, and could be written that way. Placing each attribute/value pair on its own line makes it a bit clearer to read, though. ScriptCards will assume that the section starts with repeating_ so it should not be specified in the section parameter (hence npcaction instead of "repeating_npcaction")

Wait (--w)

The --w command, which has two related methods of use. --w#| (ie, --w5|) will sleep the sandbox for # seconds (up to 10) Note that this has limited usefulness and multiple delays could crash the sandbox by Roll20 thinking it entered an infinite loop. The second option is --w#:regularscriptcardsline, for example: --w5:a|CureLightWounds which would run the script normally and trigger the system to run the ScriptCard line indicated 5 seconds later. This is done by generating a mini ScriptCard containing that single line. Variable referencing is processed when this mini-card is generated. Example:

!script {{ 
  --&SoundToPlay|Spell_FireBurst
  --w3:a|[&SoundToPlay]
  --w4:vtoken|@{selected|token_id} nova-fire
  --w5:!t:@{selected|token_id}|left:250
}}

This script will run and output the ScriptCards title. Three seconds later, the Spell_FireBurst audio track will play. One second after that, a nova-fire VFX will play at the selected token location, and finally a second after that the token will be moved to x-position 250.

Note: If the delayed command is a direct output (--+) or GM output (--*) command, the mini-ScriptCard will display the line as a new card with the title hidden.

Inline Formatting

Inline formatting is processed on both Direct Output lines and GM Output lines and the following inline format markup is available:

Formatting Tags	Description
[b]..[/b]	Bold the text between the markers
[i]..[/i]	Italicize the text between the markers
[u]..[/u]	Underline the text between the markers
[s]..[/s]	Strike-Thru the text between the markers
[c]..[/c]	Center alignment
[l]..[/l]	Left alignment
[r]..[/r]	Right alignment
[j]..[/j]	Full justification alignment
[f#]..[/f]	Set in-line font size to #px. (2.0.2e)
[F:(font_name):(font_size)]..[/F]	This formatting is case-sensitive. Set the Font Name and Font Size inline without forcing a New Line/ carriage return like [f]..[/f] will do. Example: [F:Contrail One:24] Hello! [/F] Technical info: [f] is processed as a div, which causes a new line each time it's ended. [F] is processed as a span, which does not cause a new line at all.
[br]	Line break (translates to <br> in html)
[hr] or [hr #xxxxxx]	Insert a horizontal rule. If a 3 or 6 digit (or named) color code is specified after the # the rule will be colorized
[#xxx]..[/#] or [#xxxxxx]..[/#]	Use a 3 or 6 digit hex code to colorize the text between the markers
[img]..[/img]	Insert an image. The full URL of the image goes between the markers. You can include HTML attributes to be applied to the img tag in the opening marker (ie, [img width=128 height=128] )
[button]caption::action[/button]	Create a button with the label "caption" that performs the action defined by "action". *Note*: See notes below this table regarding the inline formatting options available to override the default values you used in the settings.
[sheetbutton]caption::character::abilityname[/sheetbutton]	Create a button that, when pressed, will run the "abilityname" macro on the "character" charactersheet. Useful for launching macros from a macro mule character sheet. *Note*: See notes below this table regarding the inline formatting options available to override the default values you used in the settings.
[rbutton]Caption::ReentryLabel;Parameter[/rbutton]	Create a reentrant button which, when clicked by the user, will resume script execution at "ReentryLabel", passing "Parameter" to the [&reentryval] string variable. *Note*: See notes below this table regarding the inline formatting options available to override the default values you used in the settings.
[roll]...[/roll]	Anything entered between [roll] and [/roll] will be formatted to appear as a roll. Use [roll:c]...[/roll] for critical success formatting. Use [roll:f]...[/roll] for critical failure formatting. If you specified settings for the appearance of the different roll outcomes they will be used, otherwise the default formatting will be applied. Roll appears normal: [roll]15[/roll] Roll appears as a critical success: [roll:c]18[/roll] Roll appears as a critical failure: [roll:f]2[/roll] Text appears as a roll: [roll]What is going on?[/roll] Text appears as a critical success: [roll:c]You did it![/roll] Text appears as a critical failure: [roll:f]Oh No! You didn't make it![/roll] Settings for customization: See rollHilightcolorboth, rollHilightColorCrit, rollHilightColorFumble, rollHilightColorNormal
[t]	Converted to HTML table tag. Text after the "t" will be included inside the tag (width, border, etc) *Note*: See notes below this table regarding the inline formatting options available.
[/t]	Converted to HTML close table tag.
[tr]	Converted to HTML table row tag. Text after the "tr" will be included inside the tag. *Note*: See notes below this table regarding the inline formatting options available.
[/tr]	Converted to HTML close table row tag.
[td]	Converted to HTML table cell tag. Text after the "td" will be included inside the tag. *Note*: See notes below this table regarding the inline formatting options available.
[/td]	Converted to HTML close table cell tag.

In-line formatting can be applied to buttons and to various levels of the table sections. The syntax is a little different depending on how directly supported the html/css is, but here are a couple examples.

Button formatting

The main default color formatting for buttons comes from the buttonBackground and buttonFontColor settings, and the default font size comes from the buttonFontSize setting. These can be overridden with inline formatting commands within the initial [button] tag. The formatting overrides can be mixed and matched depending on what you'd like to accomplish. You should note that, with buttons, you cannot change the background color of a button unless you specify the font color of the button. You can specify the font color as the same as the buttonFontColor setting if you don't want to change the font color, but want to change the background color. The formatting will only go inside the brackets with the opening command with the rest of the syntax remaining the same (e.g. [button(formatting goes here)]caption::action::[/button])

ScriptCard Item	Formatting Syntax	Example	Description/ Results
[button] [sheetbutton] [rbutton]	[button:(font color):(background color)]	[button:#FFFFFF:#000000]...	This updates the font color and background color of a button. In this example they've been updated to white font over a black button background.
[button] [sheetbutton] [rbutton]	[sheetbutton:(font size)]	[sheetbutton:20px]...	This overrides the font size of the text within a button.
[button] [sheetbutton] [rbutton]	[rbutton:(tool tip message)]	[rbutton:This is a tooltip!]...	This will add a tooltip to the button you've setup. There is not a default setting for tooltips, so this is the only way to add one. Note:Because the other formatting above can be added adhoc, it's important that your tooltip not being with a '#' symbol, or end in 'px', or the formatting will get misinterpreted resulting in undesirable results.
[button] [sheetbutton] [rbutton]	[button:(text color):(background color):(font size):(tooltip for button)]	[button:#FFFFFF:#000000:26px:Awesome tool tip for an awesome button!]...	This example shows the combination of all the formatting overrides being used on a single button together.

Table formatting

Tables can also be formatted at the various levels (i.e. table, table row, table cell, etc) in order to refine the appearance of the table. The following are a few simple examples, but there are a lot more ways tables can be formatted than shown below. The formatting is done with CSS and html inline markup. Inline formatting can also be included between the opening and closing tags of table content as well.

Table Tag	Formatting Syntax	Example	Description/ Results
[t]	[t width=(size)]	[t width=100px	This specifies the width of the entire table in pixels.
[tr]	[tr width=(size)]	[tr width=25px	This specifies the width of the specific table row in pixels.
[td]	[td style=(various commands)]	[td style="width:10px; text-align:right;"]	This specifies the width of the specific cell and aligns the text to the right within the same cell.

Code Example

Formatting Tags

Description

!script {{ --#title|Inline Formatting Examples --+|This text [b]is bolded[/b] --+|This text [i]is italicized[/i] --+|This text [u]is underlined[/u] --+Alignment|[l]Left[/l] --+|[c]Center[/c] --+|[r]Right[/r] --+|[j]This long bit of text is justified to fit smoothly into the display area for the card with justified wrapping.[/j] --+Colorized|[#f00]Red[/#] [#0f0]Green[/#] [#00f]Blue[/#] --+Button|[button]Do Something::DoOnClick[/button] --+Button Colors|[button:#000:#f00]Red::RedClick[/button] [button:#000:#0f0]Blue::BlueClick[/button] [button:#000:#00f]Blue::BlueClick[/button] --+Table:| --+|[t border=2 width=100%][tr][td]Cell1[/td][td]Cell2[/td][/tr][tr][td]Cell3[/td][td]Cell4[/td][/tr][/t] }}

Variables

See the Referencing-section for information on referencing variable content

ScriptCards supports two types of variables : Roll Variables and String Variables. Either type can be used in a conditional statement, or use to substitute their value into the tag or content portion of other statements. For both types of variables, variable names are case sensitive. Roll Variables and String variables are completely separate internally, so it is possible to use the exact same name for both a Roll Variable and a String Variable; however, doing so will likely result in confusion when looking at the script later, so it is not a recommended practice.

Roll Variables

A roll variable is used to store the results of dice rolls or math calculations when more than just the final resultant value is important. Roll Variables are set via the {{{1}}} statement or the {{{1}}} referencing structure, and are processed by the ScriptCards roll parser.

--=AttackRoll|1d20 + @{selected|strength_mod} [STR] + @{selected|pb} [PROF]
--+Result|[$AttackRoll]

In this case, we are creating a roll variable called AttackRoll. The content portion of the roll will be passed to the ScriptCards roll processor, which will roll 1d20 and add two modifiers, storing the result in the AttackRoll variable. The roll parser will store extra information about the roll to various components of the AttackRoll variable, including the text passed to the parser, a formatted version of the result in a hover-over text box, and details on each die rolled.

A Roll Variable is referenced using the [$variablename] structure. See the Referencing-section for all of the additional information retrievable from a Roll Variable.

String Variables

String Variables are assigned with the --& statement and are referenced using [&variableName] notation. A string variable can contain just about any text, however there are some character sequences that will be misinterpreted by the Roll20 chat server. In that case, it is necessary to build the string variable in multiple pieces. This trick can also be useful when you want to use some character sequences in strings or output that would be clobbered by the chat server [[ for example, which the chat server will interpret as an Inline Roll.

This can be accomplished by splitting the string into pieces during its creation. For example:

  --&QB|? --&QB|+{ --&QE|}
  --&AB|@ --&AB|+{
  --&TB|& --&TB|+# --&TB|+64 --&TB|+; --&TB|+{
  --&BED|& --&BED|+# --&BED|+128719;
  --&CLOCK|& --&CLOCK|+# --&CLOCK|+128336;
  --&SPACE|X X --&SPACE|[&SPACE(1,1)]
  --&obrac|[ --&cbrac|]

The code above defines several string that are generally useful in scripts. &QB (build in two parts, ? and { can be used to initiate a roll query as part of a button without the chat server asking the question when the overall script is run. &AB is similarly used for attribute references, while &TB shows an example of escaping an HTML sequence that would be replaced by the chat server incorrectly.

The &BED and &CLOCK strings use HTML escaping to assign emojis to strings, while &SPACE uses a substring reference to create a variable that just includes a space (since a space at the end of a line, including a variable assignment will be stripped out by the parser). Finally, &obrac and &cbrac are opening and closing brackets to allow for [[ type structures.

Predefined String Variables

There are a handful of variables assigned automatically when a ScriptCard is executed that can be used in your script to retrieve information about some game conditions when the script was executed:

Variable	Value
SendingPlayerID	Contains the object ID of the player that sent the macro
SendingPlayerName	Contains the display name of the player
SendingPlayerColor	Contains the color code associated with the player
SendingPlayerSpeakingAs	The contents of the "Speaking As" dropdown window
SendingPlayerIsGM	Contains 1 if the player is a GM, and 0 if the player is NOT a GM

Arrays

Intro to Arrays

An Array is a collection of string variables that are all associated with the same variable name and retrievable/settable by an index number into the array. For example, the following ScriptCards code can be used to create a simple array called Fruits that contains 4 elements:

--~|array;define;Fruits;Banana;Mango;Pineapple;Watermelon

Alternatively, an array can be created by directly assigning strings to array element references:

--&Fruits(0)|Banana
--&Fruits(1)|Mango
--&Fruits(2)|Pineapple
--&Fruits(3)|Watermelon

Functionally, these two blocks of code are identical and both results in the creation of a four element array called Fruits.

Array indexes start at 0

Adding Elements to an Existing Array

You can use the --& command to add elements to an array, even if you don't know the size of the array. If you specify an index number that already exists in the array, that element will be replaced, but if you specify an index number larger than the last index in the array, the element will be added to the end of the array at the next available index. For example,--&Fruits(9999)|Papaya will add Papaya as element 4 of the array, since that is the next available index number.

A more proper method, however, would be to use the length of the array to ensure that you will always use an index higher than the highest index:--&Fruits([@Fruits()])|Papaya functions identically, but will not break if your array already has 9999 items in it. See the Array Metadata section below for details on the [@ArrayName()] construct.

You can also add elements to the beginning of the array by specifying a negative index: --&Fruits(-1)|Lemon will insert Lemon as element 0 and push all of the exiting elements down one index, so element 1 will become Banana, 2 Mango, etc.

Changing Array Element Values

The same syntax used to assign array elements can be used to update the element values. Let's say we previously defined the following array:

--&Fruits(0)|Banana
--&Fruits(1)|Mango
--&Fruits(2)|Pineapple
--&Fruits(3)|Watermelon

If we want to replace the value "Pineapple" (in Index position 2) with the value "Grape" we'd simply use this: --&Fruits(2)|Grape.

Referencing Array Elements

When you wish to retrieve the value stored in array element, you can reference that element with the pattern [@ArrayName(index)]. For example: [@Fruits(2)] given the array defined above, will return "Pineapple" in place of the variable reference.

You can either use the index (getfirst, getnext, etc.) to traverse an array and work with the values, or you can use (new in 1.3.1) direct array element referencing.

!script {{
 --~dummy|array;pagetokens;myarray;@{selected|token_id}
 --~count|array;getcount;myarray
 --+Total:|There are [&count] graphical objects on the page
 --~testvar|array;getfirst;myarray
 --:loop|
 --+Value|[*[&testvar]:character_name]
 --~testvar|array;getnext;myarray
 --?[&testvar] -ne ArrayError|loop
 --+Loop1|Is Done!
}}

This example defines an array based on the tokens on the page and then loops through them, starting with a getfirst, displaying the character name, and using getnext until the result is ArrayError, at which point the loop exits. Here is the same routine, except it uses a For...Next loop and direct array referencing:

!script {{
 --~dummy|array;pagetokens;myarray;@{selected|token_id}
 --~count|array;getcount;myarray
 --+Total:|There are [&count] graphical objects on the page
 --%loopCounter|1;[&count]
   --+Value|[*[@myarray([&loopCounter])]:character_name]
 --%|
 --+Loop|Is Done!
}}

This line : --+Value|[*[@myarray([&loopCounter])]:character_name] uses [@arrayName(index)] format (inside a [*characterid:attribute] syntax) to perform the same task as running through the loop with the index.

Array Metadata

Some additional information about arrays is available using specialized element notation:

[@Array()] or [@Array(length)] will return the number of items in the array. Note that the number returned will always be one larger than the maximum index of the array since indexes start at 0. [@Array(maxindex)] or [@Array(lastindex)] will return the index number of the last item in the array.

Note that using the length property will allow you to always add elements to the end of an array:

--&Fruits([@Fruits(length)])|Papaya will add Papaya to the Fruits array at the end of the array.

Traversing Arrays

The easiest method to traverse an array is to use the --% looping structure with the foreach modifier:

--%loop|foreach;Fruits
  --+Fruit|[&loop]
--%|

The code above will traverse each element in the Fruits array and print the value. It could also be written using a normal for loop and index numbers:

--%loop|0;[@Fruits(maxindex)]
  --+Fruit|[@Fruits([&loop])]
--%|

In this case the difference is that in the foreach structure, the loop variable is actually assigned the value of the element, while in the normal loop the loop variable is assigned the index number which then needs to be supplied to the [@Array(index)] structure to retrieve the element.

Additional information on looping is available in the --% loop command documentation.

Special Array Functions

There are a number of special options for the --~ (function) command that can be used to generate arrays based on information stored in Roll20. These are listed in the function table above under the array category, and include things like creating an array of all of the tokens on a page, or the entries in a repeating section on a character sheet. They are also functions to sort and otherwise manipulate the array (replacing elements, for example). Finally there are legacy functions (such as getfirst, getnext, getindex an the like) that were used for traversing arrays and iterating through the elements. While these still work, the ScriptCards language has evolved to make working with arrays quite a bit simpler using loops and array referencing.

NOTE: The documentation below remains for legacy array usage. It is still supported and will still work, but is not the currently preferred method

Each array keeps track of an internal index position (starting at 0). Several commands let you manage this index:

• getindex returns the current index value
• setindex sets the index to the specified location in the array
• getlength returns the number of elements in the array
• indexof returns the index location of the specified element

Other commands let you retrieve values from the array:

• getfirst sets the index to 0 and returns the value at that position
• getnext advances the index by 1 and returns the new current value
• getprevious reduces the index by 1 and returns the new current value
• getlast sets the index to the last elements in the array and returns the new current value

If/when you hit the end of the array, you will get a return value of ArrayError, which can be used to detect the end of the array when looping through by index. See Referencing Array Elements below for additional information.

Manipulating Array Elements

Several array commands deal with inserting, removing, and modifying elements:

• add works just like define, except that it takes an existing array and adds elements to it based on the passed parameters
• remove looks for items matching each passed parameter and removes them from the indicated array if they exist
• removeat allows you to specify an index location in the array and remove the element at that position
• replace searches an array for a value and replaces all occurrences of it with a new value (if found)
• sort sorts the elements in the array in ascending order
• stringify returns a string variable that includes each array element separated by the default semicolon (;) or (new in 1.6.7) the current #parameterdelimeter

Predefined Arrays

As with string variables, there is an array created automatically by ScriptCards when a script executes if there are tokens selected in the VTT.

Array	Value
SC_SelectedTokens	Array containing the Token IDs of any tokens selected by the user when the script is executed

Hashtables (--h)

Hashtables vs Arrays

On the surface, hashtables and arrays may seem to be very similar entities. They both store groups of string items. The primary difference is that hashtables don't store this information in any particular order, but rather with an named key that allows you to retrieve the value using that key.

Consider an array that holds the movement speed values for each of your PCs. As an array, you would simply have 30,25,30,40 and would need some way to know what character each value is associated with. If we stored Fred's speed in the first element in the array, [@Speeds(0)] would return 30, but we don't have any useful information that references the associated character anywhere.

Storing the same data in a hash table, you would associate the speeds with the names of the characters, so [:CharSpeed("Daphne")] would return 30. [:CharSpeed("Fred")] would return 25, and so on. Taking this a step further, what if one of our characters leaves? In an array, if we remove an item in the middle of the array, the indexes of all of the subsequent items change. With a hashtable, the keys all still refer to the correct values, so adding and removing entries is non-disruptive.

Defining Hashtables, Keys and Values

Referencing Hashtable Keys and Values

Removing Keys from Hashtables

You can remove a Key from a hashtable by assigning it a blank value like this:
Example:--h:Fruits("Steak")|

Built-in Functions for Hashtables

---

Practical Application Examples

Example 1:   Using Delimiters
This example demonstrates using delimiters to store multiple pieces of information about an item in a hash table.

!script {{
  --h:Fruits("Mango-Cost")|2sp
  --h:Fruits("Mango-Size")|Medium
  --h:Fruits("Mango-Shape")|Oblong
           
  --h:Fruits("Apple-Cost")|2cp
  --h:Fruits("Apple-Size")|Medium
  --h:Fruits("Apple-Shape")|Round
           
  --h:Fruits("Watermelon-Cost")|1gp
  --h:Fruits("Watermelon-Size")|Large
  --h:Fruits("Watermelon-Shape")|Oblong
           
  --h:Fruits("Grape-Cost")|1cp
  --h:Fruits("Grape-Size")|Small
  --h:Fruits("Grape-Shape")|Round
           
  --~|array;define;fruits;Apple;Mango;Watermelon;Grape
  --~|array;define;fields;Cost;Size;Shape

  --%fruit|foreach;fruits
    --%field|foreach;fields
      --+[&fruit]-[&field]|[:Fruits("[&fruit]-[&field]")]
    --%|
  --%|
}}

---

!script {{
  --h:Fruits("Mango-Cost")|2sp
  --h:Fruits("Mango-Size")|Medium
  --h:Fruits("Mango-Shape")|Oblong

  --h:Fruits("Apple-Cost")|2cp
  --h:Fruits("Apple-Size")|Medium
  --h:Fruits("Apple-Shape")|Round

  --h:Fruits("Watermelon-Cost")|1gp
  --h:Fruits("Watermelon-Size")|Large
  --h:Fruits("Watermelon-Shape")|Oblong

  --h:Fruits("Grape-Cost")|1cp
  --h:Fruits("Grape-Size")|Small
  --h:Fruits("Grape-Shape")|Round

  --~|array;define;FruitNames;Apple;Mango;Watermelon;Grape
  --~|array;define;FruitFields;Cost;Size;Shape

  --s:|Fruits
  --s@|FruitNames;FruitFields
}}

---

!script {{
  --l:|Fruits
  --&Lookup|?{Fruit|Apple|Watermelon|Mango|Grape}
  --+|A [:Fruits("[&Lookup]-Size")], [:Fruits("[&Lookup]-Shape")] [&Lookup] costs [:Fruits("[&Lookup]-Cost")]
    }}

The output from this looks like this image.

---

Example 4:   Using a hashtable with loops and arrays
A more advanced usage here... Continuing with the arrays from the previous examples, in this example they get loaded and then looped through to get all of the info from the table:

!script {{
  --l:|Fruits
  --l@|FruitNames;FruitFields

  --%fruit|foreach;FruitNames
    --%field|foreach;FruitFields
      --+[&fruit]-[&field]|[:Fruits("[&fruit]-[&field]")]
    --%|
  --%|
}}

The output from this looks like this image.

---

Looping Structures (--%)