Latest revision as of 13:15, 25 August 2024

Page Updated:   2024-08-25

API ScriptAuthor: Kurt J.
Version: 2.7.29
Last Modified: 2024-08-23
Code: ScriptCards
Dependencies: None
Conflicts: None

ScriptCards Links

---

Roll20 Forum Links:

• Main ScriptCards Thread^(Forum)
• ScriptCards Working and Sharing thread^(Forum)

GitHub Links:

• ScriptCards Changelog
• ScriptCards API
• ScriptCards Samples

Roll20 Wiki Links:

• Main Page - ScriptCards

Working Scripts Submitted by Users:

• User-submitted Scripts
• User-submitted Libraries
• User-submitted Triggers

Official Discord:

• ScriptCards Official Discord Channel

YouTube Tutorials:

• ScriptCards Intro
• ScriptCards Magic Missile Deep Dive

[edit] Introduction to ScriptCards

NOTE: The Roll20 wiki was uneditable for months, so the ScriptCards wiki is a bit out of date. I'm in the process of making updates, but there is a lot to get through, so it will take a bit of time. For information on the latest changes, please see the Changelog on the ScriptCards GitHub page. You can help the Community Wiki by improving it. (August 2024)

[edit] What is ScriptCards

NOTE: Because the Roll20 Wiki was un-editable for two months, there are sections of the Wiki that are either outdated or entirely missing (in the case of newly implemented features). We are currently in the process of updating the Wiki to bring it into line with the current version of ScriptCards. At the same time, I'm revising some portions of the Wiki to better organize and update portions that are unclear. You can help the Community Wiki by improving it. (August 2024)

The ScriptCards Mod is a Roll20 (Mod Script) that implements a scripting language interpreter, meaning that it will take the contents of a macro passed to the Roll20 chat server and execute a script (program) complete with variables, loops, branching, and many other standard programming language features. The resultant output is, by default, a "card" (patterned after the D&D 4E Power Cards entries from the official books). The output can be fully customized either directly or with templates and may even be suppressed in cases where the script is simply making attribute/value changes or other non-visual settings. The parser contains its own dice roll parser with a number of features that diverge from the Roll20 Quantum Dice Server.

The ScriptCards scripting language is the programming language specification that is used to create these macros to achieve your desired effects.

In addition to standard items such as Variables, Looping, Branching, and Conditionals, the ScriptCards language defines a number of Built-in Functions to interact with Roll20 API objects, the ability to call other Roll20 Mod scripts, and supports Triggers and Code Libraries.

The ScriptCards interpreter has built in Infinite Loop Protection, limiting the execution to 30,000 lines of code. This limit can be exceeded by altering the limit on a per-script basis with a Settings (--#) statement.

ScriptCards is developed and maintained on GitHub in the ScriptCards Repository and incorporated into the Roll20 OneClick Mod/API system. New features will appear first in the GitHub release, with occasional pushes to OneClick.

• Current OneClick Version 2.7.25
• Current Development Version
• Scriptcards Discord

❗Critically Important (especially if you are coming from PowerCards): 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.

[edit] Getting more help when you need it

If you feel like you're getting stuck or need help that you're not getting from this Wiki, please feel strongly encouraged to join the Scriptcards Discord and reach out to the amazing community via the #Scriptcards channel for help. There's an incredibly rich array of amazing information in this Wiki that covers a vast number of topics, in rather technical detail. Although the information has been broken down into sections and subsections, it can still feel overwhelming to try and absorb it all. Many of the Discord community members have been through the challenge(s) you're facing and would be glad to help you accomplish your goals.

[edit] 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 scripts (PowerCards and ScriptCards) can happily coexist in the same game, and do not interfere with each other in any way.

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

[edit] Your First ScriptCards 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 interpreted and executed by the ScriptCards language interpreter. In most cases, the result of the script will produce output displayed as an HTML formatted "card" in the chat window. A ScriptCards 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 its 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.

In the tradition of most programming/scripting languages, lets write a "Hello World" script:

!scriptcard  {{
  --#title|Hello World
  --+Hello|
}}

Running this simple script will produce the output:

This illustrates several important points about the ScriptCards language:

• Every line of a ScriptCards script begins with two dashes (--), followed by a single character that determines what kind of line it is.
• Every line must also contain a vertical bar (|). The vertical bar separates the Tag portion of the statement from the Content portion.
• A line beginning with --# is a Settings line and is used to alter default values that impact how the output is displayed. In this case, "title" is the Tag part of the statement, and "Hello World" is the statement Content.
• The "title" setting controls the caption displayed at the top of the output
• A line beginning with --+ is a Direct Output line, and is used to add a row of output to the body of the card.
• This statement does not have a Content portion, but the vertical bar used to separate Tag from Content is still required. The --+ statement can (and usually does) have a content portion, which would be displayed next to the Tag portion in the output.

[edit] 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 throughout this document whenever exceptions apply.

A ScriptCard line begins with two dashes, followed by a statement identifier character that tells the brains of the script (aka, the "interpreter") what type of line it is. There are many different types of statements which will be discussed throughout this Wiki, including detailed information on the function, and thorough instructions on the use and of each one.
After the line type identifier, an often 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 (  |  ; also called a "pipe" character), 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.

[edit] Creating the lines of instruction that a Scriptcard uses

Here is a more visual representation of the syntax used to create the various lines of instructions that Scriptcards needs in order to perform any tasks for you

[double dashes] [statement identifier character] [tag section of the line] [pipe] [content section of the line]
|  ----  Line  Type  Identifier  Section  ----  | ----  Tag Section  ---- | pipe | ---- CONTENT  SECTION ---- |

Let's break down the example and connect the dots back to the information you learned a few minutes ago. Let's go through each element individually:

• -- is the "double dash" or "two dashes" that start every type of line.
• # 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.

[edit] 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]}}

