Introduction to ScriptCards
The ScriptCards Mod 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:
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.)
Looping – For...Next, While, Until, and ForEach loops. Includs 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.
**❗Critically Important: ** ScriptCards does not parse Roll20 "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.
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.
The current version of ScriptCards (currently in development on the GitHub repo is considered to be experimental as it supports a new feature called "Hashtables", which is a construct superficially similar to arrays, except you can "label" the index values rather than being limited to working only with the index numbers. This allows for a greater degree of complexity in the data stored, while also letting you remember less complicated arrangements of information by allowing you to refer to something by its assigned name instead of arbitrary index numbers. Check out more on these new features in the Hashtables section.
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 (, , ) 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.
A ScriptCard script is text written into the (either typed directly, pasted, or run via a macro/character ability) that will be interpreted 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.
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 ---- |
Detailed example of instruction line syntax:
--#title|Longsword Attack
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.
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]}}