[edit] A Note Square Brackets

Roll20 has some issues if square brackets are next to each other (like or ) as it tries to interpret them as inline rolls. You can get around this by using \\[ and \\] instead of plain square brackets. One of the first things ScriptCards will do is globally replace these escaped values with the simply bracket equivalent.

The default ScriptCards output contains a number of sections:

[edit] ScriptCards Variables

UNDER CONSTRUCTION

ScriptCards currently supports four types of variables:

• Roll Variables are used to hold the results of dice rolls or mathematical calculations. Roll variables hold information about the individual dice rolls or other components that make up the final result of the roll/calculation.
• String Variables hold generic text that is not (normally) associated with a dice roll.
• Arrays Are groups of String variables (the elements of an array are always strings)
• Hash Tables Are called associative arrays in some languages, and can be used to store key/value pairs of strings.

[edit] 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 --= statement or the [=...] referencing structure and the content of the assignment statement is processed by the ScriptCards built-in roll parser. When outputting the content of a Roll Variable, the [$...] referencing structure is used.

When assigning a value to a Roll Variable, the variable name is specified as the tag portion of the statement, and the content is parsed by the roll parser to determine the result.

--=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 parser, which will roll 1d20 and add two modifiers, storing the result in the AttackRoll roll 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 [$...] structure, so in this case [$AttackRoll] will output the roll value in the default format for dice rolls. There are a number of suffixes that can be used to retrieve portions of the information stored in the Roll Variable:

Modifier	Meaning
No modifier	In a Direct Output Line (--+), GM Output Line (--*), or String Assignement (--&), 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 .Raw
.Total	The end result of the roll equation. Formatting rules for "No Modifier" apply based on line type.
.Raw	The total value of the roll variable without any formatting, no matter what kind of line the reference is used in.
.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	If the tableEntryText is purely numeric, will contain the numeric value

In the case of our AttackRoll variable above, if we want to know the value of the dice roll (1d20) itself without the modifiers, we will use [$AttackRoll.Base].

[edit] String Variables

[edit] Arrays

[edit] Hash Tables

[edit] ScriptCard Statement Type Details

[edit] 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.
--z	Modify Z-Order	<objectType>:<objectID>	tofront or toback	As of 2.7.0, this command works on graphic objects and allows you to manipulate the z-order (or top to bottom order) of objects. This command will be expanded when the API update (originally planned for March 2024) is released, to include additional object types and options.

The sections below detail the individual statement types supported by ScriptCards

[edit] 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!
  .
  .
  .
}}

[edit] 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]
}}

[edit] 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

[edit] 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]

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 and recalled with the basic syntax: (--Ssettings and --Lsettings).
As of Scriptcards 2.6.0, there is now expanded support for storing data, including settings. Read more about persistent data here.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.)

[edit] 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)

[edit] 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. Roll modifiers allow you to reference parts of a roll, or to display the roll results in different ways.

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.

[edit] 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.

[edit] 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]
}}

[edit] 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 .

[edit] 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]

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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%].

[edit] Conditional Statement (--?)

See the Variables section for more information on Variables

See the Referencing section for information on referencing variable content

[edit] 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 variables for comparison can, or does, contain a space (e.g. "The Dog", "Fruit salad"), it needs to be surrounded by double quotes. Here are some real-world examples of different comparisons:

Example 1:

 --?[$AttackRoll.Base] -eq 20| 

This comparison checks if the initial value of the roll, before any modifiers are included, is equal to 20. Normally -eq is case-sensitive, but rather it's case-sensitive or not only applies to text comparisons; and never applies to digits. This check is great if you want to do something special when the player rolls a "natural 20", or use a set of rules that includes the "critical success" model. You can easily change the 20 to any other number to accommodate any special rules your game uses.

Example 2:

 --?"[&Fruit]" -inc "Green grapes"| 

This comparison checks if the non-case-sensitive phrase "green grapes" is a part of the contents of the &Fruit string variable. Because the comparison is not case sensitive "Green grapes", "greEN GRapes" and "gREen GRApes" will produce the same results. This check is perfect for checking for a specific value or phrase in variables that are created by a script in an automated fashion.

General Guidance: It's safe to use double quotes any time around the variable and/or the comparator, even if the quotes are not strictly required, however the comparison will not work if the double quotes are needed, but are not being used.

Example 3:

 --?@{selected|dexterity_mod} -lt 8| 

This comparison looks at the dexterity_mod attribute of the token that is currently selected (so make sure a token is selected before running this!) to determine if the attribute is less than 8. This is perfect for determining pass/fail outcomes for anything within your game. Additionally, you can perform math operations on Roll Variables before and after any comparisons are made.

Example 4:

 --?@"{targeted|name}" -inc "dwarf"| 

This comparison will prompt the person running the script to select a target token by clicking on it on the tabletop. The Comparison will then check the name of the token to determine if it contains the phrase "dwarf"

[edit] 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]

[edit] 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]

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.

[edit] 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 because the first true and false will be false, but then false OR true that remains will be true.

Conversely:

true or false and false

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

[edit] 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.

[edit] 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.

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

[edit] Original Method of Saving and Loading

[Expand/Collapse Save & Load Info]

[edit] Examples of Syntax

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

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

!sc-liststoredsettings

[edit] Practical Application Examples

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

--Lsettings|@{selected|token_name}

[edit] 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]

[edit] 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

[edit] 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]

[edit] 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)

[edit] 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

[edit] 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

[edit] 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.

[edit] 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.

[edit] 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
search	Character_Id;SearchText;Section Prefix;Field	same syntax as --rfind, except that it will do a case-insentitive partial match. This is converted to a regex, so if you need to find special regex characters (like +), prefix them with a "\".
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. If you add ;1 to the end of the parameter list, the search will be case-insensitive
dump	none	Outputs all of the available fields for the loaded repeating section row to the Mod Scripts console for debugging or research

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.

[edit] 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]...

[edit] Function Descriptions

The section below is a work in progress to document each function fully instead of relying on the huge table further down with limited details.

Functions are called with the --~ command and follow the syntax:

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

In the function descriptions below, the following will be stated for each function:

• Purpose: What the function does
• Returns: What (if anything) is return in the [Variable Name] variable, including the variable type (RollVariable or StringVariable)
• Syntax : How to call the function
• Params : The meaning of each of the parameters

Each function (with the exception of a handful of the earliest implemented functions) are grouped into categories by the object or entity types they deal with.

[edit] Array Functions

Array functions either return/generate an array, manipulate an array, or return parts of an array as a variable.

[edit] Elementary Array Functions

Note: these array-related functions are holdovers from the original array implementation. They are all still available, but may haven been superseded by better methods. This will be indicated along with each function.

Array functions are part of the "array" category.

define Array Function

--~|array;define;Fruits;Lemon;Peach;Mango;Watermelon

--&fruits(9999)|Peach
--&fruits(9999)|Mango
--&fruits(9999)|Watermelon

add Array Function

--~|array;add;Fruits;Grape;Lime;Dragonfruit

--&fruits(9999)|Grape
--&fruits(9999)|Lime
--&fruits(9999)|Dragonfruit

remove Array Function

--~|array;remove;Fruits;Lime

replace Array Function

--~|array;replace;Fruits;Grape;Pear

getfirst Array Function